Context: Surfaced via #122 and the followup conversation with @lirantal -- there is no CLI path to add an MCP server today; users must hand-edit apm.yml. apm mcp today is read-only (list/search/show).
Proposed change
Extend apm install (the canonical add-and-deploy verb, mirroring npm install) with an explicit --mcp flag for MCP server entries. Reuses the already-existing --only [apm|mcp] vocabulary on the same command.
# Registry-backed MCP -- one-liner case
apm install --mcp io.github.github/github-mcp-server
# Self-defined stdio (the lirantal case) -- `--` boundary, args become a list
apm install --mcp nodejs-api-docs -- npx -y mcp-server-nodejs-api-docs
# Self-defined stdio with env vars
apm install --mcp my-server --env API_KEY='${{ secrets.API_KEY }}' -- ./bin/my-server --port 3000
# Self-defined HTTP / SSE / streamable-http
apm install --mcp internal-kb --transport http --url https://mcp.internal.example.comDiscoverability bridge: thin alias apm mcp install <args> delegates to apm install --mcp <args> for users arriving via apm mcp --help. Pure delegation, no code duplication.
Why --mcp flag instead of auto-detection of positional shape
Auto-detecting "is this an MCP registry name?" by string pattern is fragile and surprising -- a typo'd APM package name could silently land as an MCP entry. Explicit flag keeps the contract unambiguous.
Security-correctness by construction
After --, argv[0] becomes command (string), rest becomes args (list). No shell=True, no whitespace-splitting. Same boundary that closes the validation gap in [link-to-w4-issue].
Defaults logic
transport: stdio when -- is presenttransport: http when --url is presenttransport from --transport if explicitly set (overrides above)registry: false when -- or --url is usedregistry: true when only a registry name is given (no --, no --url)
Scope
- New click options on
apm install: --mcp, --transport, --url, --env (repeatable)
- Argv parser for
-- boundary
- yaml writer for
dependencies.mcp entries (idempotency, name collision warn)
- Trigger existing install pipeline so server deploys to
.vscode/mcp.json, .cursor/mcp.json, etc.
- Thin alias on
apm mcp install
- Help text + error wording (cli-logging-expert + devx-ux-expert)
- Unit tests, integration tests, negative tests
- Reference doc update:
docs/src/content/docs/reference/cli-commands.md
- CHANGELOG entry
Workstream: Sequential after validation warn ([link-to-w4-issue]); blocks docs consolidation ([link-to-w2-issue]) Quick Start which references the new CLI.
Context: Surfaced via #122 and the followup conversation with @lirantal -- there is no CLI path to add an MCP server today; users must hand-edit
apm.yml.apm mcptoday is read-only (list/search/show).Proposed change
Extend
apm install(the canonical add-and-deploy verb, mirroringnpm install) with an explicit--mcpflag for MCP server entries. Reuses the already-existing--only [apm|mcp]vocabulary on the same command.Discoverability bridge: thin alias
apm mcp install <args>delegates toapm install --mcp <args>for users arriving viaapm mcp --help. Pure delegation, no code duplication.Why
--mcpflag instead of auto-detection of positional shapeAuto-detecting "is this an MCP registry name?" by string pattern is fragile and surprising -- a typo'd APM package name could silently land as an MCP entry. Explicit flag keeps the contract unambiguous.
Security-correctness by construction
After
--,argv[0]becomescommand(string), rest becomesargs(list). Noshell=True, no whitespace-splitting. Same boundary that closes the validation gap in [link-to-w4-issue].Defaults logic
transport: stdiowhen--is presenttransport: httpwhen--urlis presenttransportfrom--transportif explicitly set (overrides above)registry: falsewhen--or--urlis usedregistry: truewhen only a registry name is given (no--, no--url)Scope
apm install:--mcp,--transport,--url,--env(repeatable)--boundarydependencies.mcpentries (idempotency, name collision warn).vscode/mcp.json,.cursor/mcp.json, etc.apm mcp installdocs/src/content/docs/reference/cli-commands.mdWorkstream: Sequential after validation warn ([link-to-w4-issue]); blocks docs consolidation ([link-to-w2-issue]) Quick Start which references the new CLI.