Extend MCP v0.1 runtimeArguments.variables handling to all client adapters (P3 follow-up to #1444)

[danielmeppiel]

Follow-up to #1444 (P3 -- vendor neutral by construction)

#1444 fixed VS Code's MCP client adapter to honor v0.1 runtimeArguments with variables-shaped entries (Docker mount/-w args). The same v0.1 schema is consumed by every MCP client adapter -- copilot, codex, gemini, cursor, claude -- so Docker MCP servers from registry manifests using the v0.1 shape currently emit broken [run, -i, --rm, image] invocations on every non-VS Code target.

Per PRINCIPLES.md P3 (vendor neutral by construction), registry-schema parsing on the neutral surface (MCP client adapters) must be uniform across adapters. Shipping #1444 in isolation creates vendor-uneven behavior on a neutral surface.

Scope

• Audit src/apm_cli/adapters/client/{copilot,codex,gemini,cursor,claude}.py for the equivalent of _extract_package_args (or its analog) and confirm whether they handle v0.1 variables-shaped runtimeArguments.
• Extract the v0.1 variables-handling logic from vscode.py into a shared helper (e.g. adapters/client/_mcp_v01_args.py or _runtime_args.py).
• Apply the helper across all 5 adapters with one regression test per adapter (4-arg v0.1 docker package fixture).
• Confirm mutation-break: delete the helper call from any one adapter, confirm that adapter's test fails.

Origin

Surfaced by the batch-bug-shepherd Phase 1.5 strategic-alignment gate (apm-ceo persona) during retroactive review of #1444:

The fix correctly handles MCP registry v0.1 runtimeArguments.variables shape and lands a strong regression-trap suite, but it patches only VSCodeClientAdapter._extract_package_args. The same v0.1 schema is consumed by every MCP client adapter (copilot, codex, gemini, cursor, claude), so per P3 (vendor neutral by construction) the registry-shape fix should be hoisted to a shared helper or applied across all adapters in the same PR -- otherwise Docker MCP servers remain broken on every non-VS Code target and APM ships uneven per-vendor behavior on a neutral surface (registry parsing).

cc @sergio-sisternes-epam (original reporter of #1391)

[github-actions]

Triage decision

accept

Proposed labels

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

Milestone

0.14.0

Suggested next action

Extract the v0.1 runtimeArguments.variables handling from vscode.py into adapters/client/_mcp_v01_args.py and apply the shared helper across all five non-VS Code adapters (copilot, codex, gemini, cursor, claude), with one regression test per adapter and a mutation-break gate.

Suggested issue comment

This is a well-scoped follow-up and the right call per PRINCIPLES.md P3 (vendor neutral by construction). The v0.1 `runtimeArguments.variables` shape is a registry-level contract, so parsing it correctly must be uniform across all MCP client adapters -- not just VS Code.

The proposed implementation path is sound:

1. Extract the variables-handling logic from `vscode.py`'s `_extract_package_args` into a shared helper (e.g. `adapters/client/_mcp_v01_args.py`).
2. Import and apply the helper in `copilot.py`, `codex.py`, `gemini.py`, `cursor.py`, and `claude.py`.
3. Add one regression test per adapter using a 4-arg v0.1 Docker package fixture.
4. Confirm the mutation-break gate: removing the helper call from any one adapter must cause that adapter's test to fail.

This is targeted for `0.14.0`. If you would like to pick this up, feel free to open a draft PR and reference this issue -- happy to review.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This directly affects users running Docker MCP servers via any non-VS Code MCP client (copilot, codex, gemini, cursor, claude). Broken [run, -i, --rm, image] invocations mean the MCP server never starts. Scope is clear, user impact is high across 5 of 6 adapters, and the fix aligns with the user expectation that apm run works the same regardless of which editor they use. Vendor-neutral behavior on the install/run path is a core APM promise.

Supply Chain Security Expert -- Risk-Surface Reviewer

The adapter layer parses runtimeArguments from registry manifests to assemble Docker invocations. Correct argument assembly matters for container safety -- malformed or incomplete args could allow argument injection into Docker command lines. The vscode.py fix sets the right defensive pattern; applying it uniformly across all adapters reduces the per-adapter attack surface. No new trust boundary is crossed by this change. area/mcp-config is the correct area; theme/portability is correct.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- Author is a COLLABORATOR with established project history; tone-tuning for new contributors is not needed.

Python Architect -- Architecture Reviewer

Activated. The proposal to extract the v0.1 variables-handling logic from vscode.py into adapters/client/_mcp_v01_args.py is the correct architectural move. Adapters are already relatively isolated; the cross-cutting risk is low. The scope is well-defined (5 adapter files + 1 shared helper + 5 regression tests + mutation-break gate). The design is already settled by the vscode.py implementation -- this is application of a known pattern, not a design problem. Accept as proposed; status/needs-design is not warranted.

Doc Writer -- Documentation Reviewer

Not activated -- This is a bug fix in internal adapter code. No new CLI surface or configuration options are introduced, so no user-facing documentation changes are required.

APM CEO -- Triage Arbiter

Accept. Issue #1452 is a clear, well-scoped follow-up to #1444, grounded in PRINCIPLES.md P3 (vendor neutral by construction). The existing labels (theme/portability, area/mcp-config, type/bug) are correct and need no revision. Adding status/accepted, priority/high (5 of 6 adapters broken for Docker MCP servers is broad impact), and assigning to milestone 0.14.0 (patch-appropriate bug fix). The Python Architect confirms the shared helper design is sound and implementation-ready -- no design iteration needed before code can land.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/mcp-config"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.14.0",
  "next_action": "Extract the v0.1 runtimeArguments.variables handling from vscode.py into adapters/client/_mcp_v01_args.py and apply it across all five non-VS Code adapters with one regression test per adapter and a mutation-break gate.",
  "comment_markdown": "This is a well-scoped follow-up and the right call per PRINCIPLES.md P3. Extract the variables-handling logic from vscode.py into a shared helper, apply it across copilot, codex, gemini, cursor, and claude adapters, add one regression test per adapter, and confirm the mutation-break gate."
}

---

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.

Note

🔒 Integrity filter blocked 21 items

The following items were blocked because they don't meet the GitHub integrity level.

• #1120 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1122 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1130 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1138 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1156 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1157 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1209 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1225 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1231 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1273 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1295 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1300 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1326 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1341 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1342 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #1343 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 5 more items

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel · ● 1.2M · ◷