Skip to content

Add attributed MCP install buttons across SharePoint Embedded articles - #10953

Open
Gregory Joseph (gnjoseph) wants to merge 8 commits into
SharePoint:mainfrom
gnjoseph:users/grjoseph/mcp-docs-devtools-buttons
Open

Add attributed MCP install buttons across SharePoint Embedded articles#10953
Gregory Joseph (gnjoseph) wants to merge 8 commits into
SharePoint:mainfrom
gnjoseph:users/grjoseph/mcp-docs-devtools-buttons

Conversation

@gnjoseph

@gnjoseph Gregory Joseph (gnjoseph) commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds docs-to-devtools install buttons for the SharePoint Embedded MCP server across high-intent SharePoint Embedded build articles.

Every install path supplies bounded attribution arguments:

--install-source microsoft-learn --install-content <article> --install-campaign docs-install-buttons

Each article uses its own published content value:

Article Content value
Use the MCP server to build apps with a coding agent sharepoint-embedded-mcp-server
Quickstart: Build your first app with VS Code quickstart-vscode
Create and configure a container type create-container-type
Create and manage containers create-manage-containers

The MCP client stores these arguments in its server configuration and supplies them on each launch. The server adds the bounded labels to existing Graph and ARM request metadata; it does not open a separate telemetry channel.

Existing ms.date values are intentionally unchanged.

Install targets

  • Visual Studio Code
  • Visual Studio Code Insiders
  • Visual Studio
  • Cursor
  • Claude Code
  • Codex CLI

Implementation status

Validation

  • Decoded all 16 one-click install payloads and verified their exact source, article-specific content, and campaign arguments.
  • Confirmed the Visual Studio Code and Visual Studio Code Insiders wrappers contain their expected MCP install schemes.
  • Confirmed each Visual Studio payload decodes to the expected command and arguments.
  • Confirmed each Cursor base64 configuration decodes to the expected command and arguments.
  • Confirmed the Claude Code and Codex CLI commands include all three attribution dimensions.
  • Confirmed the public alpha.4 CLI artifacts from unpkg and jsDelivr contain --install-source, --install-content, --install-campaign, and --no-install-attribution.
  • Confirmed unpkg resolves @microsoft/spe-mcp@latest to 0.2.0-alpha.4.
  • Local DocFX dry run succeeded with 0 errors. Its 309 warnings are pre-existing and outside the changed files.
  • OpenPublishing.Build, PoliCheck Scan, and license/cla checks are successful.

The Microsoft package-feed proxy and some CDN edges can temporarily return stale npm dist-tag metadata. The explicit alpha.4 package artifacts and public unpkg latest resolution were used for release-gate validation.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

Adds a docs-to-devtools install-buttons include to the SharePoint Embedded
MCP server Learn article (Install and configure section): a native
'Install in Visual Studio Code' next-step-action button plus one-click
install links for VS Code Insiders, Visual Studio, and Cursor, and the
claude/codex 'mcp add' CLI commands.

Scoped to the MCP server page only for now.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@gnjoseph
Gregory Joseph (gnjoseph) force-pushed the users/grjoseph/mcp-docs-devtools-buttons branch from 7eb3d37 to eafc4a5 Compare July 15, 2026 19:14
@gnjoseph Gregory Joseph (gnjoseph) changed the title Add docs-to-devtools MCP install/action buttons to SharePoint Embedded docs Add MCP install buttons to the SharePoint Embedded MCP server article Jul 15, 2026
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit eafc4a5:

✅ Validation status: passed

File Status Preview URL Details
docs/embedded/build/sharepoint-embedded-mcp-server.md ✅Succeeded View
docs/embedded/includes/mcp-install-buttons.md ✅Succeeded View

For more details, please refer to the build report.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

Comment thread docs/embedded/includes/mcp-install-buttons.md Outdated
Add Microsoft Learn source and campaign arguments to every supported install path, and surface the reusable install include on high-intent SharePoint Embedded build articles.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@gnjoseph Gregory Joseph (gnjoseph) changed the title Add MCP install buttons to the SharePoint Embedded MCP server article Add attributed MCP install buttons across SharePoint Embedded articles Aug 10, 2026
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 5dfce54:

✅ Validation status: passed

File Status Preview URL Details
docs/embedded/build/create-container-type.md ✅Succeeded View
docs/embedded/build/create-manage-containers.md ✅Succeeded View
docs/embedded/build/quickstart-vscode.md ✅Succeeded View
docs/embedded/build/sharepoint-embedded-mcp-server.md ✅Succeeded View
docs/embedded/includes/mcp-install-buttons.md ✅Succeeded View

For more details, please refer to the build report.

Comment thread docs/embedded/build/create-container-type.md Outdated
Keep ms.date unchanged while adding the reusable MCP install include.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@gnjoseph

Copy link
Copy Markdown
Contributor Author

Addressed the review follow-ups:

  • Restored every existing ms.date value in commit 446e83d; this PR no longer changes article dates.
  • Kept the current reusable include presentation as the initial version so its appearance can be improved once in one place later.
  • Exercised and decoded every editor payload:
    • VS Code: HTTP 302 to vscode:mcp/install with the expected attributed npx args.
    • VS Code Insiders: HTTP 302 to vscode-insiders:mcp/install with the same args.
    • Visual Studio: aka.ms 301 → vs-open.link 302 → vsweb+mcp:/install, preserving the payload.
    • Cursor: HTTP 200; its base64 config decodes to the expected command/args.
    • Claude Code: installed CLI help confirms mcp add <name> -- <command> [args...], matching this command.
    • Codex: the official MCP documentation confirms codex mcp add <server-name> -- <stdio server-command>.

All decoded configurations contain --install-source microsoft-learn --install-campaign docs-install-buttons.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 446e83d:

✅ Validation status: passed

File Status Preview URL Details
docs/embedded/build/create-container-type.md ✅Succeeded View
docs/embedded/build/create-manage-containers.md ✅Succeeded View
docs/embedded/build/quickstart-vscode.md ✅Succeeded View
docs/embedded/build/sharepoint-embedded-mcp-server.md ✅Succeeded View
docs/embedded/includes/mcp-install-buttons.md ✅Succeeded View

For more details, please refer to the build report.

Expand MCP on first use, use direct active-voice instructions, and simplify the reusable install text after reviewing the PR with the internal SPE documentation skills.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@gnjoseph

Copy link
Copy Markdown
Contributor Author

Internal odsp-microsoft/spe-dev-docs-ai review summary:

  • Cloned the repository to Q:\src\spe-dev-docs-ai and installed spe-doc-updater@spe-dev-docs-ai.
  • Verified spe-doc-updater, doc-review, and sharepoint-reader.
  • Ran /doc-review across all five PR files using the style, accuracy, and code reviewers. Most findings were pre-existing or outside the PR diff.
  • Fixed the PR-specific editorial finding in commit 41e7a9c by expanding Model Context Protocol on first use and using direct active voice.
  • Left the original ms.date values unchanged.
  • Re-decoded all editor payloads; all passed.
  • The reviewers correctly flagged that attribution flags are not present in the currently published npm version. This remains an explicit merge-order gate on OSS PR Staging #86 and the subsequent package publish.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 41e7a9c:

✅ Validation status: passed

File Status Preview URL Details
docs/embedded/build/create-container-type.md ✅Succeeded View
docs/embedded/build/create-manage-containers.md ✅Succeeded View
docs/embedded/build/quickstart-vscode.md ✅Succeeded View
docs/embedded/build/sharepoint-embedded-mcp-server.md ✅Succeeded View
docs/embedded/includes/mcp-install-buttons.md ✅Succeeded View

For more details, please refer to the build report.

Replace long editor-specific install URLs with validated, team-owned aka.ms aliases while preserving attributed Claude and Codex command examples.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@gnjoseph

Copy link
Copy Markdown
Contributor Author

Companion PR: microsoft/SharePoint-Embedded-MCP-Server#86. Eight team-owned aka.ms aliases were created under spe-mcp/install/{learn|github}/{target}, owned by Greg Joseph, Marc Windle, and Diego Luces. Every alias was validated through the complete redirect chain: VS Code/Insiders reached their correct custom schemes, Visual Studio reached vsweb+mcp:/install, Cursor configs decoded, and all command args matched the intended surface attribution. Direct URLs were replaced in Learn commit dff552a and OSS commit 9288711.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit dff552a:

✅ Validation status: passed

File Status Preview URL Details
docs/embedded/build/create-container-type.md ✅Succeeded View
docs/embedded/build/create-manage-containers.md ✅Succeeded View
docs/embedded/build/quickstart-vscode.md ✅Succeeded View
docs/embedded/build/sharepoint-embedded-mcp-server.md ✅Succeeded View
docs/embedded/includes/mcp-install-buttons.md ✅Succeeded View

For more details, please refer to the build report.

Keep the reusable one-click links compact and move Claude Code and Codex CLI commands into a dedicated, copyable console section on the MCP article.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 194d363:

✅ Validation status: passed

File Status Preview URL Details
docs/embedded/build/create-container-type.md ✅Succeeded View
docs/embedded/build/create-manage-containers.md ✅Succeeded View
docs/embedded/build/quickstart-vscode.md ✅Succeeded View
docs/embedded/build/sharepoint-embedded-mcp-server.md ✅Succeeded View
docs/embedded/includes/mcp-install-buttons.md ✅Succeeded View

For more details, please refer to the build report.

@gnjoseph

Copy link
Copy Markdown
Contributor Author

Diego’s UX feedback was addressed in commit 194d363: the reusable include now keeps only the primary VS Code button, compact secondary editor links, and a short command-line setup link; the Claude Code and Codex commands moved to a dedicated copyable console section. Learn Build and PoliCheck passed, and I verified the actual rendered UX in external Microsoft Edge on both the MCP article and the create-container-type article using the build-service preview.

Preview · Build comment

List alternative clients as scannable links and keep Claude Code and Codex CLI commands free of visible attribution parameters.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 1c7bded:

✅ Validation status: passed

File Status Preview URL Details
docs/embedded/build/create-container-type.md ✅Succeeded View
docs/embedded/build/create-manage-containers.md ✅Succeeded View
docs/embedded/build/quickstart-vscode.md ✅Succeeded View
docs/embedded/build/sharepoint-embedded-mcp-server.md ✅Succeeded View
docs/embedded/includes/mcp-install-buttons.md ✅Succeeded View

For more details, please refer to the build report.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@gnjoseph

Copy link
Copy Markdown
Contributor Author

Verified the final client setup UX for head 1c7bded8b in external Microsoft Edge: primary VS Code remains a button; Insiders, Visual Studio, Cursor, Claude Code, and Codex CLI render as a scannable bullet list. Selecting Claude Code lands on its dedicated copyable console block. Visible Claude/Codex commands now use the clean ... @microsoft/spe-mcp start forms, with no install-source or campaign parameters. Learn Build passed, and PoliCheck found no issues.

Give each SharePoint Embedded Learn placement its own bounded content label while retaining the Microsoft Learn source and docs install campaign. Attribute the Claude Code and Codex setup commands to the MCP server article.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@gnjoseph
Gregory Joseph (gnjoseph) marked this pull request as ready for review September 10, 2026 02:54
@gnjoseph

Copy link
Copy Markdown
Contributor Author

Validation evidence

Retested the attributed install links and the Microsoft Learn preview for this PR.

Automated checks

  • Decoded install payloads: 16/16 passed across the four article-specific include files. Every VS Code, VS Code Insiders, Visual Studio, and Cursor payload contains the exact expected command and bounded attribution values (microsoft-learn, the article-specific content value, and docs-install-buttons).
  • Live install endpoints: 16/16 passed: VS Code 4/4 returned HTTP 302 to vscode:, VS Code Insiders 4/4 returned HTTP 302 to vscode-insiders:, Visual Studio 4/4 returned HTTP 301 to the Visual Studio installer handoff, and Cursor 4/4 returned HTTP 200.
  • CLI examples: 2/2 passed exact-argument validation for Claude Code and Codex CLI.
  • Published package: the explicit @microsoft/spe-mcp@0.2.0-alpha.4 CLI artifacts from both unpkg and jsDelivr contain --install-source, --install-content, --install-campaign, and --no-install-attribution; public latest resolves to 0.2.0-alpha.4.
  • Docs build: DocFX dry run completed with 0 errors (the 309 warnings are pre-existing repository-wide warnings outside these changes).

Microsoft Learn preview in Edge

All eight changed files passed OpenPublishing validation and generated preview links:

OpenPublishing validation succeeded for all changed files

The create-container-type preview renders the attributed MCP install block:

Microsoft Learn preview rendering the MCP install block

Selecting Install in Visual Studio Code reaches the expected external-application handoff:

Microsoft Edge requesting permission to open Visual Studio Code

@gnjoseph

Copy link
Copy Markdown
Contributor Author

Validation evidence

Retested the attributed install links and the Microsoft Learn preview for this PR.

Automated checks

  • Decoded install payloads: 16/16 passed across the four article-specific include files. Every VS Code, VS Code Insiders, Visual Studio, and Cursor payload contains the exact expected command and bounded attribution values (microsoft-learn, the article-specific content value, and docs-install-buttons).
  • Live install endpoints: 16/16 passed: VS Code 4/4 returned HTTP 302 to vscode:, VS Code Insiders 4/4 returned HTTP 302 to vscode-insiders:, Visual Studio 4/4 returned HTTP 301 to the Visual Studio installer handoff, and Cursor 4/4 returned HTTP 200.
  • CLI examples: 2/2 passed exact-argument validation for Claude Code and Codex CLI.
  • Published package: the explicit @microsoft/spe-mcp@0.2.0-alpha.4 CLI artifacts from both unpkg and jsDelivr contain --install-source, --install-content, --install-campaign, and --no-install-attribution. Public latest resolved to 0.2.0-alpha.4 during release verification.
  • Docs build: DocFX dry run completed with 0 errors (the 309 warnings are pre-existing repository-wide warnings outside these changes).

Microsoft Learn preview in Edge

All eight changed files passed OpenPublishing validation and generated preview links:

OpenPublishing validation succeeded for all changed files

The create-container-type preview renders the attributed MCP install block:

Microsoft Learn preview rendering the MCP install block

Selecting Install in Visual Studio Code reaches the expected external-application handoff:

Microsoft Edge requesting permission to open Visual Studio Code

@dluces Diego Luces (dluces) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wish you could pass parameters into the included blocks…

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants