[FEATURE] Standalone `apm mcp export --runtime <target>` command

[danielmeppiel]

Summary

Split out from #20 as a focused residual. Today APM generates runtime MCP config (.vscode/mcp.json, ~/.copilot/mcp-config.json, Codex TOML, Claude, Cursor, Gemini, OpenCode, IntelliJ) only as a side effect of apm install. There is no way to (re)generate runtime config on demand without running a full install.

The MCP subcommand surface at HEAD is install | search | show | list only -- no export (verified: grep for export across src/apm_cli/commands/mcp.py and src/apm_cli/install/mcp/ returns nothing).

Ask

A standalone command, e.g.:

apm mcp export --runtime vscode
apm mcp export --runtime copilot --runtime codex

that materializes runtime config from the already-resolved apm.yml + lockfile, without re-resolving/installing dependencies.

Why

• @TechWatching and enterprise evaluators ([FEATURE] Extended MCP Server Configuration in apm.yml #20 thread) want to regenerate per-runtime config deterministically (CI, onboarding, drift repair) decoupled from the install lifecycle.
• The underlying per-runtime writers already exist (adapter layer). This is largely surfacing existing generation as a first-class command.

Design notes (light)

• Output target precedence and interaction with the lockfile need to be defined (export should read resolved state, not trigger resolution).
• Reuse the existing adapter writers; do not fork config-generation logic.
• Respect the existing targets: whitelist semantics (see PR fix: respect targets: whitelist for all runtimes during MCP install #1336).

Context

Parent: #20. The bulk of #20's extended-config ask shipped in v0.8.0; this is one of two genuine residuals.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/mcp-config
area/cli
type/feature
status/accepted
priority/high

Milestone

null

Suggested next action

Implement apm mcp export --runtime <target> in src/apm_cli/commands/mcp.py reusing existing per-runtime adapter writers, reading only from the resolved lockfile (no re-resolution), and ship the cli-commands.md docs update in the same PR.

Suggested issue comment

Thanks for this well-scoped residual from #20. This is a clear DX win: decoupling config generation from the install lifecycle unlocks deterministic CI workflows and on-demand drift repair without triggering dependency resolution.

The underlying runtime writers already exist in src/apm_cli/install/mcp/. The implementation path is bounded:

1. Add an export subcommand to src/apm_cli/commands/mcp.py
2. Load resolved state from the lockfile (read-only path, no resolver call)
3. Dispatch the existing per-runtime adapter writers
4. Add a --runtime repeatable option matching the existing adapter surface

Design note for the PR author: define how --runtime interacts with the targets: whitelist in apm-policy.yml and whether --force is required to overwrite an existing config file (the path should respect the same overwrite semantics as apm install). Document the new command in docs/src/content/docs/reference/cli-commands.md in the same PR.

See the apm mcp command reference at https://github.com/microsoft/apm/blob/main/docs/src/content/docs/reference/cli-commands.md for the existing subcommand surface.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps directly to a real surface gap: users need to regenerate runtime config in CI without triggering a full install. The export verb is appropriate (analogous to cargo build --release materializing a build artifact from resolved state). The --runtime <target> flag is self-explanatory to APM users and composable in shell scripts and CI pipelines. The repeatable flag form (--runtime vscode --runtime copilot) is consistent with the multi-target mental model. Exit codes, stdout vs stderr behavior, and overwrite semantics need to be defined in the PR -- the issue flags the design note around output target precedence, which is the right scope for the implementing PR, not a blocker for acceptance.

Supply Chain Security Expert -- Risk-Surface Reviewer

No new security surface: the export command reads from an already-resolved, locked state and calls writers that already exist in the apm install path. No new network calls, no new trust boundaries. The one surface to flag: generated config files (~/.copilot/mcp-config.json, .vscode/mcp.json) may contain env var references including token names. Overwrite behavior should require either --force or a user confirmation for system-wide config locations, matching the defense-in-depth pattern APM uses elsewhere. This is a UX-ergonomics refinement for the implementing PR, not a blocker for acceptance. No new theme/security implication.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR with deep project engagement; tone tuning for new contributors is not needed.

Python Architect -- Architecture Reviewer

The implementation scope is bounded to src/apm_cli/commands/mcp.py plus the existing adapter writers in src/apm_cli/install/mcp/. The main design question is how export reads resolved state: it must use the same lockfile-loading code path as install rather than forking a new reader, to preserve the single-source-of-truth contract for resolved deps. No new modules are needed; this is a new click subcommand + lockfile read path + adapter dispatch. status/accepted is appropriate -- the architecture is clear, the design question is a PR-level detail, not a gate-level design decision.

Doc Writer -- Documentation Reviewer

Docs work is required: docs/src/content/docs/reference/cli-commands.md must be updated with the apm mcp export subcommand entry in the same PR as the implementation. An implementing PR that ships the command without the docs update is incomplete per the repo doc-sync rules. Additionally, packages/apm-guide/.apm/skills/apm-usage/commands.md must be updated (Rule 4). Suggest the implementing PR also adds a note in the CI/CD integration guide explaining the apm mcp export pattern for on-demand config regeneration.

APM CEO -- Triage Arbiter

All lenses align: bounded scope, validated demand (enterprise evaluators + @TechWatching), clean architecture, real docs obligation. This is a straightforward accept with priority/high -- the CI determinism use case is a concrete demand signal from the target enterprise adopter segment. The primary theme is theme/portability: the feature makes MCP config generation portable across environments (local, CI, onboarding scripts) decoupled from the install lifecycle. Milestone: maintainer should assign to the next open minor milestone; the item is ready for implementation once the PR author settles the output-target precedence design note in the issue. No growth-hacker tone adjustment needed.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/mcp-config", "area/cli"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Implement apm mcp export --runtime <target> in src/apm_cli/commands/mcp.py reusing existing per-runtime adapter writers, reading only from resolved lockfile, and ship the cli-commands.md docs update in the same PR.",
  "comment_markdown": "Thanks for this well-scoped residual from #20. The implementation path is bounded: add an export subcommand to src/apm_cli/commands/mcp.py, load resolved state from the lockfile (read-only, no resolver call), dispatch the existing per-runtime adapter writers, and add a --runtime repeatable option. Document the new command in docs/src/content/docs/reference/cli-commands.md in the same PR."
}

---

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 · sonnet46 3M · ◷