Skip to content

fix(adapters): prepend docker run for options-only OCI packages (#3404) - #3405

Merged
Daniel Meppiel (danielmeppiel) merged 8 commits into
microsoft:mainfrom
abhishekacharya200:fix-oci-options-only-docker-launcher
Nov 11, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 8 commits into
microsoft:mainfrom
abhishekacharya200:fix-oci-options-only-docker-launcher

Conversation

@abhishekacharya200

@abhishekacharya200 Abhishek Acharya (abhishekacharya200) commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Closes #3404

Description

When an OCI package in the MCP registry specifies runtimeArguments containing Docker options without an explicit run positional argument (as shown in the MCP Registry OCI reference example), generated MCP launchers in Codex, Copilot, and Gemini omitted the run subcommand, emitting commands such as docker --network none IMAGE ... (which Docker rejects with unknown flag: --network). In VS Code, _docker_run_args declined the options-only argument list, producing an empty configuration {} with a missing option warning.

Solution

  • Added MCPClientAdapter._ensure_docker_run_args to apm_cli.adapters.client.base. If runtime_args does not lead with run (e.g. options-only metadata), it prepends run and ensures stdio flags (-i and --rm) are present without duplicating flags that may already exist. Explicit run invocations and empty argument sets are preserved as before.
  • Updated CodexClientAdapter, CopilotClientAdapter, and GeminiClientAdapter to normalize Docker runtime arguments using _ensure_docker_run_args before injecting environment variables and appending image operands.
  • Updated VSCodeClientAdapter._docker_run_args to apply _ensure_docker_run_args for OCI container packages when options are present, preventing unexpected declines and warnings.
  • Added comprehensive unit tests in TestEnsureDockerRunArgs and an end-to-end regression test across all four adapters (test_options_only_runtime_arguments_prepends_docker_run_across_adapters) in tests/unit/adapters/test_oci_docker_launcher.py.

Verification

  • Tested with Python 3.13: all 45 tests in test_oci_docker_launcher.py pass (16 subtests).
  • Verified full suite of 197 adapter unit tests in tests/unit/adapters/ (excluding POSIX-only mode bit tests on Windows).
  • Passed ruff check and ruff format --check across all modified source and test files.

â€Ķ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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ðŸŸĄ 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 run and missing stdio flags while preserving leading-run arguments.
  • 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

Comment thread src/apm_cli/adapters/client/base.py Outdated
Comment on lines +1021 to +1022
if args and args[0] == "run":
return args

@abhishekacharya200 Abhishek Acharya (abhishekacharya200) Oct 28, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/apm_cli/adapters/client/vscode.py Outdated
Comment on lines +869 to +870
if "run" in run_options and run_options[0] != "run":
return None

@abhishekacharya200 Abhishek Acharya (abhishekacharya200) Oct 28, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/apm_cli/adapters/client/vscode.py Outdated
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":

@abhishekacharya200 Abhishek Acharya (abhishekacharya200) Oct 28, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@sergio-sisternes-epam

Copy link
Copy Markdown
Collaborator

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.

@sergio-sisternes-epam Sergio Sisternes (sergio-sisternes-epam) added area/cli CLI command surface, flags, help text (cross-cutting). status/deferred Not invited for implementation now; no release commitment. triage/recommended Automated advice completed; not human scope approval. type/bug Something does not work as documented. labels Nov 3, 2026
@danielmeppiel Daniel Meppiel (danielmeppiel) removed the status/deferred Not invited for implementation now; no release commitment. label Nov 10, 2026
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>
@danielmeppiel

Copy link
Copy Markdown
Collaborator

APM Review Panel: ship_now

Community fix centralizes Docker run-arg defaults for options-only OCI packages across all four adapters, closing a parity gap that left VS Code returning an empty config while the other three omitted the run verb.

panel-mode=lean; personas=python-architect,test-coverage-expert,apm-ceo

cc Abhishek Acharya (@abhishekacharya200) Daniel Meppiel (@danielmeppiel) Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

Both panelists converge. The python-architect confirms that moving three inline docker run -i --rm defaults into MCPClientAdapter._ensure_docker_run_args gives one owner without split authority. The test-coverage-expert asked for the approved scope's "Done when" checks to be pinned; that is now done: the reporter's raw server.json from #3404 goes through SimpleRegistryClient._normalize_v0_1_server for all four adapters, explicit run, explicit run -i --rm and empty runtimeArguments keep today's argv with no duplicated run/-i/--rm, and injected -e flags stay ahead of the image.

The change stays inside the approved apm-scope:v1 record on #3404. Abhishek Acharya (@abhishekacharya200) resolved all three Copilot inline items with tests before this pass. Thank you for the careful fix.

Aligned with: multi-harness parity (Codex, Copilot, Gemini and VS Code render the same argv), portable-by-manifest (the MCP Registry OCI example now works as published), community-driven (CHANGELOG credits the contributor).

Panel summary

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 run as values, not subcommands -- resolved by the author in af32188.
  • (copilot) Normalize OCI / oci registry 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_args docstring no longer says it declines when run is 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_launcher now requires a single _ensure_docker_run_args, delegation from every container adapter, and no inline or ["run", ...] default; covered by tests/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: authored container run was rewritten; fixed in af32188 with a cross-adapter test.
  • src/apm_cli/adapters/client/vscode.py -- LEGIT: --name run was read as a subcommand; fixed in af32188 with test_options_only_named_run_across_adapters.
  • src/apm_cli/adapters/client/vscode.py -- LEGIT: raw oci comparison 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's src/ 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_args call with the old inline default; both FAILED as expected; restored.
  • test_architecture_mcp_docker_run_args.py bypass 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: Commit TestIssue3404OptionsOnlyRuntimeArguments. 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>
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit 3eccb72 into microsoft:main Nov 11, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/cli CLI command surface, flags, help text (cross-cutting). triage/recommended Automated advice completed; not human scope approval. type/bug Something does not work as documented.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] OCI options-only runtimeArguments omit docker run in generated MCP launchers

4 participants