cli: add install-source and agent-host attribution

[Gregory Joseph (gnjoseph)]

Summary

Adds 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 and Azure 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 MCP initialization from the client's self-reported clientInfo.
• Appends bounded labels to Graph User-Agent, Azure CLI AZURE_HTTP_USER_AGENT, and Azure Developer CLI AZURE_DEV_USER_AGENT.
• Preserves unrelated caller-provided User-Agent values, replaces stale SPE-owned tokens, and avoids duplicate tokens.
• Keeps raw MCP client names and versions out of transmitted attribution and never uses host classification for authentication or authorization.
• Adds --no-install-attribution / SPE_INSTALL_ATTRIBUTION=off to disable install and host labels.
• Updates the README install paths and the public privacy, data-flow, notice, 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 attribution is automatic after initialization.

Trust boundary and user controls

• Agent-host classification uses self-reported MCP clientInfo; it is attribution only and is never used for a security decision.
• Unrecognized client names become other; missing or generic values become unknown.
• Raw client names and client versions are not transmitted.
• --no-install-attribution disables install and agent-host labels while retaining the product token.
• SPE_MCP_COLLECT_TELEMETRY=false removes all SPE-owned product, install, campaign, and agent-host tokens while preserving unrelated caller User-Agent content.

Validation

• Focused attribution suites: 106 tests passed.
• Post-review Graph/User-Agent regression suites: 85 tests passed.
• npm run lint: 0 errors, 12 existing warnings.
• npm run ci: typecheck and build passed; 970 tests passed and 7 skipped.
• npm audit --audit-level=high: passes after updating the transitive fast-uri lock entry to 3.1.6; two moderate qs advisories remain below the configured threshold.
• Independent review findings for caller User-Agent preservation and case-insensitive header handling were fixed with regression coverage.

Related documentation

• SharePoint developer documentation companion: Add attributed MCP install buttons across SharePoint Embedded articles SharePoint/sp-dev-docs#10953

[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.