Repository navigation
fix(docker): pick a git-capable isolation image, and classify container-toolchain failures - #1156
Conversation
…er-toolchain failures (#1143, #1144) Docker isolation was unusable for the large share of MCP servers that ship only as a git URL, and the resulting failure told the user to file a bug. #1143 — the Python default image is Astral's slim uv image, which has no git: $ docker run --rm --entrypoint sh ghcr.io/astral-sh/uv:python3.13-bookworm-slim -c 'git --version' sh: 1: git: not found so `uvx --from pkg@git+https://…` died at resolve time. Raising the global default would cost every user a ~1.5GB pull for a case many never hit, so the substitution is per-server: when a Python package runner's args reference a `git+` URL and the server pins no `isolation.image`, resolution uses the new `default_images.uvx-git` key (built-in `ghcr.io/astral-sh/uv:python3.13-bookworm`, verified to ship git 2.39.5). Operators can retarget the key; an explicit per-server override still wins; node's default (node:22) already has git and is untouched. Configs written before the key existed are not re-seeded on load, so the built-in value is also the hard fallback. ResolveDefaults reuses the same resolution, so the REST/tray placeholder shows the image that will really run. #1144 — container stderr is a different failure surface from mcpproxy's own errors: anything the image lacks landed in MCPX_UNKNOWN_UNCLASSIFIED, whose catalog entry asks the user to file a bug report. Adds MCPX_DOCKER_MISSING_TOOLCHAIN, matched under the Docker-isolation hint for uv's "Git executable not found" / "Git operation failed" wordings and the shell `<tool>: not found` shape, ordered so the existing #696 CLI-missing and OCI entrypoint codes keep winning their cases. "Git operation failed" with an auth/DNS cause is excluded — that clone failed with git present. The runtime-aware remediation says whether the automatic image selection already covers the failure, and names a per-server override as the opt-out when one is set.
…nd let the operator's image map win (#1143, #1144) Follow-up to fc61a26 after a three-lens adversarial review. Five findings were real; one was not. Classifier (#1144): - `shellToolNotFoundRe` matched a bare `<word>: not found` ANYWHERE in the error, and classifyDockerIsolatedSpawn runs before every generic stdio arm — so one line in the captured stderr tail claimed the whole failure. A server that died on its own config (`ERROR config profile production: not found`) was diagnosed as a missing container toolchain and sent to a docs page telling it to change images. The regex is now anchored on the shell prefix such a line always carries (`sh: 1:`, `/bin/sh: 1: exec:`, `bash: line 1:`). Being anchored, it is also specific enough to move above the ENTRYPOINT-missing arm, so the bash and dash wordings of one failure finally agree. - A handshake TIMEOUT means the container is still running; a shell line written minutes earlier did not kill it. Toolchain attribution no longer overrides MCPX_STDIO_HANDSHAKE_TIMEOUT. - `uv` collapses every clone failure into "Git operation failed", so the exclusion list is the only thing keeping a private-repo failure out of the missing-git diagnosis, and it covered three wordings. GitHub's password-authentication removal notice, 401/403, host-key verification, connection refused, name-resolution failure, `server certificate verification failed` and `repository '<url>' not found` all landed on "your image has no git". Broadened to the wordings a private repo actually produces; each one is text only git/ssh/curl can emit, which is itself proof git ran. Image resolution (#1143): - resolveDefaultImage reached past the operator's `default_images` to a hardcoded ghcr.io URL whenever the `uvx-git` key was absent — an image a mirrored or air-gapped host cannot pull at all, while their own `uvx` entry sat right there. The map is authoritative now: key set wins, key set to `""` is the opt-out, absent falls back to the runtime's configured image, and the built-in is used only where the map has no answer at all (the alternative being the alpine fallback, which has neither git nor python). The premise for the old fallback — "configs written before the key existed are not re-seeded on load" — is false: a config file's `default_images` is decoded INTO the built-in map, so the built-in entry survives an upgrade. TestDefaultImagesMergeOverBuiltInsOnLoad pins that. - The "we swapped your image" log now tracks the substitution that actually happened rather than the server merely qualifying for one. - The REST/tray `isolation_defaults.image` placeholder built a throwaway ServerConfig with no Args, so the git substitution never fired and the placeholder showed the slim image while the container ran the git one. - hintsHaveGitDependency dropped the runtime-type half of config.NeedsGitCapableImage's gate, promising `node`/`go`/`ruby` users an automatic fix that never runs and naming a config key with no effect on them. Not a defect: the docs' retarget snippet does not cost a user their other runtime mappings — `default_images` merges over the built-in map rather than replacing it. Documented that explicitly, along with the `""` opt-out.
…top stderr noise hijacking codes (#1143, #1144) The git-capable image selection reached past the operator's own `default_images` on the path that matters. A config file's map is decoded INTO the built-in map, so `uvx-git` is populated in every install — the "key absent" fallback the previous fix relied on never runs, and an air-gapped or mirrored operator whose `uvx` entry points at their registry still resolved the hardcoded public ghcr.io image their host cannot pull. Presence cannot express intent after that merge, so the resolver now asks whose VALUE each entry holds (config.IsBuiltInDefaultImage): an operator's `uvx-git` wins outright; an emptied key still opts out; a shipped `uvx-git` next to a retargeted runtime image stands down to the operator's image and warns on spawn, naming the key that makes the choice explicit. The new test drives the real path — config file without `uvx-git` → LoadFromFile → merge → resolve — instead of hand-building the merged map. The MCPX_DOCKER_MISSING_TOOLCHAIN remediation mirrors the same rule so it stops claiming a substitution that did not happen. Classifier, same theme — a guard applied to one arm and not its siblings: - the handshake-timeout suppression now covers arm (4) as well as (2)/(3), and the timeout arm moves above the spawn arms in classifyStdio, so a benign "no such file or directory" in the stderr tail of a container that is alive and silent no longer outranks MCPX_STDIO_HANDSHAKE_TIMEOUT; - a shell reporting a BUILTIN missing (`/bin/sh: 1: source: not found`) is a bashism under dash, not a missing image toolchain: it no longer hijacks MCPX_DOCKER_MISSING_TOOLCHAIN / MCPX_DOCKER_EXEC_NOT_FOUND, restoring MCPX_STDIO_EXIT_BEFORE_INITIALIZE. A real missing tool alongside it still classifies; - `Permission denied (publickey)` is git SSH auth, not a file mode on the server's executable: it lands with the other thirteen git-clone failure wordings on MCPX_STDIO_EXIT_BEFORE_INITIALIZE instead of MCPX_STDIO_SPAWN_EACCES.
…ot the word "docker" (#1144) mcpproxy's own stdio wrapper formats every Docker-isolated failure as stdio transport (command="/usr/local/bin/docker", docker_isolation=true): %w so the literal substring "docker" is present in ALL of them. The `permission denied && docker` arm therefore fired on any "permission denied" anywhere in the captured container stderr: a git deploy key rejected by GitHub came back as MCPX_DOCKER_NO_PERMISSION, telling the user to fix Docker socket permissions that were never broken — the exact class of misleading diagnosis #1144 exists to remove. The arm was effectively unfalsifiable under isolation. - Gate the permission and image-pull arms on dockerDaemonEvidence: text only the docker CLI, the daemon or a socket dial can produce (docker daemon / docker.sock / pipe/docker_engine / dockerd / error response from daemon), none of which the wrapper injects. - Share those arms as dockerLayerCode between classifyDocker and the docker-isolated spawn path, and consult it there BEFORE any stderr-tail arm. A REAL socket refusal previously fell through to the generic stdio "permission denied" arm and returned MCPX_STDIO_SPAWN_EACCES (chmod advice for a server binary that is fine); a daemon-down or pull-denied returned MCPX_STDIO_EXIT_BEFORE_INITIALIZE. - Accept DockerIsolated on its own as implying the stdio rules. ResolveIsolation only reports mode=docker for a server that has a Command, so isolation is always stdio; without this a caller that filled only the isolation hint skipped every stdio arm and left mcpproxy's own wrappers on MCPX_UNKNOWN_UNCLASSIFIED and its "file a bug report" CTA, with the loose docker arms as the only thing that could fire. Tests use the REAL wrapped message shape (command=…docker, docker_isolation=true prefix) under both hint shapes; the previous round's probes omitted the prefix, which is why the misfire survived.
…r daemon is down A handshake timeout means the container is alive and merely silent, so docker-daemon wording in its stderr tail is the server's own log line, not evidence that our docker layer failed. A real daemon refusal never produces a handshake timeout — no container would exist to time out — so gating the layer arm on the same toolchainSuppressed guard the stderr-tail arms use costs nothing and stops MCPX_DOCKER_DAEMON_DOWN sending users to restart Docker over an application message.
Deploying mcpproxy-docs with
|
| Latest commit: |
891e892
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://43a12814.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://fix-1143-1144-docker-image-d.mcpproxy-docs.pages.dev |
Correction: the air-gap claim in the PR description is not yet trueAn independent The description says an operator's mirrored/air-gapped configuration wins. That holds only if they set const DefaultGitCapableImage = "ghcr.io/astral-sh/uv:python3.13-bookworm" // fully qualifiedand Second High: the arm-exemption pattern again.
The standing rationale for exempting these arms — "it means no container ever started" — is exactly as false for them as it was for the daemon arm that round 4 fixed: if the handshake timed out, a container is alive. Three Mediums also stand: benign exit stderr stealing Do not merge this PR until the follow-up lands. I will update the description once the claims in it are true. |
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 33493222691 --repo smart-mcp-proxy/mcpproxy-go
|
|
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
…ror own the git image
Five defects from a cross-model review of this branch, all of the same two
shapes: a diagnosis read out of the captured stderr TAIL outranking a fact
mcpproxy knows for certain, and operator intent inferred from a value that
cannot express it.
Classifier (internal/diagnostics):
- The handshake-timeout guard now covers EVERY arm of
classifyDockerIsolatedSpawn that reads the stderr tail, not the two a
previous round happened to fix. A timeout means the container is ALIVE, so
"docker: command not found", "OCI runtime …", "exec format error" and "runc"
in its stderr are the container's own log lines, not our docker layer
failing. Only two things stay exempt, and the comment says which and why:
the typed *exec.Error (the host's own failed execve of docker) and
mcpproxy's own "docker not found in PATH / login shell" wording. The same
guard is applied to classifyDocker, the sibling path a hint-less caller
reaches, and the STDIO_HANDSHAKE_TIMEOUT arm now leads its switch instead of
sitting below another tail-reading arm.
- On the EXIT path, the spawn-class codes (ENOENT / EACCES / ENOEXEC) are
suppressed when mcpproxy's own premature-exit wrapper is present: that
wrapper is written only when the transport closed, i.e. the child ran, so a
"we never started it" code is provably wrong. "no such file or directory"
now also requires exec/OCI context in the container arm — on its own it is
an ordinary line about an optional file, and it was turning an unrelated
cache warning into MCPX_DOCKER_EXEC_NOT_FOUND ahead of the real fatal error.
- "Git operation failed" no longer DEFAULTS to a missing git binary unless an
exclusion list says otherwise. The claim now needs positive evidence: a
wording naming the missing binary, or uv reporting the failure with no
diagnostic of git's own beneath it. Anything git/ssh/curl themselves printed
proves git ran. The old list could never be complete, so wordings it missed
("could not read from remote repository", an HTTP 429, a redirect) told the
user to rebuild their image over a failure that proves the opposite.
Git-capable image (internal/config, internal/upstream/core):
- An operator who set only `docker_isolation.registry` still pulled public
ghcr.io: the built-in image is fully qualified and buildFullImageName returns
a qualified reference unchanged. The built-in image is now split into
registry + repo and qualified with the configured registry ("" and the
shipped "docker.io" both mean "the public default", and the image is not on
Docker Hub).
- `uvx-git` is no longer seeded into the shipped `default_images`. SaveConfig
writes the whole merged map back into the operator's file, so a seeded key's
presence says nothing and value equality was the only signal left — which
cannot express "I explicitly chose the image mcpproxy ships". With the key
unseeded, its presence means exactly one thing, so an operator mirroring
`uvx` who deliberately points `uvx-git` at the public image now gets it
instead of their git-less mirror. The remediation text follows the same rule.
Docs updated for the new contract.
The key has never shipped in a release, so no existing install has it seeded;
a config written by an earlier build of this branch reads as an explicit
choice, which is what its value asks for.
…guard isStdioHandshakeTimeout ORed in the loose "handshake timeout" substring, which is unbounded child stderr: Go's own net/http TLS error carries it, so a docker image pull over TLS printed it verbatim. On the exit path that let the tail both suppress every docker arm and win the leading arm of classifyStdio, turning a real pull or exec failure into "raise your timeout". mcpproxy never writes both of its wrappers, so the premature-exit wrapper co-occurring with the loose substring is proof the text came from the tail, not from us. Keyed on that.
…anence gate main extracted classifier-hint building into internal/diagnostics/hints, which already covers the Docker enrichment this branch was adding inline — so the conflict resolves to main's hints.For call, with DockerArgs added there because the #1143 git-dependency remediation reads it. #1155's TestParkableCode_ChildStderrNeverProvesPermanence pinned the OLD classifications to isolate its permanence gate; this branch fixes those classifications, so the expected codes move. The gate's invariant is unchanged and still asserted: two stderr-only rows that still reach a PERMANENT code are added so it is never left untested.
Resolved — the do-not-merge hold is liftedAll five opencode findings are fixed, plus two more the follow-up review found. Verified by running the real code with the realistic wrapper shape:
The air-gap claim in the description is now true. Two structural changes rather than more arm-patching:
Merge-conflict resolution worth a lookmain's #1155's |
Fixes #1143. Fixes #1144.
#1143 — the default uvx image cannot install most MCP servers
default_imagesmappeduvx/python/pip/pipxtoghcr.io/astral-sh/uv:python3.13-bookworm-slim, which has no git. A large share of MCP servers ship only as a git URL with no PyPI release, so under Docker isolation they could never install:GetDockerImagenow resolves a git-capable image when a server's args carrygit+and no per-serverisolation.imageoverride is set, via a nameddefault_images["uvx-git"]key operators can retarget. The global default stays slim — nobody pays ~700MB for a case they don't hit.An operator's own image map wins. Review caught that the first attempt hardcoded a public
ghcr.ioURL that beat a mirrored/air-gapped operator's configureddefault_images.uvx, because the load-time merge seeds the key in every install so the "key absent" fallback never ran. Resolution now decides on values, not key presence: the operator'suvx-gitwins outright; an explicitly-empty key opts out; a still-shipped built-in next to a retargeted runtime image stands down to the operator's image and logs a Warn naming the key to set. Pinned by a test that models the real load path — config file →LoadFromFile→ merge → resolve — rather than hand-building the merged map.#1144 — the resulting error told users to file a bug
The failure above classified as
MCPX_UNKNOWN_UNCLASSIFIED, whose message is "Please file a bug report so we can add a specific code." — for a one-line config problem. NewMCPX_DOCKER_MISSING_TOOLCHAINcovers container-toolchain failures, with a docs page following the existingMCPX_DOCKER_EXEC_NOT_FOUNDpattern.The hard part: not hijacking correct diagnoses
Container stderr is attacker-adjacent free text, and four separate review rounds found the new arms stealing classifications they shouldn't. Final behaviour, probed with the realistic wrapper shape mcpproxy actually produces (
command="/usr/local/bin/docker", docker_isolation=true):Git executable not found(the real failure)MCPX_DOCKER_MISSING_TOOLCHAINgit@github.com: Permission denied (publickey)MCPX_STDIO_EXIT_BEFORE_INITIALIZECannot connect to the Docker daemon(on exit)MCPX_DOCKER_DAEMON_DOWNMCPX_STDIO_HANDSHAKE_TIMEOUT/bin/sh: 1: source: not foundMCPX_STDIO_EXIT_BEFORE_INITIALIZEdocker: permission denied … daemon socketMCPX_DOCKER_NO_PERMISSIONThree of these were bugs found during review, each the same shape — a guard applied to one arm but not its sibling:
classifyDocker's arm iscontains("permission denied") && contains("docker"), and mcpproxy's own error wrapper injects the docker command into the string — so under isolation that arm was near-unfalsifiable and swallowed any permission-denied text from child stderr.source: not found) read as a missing image toolchain, sending users to rebuild an image over a#!/bin/shline. Now requires that every missing name be a non-builtin.DAEMON_DOWN. A handshake timeout means the container is alive, so a layer failure cannot also be true — the wording came from the server's own log. A genuine daemon refusal is unaffected: it surfaces on the exit path.Verification
Four fix→re-review rounds (3-lens adversarial). The final round's "clean" verdict was wrong — its probes omitted the wrapper prefix, which is exactly how the git-auth misdiagnosis survived. Caught by hand-probing with the realistic shape; tests now pin that shape so it can't recur.
Gates:
go build ./...,-tags server,go test ./internal/... -race, golangci-lint v2 → 0 issues.