Repository navigation
fix(adapters): prepend docker run for options-only OCI packages (#3404) - #3405
Conversation
âĶosoft#3404) When an OCI package specifies runtimeArguments containing Docker options without an explicit 'run' subcommand, generated MCP launchers in Codex, Copilot, and Gemini omitted 'run', causing Docker to reject options as invalid flags, while VSCode declined target configuration. Add MCPClientAdapter._ensure_docker_run_args to prepend 'run' and ensure stdio flags ('-i' and '--rm') are present for options-only container packages while preserving explicit 'run' invocations. Update Codex, Copilot, Gemini, and VSCode client adapters to use this helper. Add unit and end-to-end regression tests covering options-only arguments across all four adapters.
There was a problem hiding this comment.
ðĄ Changes recommended
Docker argument handling still rejects valid option values, misses normalized OCI registry spellings, and rewrites complete invocations incorrectly, leaving valid configurations without working launchers.
3 open issues
What changed in this PR
This PR addresses #3404 by normalizing options-only OCI runtime arguments into Docker launch commands across the four MCP client adapters.
Changes:
- Adds a shared helper to prepend
runand missing stdio flags while preserving leading-runarguments. - Integrates normalization into Codex, Copilot, Gemini, and VS Code.
- Adds helper tests and a cross-adapter regression for options-only OCI metadata.
| File | Description |
|---|---|
| tests/âunit/âadapters/âtest_oci_docker_launcher.py | Tests argument normalization and launcher output across all four adapters. |
| src/âapm_cli/âadapters/âclient/âvscode.py | Normalizes OCI options-only arguments and adds argument guards. |
| src/âapm_cli/âadapters/âclient/âgemini.py | Uses the shared Docker argument helper. |
| src/âapm_cli/âadapters/âclient/âcopilot.py | Uses the shared Docker argument helper. |
| src/âapm_cli/âadapters/âclient/âcodex.py | Uses the shared Docker argument helper. |
| src/âapm_cli/âadapters/âclient/âbase.py | Defines shared run and stdio-flag normalization. |
Review effort: Balanced
| if args and args[0] == "run": | ||
| return args |
There was a problem hiding this comment.
Resolved in af32188. Added _is_options_only to ensure complete authored Docker invocations (such as ['container', 'run', '-i', '--rm']) are preserved as-is across all affected adapters (Codex, Copilot, Gemini) without prepending run. Added regression test test_authored_container_run_invocation_preserved_across_affected_adapters.
| if "run" in run_options and run_options[0] != "run": | ||
| return None |
There was a problem hiding this comment.
Resolved in af32188. Replaced substring checks with _is_options_only, which correctly distinguishes option values from command operands using Docker's run options specifications. Options with values (such as --name run) are recognized as option-value arguments rather than subcommands, enabling VS Code and other adapters to produce valid launchers. Added test coverage in test_options_only_named_run_across_adapters.
| package_args = package_args[image_index + 1 :] | ||
| elif not run_options and package_args: | ||
| run_options = ["run", "-i", "--rm"] | ||
| elif package.get("registry_name") == "oci": |
There was a problem hiding this comment.
Resolved in af32188. Replaced raw dictionary comparisons with canonical Docker classification via self._is_docker_package(package) and _is_options_only, so packages with registry_name='OCI', ' oci ', or legacy Docker metadata normalize options-only arguments consistently across all adapters. Updated test_vscode_v01_value_runtime_args.py and added test_registry_casing_and_whitespace_variants_across_adapters.
|
Thank you for contributing this pull request. The linked issue #3404 is open but has not been accepted by a maintainer. APM starts with an issue, not an implementation (https://github.com/microsoft/apm/blob/main/CONTRIBUTING.md). Please wait for a maintainer to review and accept the scope in #3404 before proceeding. This PR is labelled status/deferred until then. Generated by autopilot-pr-triage-worker. This comment is AI-generated and may contain errors. |
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
âĶadapters The approved scope for microsoft#3404 requires the reporter's raw server.json, through SimpleRegistryClient._normalize_v0_1_server, to render docker run -i --rm on all four adapters; explicit run, explicit run -i --rm and empty runtimeArguments to keep today's argv; and env -e flags to stay ahead of the image. Existing tests used post-normalization dicts only. Addresses panel test-coverage follow-up; fixture and env tests fail on main, parity test passes on main by design. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The docstring still said the assembler declines when the run verb is absent; options-only runtime arguments now gain run -i --rm, and only a non-run subcommand declines. Keeps the contract text truthful with the microsoft#3404 change. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
) Consumer docs and the apm-guide usage skill already promise run options before the image; state that options-only runtimeArguments gain run -i --rm, and record the user-visible fix in CHANGELOG under Unreleased/Fixed crediting the contributor. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The PR routes the docker run -i --rm default and options-only normalization from three inline adapter defaults into MCPClientAdapter._ensure_docker_run_args. Extend the existing mutation_writes.mcp_package_launcher rule so the helper stays single-defined, every container consumer delegates to it, and no inline 'or ["run", ...]' default returns; pin bypass and duplicate cases in a matching architecture test. Mutation-break: removing the new checks fails 5 of 6 cases; reverting the codex call fails both behavioral and architecture tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 0 | Clean centralization of docker run-arg normalization into the base adapter; no split authority. |
| Test Coverage Expert | 0 | 1 | 0 | Asked to pin the #3404 fixture, run-arg parity and env ordering; folded in c1c543c. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Recommendation
No open follow-ups after the fold. The coverage gap is closed (fixture and env subtests fail on main, pass on this head), the architecture guardrail is in place, docs and CHANGELOG are updated, and lint and CI are green. Ready for maintainer review.
Folded in this run
- (copilot) Preserve authored docker invocations such as
container run-- resolved by the author in af32188. - (copilot) Treat option values such as
--name runas values, not subcommands -- resolved by the author in af32188. - (copilot) Normalize
OCI/ociregistry spellings before Docker classification -- resolved by the author in af32188. - (panel) Pin the [BUG] OCI options-only runtimeArguments omit docker run in generated MCP launchers #3404 raw fixture on all four adapters, explicit run / run -i --rm / empty parity, and env flags before the image -- resolved in c1c543c.
- (panel) VS Code
_docker_run_argsdocstring no longer says it declines whenrunis missing -- resolved in eacf6ab. - (panel) CHANGELOG entry under Unreleased/Fixed plus one-clause updates to the consumer MCP guide and apm-guide skill -- resolved in b41ffc8.
- (panel) Owner guardrail:
mutation_writes.mcp_package_launchernow requires a single_ensure_docker_run_args, delegation from every container adapter, and no inlineor ["run", ...]default; covered bytests/integration/test_architecture_mcp_docker_run_args.py-- resolved in 1afbfe3.
Current main was merged in a4ee164 (clean merge).
Copilot signals reviewed
src/apm_cli/adapters/client/base.py-- LEGIT: authoredcontainer runwas rewritten; fixed in af32188 with a cross-adapter test.src/apm_cli/adapters/client/vscode.py-- LEGIT:--name runwas read as a subcommand; fixed in af32188 withtest_options_only_named_run_across_adapters.src/apm_cli/adapters/client/vscode.py-- LEGIT: rawocicomparison skipped normalization; fixed in af32188 with a casing test.
No new Copilot review on the updated head.
Regression-trap evidence (mutation-break gate)
TestIssue3404OptionsOnlyRuntimeArguments-- deleted the PR'ssrc/changes (main behavior); fixture and env tests FAILED (7 subtests) as expected; restored.- Codex behavioral subtests and
test_docker_run_args_owner_routes_are_intact-- replaced the codex_ensure_docker_run_argscall with the old inline default; both FAILED as expected; restored. test_architecture_mcp_docker_run_args.pybypass and duplicate cases -- deleted the new static checks; 5 of 6 FAILED as expected; restored.
Lint contract
ruff check and ruff format --check (src, tests, architecture linter) silent; pylint R0801 10.00/10; lint-auth-signals.sh clean; lint-architecture-boundaries.sh exit 0; owner-rule mutation matrix 560 passed.
CI
gh pr checks 3405: 48 pass, 6 skipped, 0 failing on 1afbfe3 (after 0 CI fix iterations). The earlier red marks were cancelled agentic advisory jobs, not test failures. CLA: signed.
Mergeability status
| PR | head SHA | CEO stance | iters | folds | defers | Copilot rounds | CI | mergeable | mergeStateStatus | notes |
|---|---|---|---|---|---|---|---|---|---|---|
| #3405 | 1afbfe3 |
ship_now | 1 | 7 | 0 | 2 | green | MERGEABLE | BLOCKED | pending required review |
Convergence
1 outer iteration; 2 Copilot rounds. Final panel stance: ship_now. Ready for maintainer review.
Full per-persona findings
Python Architect
No findings.
Test Coverage Expert
- [recommended] The scope's "Done when" checks (raw fixture through the normalizer, explicit run / empty parity, env-flag ordering) were not yet committed at review time, at
tests/unit/adapters/test_oci_docker_launcher.py
Without them, normalizer or env-injection drift would go unnoticed.
Suggested: CommitTestIssue3404OptionsOnlyRuntimeArguments. Done in c1c543c.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-merge-worker. This comment is AI-generated and may contain errors.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
3eccb72
into
microsoft:main

Closes #3404
Description
When an OCI package in the MCP registry specifies
runtimeArgumentscontaining Docker options without an explicitrunpositional argument (as shown in the MCP Registry OCI reference example), generated MCP launchers in Codex, Copilot, and Gemini omitted therunsubcommand, emitting commands such asdocker --network none IMAGE ...(which Docker rejects withunknown flag: --network). In VS Code,_docker_run_argsdeclined the options-only argument list, producing an empty configuration{}with a missing option warning.Solution
MCPClientAdapter._ensure_docker_run_argstoapm_cli.adapters.client.base. Ifruntime_argsdoes not lead withrun(e.g. options-only metadata), it prependsrunand ensures stdio flags (-iand--rm) are present without duplicating flags that may already exist. Explicitruninvocations and empty argument sets are preserved as before.CodexClientAdapter,CopilotClientAdapter, andGeminiClientAdapterto normalize Docker runtime arguments using_ensure_docker_run_argsbefore injecting environment variables and appending image operands.VSCodeClientAdapter._docker_run_argsto apply_ensure_docker_run_argsfor OCI container packages when options are present, preventing unexpected declines and warnings.TestEnsureDockerRunArgsand an end-to-end regression test across all four adapters (test_options_only_runtime_arguments_prepends_docker_run_across_adapters) intests/unit/adapters/test_oci_docker_launcher.py.Verification
test_oci_docker_launcher.pypass (16 subtests).tests/unit/adapters/(excluding POSIX-only mode bit tests on Windows).ruff checkandruff format --checkacross all modified source and test files.