Feature: Support VS Code user-profile `mcp.json` for `--global` scope

[sergio-sisternes-epam]

Summary

Issue #637 named VS Code user-profile mcp.json as in-scope for --global MCP installation. However, the implementation in PR #638 marks VS Code as workspace-only (supports_user_scope = False) because the current VS Code adapter only writes to .vscode/mcp.json (project-local).

VS Code does support a user-level MCP configuration path (e.g. ~/.config/Code/User/settings.json or the VS Code user-profile mcp.json), but the adapter does not currently implement this.

Proposed Change

1. Investigate the correct user-profile MCP configuration path for VS Code (varies by platform: Linux, macOS, Windows).
2. Add a user_scope_config_path property (or similar) to VSCodeClientAdapter that returns the user-level config path.
3. Set supports_user_scope = True on VSCodeClientAdapter once the user-profile path is implemented.
4. Add tests for the new behavior.

Context

• Parent issue: [BUG] apm install --global skips MCP server installation for all runtimes #637
• Related PR: Fix apm install --global skipping MCP server installation #638 (marks VS Code as workspace-only as a pragmatic scope cut)
• The Copilot CLI and Codex CLI adapters already support user scope via ~/.copilot/ and ~/.codex/ respectively.

Labels

enhancement

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/mcp-config
area/multi-target
type/feature
status/needs-design

Milestone

null

Suggested next action

Document the exact user-profile MCP config paths for VS Code, VS Code Insiders, and VS Codium on Windows/macOS/Linux, decide which variants APM will support, and post that table as a design comment before implementation begins.

Suggested issue comment

This is a natural extension of the work in #637/#638 and the direction is right -- `--global` for VS Code should write to the user-level MCP config, not just the project-local `.vscode/mcp.json`.

The implementation blocker is cross-platform path resolution. VS Code user-profile MCP config paths differ by platform and by VS Code variant:

- **VS Code (stable):** `~/Library/Application Support/Code/User/mcp.json` (macOS), `%APPDATA%\Code\User\mcp.json` (Windows), `~/.config/Code/User/mcp.json` (Linux)
- **VS Code Insiders:** similar paths with `Code - Insiders` instead of `Code`
- **VS Codium:** similar paths with `VSCodium`

Before implementing `get_user_mcp_config_path()` in the VS Code adapter, we need to decide:
1. Which variants does APM support for `--global` scope? (stable only? Insiders? Codium?)
2. How does APM detect which variant is installed? (check paths in order? Require explicit `--client` flag?)
3. What is the fallback when none of the expected paths exist?

Once those questions are answered in a design comment here, the implementation is straightforward and follows the existing multi-target adapter pattern. The path security requirement (validate with `ensure_path_within`) is non-negotiable regardless of which paths are chosen.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user task is "install an MCP server once and have it available across all VS Code projects." This maps directly to the --global scope concept. The request is clearly grounded in how VS Code itself separates user-profile settings from workspace settings. The gap (supports_user_scope = False in the current adapter) was a known shortcut in PR #638; this issue is the natural follow-up.

Supply Chain Security Expert -- Risk-Surface Reviewer

Writing to the VS Code user-profile MCP config is higher blast-radius than project-local: a misconfigured or malicious entry affects all VS Code projects on the machine. The implementation must use ensure_path_within path guards when resolving the user config path, validate MCP config before writing, and not follow symlinks out of the expected config directory. theme/portability is primary (cross-OS path resolution); a secondary theme/security concern exists but is addressed by the existing path-security framework.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- sergio-sisternes-epam is an established collaborator with extensive prior interactions on microsoft/apm; warmth tuning for a new contributor is not needed.

Python Architect -- Architecture Reviewer

The design question is concrete: what are the exact user-profile MCP config paths for each VS Code variant on each platform, and which does APM support? The implementation pattern is well-understood (add get_user_mcp_config_path() to the VS Code adapter, flip supports_user_scope = True). The risk is getting the platform-specific path table wrong. status/needs-design is the right call: a design comment with the confirmed path table should precede the PR to avoid multiple rounds of cross-platform correction.

Doc Writer -- Documentation Reviewer

Implementing --global scope for VS Code will require updating the VS Code installation guide and the CLI reference for the --global flag. area/docs-site as a secondary area is warranted -- but since this is needs-design, deferred until the design is settled. The implementing PR must include doc updates.

APM CEO -- Triage Arbiter

Sound direction, non-trivial cross-platform path resolution. The Python Architect's needs-design recommendation is correct: getting the VS Code variant path table wrong would ship a broken feature and require a fast follow-up release. Spend the design cost upfront. No milestone until design is settled.

{
  "decision": "needs-design",
  "decision_detail": "Enumerate exact user-profile MCP config paths for VS Code, VS Code Insiders, and VS Codium on Windows/macOS/Linux; decide which variants APM will support and how detection works when multiple variants are installed.",
  "theme": "theme/portability",
  "areas": ["area/mcp-config", "area/multi-target"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Post a design comment with the confirmed VS Code user-profile MCP config path table (all supported variants x all platforms) before implementation begins.",
  "comment_markdown": "This is a natural extension of the work in #637/#638 and the direction is right -- `--global` for VS Code should write to the user-level MCP config, not just the project-local `.vscode/mcp.json`.\n\nThe implementation blocker is cross-platform path resolution. VS Code user-profile MCP config paths differ by platform and by VS Code variant:\n\n- **VS Code (stable):** `~/Library/Application Support/Code/User/mcp.json` (macOS), `%APPDATA%\\Code\\User\\mcp.json` (Windows), `~/.config/Code/User/mcp.json` (Linux)\n- **VS Code Insiders:** similar paths with `Code - Insiders` instead of `Code`\n- **VS Codium:** similar paths with `VSCodium`\n\nBefore implementing `get_user_mcp_config_path()` in the VS Code adapter, we need to decide:\n1. Which variants does APM support for `--global` scope? (stable only? Insiders? Codium?)\n2. How does APM detect which variant is installed? (check paths in order? Require explicit `--client` flag?)\n3. What is the fallback when none of the expected paths exist?\n\nOnce those questions are answered in a design comment here, the implementation is straightforward and follows the existing multi-target adapter pattern. The path security requirement (validate with `ensure_path_within`) is non-negotiable regardless of which paths are chosen."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 2.3M · ◷