cli: add install-source and agent-host attribution

[Gregory Joseph (gnjoseph)]

Summary

Adds opt-in, bounded install-source and agent-host attribution to the SPE MCP server so install configurations can identify the publishing surface and initialized MCP clients can identify the host associated with later Graph/ARM activity, without opening a separate telemetry channel.

What changed

• Adds --install-source, --install-content, and --install-campaign to spe-mcp start, with environment-variable equivalents.
• Derives agent-host after initialized from the MCP client's self-reported initialize.clientInfo.
• Appends bounded labels to Graph User-Agent, Azure CLI AZURE_HTTP_USER_AGENT, and Azure Developer CLI AZURE_DEV_USER_AGENT without clobbering caller values.
• Keeps raw MCP client name/version out of sent attribution and never uses host classification for authorization.
• Adds --no-install-attribution / SPE_INSTALL_ATTRIBUTION=off to disable all install and host labels.
• Adds attributed VS Code, VS Code Insiders, Visual Studio, Cursor, Claude Code, and Codex install paths to the README.
• Updates privacy, data-flow, and changelog documentation.

The client configuration retains the startup arguments, so install source is supplied on each launch without a new state file or telemetry endpoint.

Bounded values

Dimension	Allowed values
source	microsoft-learn, github-readme, github-release, mcp-registry, npm, other
content	readme-install, sharepoint-embedded-mcp-server, quickstart-vscode, create-container-type, create-manage-containers
campaign	docs-install-buttons
agent-host	vscode, visual-studio, cursor, claude-code, claude-desktop, codex, github-copilot-cli, azure-ai-foundry, other, unknown

content and campaign are optional but require source. Agent host is automatic.

Trust boundary

• Agent-host classification uses self-reported MCP clientInfo; it is attribution only and must never be used for a security decision.
• VS Code identity was verified from the public microsoft/vscode source.
• Closed-source host-name mappings are advisory; unrecognized values become other, and missing/generic values become unknown.
• Raw client name and version are not sent.

Validation

• npm run lint
• npm run build
• npm test — 773 passed, 7 skipped
• GitHub build/test checks passed on Node 22, 24, and 26; CLA and secret checks passed.
• Exercised the VS Code, VS Code Insiders, Visual Studio, and Cursor HTTP wrappers and decoded every payload.
• Installed Claude Code CLI help and official Codex documentation confirm the command forms.
• Focused review found no issues.

Release gates

• Obtain privacy/CELA approval for the attribution disclosure before publishing or enabling attributed install links broadly.
• Implement SPO.Core ingestion under AB#3198658: validate the bounded tokens on create-container-type and persist them once for COGSDB/dashboard reporting.
• Resolve or formally accept the existing high-severity dependency-audit baseline. This PR does not change package.json or package-lock.json.
• Reconcile the pre-existing server.json version/registry metadata before the next MCP Registry publication.

Coordination

Companion Learn draft: SharePoint/sp-dev-docs#10953

The Learn change should merge only after these CLI flags are available in the published npm package and the attribution disclosure is approved.

Marc Windle is the intended PM reviewer; GitHub could not add him automatically because he is not currently a collaborator on this repository.

[Gregory Joseph (gnjoseph)]

Confirmed the bounded attribution contract and downstream dependency.

Dimension	Allowed values
source	microsoft-learn, github-readme, github-release, mcp-registry, npm, other
content	readme-install, sharepoint-embedded-mcp-server, quickstart-vscode, create-container-type, create-manage-containers
campaign	docs-install-buttons
agent-host	vscode, visual-studio, cursor, claude-code, claude-desktop, codex, github-copilot-cli, azure-ai-foundry, other, unknown

content and campaign are optional but require source. Agent host is derived automatically from the MCP handshake's self-reported clientInfo.name; only the bounded category is sent, never the raw name/version, and it is not a security signal. --no-install-attribution / SPE_INSTALL_ATTRIBUTION=off suppresses both install and host labels.

SPO.Core ingestion is now tracked by AB#3198658: consume and validate the tokens on the authenticated create-container-type request, persist attribution once for COGSDB/dashboard reporting, and treat missing/invalid values as unknown.

[Gregory Joseph (gnjoseph)]

Companion PR: SharePoint/sp-dev-docs#10953. 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.