Add 'apm config' surface for persistent MCP registry URL (item 4b from #810)

[danielmeppiel]

Background

PR #810 ships apm install --mcp NAME ... for declaratively adding MCP servers to apm.yml, with MCP_REGISTRY_URL as the env-var-based registry override. PR #810 is also adding apm install --mcp --registry <url> (item 4a from the same review) for one-shot installs against a non-default registry.

This issue tracks the third (and final) layer of the precedence chain: persistent, cross-platform configuration.

Problem

Env vars are awkward on Windows (no .bashrc-style equivalent for terminal profiles; setting them per-shell is cumbersome). Enterprise teams that consistently use a private MCP registry need a way to set this once, persistently, in a way apm itself manages.

Proposed solution

Add apm config set mcp-registry-url <url> (and apm config get / apm config unset).

Final precedence chain (after this issue lands)

1. apm install --mcp --registry <url> (CLI flag — already in PR feat(install): add --mcp flag for declaratively adding MCP servers to apm.yml #810)
2. MCP_REGISTRY_URL env var (already shipped)
3. apm config get mcp-registry-url (this issue)
4. Default: https://api.mcp.github.com

The first non-empty / non-null value wins.

Design surface to resolve

• Config namespace: does apm config already exist? If not, this issue includes designing the surface (storage location, file format, scoping — global vs project). If it exists, just add the new key.
• Storage location: ~/.config/apm/config.yaml (XDG) on Linux/macOS, %APPDATA%/apm/config.yaml on Windows.
• Schema: Single key mcp.registry-url (or mcp_registry_url) — needs decision, with room to grow (other mcp.* keys later).
• Validation on set: same URL allowlist as --mcp --registry (http/https only; reject file://, ws://, etc.). Reuse _ALLOWED_URL_SCHEMES from models/dependency/mcp.py.
• Display: apm config get mcp-registry-url prints the value or "(unset)" — never crashes.
• Diagnostic: when an apm install --mcp or apm mcp search resolves the registry from this layer (not env, not flag), emit a single-line diagnostic naming the source: Registry: https://corp.mcp.example.com (from apm config). Mirrors the existing env-var diagnostic.

Acceptance criteria

• apm config set mcp-registry-url https://corp.mcp.example.com writes to user config
• apm config get mcp-registry-url returns the stored value
• apm config unset mcp-registry-url removes it
• Invalid URL schemes (file://, ws://, javascript:) rejected at set time
• apm install --mcp NAME (no --registry, no env) uses the configured value
• CLI --registry flag overrides config; env var overrides config; config overrides default
• One-line diagnostic when the config-layer URL is in effect
• Documented in docs/src/content/docs/guides/mcp-servers.md with the full precedence chain
• CHANGELOG entry under Added with the issue + PR number suffix

Out of scope

• Project-scoped (vs user-scoped) config — single user-level value is enough for v1.
• Migration tooling for existing MCP_REGISTRY_URL users — env keeps working at higher precedence; no migration needed.
• Auth/credentials per registry — separate concern, file separately if needed.

Panel context

This issue was distilled from a multi-expert review (supply-chain security, devx-ux, cli-logging, python-architecture) of PR #810. When this is implemented, invoke the APM Review Panel skill (.github/skills/apm-review-panel/).

References

• PR feat(install): add --mcp flag for declaratively adding MCP servers to apm.yml #810 (introduces --mcp and --registry flag + MCP_REGISTRY_URL env var)
• Original review: feat(install): add --mcp flag for declaratively adding MCP servers to apm.yml #810 (comment) (item 4)

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/mcp-config
area/cli
area/docs-site
type/feature
status/accepted
priority/low

Milestone

0.9.4

Suggested next action

Implement apm config set/get/unset mcp-registry-url with XDG-compliant storage and URL-scheme validation reusing _ALLOWED_URL_SCHEMES, wiring it as the third layer in the MCP registry precedence chain.

Suggested issue comment

Thanks for filing this -- it completes the MCP registry precedence chain introduced in PR #810.

The `apm config set mcp-registry-url` surface is accepted. The design is clear: user-level persistent config at `~/.config/apm/config.yaml` (XDG on Linux/macOS, `%APPDATA%/apm/config.yaml` on Windows), with URL-scheme validation reusing `_ALLOWED_URL_SCHEMES` from `models/dependency/mcp.py`, wired as the third layer below the `--registry` flag and `MCP_REGISTRY_URL` env var.

A few notes for the implementing PR:
- Use a keyed config structure (e.g., `mcp.registry-url`) so future `mcp.*` keys can be added without a schema migration.
- Emit the single-line diagnostic ("Registry: (redacted) (from apm config)") from the same location as the existing env-var diagnostic for consistency.
- Update `docs/src/content/docs/guides/mcp-servers.md` with the full four-level precedence chain.
- Invoke the APM Review Panel skill (`.github/skills/apm-review-panel/`) when the PR is open, as noted in the issue.

CHANGELOG entry under `Added`.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps to a real cross-platform usability gap: enterprise users on Windows cannot easily set a persistent MCP registry override without shell profile editing. The apm config set/get/unset surface follows the standard package manager config pattern (npm .npmrc, pip pip.ini, cargo config.toml). The proposed precedence chain (CLI flag > env > config > default) is idiomatic and correct. The issue is well-scoped with concrete acceptance criteria and a clear out-of-scope boundary for v1.

Supply Chain Security Expert -- Risk-Surface Reviewer

A persistent config file at ~/.config/apm/config.yaml introduces a new trust surface: another process could redirect APM to a malicious registry. However, the issue already specifies URL-scheme validation reusing _ALLOWED_URL_SCHEMES (http/https only), which is the same mitigation that applies to the --registry flag and MCP_REGISTRY_URL env var. The trust model is equivalent to npm config set registry -- acceptable. No theme/security label needed; the primary theme is portability (cross-platform enterprise config).

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a core collaborator (COLLABORATOR association) with extensive repo history; no tone-tuning adjustment needed for this internally-filed, well-specified issue.

Python Architect -- Architecture Reviewer

The implementation requires: (1) a new apm config command surface (command group or subcommands), (2) a new config-storage layer with OS-conditional paths, and (3) threading the resolved value through the MCP registry URL resolution chain. A keyed data model (not flat) is essential for future extensibility. The acceptance criteria are concrete enough to proceed without a separate design doc -- status/accepted is appropriate. The implementing PR should engage the APM Review Panel skill as stated in the issue.

Doc Writer -- Documentation Reviewer

Docs work is explicit in the acceptance criteria: docs/src/content/docs/guides/mcp-servers.md must be updated with the full four-level precedence chain. area/docs-site rides as a secondary area. The suggested comment wording is clear and grounded in user vocabulary from the README and MCP guide.

APM CEO -- Triage Arbiter

Accepted. This issue completes planned work from the PR #810 review and fills a real enterprise usability gap on Windows. The design is clear, the acceptance criteria are concrete, and the URL-scheme mitigation is already specified. priority/low is appropriate -- env vars cover the use case today; this is an ergonomic improvement for cross-platform teams. Milestone 0.9.4.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/mcp-config", "area/cli", "area/docs-site"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Implement apm config set/get/unset mcp-registry-url with XDG-compliant storage and URL-scheme validation, wiring it as the third layer in the MCP registry precedence chain.",
  "comment_markdown": "Thanks for filing this -- it completes the MCP registry precedence chain introduced in PR #810.\n\nThe `apm config set mcp-registry-url` surface is accepted. The design is clear: user-level persistent config at `~/.config/apm/config.yaml` (XDG on Linux/macOS, `%APPDATA%/apm/config.yaml` on Windows), with URL-scheme validation reusing `_ALLOWED_URL_SCHEMES` from `models/dependency/mcp.py`, wired as the third layer below the `--registry` flag and `MCP_REGISTRY_URL` env var.\n\nA few notes for the implementing PR:\n- Use a keyed config structure (e.g., `mcp.registry-url`) so future `mcp.*` keys can be added without a schema migration.\n- Emit the single-line diagnostic from the same location as the existing env-var diagnostic for consistency.\n- Update `docs/src/content/docs/guides/mcp-servers.md` with the full four-level precedence chain.\n- Invoke the APM Review Panel skill when the PR is open, as noted in the issue.\n\nCHANGELOG entry under `Added`."
}

---

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.2M · ◷