feat(cli): extend 'apm install --mcp' for declarative MCP server addition

[danielmeppiel]

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

Discoverability 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 present
• transport: http when --url is present
• transport from --transport if explicitly set (overrides above)
• registry: false when -- or --url is used
• registry: 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.

[lirantal]

Love this one!