From fc61a26618b55469043c6699a69a019be1787240 Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Tue, 1 Sep 2026 05:59:08 +0300 Subject: [PATCH 1/7] fix(docker): pick a git-capable isolation image, and classify container-toolchain failures (#1143, #1144) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 `: 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. --- docs/configuration.md | 10 +- docs/docker-isolation.md | 46 +++- docs/errors/MCPX_DOCKER_EXEC_NOT_FOUND.md | 1 + docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md | 110 +++++++++ docs/errors/README.md | 1 + docs/features/docker-isolation.md | 46 +++- internal/config/config.go | 6 + internal/config/isolation_git.go | 60 +++++ internal/config/isolation_git_test.go | 62 +++++ internal/diagnostics/classifier.go | 63 ++++- .../classifier_container_toolchain_test.go | 219 ++++++++++++++++++ internal/diagnostics/codes.go | 9 + internal/diagnostics/registry.go | 11 + internal/diagnostics/remediation.go | 68 ++++++ .../diagnostics/remediation_gitkey_test.go | 18 ++ internal/diagnostics/types.go | 7 + .../isolation_classification_test.go | 33 +++ internal/runtime/supervisor/supervisor.go | 5 +- internal/upstream/core/isolation.go | 70 +++++- .../upstream/core/isolation_git_image_test.go | 168 ++++++++++++++ website/sidebars.js | 1 + 21 files changed, 977 insertions(+), 37 deletions(-) create mode 100644 docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md create mode 100644 internal/config/isolation_git.go create mode 100644 internal/config/isolation_git_test.go create mode 100644 internal/diagnostics/classifier_container_toolchain_test.go create mode 100644 internal/diagnostics/remediation_gitkey_test.go create mode 100644 internal/upstream/core/isolation_git_image_test.go diff --git a/docs/configuration.md b/docs/configuration.md index 5e5556a59..f14fd48fe 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -925,9 +925,11 @@ See [Logging Documentation](logging.md) for complete details. "docker_isolation": { "enabled": false, "default_images": { - "python": "python:3.11", - "node": "node:20", - "npx": "node:20" + "python": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "uvx-git": "ghcr.io/astral-sh/uv:python3.13-bookworm", + "node": "node:22", + "npx": "node:22" }, "registry": "docker.io", "network_mode": "bridge", @@ -945,7 +947,7 @@ See [Logging Documentation](logging.md) for complete details. | Field | Type | Default | Description | |-------|------|---------|-------------| | `enabled` | boolean | `false` | Enable Docker isolation globally | -| `default_images` | object | See below | Map of runtime type to Docker image | +| `default_images` | object | See below | Map of runtime type to Docker image. The `uvx-git` entry is used instead of the Python default when a Python package runner installs from a `git+` URL (the slim uv image has no git) | | `registry` | string | `"docker.io"` | Docker registry to use | | `network_mode` | string | `"bridge"` | Docker network mode | | `memory_limit` | string | `"512m"` | Memory limit for containers | diff --git a/docs/docker-isolation.md b/docs/docker-isolation.md index d1c495db0..b07dcd6b1 100644 --- a/docs/docker-isolation.md +++ b/docs/docker-isolation.md @@ -96,15 +96,16 @@ Add to your `~/.mcpproxy/mcp_config.json`: "network_mode": "bridge", "registry": "docker.io", "default_images": { - "python": "python:3.11", - "python3": "python:3.11", - "uvx": "python:3.11", - "pip": "python:3.11", - "pipx": "python:3.11", - "node": "node:20", - "npm": "node:20", - "npx": "node:20", - "yarn": "node:20", + "python": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "python3": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "pip": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "pipx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "uvx-git": "ghcr.io/astral-sh/uv:python3.13-bookworm", + "node": "node:22", + "npm": "node:22", + "npx": "node:22", + "yarn": "node:22", "go": "golang:1.21-alpine", "cargo": "rust:1.75-slim", "rustc": "rust:1.75-slim", @@ -131,9 +132,34 @@ Add to your `~/.mcpproxy/mcp_config.json`: | `timeout` | Container startup timeout | `"30s"` | | `network_mode` | Docker network mode | `"bridge"` | | `registry` | Docker registry to use | `"docker.io"` | -| `default_images` | Runtime to image mappings | See above | +| `default_images` | Runtime to image mappings (including `uvx-git`, used when a Python runner installs from a `git+` URL) | See above | | `extra_args` | Additional docker run arguments | `[]` | +### Git dependencies (`uvx-git`) + +The Python default image is Astral's **slim** `uv` image, which does not contain +`git`. A server installed straight from a repository — + +```json +{ "name": "my-server", "command": "uvx", "args": ["--from", "my-server@git+https://github.com/o/r", "my-server"] } +``` + +— cannot resolve without it, and fails with `Git executable not found` / +`Git operation failed` ([`MCPX_DOCKER_MISSING_TOOLCHAIN`](errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md)). + +MCPProxy detects the `git+` URL in a Python package runner's arguments and uses +the **`uvx-git`** image (`ghcr.io/astral-sh/uv:python3.13-bookworm`, which ships +git) for that server only — everyone else keeps the small slim image. Retarget +the key to use your own mirror or a custom build: + +```json +{ "docker_isolation": { "default_images": { "uvx-git": "my-registry.example/uv-git:1" } } } +``` + +A per-server `isolation.image` override always wins over this selection, so a +pinned image must ship git itself. `node`/`npx` need no equivalent: `node:22` +already includes git. + ### Per-Server Configuration You can override isolation settings per server: diff --git a/docs/errors/MCPX_DOCKER_EXEC_NOT_FOUND.md b/docs/errors/MCPX_DOCKER_EXEC_NOT_FOUND.md index bd3498161..49852cff5 100644 --- a/docs/errors/MCPX_DOCKER_EXEC_NOT_FOUND.md +++ b/docs/errors/MCPX_DOCKER_EXEC_NOT_FOUND.md @@ -75,6 +75,7 @@ docker run --rm which uvx # or: node, npx, python3 … ## Related - [Docker Isolation](../features/docker-isolation.md) +- [`MCPX_DOCKER_MISSING_TOOLCHAIN`](MCPX_DOCKER_MISSING_TOOLCHAIN.md) — the interpreter is present but a tool it calls (e.g. `git`) is not - [`MCPX_DOCKER_IMAGE_PULL_FAILED`](MCPX_DOCKER_IMAGE_PULL_FAILED.md) - [`MCPX_DOCKER_DAEMON_DOWN`](MCPX_DOCKER_DAEMON_DOWN.md) diff --git a/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md b/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md new file mode 100644 index 000000000..750add814 --- /dev/null +++ b/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md @@ -0,0 +1,110 @@ +--- +id: MCPX_DOCKER_MISSING_TOOLCHAIN +title: MCPX_DOCKER_MISSING_TOOLCHAIN +sidebar_label: MISSING_TOOLCHAIN +description: The Docker isolation image is missing a tool the server shells out to at runtime (most often git). +--- + +# `MCPX_DOCKER_MISSING_TOOLCHAIN` + +**Severity:** error +**Domain:** Docker + +## What happened + +The container started and the server's interpreter ran, but a tool the server +shells out to is **not installed in the image**. The failure text comes from +*inside* the container, e.g.: + +``` +Git executable not found. Ensure that Git is installed and available. +``` + +``` + × Failed to resolve `--with` requirement + ╰─▶ Git operation failed +``` + +``` +sh: 1: git: not found +``` + +This is a different failure from +[`MCPX_DOCKER_EXEC_NOT_FOUND`](MCPX_DOCKER_EXEC_NOT_FOUND.md), which is the +container's **entrypoint interpreter** missing — reported by the OCI runtime +before the server process runs at all. + +## Common cause: a git dependency in a slim Python image + +By far the most common case is an MCP server distributed only as a git URL: + +```jsonc +{ + "name": "my-server", + "command": "uvx", + "args": ["--from", "my-server@git+https://github.com/o/r", "my-server"] +} +``` + +`uv` clones the repository with `git`, and the Python default image is Astral's +**slim** uv image, which does not contain git: + +```console +$ docker run --rm --entrypoint sh ghcr.io/astral-sh/uv:python3.13-bookworm-slim -c 'git --version' +sh: 1: git: not found +$ docker run --rm --entrypoint sh ghcr.io/astral-sh/uv:python3.13-bookworm -c 'git --version' +git version 2.39.5 +``` + +## Is this handled automatically? + +**Yes, for git dependencies with no per-server image override.** MCPProxy +detects a `git+` URL in a Python package runner's arguments and swaps in the +git-capable image named by `docker_isolation.default_images.uvx-git` +(`ghcr.io/astral-sh/uv:python3.13-bookworm` by default). Servers without a git +dependency keep the small slim image. + +So if you still see this code, one of these applies: + +| Situation | Fix | +|-----------|-----| +| The server pins `isolation.image` | The override opts out of the automatic selection. Remove it, or pin an image that ships the tool. | +| `default_images.uvx-git` was retargeted to an image without git | Point it at an image that has git. | +| The missing tool is **not** git (e.g. `make`, `gcc`, `cargo`) | There is no automatic selection for it — pin an `isolation.image` that ships it. | +| You are running an older MCPProxy | Upgrade, or set the image explicitly. | + +## How to fix + +### Remove a per-server override so the automatic selection applies + +```jsonc +{ "name": "my-server", "command": "uvx", "args": ["--from", "my-server@git+https://github.com/o/r", "my-server"] } +``` + +### Or point the shared key at your own image + +```jsonc +{ + "docker_isolation": { + "default_images": { "uvx-git": "my-registry.example/uv-git:1" } + } +} +``` + +### Or pin this one server to an image that ships the tool + +```jsonc +{ "isolation": { "image": "ghcr.io/astral-sh/uv:python3.13-bookworm" } } +``` + +### Verify the image has the tool + +```bash +docker run --rm --entrypoint sh -c 'git --version' +``` + +## Related + +- [Docker Isolation](../features/docker-isolation.md) +- [`MCPX_DOCKER_EXEC_NOT_FOUND`](MCPX_DOCKER_EXEC_NOT_FOUND.md) +- [`MCPX_DOCKER_IMAGE_PULL_FAILED`](MCPX_DOCKER_IMAGE_PULL_FAILED.md) diff --git a/docs/errors/README.md b/docs/errors/README.md index c1b6305ea..fcc645876 100644 --- a/docs/errors/README.md +++ b/docs/errors/README.md @@ -70,6 +70,7 @@ Run `mcpproxy doctor list-codes` for the machine-readable list. - [`MCPX_DOCKER_DAEMON_DOWN`](MCPX_DOCKER_DAEMON_DOWN.md) — daemon unreachable - [`MCPX_DOCKER_IMAGE_PULL_FAILED`](MCPX_DOCKER_IMAGE_PULL_FAILED.md) — pull failed - [`MCPX_DOCKER_EXEC_NOT_FOUND`](MCPX_DOCKER_EXEC_NOT_FOUND.md) — image missing the runtime interpreter (e.g. no `uvx`) +- [`MCPX_DOCKER_MISSING_TOOLCHAIN`](MCPX_DOCKER_MISSING_TOOLCHAIN.md) — image missing a tool the server calls at runtime (e.g. no `git` for a `git+https://…` dependency) - [`MCPX_DOCKER_NO_PERMISSION`](MCPX_DOCKER_NO_PERMISSION.md) — socket permission denied - [`MCPX_DOCKER_SNAP_APPARMOR`](MCPX_DOCKER_SNAP_APPARMOR.md) — snap Docker AppArmor block diff --git a/docs/features/docker-isolation.md b/docs/features/docker-isolation.md index 47b049778..72a68c14b 100644 --- a/docs/features/docker-isolation.md +++ b/docs/features/docker-isolation.md @@ -89,15 +89,16 @@ Add to your `~/.mcpproxy/mcp_config.json`: "network_mode": "bridge", "registry": "docker.io", "default_images": { - "python": "python:3.11", - "python3": "python:3.11", - "uvx": "python:3.11", - "pip": "python:3.11", - "pipx": "python:3.11", - "node": "node:20", - "npm": "node:20", - "npx": "node:20", - "yarn": "node:20", + "python": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "python3": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "pip": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "pipx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "uvx-git": "ghcr.io/astral-sh/uv:python3.13-bookworm", + "node": "node:22", + "npm": "node:22", + "npx": "node:22", + "yarn": "node:22", "go": "golang:1.21-alpine", "cargo": "rust:1.75-slim", "rustc": "rust:1.75-slim", @@ -124,9 +125,34 @@ Add to your `~/.mcpproxy/mcp_config.json`: | `timeout` | Container startup timeout | `"30s"` | | `network_mode` | Docker network mode | `"bridge"` | | `registry` | Docker registry to use | `"docker.io"` | -| `default_images` | Runtime to image mappings | See above | +| `default_images` | Runtime to image mappings (including `uvx-git`, used when a Python runner installs from a `git+` URL) | See above | | `extra_args` | Additional docker run arguments | `[]` | +### Git dependencies (`uvx-git`) + +The Python default image is Astral's **slim** `uv` image, which does not contain +`git`. A server installed straight from a repository — + +```json +{ "name": "my-server", "command": "uvx", "args": ["--from", "my-server@git+https://github.com/o/r", "my-server"] } +``` + +— cannot resolve without it, and fails with `Git executable not found` / +`Git operation failed` ([`MCPX_DOCKER_MISSING_TOOLCHAIN`](../errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md)). + +MCPProxy detects the `git+` URL in a Python package runner's arguments and uses +the **`uvx-git`** image (`ghcr.io/astral-sh/uv:python3.13-bookworm`, which ships +git) for that server only — everyone else keeps the small slim image. Retarget +the key to use your own mirror or a custom build: + +```json +{ "docker_isolation": { "default_images": { "uvx-git": "my-registry.example/uv-git:1" } } } +``` + +A per-server `isolation.image` override always wins over this selection, so a +pinned image must ship git itself. `node`/`npx` need no equivalent: `node:22` +already includes git. + ### Per-Server Configuration You can override isolation settings per server: diff --git a/internal/config/config.go b/internal/config/config.go index 586b2ed87..55cc75bcf 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -1560,6 +1560,12 @@ func DefaultDockerIsolationConfig() *DockerIsolationConfig { "pip": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", "pipx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + // Python + git: the slim image above has no git, so a server + // installed from a git URL (`uvx --from …git+https://…`) cannot + // resolve at all. Selected per-server by NeedsGitCapableImage — + // see internal/config/isolation_git.go (#1143). + GitCapableImageKey: DefaultGitCapableImage, + // Node.js environments - full image for git deps and native modules (LTS until Apr 2028) "node": "node:22", "npm": "node:22", diff --git a/internal/config/isolation_git.go b/internal/config/isolation_git.go new file mode 100644 index 000000000..55da968d9 --- /dev/null +++ b/internal/config/isolation_git.go @@ -0,0 +1,60 @@ +package config + +import "strings" + +// GitCapableImageKey is the `docker_isolation.default_images` key naming the +// image used for Python package runners that install from a git URL. +// +// The shipped Python default is Astral's *slim* uv image, which does not +// contain 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 …git+https://…` (the only distribution channel for a large +// share of MCP servers) failed under Docker isolation with "Git executable not +// found" / "Git operation failed" (#1143). Raising the global Python default to +// the non-slim image would cost every user a ~1.5GB pull for a case many never +// hit, so the git-capable image is selected per-server, from its own named key, +// which operators can retarget to a mirror or a custom build. +const GitCapableImageKey = "uvx-git" + +// DefaultGitCapableImage is the built-in value for GitCapableImageKey: the +// non-slim uv image, which ships git (verified: git version 2.39.5). +// +// It is also the hard fallback when the key is absent from the configured +// map — configs written before this key existed persist their own +// default_images and are not re-seeded on load, and falling through to the +// generic alpine fallback there would be worse than the bug being fixed. +const DefaultGitCapableImage = "ghcr.io/astral-sh/uv:python3.13-bookworm" + +// gitCapableRuntimeTypes are the runtime types whose default image is the +// git-less slim uv image. Node's default (node:22) already ships git — verified +// git version 2.39.5 — so npx/node git dependencies work today and must not be +// pushed onto a second large image. +var gitCapableRuntimeTypes = map[string]bool{ + "uvx": true, + "python": true, + "python3": true, + "pip": true, + "pipx": true, +} + +// NeedsGitCapableImage reports whether a server with the given detected runtime +// type and args needs an isolation image that contains git — i.e. it is a +// Python package runner asked to install from a git URL (`git+https://`, +// `pkg@git+ssh://`, …). +// +// It deliberately looks only at the `git+` marker that pip/uv URLs require: a +// package merely *named* something with "git" in it does not match. +func NeedsGitCapableImage(runtimeType string, args []string) bool { + if !gitCapableRuntimeTypes[runtimeType] { + return false + } + for _, arg := range args { + if strings.Contains(strings.ToLower(arg), "git+") { + return true + } + } + return false +} diff --git a/internal/config/isolation_git_test.go b/internal/config/isolation_git_test.go new file mode 100644 index 000000000..5b488009f --- /dev/null +++ b/internal/config/isolation_git_test.go @@ -0,0 +1,62 @@ +package config + +import "testing" + +// The shipped Python default image is the 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 +// $ docker run --rm --entrypoint sh ghcr.io/astral-sh/uv:python3.13-bookworm -c 'git --version' +// git version 2.39.5 +// +// So every `uvx --from …git+https://…` server fails under Docker isolation +// (#1143). The git-capable image is named by its own default_images key so +// operators can retarget it instead of us bumping a ~1.5GB image on everyone. +func TestDefaultDockerIsolationConfig_HasGitCapableKey(t *testing.T) { + images := DefaultDockerIsolationConfig().DefaultImages + + got, ok := images[GitCapableImageKey] + if !ok { + t.Fatalf("default_images has no %q key; keys=%v", GitCapableImageKey, images) + } + if got != DefaultGitCapableImage { + t.Errorf("default_images[%q] = %q, want %q", GitCapableImageKey, got, DefaultGitCapableImage) + } + // The git-capable default must not be the slim image it exists to replace. + if got == images["uvx"] { + t.Errorf("git-capable default equals the (git-less) uvx default %q", got) + } +} + +func TestNeedsGitCapableImage(t *testing.T) { + tests := []struct { + name string + runtimeType string + args []string + want bool + }{ + {"uvx --from git+https", "uvx", []string{"--from", "git+https://github.com/o/r", "srv"}, true}, + {"uvx pkg@git+https", "uvx", []string{"--from", "pkg@git+https://github.com/o/r@main", "pkg"}, true}, + {"uvx git+ssh", "uvx", []string{"--from", "git+ssh://git@github.com/o/r", "srv"}, true}, + {"pip install git+", "pip", []string{"install", "git+https://github.com/o/r"}, true}, + {"pipx git+", "pipx", []string{"run", "--spec", "git+https://github.com/o/r", "srv"}, true}, + {"python -m pip git+", "python", []string{"-m", "pip", "install", "git+https://github.com/o/r"}, true}, + {"uppercase GIT+ still matches", "uvx", []string{"--from", "GIT+HTTPS://github.com/o/r"}, true}, + {"plain uvx package", "uvx", []string{"mcp-server-fetch"}, false}, + {"uvx package merely named git", "uvx", []string{"mcp-git"}, false}, + // node:22 already ships git (verified: git version 2.39.5), so npx git + // deps work today — swapping its image would be a pointless 1.6GB + // regression. + {"npx git+ needs no swap", "npx", []string{"git+https://github.com/o/r"}, false}, + {"node git+ needs no swap", "node", []string{"git+https://github.com/o/r"}, false}, + {"no args", "uvx", nil, false}, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + if got := NeedsGitCapableImage(tc.runtimeType, tc.args); got != tc.want { + t.Errorf("NeedsGitCapableImage(%q, %v) = %v, want %v", tc.runtimeType, tc.args, got, tc.want) + } + }) + } +} diff --git a/internal/diagnostics/classifier.go b/internal/diagnostics/classifier.go index 09a78c842..ce0f48f4f 100644 --- a/internal/diagnostics/classifier.go +++ b/internal/diagnostics/classifier.go @@ -5,6 +5,7 @@ import ( "errors" "net" "os/exec" + "regexp" "strings" "syscall" @@ -216,20 +217,78 @@ func classifyDockerIsolatedSpawn(err error) Code { strings.Contains(msg, "docker not found in path"), strings.Contains(msg, "docker not found in login shell"): return DockerCLINotFound - // (2) in-container interpreter missing (image lacks uvx/node/python/…). + // (2) a TOOL the server shells out to is missing from the image. git is + // the case that matters in practice: the Python default image is slim and + // has no git, so every `--from …git+https://…` server fails here (#1143). + // Must precede (3): bash reports it as "git: command not found", which + // would otherwise be read as the ENTRYPOINT interpreter missing and put + // the wrong image advice in front of the user. + case isContainerGitMissing(msg): + return DockerMissingToolchain + // (3) in-container interpreter missing (image lacks uvx/node/python/…). case strings.Contains(msg, "executable file not found"), strings.Contains(msg, "no such file or directory"), strings.Contains(msg, "command not found"): return DockerExecNotFound - // (3) other OCI runtime failures (arch mismatch, runc start failure). + // (4) other OCI runtime failures (arch mismatch, runc start failure). case strings.Contains(msg, "oci runtime"), strings.Contains(msg, "exec format error"), strings.Contains(msg, "runc"): return DockerOCIRuntime + // (5) any other `: not found` on the container's stderr — the dash / + // BusyBox wording, which none of the cases above match. The image simply + // lacks something the server calls. + case shellToolNotFoundRe.MatchString(msg): + return DockerMissingToolchain } return "" } +// shellToolNotFoundRe matches the shell "missing command" line as dash, ash and +// BusyBox write it — `sh: 1: git: not found`, `sh: make: not found` — which no +// other classifier arm covers ("command not found" is the bash/zsh wording and +// is handled above). Anchored on `: not found` so a docker daemon message +// such as "manifest for x:latest not found" does not match. +var shellToolNotFoundRe = regexp.MustCompile(`(?:^|[\s:])[\w.+-]+: (?:command )?not found`) + +// gitCloneFailureCauses are causes of a failed git clone that are NOT a missing +// git binary. `uv` collapses them all into "Git operation failed", so without +// this guard a private-repo or offline clone would be diagnosed as a +// missing-toolchain problem and send the user changing images for nothing. +var gitCloneFailureCauses = []string{ + "authentication failed", + "could not read username", + "could not read password", + "permission denied (publickey)", + "could not resolve host", + "repository not found", + "connection timed out", + "ssl certificate problem", +} + +// isContainerGitMissing reports whether the container stderr says git is absent +// from the image. It covers uv's own wording ("Git executable not found…" and +// the terser "Git operation failed" of newer releases) plus the shell wordings +// for a missing `git` binary. +func isContainerGitMissing(msg string) bool { + switch { + case strings.Contains(msg, "git executable not found"), + strings.Contains(msg, "ensure that git is installed"), + strings.Contains(msg, "git: not found"), + strings.Contains(msg, "git: command not found"), + strings.Contains(msg, "command not found: git"): + return true + case strings.Contains(msg, "git operation failed"): + for _, cause := range gitCloneFailureCauses { + if strings.Contains(msg, cause) { + return false + } + } + return true + } + return false +} + // classifyStdio handles os/exec spawn errors and handshake failures. func classifyStdio(err error, hints ClassifierHints) Code { // Docker-isolated servers run `docker run …` over the stdio transport, so diff --git a/internal/diagnostics/classifier_container_toolchain_test.go b/internal/diagnostics/classifier_container_toolchain_test.go new file mode 100644 index 000000000..dfd6bbcb1 --- /dev/null +++ b/internal/diagnostics/classifier_container_toolchain_test.go @@ -0,0 +1,219 @@ +package diagnostics + +import ( + "errors" + "strings" + "testing" +) + +// Container stderr is a DIFFERENT failure surface from mcpproxy's own errors: +// anything the isolated image lacks lands here, and every shape below reached +// the user as MCPX_UNKNOWN_UNCLASSIFIED — whose catalog entry asks them to file +// a bug report — for a one-line config/image problem (#1144). +// +// The git samples are verbatim from `uv` inside the shipped default image: +// +// $ docker run --rm ghcr.io/astral-sh/uv:python3.13-bookworm-slim \ +// uvx --from git+https://github.com/o/r srv +// × Failed to resolve `--with` requirement +// ╰─▶ Git operation failed +// $ docker run --rm --entrypoint sh ghcr.io/astral-sh/uv:python3.13-bookworm-slim -c 'git --version' +// sh: 1: git: not found +// +// ("Git executable not found. Ensure that Git is installed and available." is +// the same failure from an older uv, and is the wording in the bug report.) +func TestContainerToolchainStderrNeverClassifiesAsUnknown(t *testing.T) { + dockerHints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + cases := []struct { + name string + err string + hints ClassifierHints + want Code + }{ + { + name: "uv reports git missing from the image", + err: "Git executable not found. Ensure that Git is installed and available.", + hints: dockerHints, + want: DockerMissingToolchain, + }, + { + name: "uv git resolution failure as mcpproxy wraps it", + err: "server process exited before completing the MCP initialize handshake; recent stderr:\n × Failed to resolve `--with` requirement\n ╰─▶ Git operation failed: transport closed", + hints: dockerHints, + want: DockerMissingToolchain, + }, + { + name: "dash reports the missing tool", + err: "stdio transport (docker_isolation=true): recent stderr: sh: 1: git: not found", + hints: dockerHints, + want: DockerMissingToolchain, + }, + { + name: "bash reports the missing tool", + err: "stdio transport (docker_isolation=true): recent stderr: bash: line 1: git: command not found", + hints: dockerHints, + want: DockerMissingToolchain, + }, + { + name: "a non-git tool missing from the image is the same class of failure", + err: "stdio transport (docker_isolation=true): recent stderr: sh: 1: make: not found", + hints: dockerHints, + want: DockerMissingToolchain, + }, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got := Classify(errors.New(tc.err), tc.hints) + if got == UnknownUnclassified { + t.Fatal("container-toolchain stderr must never ask the user to file a bug report") + } + if got != tc.want { + t.Fatalf("Classify() = %q, want %q", got, tc.want) + } + }) + } +} + +// The new rule must not eat the codes that already worked: the docker BINARY +// missing (#696) and the container ENTRYPOINT interpreter missing are +// different fixes with different docs pages. +func TestContainerToolchainDoesNotSwallowExistingDockerCodes(t *testing.T) { + dockerHints := ClassifierHints{Transport: "stdio", DockerIsolated: true} + + cases := []struct { + name string + err string + want Code + }{ + { + name: "docker binary missing (sh wording)", + err: "stdio transport (docker_isolation=true): recent stderr: docker: command not found", + want: DockerCLINotFound, + }, + { + name: "docker binary missing (zsh wording)", + err: "stdio transport (docker_isolation=true): recent stderr: zsh:1: command not found: docker", + want: DockerCLINotFound, + }, + { + name: "docker binary missing (dash wording)", + err: "stdio transport (docker_isolation=true): recent stderr: sh: 1: docker: not found", + want: DockerCLINotFound, + }, + { + name: "entrypoint interpreter missing from the image", + err: `docker: Error response from daemon: failed to create task: OCI runtime create failed: runc create failed: exec: "uvx": executable file not found in $PATH: unknown`, + want: DockerExecNotFound, + }, + { + name: "OCI architecture mismatch", + err: "docker: Error response from daemon: failed to create task: OCI runtime create failed: exec format error", + want: DockerOCIRuntime, + }, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := Classify(errors.New(tc.err), dockerHints); got != tc.want { + t.Fatalf("Classify() = %q, want %q", got, tc.want) + } + }) + } +} + +// The rule is gated on the Docker-isolation hint: the same wording from a HOST +// stdio server means "install git on this machine", which is a different fix +// and a different code. +func TestContainerToolchainIsGatedOnDockerHint(t *testing.T) { + err := errors.New("Git executable not found. Ensure that Git is installed and available.") + if got := Classify(err, ClassifierHints{Transport: "stdio"}); got == DockerMissingToolchain { + t.Fatalf("Classify() = %q for a non-isolated server; the DOCKER code must stay gated", got) + } +} + +// A git clone that failed for a NETWORK/auth reason is not a missing toolchain — +// telling the user to change images would send them down the wrong path. +func TestGitOperationFailedWithAuthCauseIsNotToolchain(t *testing.T) { + for _, msg := range []string{ + "Git operation failed: fatal: could not read Username for 'https://github.com': No such device or address", + "Git operation failed: fatal: Authentication failed for 'https://github.com/o/r/'", + "Git operation failed: fatal: could not resolve host: github.com", + } { + if got := Classify(errors.New(msg), ClassifierHints{Transport: "stdio", DockerIsolated: true}); got == DockerMissingToolchain { + t.Errorf("Classify(%q) = %q, want anything but the missing-toolchain code", msg, got) + } + } +} + +// A registered code, or the API emits a diagnostic with no message, no fix +// steps and no docs URL. +func TestMissingToolchainIsRegistered(t *testing.T) { + entry, ok := Get(DockerMissingToolchain) + if !ok { + t.Fatalf("%s is not registered in the catalog", DockerMissingToolchain) + } + if entry.UserMessage == "" { + t.Error("no user message") + } + if len(entry.FixSteps) == 0 { + t.Error("no fix steps") + } + if entry.DocsURL == "" { + t.Error("no docs URL") + } +} + +// #1143 fixed the git case automatically, so the remediation has to say so — +// otherwise it sends the user editing config for a problem mcpproxy already +// solved, or leaves them wondering why the override they pinned still fails. +func TestMissingToolchainRemediationNamesTheAutomaticFix(t *testing.T) { + base := ClassifierHints{ + Transport: "stdio", + DockerIsolated: true, + DockerCommand: "uvx", + DockerArgs: []string{"--from", "srv@git+https://github.com/o/r", "srv"}, + DockerDefaultImages: map[string]string{ + "uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "uvx-git": "ghcr.io/astral-sh/uv:python3.13-bookworm", + }, + } + + t.Run("no override: automatic selection already handles it", func(t *testing.T) { + msg := RuntimeAwareRemediation(DockerMissingToolchain, base) + if msg == "" { + t.Fatal("no runtime-aware remediation for a git-dependency server") + } + if !strings.Contains(msg, "ghcr.io/astral-sh/uv:python3.13-bookworm") { + t.Errorf("remediation does not name the git-capable image: %s", msg) + } + if !strings.Contains(strings.ToLower(msg), "automatic") { + t.Errorf("remediation does not mention the automatic image selection: %s", msg) + } + }) + + t.Run("override present: name it as the culprit", func(t *testing.T) { + hints := base + hints.DockerImageOverride = "python:3.11" + msg := RuntimeAwareRemediation(DockerMissingToolchain, hints) + if !strings.Contains(msg, "python:3.11") { + t.Errorf("remediation does not name the pinned image: %s", msg) + } + if !strings.Contains(msg, "isolation.image") { + t.Errorf("remediation does not point at the override: %s", msg) + } + }) + + t.Run("non-git toolchain: still concrete", func(t *testing.T) { + hints := base + hints.DockerArgs = []string{"mcp-server-fetch"} + msg := RuntimeAwareRemediation(DockerMissingToolchain, hints) + if msg == "" { + t.Fatal("no remediation for a non-git missing tool") + } + if strings.Contains(strings.ToLower(msg), "automatic") { + t.Errorf("must not claim the automatic git selection covers a non-git tool: %s", msg) + } + }) +} diff --git a/internal/diagnostics/codes.go b/internal/diagnostics/codes.go index c3493c952..25e15a9be 100644 --- a/internal/diagnostics/codes.go +++ b/internal/diagnostics/codes.go @@ -73,6 +73,15 @@ const ( // DockerOCIRuntime: the OCI runtime (runc) failed to start the container — // e.g. an `exec format error` (image/host architecture mismatch). DockerOCIRuntime Code = "MCPX_DOCKER_OCI_RUNTIME" + // DockerMissingToolchain: the container started and its entrypoint ran, but + // a tool the server shells out to is absent from the image — git for a + // `uvx --from …git+https://…` server, or any `: not found` on the + // container's stderr. Distinct from DockerExecNotFound, which is the + // ENTRYPOINT interpreter missing (an OCI exec failure, before the process + // runs). Container stderr is its own failure surface, and everything the + // image lacked used to land in MCPX_UNKNOWN_UNCLASSIFIED — i.e. a + // "please file a bug report" CTA on an image/config problem (#1144). + DockerMissingToolchain Code = "MCPX_DOCKER_MISSING_TOOLCHAIN" ) // CONFIG domain — configuration parsing and validation failures. diff --git a/internal/diagnostics/registry.go b/internal/diagnostics/registry.go index d77166564..13159fcc6 100644 --- a/internal/diagnostics/registry.go +++ b/internal/diagnostics/registry.go @@ -331,6 +331,17 @@ func seedDOCKER() { }, DocsURL: docsURL(DockerExecNotFound), }) + register(CatalogEntry{ + Code: DockerMissingToolchain, + Severity: SeverityError, + UserMessage: "The Docker image is missing a tool this server needs at runtime (e.g. no `git` for a `git+https://…` dependency). " + + "Use an image that ships it, or drop a per-server `isolation.image` override so mcpproxy can pick one.", + FixSteps: []FixStep{ + {Type: FixStepCommand, Label: "Check whether the image has the tool", Command: "docker run --rm --entrypoint sh -c 'git --version'"}, + {Type: FixStepLink, Label: "Choosing a Docker isolation image", URL: docsURL(DockerMissingToolchain)}, + }, + DocsURL: docsURL(DockerMissingToolchain), + }) register(CatalogEntry{ Code: DockerOCIRuntime, Severity: SeverityError, diff --git a/internal/diagnostics/remediation.go b/internal/diagnostics/remediation.go index 9f804687b..ae74f6edb 100644 --- a/internal/diagnostics/remediation.go +++ b/internal/diagnostics/remediation.go @@ -21,6 +21,9 @@ import ( // // This is diagnostics-only: it never changes classification or image selection. func RuntimeAwareRemediation(code Code, hints ClassifierHints) string { + if code == DockerMissingToolchain { + return missingToolchainRemediation(hints) + } if code != DockerExecNotFound || hints.DockerCommand == "" { return "" } @@ -108,3 +111,68 @@ func detectDockerRuntimeType(command string) string { return cmdName } } + +// gitCapableImageKey mirrors config.GitCapableImageKey — the default_images key +// naming the git-capable image mcpproxy substitutes for a git dependency +// (#1143). It is mirrored rather than imported for the same reason +// detectDockerRuntimeType is: this package stays dependency-free so it can be +// used from every layer. TestGitCapableImageKeyMatchesConfig pins the two +// together. +const gitCapableImageKey = "uvx-git" + +// missingToolchainRemediation explains a DockerMissingToolchain failure: the +// container ran, but the image lacks a tool the server calls. The git case is +// special — mcpproxy now selects a git-capable image automatically (#1143), so +// the message must say so, or it sends the user editing config for a problem +// that is already handled (and leaves the real remaining cause — a per-server +// `isolation.image` override, which opts OUT of that selection — unnamed). +func missingToolchainRemediation(hints ClassifierHints) string { + runtimeType := "" + if hints.DockerCommand != "" { + runtimeType = detectDockerRuntimeType(hints.DockerCommand) + } + override := strings.TrimSpace(hints.DockerImageOverride) + + var b strings.Builder + if runtimeType != "" { + fmt.Fprintf(&b, "This Docker-isolated `%s` server ran, but its image is missing a command it needs.", runtimeType) + } else { + b.WriteString("This Docker-isolated server ran, but its image is missing a command it needs.") + } + + if !hintsHaveGitDependency(hints) { + if override != "" { + fmt.Fprintf(&b, " The per-server `isolation.image` override `%s` is the likely culprit — remove it to inherit the runtime default, or pick an image that ships the missing tool.", override) + } else { + b.WriteString(" Pin an `isolation.image` that ships the missing tool (or build one) for this server.") + } + return b.String() + } + + gitImage := hints.DockerDefaultImages[gitCapableImageKey] + b.WriteString(" It installs from a git URL, so the image must contain `git`.") + switch { + case override != "" && gitImage != "": + fmt.Fprintf(&b, " The per-server `isolation.image` override `%s` is the likely culprit: it opts out of the automatic git-capable image selection. Remove the override to inherit `%s`, or pin an image that ships git.", override, gitImage) + case override != "": + fmt.Fprintf(&b, " The per-server `isolation.image` override `%s` is the likely culprit: it opts out of the automatic git-capable image selection. Remove the override, or pin an image that ships git.", override) + case gitImage != "": + fmt.Fprintf(&b, " mcpproxy selects a git-capable image (`%s`, from `docker_isolation.default_images.%s`) automatically for git dependencies — if this still fails, that key points at an image without git, or this server is running an older mcpproxy.", gitImage, gitCapableImageKey) + default: + fmt.Fprintf(&b, " mcpproxy selects a git-capable image automatically for git dependencies — set `docker_isolation.default_images.%s` to an image that ships git if this still fails.", gitCapableImageKey) + } + return b.String() +} + +// hintsHaveGitDependency reports whether the server installs from a git URL — +// the `git+` marker pip/uv URLs require. Mirrors config.NeedsGitCapableImage's +// arg scan (the runtime-type half is irrelevant here: the container already +// told us the tool is missing). +func hintsHaveGitDependency(hints ClassifierHints) bool { + for _, arg := range hints.DockerArgs { + if strings.Contains(strings.ToLower(arg), "git+") { + return true + } + } + return false +} diff --git a/internal/diagnostics/remediation_gitkey_test.go b/internal/diagnostics/remediation_gitkey_test.go new file mode 100644 index 000000000..24055f5a9 --- /dev/null +++ b/internal/diagnostics/remediation_gitkey_test.go @@ -0,0 +1,18 @@ +package diagnostics + +import ( + "testing" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +// The remediation names a config key by mirroring its literal (this package +// stays free of internal dependencies in non-test code, as detectDockerRuntimeType +// already does). A rename on the config side would otherwise leave the message +// pointing at a key that no longer exists, with the whole suite green. +func TestGitCapableImageKeyMatchesConfig(t *testing.T) { + if gitCapableImageKey != config.GitCapableImageKey { + t.Fatalf("mirrored key %q != config.GitCapableImageKey %q — update remediation.go", + gitCapableImageKey, config.GitCapableImageKey) + } +} diff --git a/internal/diagnostics/types.go b/internal/diagnostics/types.go index 0e2b2c1af..5982ca72c 100644 --- a/internal/diagnostics/types.go +++ b/internal/diagnostics/types.go @@ -96,6 +96,13 @@ type ClassifierHints struct { // DockerDefaultImages is the global default_images map (runtime → image). // Used to name the recommended image for the detected runtime. DockerDefaultImages map[string]string + + // DockerArgs is the configured stdio args for a Docker-isolated server. + // The DockerMissingToolchain remediation reads it to tell a git-dependency + // server (`--from …git+https://…`) apart from any other missing tool, so it + // can say whether mcpproxy's automatic git-capable image selection already + // covers the failure (#1143). + DockerArgs []string } // FixRequest is the input to a registered fixer. diff --git a/internal/runtime/supervisor/isolation_classification_test.go b/internal/runtime/supervisor/isolation_classification_test.go index 120367eab..8f54e6bc6 100644 --- a/internal/runtime/supervisor/isolation_classification_test.go +++ b/internal/runtime/supervisor/isolation_classification_test.go @@ -133,3 +133,36 @@ func TestUsesDockerIsolation_MatchesResolver(t *testing.T) { }) } } + +// The DockerMissingToolchain remediation can only say whether mcpproxy's +// automatic git-capable image selection covers the failure if the server's args +// reach the classifier (#1143/#1144). +func TestClassifierHints_CarryArgsForGitDependencies(t *testing.T) { + srv := &config.ServerConfig{ + Name: "git-server", + Command: "uvx", + Args: []string{"--from", "srv@git+https://github.com/o/r", "srv"}, + } + cfg := &config.Config{ + DockerIsolation: &config.DockerIsolationConfig{Enabled: true, DefaultImages: config.DefaultDockerIsolationConfig().DefaultImages}, + Servers: []*config.ServerConfig{srv}, + } + configSvc := configsvc.NewService(cfg, "/tmp/config.json", zap.NewNop()) + defer configSvc.Close() + + mockUpstream := NewMockUpstreamAdapter() + defer mockUpstream.Close() + + s := New(configSvc, mockUpstream, zap.NewNop()) + + hints := s.classifierHints(srv, "stdio") + if !hints.DockerIsolated { + t.Fatal("expected the server to be classified Docker-isolated") + } + if len(hints.DockerArgs) != len(srv.Args) { + t.Fatalf("classifierHints().DockerArgs = %v, want %v", hints.DockerArgs, srv.Args) + } + if got := hints.DockerDefaultImages[config.GitCapableImageKey]; got != config.DefaultGitCapableImage { + t.Errorf("hints do not carry the git-capable default image: %q", got) + } +} diff --git a/internal/runtime/supervisor/supervisor.go b/internal/runtime/supervisor/supervisor.go index 417d63627..b066500e0 100644 --- a/internal/runtime/supervisor/supervisor.go +++ b/internal/runtime/supervisor/supervisor.go @@ -59,7 +59,9 @@ func classifyAndAttach(status *stateview.ServerStatus, err error, hints diagnost // including the Docker-isolation enrichment context (MCP-2909) the // DockerExecNotFound remediation needs: the configured command (→ detected // runtime), the per-server isolation.image override (likely culprit), and the -// global default_images map (→ recommended image). The enrichment fields are +// global default_images map (→ recommended image). The args come along for +// DockerMissingToolchain, which reads them to tell a git dependency apart from +// any other missing tool (#1144). The enrichment fields are // only populated for Docker-isolated servers; they are inert for every other // code. func (s *Supervisor) classifierHints(srv *config.ServerConfig, transport string) diagnostics.ClassifierHints { @@ -69,6 +71,7 @@ func (s *Supervisor) classifierHints(srv *config.ServerConfig, transport string) } if hints.DockerIsolated && srv != nil { hints.DockerCommand = srv.Command + hints.DockerArgs = srv.Args if srv.Isolation != nil { hints.DockerImageOverride = srv.Isolation.Image } diff --git a/internal/upstream/core/isolation.go b/internal/upstream/core/isolation.go index 98d585d4a..262eb441b 100644 --- a/internal/upstream/core/isolation.go +++ b/internal/upstream/core/isolation.go @@ -256,20 +256,55 @@ func (im *IsolationManager) DetectRuntimeType(command string) string { } } -// GetDockerImage returns the appropriate Docker image for a server +// GetDockerImage returns the appropriate Docker image for a server. +// +// Resolution order: +// 1. the per-server `isolation.image` override — an explicit user choice +// always wins; +// 2. the git-capable image, when the server is a Python package runner +// installing from a git URL (#1143 — see resolveDefaultImage); +// 3. the runtime type's entry in `default_images`; +// 4. alpine, for unknown runtime types. func (im *IsolationManager) GetDockerImage(serverConfig *config.ServerConfig, runtimeType string) (string, error) { // Check if server has custom image override if serverConfig.Isolation != nil && serverConfig.Isolation.Image != "" { return im.buildFullImageName(serverConfig.Isolation.Image), nil } + image, _ := im.resolveDefaultImage(serverConfig, runtimeType) + return image, nil +} + +// resolveDefaultImage computes the image a server gets from the GLOBAL config +// — per-server `isolation.image` overrides are handled by the caller. The +// second return value reports whether the git-capable image was substituted, +// so the spawn path can say why it is pulling a much larger image. +// +// The substitution exists because the Python default is Astral's slim uv image, +// which contains no git; a `uvx --from …git+https://…` server therefore died +// with "Git executable not found" / "Git operation failed" under isolation +// (#1143). Bumping the global Python default instead would cost every user a +// ~1.5GB pull for a case many never hit, so the swap is scoped to the servers +// whose args actually reference a git URL. +func (im *IsolationManager) resolveDefaultImage(serverConfig *config.ServerConfig, runtimeType string) (image string, gitSubstituted bool) { + if serverConfig != nil && config.NeedsGitCapableImage(runtimeType, serverConfig.Args) { + gitImage, exists := im.globalConfig.DefaultImages[config.GitCapableImageKey] + if !exists || gitImage == "" { + // Configs written before this key existed keep their own + // default_images map and are not re-seeded on load, so the + // built-in value is the fallback rather than the alpine one. + gitImage = config.DefaultGitCapableImage + } + return im.buildFullImageName(gitImage), true + } + // Use default image from global config - if image, exists := im.globalConfig.DefaultImages[runtimeType]; exists { - return im.buildFullImageName(image), nil + if img, exists := im.globalConfig.DefaultImages[runtimeType]; exists { + return im.buildFullImageName(img), false } // Fallback to alpine for unknown runtime types - return im.buildFullImageName("alpine:3.18"), nil + return im.buildFullImageName("alpine:3.18"), false } // ResolvedIsolationDefaults captures the per-runtime default values that @@ -320,12 +355,10 @@ func (im *IsolationManager) ResolveDefaults(serverConfig *config.ServerConfig) * // Compute the default image without consulting per-server overrides. // We deliberately avoid calling GetDockerImage(serverConfig, ...) // because that prefers the override; here we want the *baseline*. - var image string - if img, exists := im.globalConfig.DefaultImages[runtimeType]; exists { - image = im.buildFullImageName(img) - } else { - image = im.buildFullImageName("alpine:3.18") - } + // The git-capable substitution IS part of that baseline (it is derived + // from the server's args, not from an override), so the placeholder shows + // the image the container will really run (#1143). + image, _ := im.resolveDefaultImage(serverConfig, runtimeType) defaults := &ResolvedIsolationDefaults{ RuntimeType: runtimeType, @@ -374,6 +407,18 @@ func (im *IsolationManager) BuildDockerArgs(serverConfig *config.ServerConfig, r return nil, err } + // A git dependency silently switches the server to a much larger image, so + // say so once per spawn — otherwise the first pull looks like an + // unexplained multi-hundred-MB download (#1143). + if im.logger != nil && !hasImageOverride(serverConfig) && + config.NeedsGitCapableImage(runtimeType, serverConfig.Args) { + im.logger.Info("using git-capable isolation image for a git dependency", + zap.String("server", serverConfig.Name), + zap.String("runtime", runtimeType), + zap.String("image", image), + zap.String("hint", "override docker_isolation.default_images."+config.GitCapableImageKey+" to use a different image")) + } + args := []string{"run", "--rm", "-i"} // Add container name for easier identification @@ -508,6 +553,11 @@ func (im *IsolationManager) TransformCommandForContainer(command string, args [] } } +// hasImageOverride reports whether the server pins its own isolation image. +func hasImageOverride(serverConfig *config.ServerConfig) bool { + return serverConfig != nil && serverConfig.Isolation != nil && serverConfig.Isolation.Image != "" +} + // generateContainerName creates a Docker container name from server name with random suffix func generateContainerName(serverName string) string { // Sanitize server name for Docker container naming diff --git a/internal/upstream/core/isolation_git_image_test.go b/internal/upstream/core/isolation_git_image_test.go new file mode 100644 index 000000000..dc569c6a5 --- /dev/null +++ b/internal/upstream/core/isolation_git_image_test.go @@ -0,0 +1,168 @@ +package core + +import ( + "testing" + + "go.uber.org/zap" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +const ( + slimUvImage = "ghcr.io/astral-sh/uv:python3.13-bookworm-slim" + gitUvImage = "ghcr.io/astral-sh/uv:python3.13-bookworm" +) + +func gitTestManager(images map[string]string) *IsolationManager { + global := config.DefaultDockerIsolationConfig() + global.Enabled = true + if images != nil { + global.DefaultImages = images + } + return NewIsolationManagerWithLogger(global, zap.NewNop()) +} + +// #1143: a `uvx --from …git+https://…` server is unusable under Docker +// isolation because the default uv image is -slim and has no git: +// +// × Failed to resolve `--with` requirement +// ╰─▶ Git operation failed +// +// The runtime already has the whole ServerConfig here, so it can pick the +// git-capable image for exactly the servers that need it instead of making +// every user pull a ~1.5GB image. +func TestGetDockerImage_GitDependencySelectsGitCapableImage(t *testing.T) { + im := gitTestManager(nil) + srv := &config.ServerConfig{ + Name: "git-server", + Command: "uvx", + Args: []string{"--from", "mcp-thing@git+https://github.com/o/r", "mcp-thing"}, + } + + got, err := im.GetDockerImage(srv, im.DetectRuntimeType(srv.Command)) + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != gitUvImage { + t.Errorf("GetDockerImage() = %q, want the git-capable %q", got, gitUvImage) + } +} + +// The swap must be narrow: a plain PyPI server keeps the small slim image. +func TestGetDockerImage_NoGitDependencyKeepsSlimImage(t *testing.T) { + im := gitTestManager(nil) + srv := &config.ServerConfig{Name: "plain", Command: "uvx", Args: []string{"mcp-server-fetch"}} + + got, err := im.GetDockerImage(srv, im.DetectRuntimeType(srv.Command)) + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != slimUvImage { + t.Errorf("GetDockerImage() = %q, want %q", got, slimUvImage) + } +} + +// An explicit per-server image override always wins — the user asked for it. +func TestGetDockerImage_PerServerOverrideBeatsGitSelection(t *testing.T) { + im := gitTestManager(nil) + srv := &config.ServerConfig{ + Name: "pinned", + Command: "uvx", + Args: []string{"--from", "git+https://github.com/o/r", "srv"}, + Isolation: &config.IsolationConfig{Image: "my-registry.test/uv-with-git:1"}, + } + + got, err := im.GetDockerImage(srv, im.DetectRuntimeType(srv.Command)) + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != "my-registry.test/uv-with-git:1" { + t.Errorf("GetDockerImage() = %q, want the per-server override", got) + } +} + +// Operators retarget the git-capable image through its named default_images +// key rather than editing every server. +func TestGetDockerImage_GitCapableKeyIsRetargetable(t *testing.T) { + images := config.DefaultDockerIsolationConfig().DefaultImages + images[config.GitCapableImageKey] = "my-registry.test/uv-git:pinned" + im := gitTestManager(images) + + srv := &config.ServerConfig{ + Name: "git-server", + Command: "uvx", + Args: []string{"--from", "git+https://github.com/o/r", "srv"}, + } + + got, err := im.GetDockerImage(srv, im.DetectRuntimeType(srv.Command)) + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != "my-registry.test/uv-git:pinned" { + t.Errorf("GetDockerImage() = %q, want the retargeted git image", got) + } +} + +// Upgrade path: configs written before this key existed still have a +// default_images map on disk, and it is NOT re-seeded on load. Falling through +// to the alpine fallback there would be worse than the bug we are fixing. +func TestGetDockerImage_LegacyConfigWithoutGitKeyStillResolves(t *testing.T) { + legacy := map[string]string{ + "uvx": slimUvImage, + "python": slimUvImage, + "npx": "node:22", + } + im := gitTestManager(legacy) + + srv := &config.ServerConfig{ + Name: "git-server", + Command: "uvx", + Args: []string{"--from", "git+https://github.com/o/r", "srv"}, + } + + got, err := im.GetDockerImage(srv, im.DetectRuntimeType(srv.Command)) + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != gitUvImage { + t.Errorf("GetDockerImage() = %q, want the built-in git-capable fallback %q", got, gitUvImage) + } +} + +// node:22 already has git (verified: git version 2.39.5) — no swap, no 1.6GB +// second image. +func TestGetDockerImage_NpxGitDependencyUnchanged(t *testing.T) { + im := gitTestManager(nil) + srv := &config.ServerConfig{ + Name: "node-git", + Command: "npx", + Args: []string{"git+https://github.com/o/r"}, + } + + got, err := im.GetDockerImage(srv, im.DetectRuntimeType(srv.Command)) + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != "docker.io/library/node:22" { + t.Errorf("GetDockerImage() = %q, want %q", got, "docker.io/library/node:22") + } +} + +// The REST/tray placeholder surface must show the image that would actually be +// used, or the user reads "…-slim" while the container runs the git image. +func TestResolveDefaults_ReflectsGitCapableSelection(t *testing.T) { + im := gitTestManager(nil) + srv := &config.ServerConfig{ + Name: "git-server", + Command: "uvx", + Args: []string{"--from", "git+https://github.com/o/r", "srv"}, + } + + defaults := im.ResolveDefaults(srv) + if defaults == nil { + t.Fatal("ResolveDefaults() = nil") + } + if defaults.Image != gitUvImage { + t.Errorf("ResolveDefaults().Image = %q, want %q", defaults.Image, gitUvImage) + } +} diff --git a/website/sidebars.js b/website/sidebars.js index 248a1e3e8..f5192d7af 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -199,6 +199,7 @@ const sidebars = { 'errors/MCPX_DOCKER_NO_PERMISSION', 'errors/MCPX_DOCKER_SNAP_APPARMOR', 'errors/MCPX_DOCKER_EXEC_NOT_FOUND', + 'errors/MCPX_DOCKER_MISSING_TOOLCHAIN', ], }, { From 6f9dea6c0423735a3e3d385c1d12e36221240f1b Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Tue, 1 Sep 2026 07:37:38 +0300 Subject: [PATCH 2/7] fix(docker): stop the toolchain diagnosis hijacking specific codes, and let the operator's image map win (#1143, #1144) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to fc61a26 after a three-lens adversarial review. Five findings were real; one was not. Classifier (#1144): - `shellToolNotFoundRe` matched a bare `: 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 '' 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. --- docs/configuration.md | 2 +- docs/docker-isolation.md | 13 +- docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md | 2 + docs/features/docker-isolation.md | 13 +- internal/config/isolation_git.go | 12 +- internal/config/isolation_git_seed_test.go | 65 ++++++++++ internal/diagnostics/classifier.go | 91 +++++++++++--- .../classifier_toolchain_precision_test.go | 110 +++++++++++++++++ internal/diagnostics/remediation.go | 27 +++- .../remediation_runtime_gate_test.go | 74 +++++++++++ .../management/isolation_defaults_git_test.go | 60 +++++++++ internal/management/service.go | 6 +- internal/upstream/core/isolation.go | 53 ++++++-- .../core/isolation_git_image_operator_test.go | 116 ++++++++++++++++++ .../upstream/core/isolation_git_image_test.go | 18 ++- 15 files changed, 615 insertions(+), 47 deletions(-) create mode 100644 internal/config/isolation_git_seed_test.go create mode 100644 internal/diagnostics/classifier_toolchain_precision_test.go create mode 100644 internal/diagnostics/remediation_runtime_gate_test.go create mode 100644 internal/management/isolation_defaults_git_test.go create mode 100644 internal/upstream/core/isolation_git_image_operator_test.go diff --git a/docs/configuration.md b/docs/configuration.md index f14fd48fe..3584423cd 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -947,7 +947,7 @@ See [Logging Documentation](logging.md) for complete details. | Field | Type | Default | Description | |-------|------|---------|-------------| | `enabled` | boolean | `false` | Enable Docker isolation globally | -| `default_images` | object | See below | Map of runtime type to Docker image. The `uvx-git` entry is used instead of the Python default when a Python package runner installs from a `git+` URL (the slim uv image has no git) | +| `default_images` | object | See below | Map of runtime type to Docker image, merged over the built-in map (a partial map only overrides the keys it lists). The `uvx-git` entry is used instead of the Python default when a Python package runner installs from a `git+` URL (the slim uv image has no git); set it to `""` to opt out | | `registry` | string | `"docker.io"` | Docker registry to use | | `network_mode` | string | `"bridge"` | Docker network mode | | `memory_limit` | string | `"512m"` | Memory limit for containers | diff --git a/docs/docker-isolation.md b/docs/docker-isolation.md index b07dcd6b1..7aed3ec2a 100644 --- a/docs/docker-isolation.md +++ b/docs/docker-isolation.md @@ -156,9 +156,20 @@ the key to use your own mirror or a custom build: { "docker_isolation": { "default_images": { "uvx-git": "my-registry.example/uv-git:1" } } } ``` +`default_images` from your config file is merged **over** the built-in map, so a +partial map like the one above only changes the keys it lists — every other +runtime keeps its built-in image. + +To turn the substitution off entirely, set the key to an empty string; those +servers then keep whatever `uvx`/`python` image you configured: + +```json +{ "docker_isolation": { "default_images": { "uvx-git": "" } } } +``` + A per-server `isolation.image` override always wins over this selection, so a pinned image must ship git itself. `node`/`npx` need no equivalent: `node:22` -already includes git. +already includes git, and the substitution never applies to them. ### Per-Server Configuration diff --git a/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md b/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md index 750add814..bb7cbc66b 100644 --- a/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md +++ b/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md @@ -70,6 +70,8 @@ So if you still see this code, one of these applies: |-----------|-----| | The server pins `isolation.image` | The override opts out of the automatic selection. Remove it, or pin an image that ships the tool. | | `default_images.uvx-git` was retargeted to an image without git | Point it at an image that has git. | +| `default_images.uvx-git` was set to `""` | That is the opt-out — the server keeps your `uvx`/`python` image. Remove the empty value, or pin an image that ships git. | +| The server is a `node`/`npx` (or other non-Python) runner | The selection is Python-only, because `node:22` already ships git. Pin an `isolation.image` that has the tool. | | The missing tool is **not** git (e.g. `make`, `gcc`, `cargo`) | There is no automatic selection for it — pin an `isolation.image` that ships it. | | You are running an older MCPProxy | Upgrade, or set the image explicitly. | diff --git a/docs/features/docker-isolation.md b/docs/features/docker-isolation.md index 72a68c14b..a5c106434 100644 --- a/docs/features/docker-isolation.md +++ b/docs/features/docker-isolation.md @@ -149,9 +149,20 @@ the key to use your own mirror or a custom build: { "docker_isolation": { "default_images": { "uvx-git": "my-registry.example/uv-git:1" } } } ``` +`default_images` from your config file is merged **over** the built-in map, so a +partial map like the one above only changes the keys it lists — every other +runtime keeps its built-in image. + +To turn the substitution off entirely, set the key to an empty string; those +servers then keep whatever `uvx`/`python` image you configured: + +```json +{ "docker_isolation": { "default_images": { "uvx-git": "" } } } +``` + A per-server `isolation.image` override always wins over this selection, so a pinned image must ship git itself. `node`/`npx` need no equivalent: `node:22` -already includes git. +already includes git, and the substitution never applies to them. ### Per-Server Configuration diff --git a/internal/config/isolation_git.go b/internal/config/isolation_git.go index 55da968d9..423833ef7 100644 --- a/internal/config/isolation_git.go +++ b/internal/config/isolation_git.go @@ -22,10 +22,14 @@ const GitCapableImageKey = "uvx-git" // DefaultGitCapableImage is the built-in value for GitCapableImageKey: the // non-slim uv image, which ships git (verified: git version 2.39.5). // -// It is also the hard fallback when the key is absent from the configured -// map — configs written before this key existed persist their own -// default_images and are not re-seeded on load, and falling through to the -// generic alpine fallback there would be worse than the bug being fixed. +// A config file's `default_images` is decoded INTO this built-in map rather +// than replacing it, so the key survives an upgrade from a config written +// before it existed (TestDefaultImagesMergeOverBuiltInsOnLoad). The resolver +// therefore does NOT reach for this constant whenever the key is missing — +// doing so would pull a public ghcr.io image behind the back of a mirrored or +// air-gapped operator whose own `uvx` entry is right there. It is used only +// where the map has no answer at all; see +// core.IsolationManager.resolveDefaultImage. const DefaultGitCapableImage = "ghcr.io/astral-sh/uv:python3.13-bookworm" // gitCapableRuntimeTypes are the runtime types whose default image is the diff --git a/internal/config/isolation_git_seed_test.go b/internal/config/isolation_git_seed_test.go new file mode 100644 index 000000000..68af3b905 --- /dev/null +++ b/internal/config/isolation_git_seed_test.go @@ -0,0 +1,65 @@ +package config + +import ( + "os" + "path/filepath" + "testing" +) + +// The upgrade path for #1143 rests entirely on this: a config file written +// before the git-capable key existed persists its own `default_images` map, and +// encoding/json decodes an object into the ALREADY-POPULATED default map rather +// than replacing it. The built-in entry therefore survives the merge, and the +// operator's own entries win where they overlap. +// +// This is also why the resolver does not need to hardcode a public image as its +// upgrade fallback, and why a partial `default_images` in a config file does +// not blank out the runtimes it omits. +func TestDefaultImagesMergeOverBuiltInsOnLoad(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, ConfigFileName) + legacy := `{ + "listen": "127.0.0.1:8080", + "data_dir": ` + jsonString(dir) + `, + "docker_isolation": { + "enabled": true, + "default_images": { + "uvx": "mirror.internal/astral/uv:slim", + "python": "mirror.internal/astral/uv:slim", + "npx": "mirror.internal/library/node:22" + } + } + }` + if err := os.WriteFile(path, []byte(legacy), 0600); err != nil { + t.Fatal(err) + } + + cfg, err := LoadFromFile(path) + if err != nil { + t.Fatalf("LoadFromFile() error: %v", err) + } + images := cfg.DockerIsolation.DefaultImages + + if got := images["uvx"]; got != "mirror.internal/astral/uv:slim" { + t.Errorf("operator's uvx entry = %q, want it to win the merge", got) + } + if got := images[GitCapableImageKey]; got != DefaultGitCapableImage { + t.Errorf("default_images[%q] = %q, want the built-in %q seeded by the merge", + GitCapableImageKey, got, DefaultGitCapableImage) + } + if got := images["ruby"]; got == "" { + t.Error("a runtime the config file omits lost its built-in image — the map was replaced, not merged") + } +} + +func jsonString(s string) string { + out := make([]byte, 0, len(s)+2) + out = append(out, '"') + for i := 0; i < len(s); i++ { + if s[i] == '\\' || s[i] == '"' { + out = append(out, '\\') + } + out = append(out, s[i]) + } + return string(append(out, '"')) +} diff --git a/internal/diagnostics/classifier.go b/internal/diagnostics/classifier.go index ce0f48f4f..3692cd06a 100644 --- a/internal/diagnostics/classifier.go +++ b/internal/diagnostics/classifier.go @@ -204,6 +204,15 @@ func classifyDockerIsolatedSpawn(err error) Code { } msg := strings.ToLower(err.Error()) + + // A handshake TIMEOUT means the container is still running — it simply + // never answered `initialize`. Whatever a startup script wrote to stderr + // minutes earlier (dash has no `source`, npm prints notices, …) did not + // kill anything, so it must not be promoted to the terminal cause and + // outrank MCPX_STDIO_HANDSHAKE_TIMEOUT. A missing toolchain makes the + // process EXIT, which is the other wrapper and is unaffected here. + toolchainSuppressed := isStdioHandshakeTimeout(msg) + switch { // (1) docker binary unresolved: shellwrap resolution failure, or the shell // / Go exec layer reporting `docker` itself missing. Cover both shell @@ -220,50 +229,100 @@ func classifyDockerIsolatedSpawn(err error) Code { // (2) a TOOL the server shells out to is missing from the image. git is // the case that matters in practice: the Python default image is slim and // has no git, so every `--from …git+https://…` server fails here (#1143). - // Must precede (3): bash reports it as "git: command not found", which + // Must precede (4): bash reports it as "git: command not found", which // would otherwise be read as the ENTRYPOINT interpreter missing and put // the wrong image advice in front of the user. - case isContainerGitMissing(msg): + case !toolchainSuppressed && isContainerGitMissing(msg): + return DockerMissingToolchain + // (3) any other shell "missing command" line on the container's stderr. + // Anchored to a shell prefix (see shellToolNotFoundRe), so it is specific + // enough to sit above (4) — which would otherwise answer the bash wording + // of this exact failure with the ENTRYPOINT-missing code. Real OCI + // entrypoint errors never carry a shell prefix, so they still fall to (4). + case !toolchainSuppressed && shellToolNotFoundRe.MatchString(msg): return DockerMissingToolchain - // (3) in-container interpreter missing (image lacks uvx/node/python/…). + // (4) in-container interpreter missing (image lacks uvx/node/python/…). case strings.Contains(msg, "executable file not found"), strings.Contains(msg, "no such file or directory"), strings.Contains(msg, "command not found"): return DockerExecNotFound - // (4) other OCI runtime failures (arch mismatch, runc start failure). + // (5) other OCI runtime failures (arch mismatch, runc start failure). case strings.Contains(msg, "oci runtime"), strings.Contains(msg, "exec format error"), strings.Contains(msg, "runc"): return DockerOCIRuntime - // (5) any other `: not found` on the container's stderr — the dash / - // BusyBox wording, which none of the cases above match. The image simply - // lacks something the server calls. - case shellToolNotFoundRe.MatchString(msg): - return DockerMissingToolchain } return "" } -// shellToolNotFoundRe matches the shell "missing command" line as dash, ash and -// BusyBox write it — `sh: 1: git: not found`, `sh: make: not found` — which no -// other classifier arm covers ("command not found" is the bash/zsh wording and -// is handled above). Anchored on `: not found` so a docker daemon message -// such as "manifest for x:latest not found" does not match. -var shellToolNotFoundRe = regexp.MustCompile(`(?:^|[\s:])[\w.+-]+: (?:command )?not found`) +// isStdioHandshakeTimeout reports whether the error is the "the child is alive +// but silent" wrapper (connection_lifecycle.go) rather than a process that +// died. Kept in lockstep with the MCPX_STDIO_HANDSHAKE_TIMEOUT arm of +// classifyStdio below. +func isStdioHandshakeTimeout(msg string) bool { + return strings.Contains(msg, "did not respond to mcp initialize") || + strings.Contains(msg, "handshake timeout") +} + +// shellToolNotFoundRe matches a shell's "missing command" line, and only that. +// It is anchored on the SHELL PREFIX the line always carries — +// +// sh: 1: git: not found (dash / ash / BusyBox) +// /bin/sh: 1: exec: cmake: not found +// bash: line 1: cmake: command not found +// +// — because the bare `: not found` shape it used to match occurs all over +// ordinary captured stderr (`ERROR config profile production: not found`, an +// MCP error body, a registry lookup) and the container-toolchain arm runs +// before every generic stdio arm. Unanchored, one such line anywhere in the +// stderr tail claimed the whole failure and sent the user to a docs page +// telling them to change their Docker image. +// +// zsh's reversed wording (`zsh:1: command not found: cmake`) is deliberately +// NOT matched here — it has no space after the shell's colon, and the generic +// "command not found" arm already covers it. +var shellToolNotFoundRe = regexp.MustCompile( + `(?:^|\s)(?:[\w./+-]*/)?(?:sh|bash|dash|ash|ksh|zsh|busybox)(?:\[\d+\])?: (?:(?:line )?\d+: )?(?:exec: )?[\w.+-]+: (?:command )?not found`) // gitCloneFailureCauses are causes of a failed git clone that are NOT a missing // git binary. `uv` collapses them all into "Git operation failed", so without // this guard a private-repo or offline clone would be diagnosed as a // missing-toolchain problem and send the user changing images for nothing. +// +// Every entry is text only git/ssh/curl can produce, which is itself the proof +// that git RAN. The list has to cover the wordings a private repository +// actually produces — an incomplete one is not a near-miss, it is the wrong +// diagnosis with a confident docs link attached. var gitCloneFailureCauses = []string{ + // Credentials. "authentication failed", "could not read username", "could not read password", + "terminal prompts disabled", + "invalid username or password", + "support for password authentication was removed", "permission denied (publickey)", - "could not resolve host", + "no supported authentication methods available", + "host key verification failed", + "returned error: 401", + "returned error: 403", + // Repository addressing. "repository not found", + "' not found", // git: fatal: repository 'https://…/' not found + "does not appear to be a git repository", + // Network / TLS. "unable to access" is git's own prefix for this whole + // family, so it catches the wordings not spelled out individually. + "unable to access", + "could not resolve host", + "temporary failure in name resolution", "connection timed out", + "connection refused", + "network is unreachable", + "failed to connect to", "ssl certificate problem", + "server certificate verification failed", + "the remote end hung up unexpectedly", + "early eof", } // isContainerGitMissing reports whether the container stderr says git is absent diff --git a/internal/diagnostics/classifier_toolchain_precision_test.go b/internal/diagnostics/classifier_toolchain_precision_test.go new file mode 100644 index 000000000..fa33dc243 --- /dev/null +++ b/internal/diagnostics/classifier_toolchain_precision_test.go @@ -0,0 +1,110 @@ +package diagnostics + +import ( + "errors" + "testing" +) + +// The `: not found` arm added for #1144 is the loosest rule in +// classifyDockerIsolatedSpawn, and classifyDockerIsolatedSpawn runs BEFORE +// every generic stdio arm. Unanchored, it lets one line anywhere in the +// captured stderr tail claim the whole failure and outrank a strictly more +// specific classification. +func TestMissingToolchainDoesNotHijackMoreSpecificStdioCodes(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + cases := []struct { + name string + err string + want Code + }{ + { + // A handshake timeout means the container is still RUNNING — it just + // never answered `initialize`. A dash line from an earlier startup + // script (`source` is a bash builtin dash does not have, and is + // harmless) is not the terminal error. + name: "handshake timeout with a benign shell line in the stderr tail", + err: "server did not respond to MCP initialize within 30s (subprocess may have crashed " + + "or printed to stderr instead of stdout); recent stderr:\n/bin/sh: 1: source: not found\n", + want: STDIOHandshakeTimeout, + }, + { + // An application-level ": not found" is not a shell + // missing-command line: the image is fine, the server's own config + // is not. Diagnosing it as a missing container toolchain sends the + // user to a docs page telling them to change images. + name: "application-level not-found is not a shell missing-command line", + err: "server process exited before completing the MCP initialize handshake; recent stderr:\n" + + "[mcp-server] ERROR config profile production: not found\n: transport closed", + want: STDIOExitBeforeInitialize, + }, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if got := Classify(errors.New(tc.err), hints); got != tc.want { + t.Fatalf("Classify() = %q, want %q", got, tc.want) + } + }) + } +} + +// Anchoring must not cost the shapes the rule exists for: every real shell +// wording for a missing command still has to reach the toolchain code. +func TestShellMissingCommandWordingsStillClassify(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + for _, msg := range []string{ + "stdio transport (docker_isolation=true): recent stderr: sh: 1: cmake: not found", + "stdio transport (docker_isolation=true): recent stderr: /bin/sh: 1: exec: cmake: not found", + "stdio transport (docker_isolation=true): recent stderr: sh: cmake: not found", + "stdio transport (docker_isolation=true): recent stderr: ash: cmake: not found", + "stdio transport (docker_isolation=true): recent stderr: bash: line 1: cmake: command not found", + } { + if got := Classify(errors.New(msg), hints); got != DockerMissingToolchain { + t.Errorf("Classify(%q) = %q, want %q", msg, got, DockerMissingToolchain) + } + } +} + +// `uv` collapses every clone failure into "Git operation failed", so the +// exclusion list is the only thing keeping a credential or network failure out +// of the missing-git diagnosis. The list shipped with #1144 covered three +// wordings; these are the ones a private repo actually produces, and each was +// being sent to a docs page that says to change the Docker image. +func TestGitCloneFailuresAreNotDiagnosedAsAMissingImage(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + wrap := func(cause string) string { + return "server process exited before completing the MCP initialize handshake; recent stderr:\n" + + " × Failed to resolve `--with` requirement\n ╰─▶ Git operation failed\n ╰─▶ " + cause + + "\n: transport closed" + } + + causes := []string{ + "remote: Support for password authentication was removed on August 13, 2021.", + "remote: Invalid username or password.", + "fatal: could not read Username for 'https://github.com': terminal prompts disabled", + "fatal: unable to access 'https://github.com/o/r/': The requested URL returned error: 403", + "fatal: unable to access 'https://github.com/o/r/': The requested URL returned error: 401", + "Host key verification failed.", + "git@github.com: Permission denied (publickey).", + "fatal: unable to access 'https://github.com/o/r/': Failed to connect to github.com port 443: Connection refused", + "fatal: unable to access 'https://github.com/o/r/': Could not resolve host: github.com", + "ssh: Could not resolve hostname github.com: Temporary failure in name resolution", + "fatal: unable to access 'https://github.com/o/r/': server certificate verification failed. CAfile: none CRLfile: none", + "fatal: unable to access 'https://github.com/o/r/': Network is unreachable", + "fatal: repository 'https://github.com/o/r/' not found", + } + + for _, cause := range causes { + msg := wrap(cause) + got := Classify(errors.New(msg), hints) + if got == DockerMissingToolchain { + t.Errorf("cause %q classified as %q — git ran, the image is not missing it", cause, got) + } + if got == UnknownUnclassified { + t.Errorf("cause %q classified as %q — the #1144 bug-report CTA is back", cause, got) + } + } +} diff --git a/internal/diagnostics/remediation.go b/internal/diagnostics/remediation.go index ae74f6edb..3e0100286 100644 --- a/internal/diagnostics/remediation.go +++ b/internal/diagnostics/remediation.go @@ -164,11 +164,30 @@ func missingToolchainRemediation(hints ClassifierHints) string { return b.String() } -// hintsHaveGitDependency reports whether the server installs from a git URL — -// the `git+` marker pip/uv URLs require. Mirrors config.NeedsGitCapableImage's -// arg scan (the runtime-type half is irrelevant here: the container already -// told us the tool is missing). +// gitCapableRuntimeTypes mirrors config.gitCapableRuntimeTypes — the runtime +// types whose default image is the git-less slim uv image, and therefore the +// only ones config.NeedsGitCapableImage substitutes an image for. Mirrored for +// the same reason gitCapableImageKey is; TestMirroredGitRuntimeGateMatchesConfig +// pins the two together. +var gitCapableRuntimeTypes = map[string]bool{ + "uvx": true, + "python": true, + "python3": true, + "pip": true, + "pipx": true, +} + +// hintsHaveGitDependency reports whether mcpproxy's automatic git-capable image +// selection applies to this server — i.e. whether config.NeedsGitCapableImage +// would fire for it. BOTH halves of that gate matter: the `git+` marker pip/uv +// URLs require, AND the Python-package-runner runtime type. node:22 already +// ships git and is deliberately left alone, so a node/go/ruby server never gets +// the substitution — claiming otherwise promises a fix that never runs and +// points at a `default_images` key with no effect on that server. func hintsHaveGitDependency(hints ClassifierHints) bool { + if hints.DockerCommand == "" || !gitCapableRuntimeTypes[detectDockerRuntimeType(hints.DockerCommand)] { + return false + } for _, arg := range hints.DockerArgs { if strings.Contains(strings.ToLower(arg), "git+") { return true diff --git a/internal/diagnostics/remediation_runtime_gate_test.go b/internal/diagnostics/remediation_runtime_gate_test.go new file mode 100644 index 000000000..08f5786c6 --- /dev/null +++ b/internal/diagnostics/remediation_runtime_gate_test.go @@ -0,0 +1,74 @@ +package diagnostics + +import ( + "strings" + "testing" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +// The automatic git-capable image selection is gated on the runtime type as +// well as the `git+` marker: config.NeedsGitCapableImage only fires for Python +// package runners, because node:22 already ships git and must not be pushed +// onto a second large image. A remediation that drops that half of the gate +// promises a `node`/`go`/`ruby` user an automatic fix that will never run, and +// points them at `docker_isolation.default_images.uvx-git` — a key that has no +// effect on their server at all. +func TestMissingToolchainRemediationHonoursTheRuntimeGate(t *testing.T) { + images := map[string]string{ + "uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "uvx-git": "ghcr.io/astral-sh/uv:python3.13-bookworm", + "npx": "node:22", + } + + nonPython := ClassifierHints{ + Transport: "stdio", + DockerIsolated: true, + DockerCommand: "npx", + DockerArgs: []string{"git+https://github.com/o/r"}, + DockerDefaultImages: images, + } + + msg := RuntimeAwareRemediation(DockerMissingToolchain, nonPython) + if msg == "" { + t.Fatal("no remediation for a Docker-isolated node server") + } + if strings.Contains(strings.ToLower(msg), "automatic") { + t.Errorf("claims an automatic fix that NeedsGitCapableImage never runs for npx: %s", msg) + } + if strings.Contains(msg, gitCapableImageKey) { + t.Errorf("points at %s, which does not apply to a node runtime: %s", gitCapableImageKey, msg) + } +} + +// The mirrored gate has to stay in lockstep with the resolver it describes, or +// the message drifts back into promising a fix that does not run. +func TestMirroredGitRuntimeGateMatchesConfig(t *testing.T) { + cases := []struct { + command string + want bool + }{ + {"uvx", true}, + {"python", true}, + {"python3", true}, + {"pip", true}, + {"pipx", true}, + {"npx", false}, + {"node", false}, + {"go", false}, + {"ruby", false}, + } + + args := []string{"--from", "srv@git+https://github.com/o/r", "srv"} + for _, tc := range cases { + runtimeType := detectDockerRuntimeType(tc.command) + got := hintsHaveGitDependency(ClassifierHints{DockerCommand: tc.command, DockerArgs: args}) + want := config.NeedsGitCapableImage(runtimeType, args) + if want != tc.want { + t.Fatalf("config.NeedsGitCapableImage(%q) = %v, test table says %v", runtimeType, want, tc.want) + } + if got != want { + t.Errorf("hintsHaveGitDependency(%q) = %v, config.NeedsGitCapableImage = %v", tc.command, got, want) + } + } +} diff --git a/internal/management/isolation_defaults_git_test.go b/internal/management/isolation_defaults_git_test.go new file mode 100644 index 000000000..fec9537d1 --- /dev/null +++ b/internal/management/isolation_defaults_git_test.go @@ -0,0 +1,60 @@ +package management + +import ( + "context" + "testing" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" + + "github.com/stretchr/testify/require" + "go.uber.org/zap/zaptest" +) + +// The REST/tray `isolation_defaults.image` placeholder exists so a user can see +// the image the container will really run before deciding whether to override +// it. ResolveDefaults picks the git-capable image from the server's ARGS +// (#1143), so a call site that builds a throwaway ServerConfig without them +// resolves a different image than the spawn path — the placeholder shows the +// slim image while the container runs the git one, and the two surfaces +// disagree with no way for the user to tell which is right. +func TestListServers_IsolationDefaultsReflectGitDependency(t *testing.T) { + logger := zaptest.NewLogger(t).Sugar() + cfg := &config.Config{DockerIsolation: config.DefaultDockerIsolationConfig()} + cfg.DockerIsolation.Enabled = true + + rt := newMockRuntime() + rt.servers = []map[string]interface{}{ + { + "id": "git-server", "name": "git-server", "protocol": "stdio", + "command": "uvx", "enabled": true, + "args": []string{"--from", "srv@git+https://github.com/o/r", "srv"}, + }, + { + "id": "plain", "name": "plain", "protocol": "stdio", + "command": "uvx", "enabled": true, + "args": []string{"mcp-server-fetch"}, + }, + } + + svc := NewService(rt, cfg, "", &mockEventEmitter{}, nil, logger) + servers, _, err := svc.ListServers(context.Background()) + require.NoError(t, err) + require.Len(t, servers, 2) + + byName := map[string]int{} + for i, s := range servers { + byName[s.Name] = i + } + + gitSrv := servers[byName["git-server"]] + require.NotNil(t, gitSrv.IsolationDefaults) + if got, want := gitSrv.IsolationDefaults.Image, config.DefaultGitCapableImage; got != want { + t.Errorf("git-dependency placeholder image = %q, want %q (what the spawn path resolves)", got, want) + } + + plain := servers[byName["plain"]] + require.NotNil(t, plain.IsolationDefaults) + if got, want := plain.IsolationDefaults.Image, cfg.DockerIsolation.DefaultImages["uvx"]; got != want { + t.Errorf("plain server placeholder image = %q, want the slim runtime default %q", got, want) + } +} diff --git a/internal/management/service.go b/internal/management/service.go index 30aa55288..78f4f2770 100644 --- a/internal/management/service.go +++ b/internal/management/service.go @@ -417,7 +417,11 @@ func (s *service) ListServers(ctx context.Context) ([]*contracts.Server, *contra // server is currently isolated; the UI uses it as a hint. if srv.Protocol == "stdio" && srv.Command != "" && s.config != nil && s.config.DockerIsolation != nil { im := core.NewIsolationManager(s.config.DockerIsolation) - tmpCfg := &config.ServerConfig{Name: srv.Name, Command: srv.Command} + // Args are load-bearing, not decoration: the git-capable image + // substitution (#1143) is derived from them, so dropping them here + // makes the placeholder resolve a different image than the spawn + // path and the two surfaces disagree. + tmpCfg := &config.ServerConfig{Name: srv.Name, Command: srv.Command, Args: srv.Args} if defaults := im.ResolveDefaults(tmpCfg); defaults != nil { srv.IsolationDefaults = &contracts.IsolationDefaults{ RuntimeType: defaults.RuntimeType, diff --git a/internal/upstream/core/isolation.go b/internal/upstream/core/isolation.go index 262eb441b..997cbb13f 100644 --- a/internal/upstream/core/isolation.go +++ b/internal/upstream/core/isolation.go @@ -286,21 +286,42 @@ func (im *IsolationManager) GetDockerImage(serverConfig *config.ServerConfig, ru // (#1143). Bumping the global Python default instead would cost every user a // ~1.5GB pull for a case many never hit, so the swap is scoped to the servers // whose args actually reference a git URL. +// +// The operator's `default_images` map is authoritative throughout. In +// particular the substitution NEVER reaches past it to a hardcoded public +// image while the map has an answer: a mirrored or air-gapped install +// retargets these keys at its own registry, and pulling ghcr.io behind its back +// is an image that host cannot fetch at all. So: +// +// - key set → use it (the operator retargeted the git image); +// - key set to "" → opt out, keep the runtime default (the lever for an +// operator who does not want a second large image); +// - key absent → the runtime's own configured image, exactly as before +// #1143. On the real upgrade path the key is never absent: a config file's +// `default_images` is decoded INTO the built-in map, so the built-in entry +// survives (TestDefaultImagesMergeOverBuiltInsOnLoad); +// - key absent AND no runtime image → the built-in git-capable image, because +// the only alternative there is the alpine fallback, which has neither git +// nor python. func (im *IsolationManager) resolveDefaultImage(serverConfig *config.ServerConfig, runtimeType string) (image string, gitSubstituted bool) { - if serverConfig != nil && config.NeedsGitCapableImage(runtimeType, serverConfig.Args) { - gitImage, exists := im.globalConfig.DefaultImages[config.GitCapableImageKey] - if !exists || gitImage == "" { - // Configs written before this key existed keep their own - // default_images map and are not re-seeded on load, so the - // built-in value is the fallback rather than the alpine one. - gitImage = config.DefaultGitCapableImage + runtimeImage, runtimeExists := im.globalConfig.DefaultImages[runtimeType] + needsGit := serverConfig != nil && config.NeedsGitCapableImage(runtimeType, serverConfig.Args) + + if needsGit { + gitImage, gitKeySet := im.globalConfig.DefaultImages[config.GitCapableImageKey] + switch { + case strings.TrimSpace(gitImage) != "": + return im.buildFullImageName(gitImage), true + case gitKeySet: + // Explicitly emptied: the operator opted out of the substitution. + case !runtimeExists || strings.TrimSpace(runtimeImage) == "": + return im.buildFullImageName(config.DefaultGitCapableImage), true } - return im.buildFullImageName(gitImage), true } // Use default image from global config - if img, exists := im.globalConfig.DefaultImages[runtimeType]; exists { - return im.buildFullImageName(img), false + if runtimeExists { + return im.buildFullImageName(runtimeImage), false } // Fallback to alpine for unknown runtime types @@ -409,9 +430,15 @@ func (im *IsolationManager) BuildDockerArgs(serverConfig *config.ServerConfig, r // A git dependency silently switches the server to a much larger image, so // say so once per spawn — otherwise the first pull looks like an - // unexplained multi-hundred-MB download (#1143). - if im.logger != nil && !hasImageOverride(serverConfig) && - config.NeedsGitCapableImage(runtimeType, serverConfig.Args) { + // unexplained multi-hundred-MB download (#1143). Keyed on whether the + // substitution ACTUALLY happened, not merely on the server qualifying for + // it: an operator who emptied the key opted out, and logging a swap that + // did not occur would send them looking for a pull that never runs. + gitSubstituted := false + if !hasImageOverride(serverConfig) { + _, gitSubstituted = im.resolveDefaultImage(serverConfig, runtimeType) + } + if im.logger != nil && gitSubstituted { im.logger.Info("using git-capable isolation image for a git dependency", zap.String("server", serverConfig.Name), zap.String("runtime", runtimeType), diff --git a/internal/upstream/core/isolation_git_image_operator_test.go b/internal/upstream/core/isolation_git_image_operator_test.go new file mode 100644 index 000000000..605025813 --- /dev/null +++ b/internal/upstream/core/isolation_git_image_operator_test.go @@ -0,0 +1,116 @@ +package core + +import ( + "testing" + + "go.uber.org/zap" + "go.uber.org/zap/zaptest/observer" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +func gitDepServer(command string) *config.ServerConfig { + return &config.ServerConfig{ + Name: "git-server", + Command: command, + Args: []string{"--from", "srv@git+https://github.com/o/r", "srv"}, + } +} + +// A mirrored / air-gapped install retargets `default_images` at its own +// registry. When the git-capable key is absent from that map, falling back to a +// hardcoded public ghcr.io URL silently sends the container pull outside the +// operator's registry — an image that host cannot reach at all — and ignores +// the `uvx` entry they did configure. The operator's own map must win. +func TestGetDockerImage_AbsentGitKeyRespectsOperatorRuntimeDefault(t *testing.T) { + im := gitTestManager(map[string]string{ + "uvx": "mirror.internal/astral/uv:python3.13-bookworm", + "python": "mirror.internal/astral/uv:python3.13-bookworm", + "npx": "mirror.internal/library/node:22", + }) + + got, err := im.GetDockerImage(gitDepServer("uvx"), "uvx") + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got == gitUvImage { + t.Fatalf("GetDockerImage() = %q — a hardcoded public image the mirrored host cannot pull", got) + } + if got != "mirror.internal/astral/uv:python3.13-bookworm" { + t.Errorf("GetDockerImage() = %q, want the operator's configured uvx image", got) + } +} + +// An operator who does not want the substitution needs a way to say so without +// editing every server. An explicitly empty value for the key is that opt-out; +// treating empty as "absent" and substituting anyway leaves them no lever. +func TestGetDockerImage_EmptyGitKeyIsAnOptOut(t *testing.T) { + images := config.DefaultDockerIsolationConfig().DefaultImages + images[config.GitCapableImageKey] = "" + im := gitTestManager(images) + + got, err := im.GetDockerImage(gitDepServer("uvx"), "uvx") + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != slimUvImage { + t.Errorf("GetDockerImage() = %q, want the runtime default %q (substitution opted out)", got, slimUvImage) + } +} + +// The built-in git-capable image stays the fallback where there is nothing +// better to fall back TO: with no runtime entry the alternative is alpine, +// which has neither git nor python. +func TestGetDockerImage_NoRuntimeDefaultFallsBackToBuiltInGitImage(t *testing.T) { + im := gitTestManager(map[string]string{"npx": "node:22"}) + + got, err := im.GetDockerImage(gitDepServer("uvx"), "uvx") + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != gitUvImage { + t.Errorf("GetDockerImage() = %q, want the built-in git-capable fallback %q", got, gitUvImage) + } +} + +// The "we swapped your image" log line is the only warning a user gets before a +// multi-hundred-MB pull. It must track the substitution that actually happened, +// not the server merely qualifying for one. +func TestBuildDockerArgs_GitImageLogTracksTheRealSubstitution(t *testing.T) { + run := func(t *testing.T, images map[string]string) (logged bool, image string) { + t.Helper() + core, logs := observer.New(zap.InfoLevel) + global := config.DefaultDockerIsolationConfig() + global.Enabled = true + global.DefaultImages = images + im := NewIsolationManagerWithLogger(global, zap.New(core)) + + args, err := im.BuildDockerArgs(gitDepServer("uvx"), "uvx") + if err != nil { + t.Fatalf("BuildDockerArgs() error: %v", err) + } + return logs.FilterMessage("using git-capable isolation image for a git dependency").Len() > 0, args[len(args)-1] + } + + t.Run("substitution happens: say so", func(t *testing.T) { + logged, image := run(t, config.DefaultDockerIsolationConfig().DefaultImages) + if !logged { + t.Error("no log line for a substituted git-capable image") + } + if image != gitUvImage { + t.Errorf("image = %q, want %q", image, gitUvImage) + } + }) + + t.Run("opted out: stay quiet", func(t *testing.T) { + images := config.DefaultDockerIsolationConfig().DefaultImages + images[config.GitCapableImageKey] = "" + logged, image := run(t, images) + if logged { + t.Error("logged an image swap that did not happen") + } + if image != slimUvImage { + t.Errorf("image = %q, want the runtime default %q", image, slimUvImage) + } + }) +} diff --git a/internal/upstream/core/isolation_git_image_test.go b/internal/upstream/core/isolation_git_image_test.go index dc569c6a5..990ac4e27 100644 --- a/internal/upstream/core/isolation_git_image_test.go +++ b/internal/upstream/core/isolation_git_image_test.go @@ -103,10 +103,16 @@ func TestGetDockerImage_GitCapableKeyIsRetargetable(t *testing.T) { } } -// Upgrade path: configs written before this key existed still have a -// default_images map on disk, and it is NOT re-seeded on load. Falling through -// to the alpine fallback there would be worse than the bug we are fixing. -func TestGetDockerImage_LegacyConfigWithoutGitKeyStillResolves(t *testing.T) { +// Upgrade path. A config written before this key existed persists its own +// default_images map, but that map is decoded INTO the built-in one, so the +// key is present after load and the substitution happens +// (config.TestDefaultImagesMergeOverBuiltInsOnLoad pins the merge). +// +// Here the key is genuinely absent — a hand-built or PATCH-replaced map — and +// the operator's own entry for the runtime is the answer, not a hardcoded +// public image. See TestGetDockerImage_AbsentGitKeyRespectsOperatorRuntimeDefault +// for why: a mirrored host cannot pull ghcr.io at all. +func TestGetDockerImage_MapWithoutGitKeyUsesTheConfiguredRuntimeImage(t *testing.T) { legacy := map[string]string{ "uvx": slimUvImage, "python": slimUvImage, @@ -124,8 +130,8 @@ func TestGetDockerImage_LegacyConfigWithoutGitKeyStillResolves(t *testing.T) { if err != nil { t.Fatalf("GetDockerImage() error: %v", err) } - if got != gitUvImage { - t.Errorf("GetDockerImage() = %q, want the built-in git-capable fallback %q", got, gitUvImage) + if got != slimUvImage { + t.Errorf("GetDockerImage() = %q, want the configured runtime image %q", got, slimUvImage) } } From 7f660f6857cdbc571c65d9dcedf7132078bed257 Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Tue, 1 Sep 2026 08:20:53 +0300 Subject: [PATCH 3/7] fix(docker): let a mirrored registry win the git-capable image, and stop stderr noise hijacking codes (#1143, #1144) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/configuration.md | 2 +- docs/docker-isolation.md | 13 ++ docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md | 1 + docs/features/docker-isolation.md | 13 ++ internal/config/isolation_git.go | 48 +++++-- internal/diagnostics/classifier.go | 93 +++++++++++-- .../classifier_stderr_precedence_test.go | 115 ++++++++++++++++ internal/diagnostics/remediation.go | 32 ++++- .../remediation_mirrored_registry_test.go | 85 ++++++++++++ internal/upstream/core/isolation.go | 118 ++++++++++++----- .../core/isolation_git_image_loadpath_test.go | 124 ++++++++++++++++++ .../upstream/core/isolation_git_image_test.go | 22 ++-- 12 files changed, 596 insertions(+), 70 deletions(-) create mode 100644 internal/diagnostics/classifier_stderr_precedence_test.go create mode 100644 internal/diagnostics/remediation_mirrored_registry_test.go create mode 100644 internal/upstream/core/isolation_git_image_loadpath_test.go diff --git a/docs/configuration.md b/docs/configuration.md index 3584423cd..ee6e5b47e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -947,7 +947,7 @@ See [Logging Documentation](logging.md) for complete details. | Field | Type | Default | Description | |-------|------|---------|-------------| | `enabled` | boolean | `false` | Enable Docker isolation globally | -| `default_images` | object | See below | Map of runtime type to Docker image, merged over the built-in map (a partial map only overrides the keys it lists). The `uvx-git` entry is used instead of the Python default when a Python package runner installs from a `git+` URL (the slim uv image has no git); set it to `""` to opt out | +| `default_images` | object | See below | Map of runtime type to Docker image, merged over the built-in map (a partial map only overrides the keys it lists). The `uvx-git` entry is used instead of the Python default when a Python package runner installs from a `git+` URL (the slim uv image has no git); set it to `""` to opt out. If you retarget `uvx`/`python` at your own registry and leave `uvx-git` at its shipped value, your image is used rather than a public pull your host may not reach | | `registry` | string | `"docker.io"` | Docker registry to use | | `network_mode` | string | `"bridge"` | Docker network mode | | `memory_limit` | string | `"512m"` | Memory limit for containers | diff --git a/docs/docker-isolation.md b/docs/docker-isolation.md index 7aed3ec2a..db42676bd 100644 --- a/docs/docker-isolation.md +++ b/docs/docker-isolation.md @@ -160,6 +160,19 @@ the key to use your own mirror or a custom build: partial map like the one above only changes the keys it lists — every other runtime keeps its built-in image. +**Mirrored / air-gapped registries.** Because of that merge, `uvx-git` is +present in every install whether or not you wrote it, so MCPProxy decides by +*value*, not presence: if you have retargeted `uvx`/`python` at your own +registry and left `uvx-git` at its shipped `ghcr.io` value, that shipped value +is not treated as your choice — the server runs on **your** image instead of +pulling a public one your host may not be able to reach, and MCPProxy logs a +warning naming this key. Point `uvx-git` at a git-capable image in your registry +to get the substitution back: + +```json +{ "docker_isolation": { "default_images": { "uvx-git": "mirror.internal/astral/uv:python3.13-bookworm" } } } +``` + To turn the substitution off entirely, set the key to an empty string; those servers then keep whatever `uvx`/`python` image you configured: diff --git a/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md b/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md index bb7cbc66b..9309927ab 100644 --- a/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md +++ b/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md @@ -71,6 +71,7 @@ So if you still see this code, one of these applies: | The server pins `isolation.image` | The override opts out of the automatic selection. Remove it, or pin an image that ships the tool. | | `default_images.uvx-git` was retargeted to an image without git | Point it at an image that has git. | | `default_images.uvx-git` was set to `""` | That is the opt-out — the server keeps your `uvx`/`python` image. Remove the empty value, or pin an image that ships git. | +| You retargeted `default_images.uvx`/`python` at your own registry and left `uvx-git` at its shipped `ghcr.io` value | MCPProxy will not pull a public image behind a mirrored install, so the server ran on **your** image (a warning naming this key is in the log). Point `uvx-git` at a git-capable image in your registry. | | The server is a `node`/`npx` (or other non-Python) runner | The selection is Python-only, because `node:22` already ships git. Pin an `isolation.image` that has the tool. | | The missing tool is **not** git (e.g. `make`, `gcc`, `cargo`) | There is no automatic selection for it — pin an `isolation.image` that ships it. | | You are running an older MCPProxy | Upgrade, or set the image explicitly. | diff --git a/docs/features/docker-isolation.md b/docs/features/docker-isolation.md index a5c106434..4489b953f 100644 --- a/docs/features/docker-isolation.md +++ b/docs/features/docker-isolation.md @@ -153,6 +153,19 @@ the key to use your own mirror or a custom build: partial map like the one above only changes the keys it lists — every other runtime keeps its built-in image. +**Mirrored / air-gapped registries.** Because of that merge, `uvx-git` is +present in every install whether or not you wrote it, so MCPProxy decides by +*value*, not presence: if you have retargeted `uvx`/`python` at your own +registry and left `uvx-git` at its shipped `ghcr.io` value, that shipped value +is not treated as your choice — the server runs on **your** image instead of +pulling a public one your host may not be able to reach, and MCPProxy logs a +warning naming this key. Point `uvx-git` at a git-capable image in your registry +to get the substitution back: + +```json +{ "docker_isolation": { "default_images": { "uvx-git": "mirror.internal/astral/uv:python3.13-bookworm" } } } +``` + To turn the substitution off entirely, set the key to an empty string; those servers then keep whatever `uvx`/`python` image you configured: diff --git a/internal/config/isolation_git.go b/internal/config/isolation_git.go index 423833ef7..ba102ef22 100644 --- a/internal/config/isolation_git.go +++ b/internal/config/isolation_git.go @@ -1,6 +1,9 @@ package config -import "strings" +import ( + "strings" + "sync" +) // GitCapableImageKey is the `docker_isolation.default_images` key naming the // image used for Python package runners that install from a git URL. @@ -22,16 +25,43 @@ const GitCapableImageKey = "uvx-git" // DefaultGitCapableImage is the built-in value for GitCapableImageKey: the // non-slim uv image, which ships git (verified: git version 2.39.5). // -// A config file's `default_images` is decoded INTO this built-in map rather -// than replacing it, so the key survives an upgrade from a config written -// before it existed (TestDefaultImagesMergeOverBuiltInsOnLoad). The resolver -// therefore does NOT reach for this constant whenever the key is missing — -// doing so would pull a public ghcr.io image behind the back of a mirrored or -// air-gapped operator whose own `uvx` entry is right there. It is used only -// where the map has no answer at all; see -// core.IsolationManager.resolveDefaultImage. +// It is a PUBLIC ghcr.io URL, which makes it the wrong answer for a mirrored or +// air-gapped install: that host cannot pull it at all. Key absence is no +// protection either — a config file's `default_images` is decoded INTO the +// built-in map rather than replacing it, so this value is present in the merged +// map of every install, including one whose own `uvx` entry points at an +// internal registry (TestDefaultImagesMergeOverBuiltInsOnLoad). The resolver +// therefore treats "the key still holds this exact value" as "nobody chose it" +// and lets the operator's own runtime image win instead — see +// IsBuiltInDefaultImage and core.IsolationManager.resolveDefaultImage. const DefaultGitCapableImage = "ghcr.io/astral-sh/uv:python3.13-bookworm" +var ( + builtInImagesOnce sync.Once + builtInImages map[string]string +) + +// IsBuiltInDefaultImage reports whether image is exactly the value mcpproxy +// ships for that `default_images` key — i.e. whether the entry is still +// mcpproxy's own choice rather than the operator's. +// +// The comparison exists because the merge makes presence meaningless: every +// built-in key is present in every loaded config, so "is this key set?" cannot +// distinguish a deliberate operator choice from a shipped default, and treating +// a shipped default as a choice is how an air-gapped install ends up pulling a +// public image. Value equality is the distinction that survives the merge. +// +// An operator who deliberately configures the shipped value is not harmed by +// being read as "unset": every branch that consults this then falls back to +// their other entries, which point at the same place the shipped value does +// unless they are mirroring — in which case the mirror is what they wanted. +func IsBuiltInDefaultImage(key, image string) bool { + builtInImagesOnce.Do(func() { + builtInImages = DefaultDockerIsolationConfig().DefaultImages + }) + return builtInImages[key] == strings.TrimSpace(image) +} + // gitCapableRuntimeTypes are the runtime types whose default image is the // git-less slim uv image. Node's default (node:22) already ships git — verified // git version 2.39.5 — so npx/node git dependencies work today and must not be diff --git a/internal/diagnostics/classifier.go b/internal/diagnostics/classifier.go index 3692cd06a..351170cb1 100644 --- a/internal/diagnostics/classifier.go +++ b/internal/diagnostics/classifier.go @@ -211,8 +211,24 @@ func classifyDockerIsolatedSpawn(err error) Code { // kill anything, so it must not be promoted to the terminal cause and // outrank MCPX_STDIO_HANDSHAKE_TIMEOUT. A missing toolchain makes the // process EXIT, which is the other wrapper and is unaffected here. + // + // The guard covers EVERY arm that reads the stderr tail for a missing + // command — (2), (3) and (4) below. Guarding only some of them is + // decoration: the unguarded arm claims the failure exactly as the guarded + // ones would have. Arms (1) and (5) are exempt on purpose: "docker: command + // not found" and an OCI/runc failure describe the docker layer never + // starting a container, which cannot be true of a container that is alive + // and merely silent. toolchainSuppressed := isStdioHandshakeTimeout(msg) + // A shell reporting a BUILTIN missing (`sh: 1: source: not found`) is a + // portability bug in the server's own startup script — dash has no + // `source`, `shopt` or `pushd` — and says nothing about what the image + // contains. Treating it as evidence sends the user rebuilding a Docker + // image over a `#!/bin/sh` line, and hijacks the code that would have + // pointed at the stderr where the real cause is. + builtinOnly := onlyShellBuiltinsMissing(msg) + switch { // (1) docker binary unresolved: shellwrap resolution failure, or the shell // / Go exec layer reporting `docker` itself missing. Cover both shell @@ -239,12 +255,16 @@ func classifyDockerIsolatedSpawn(err error) Code { // enough to sit above (4) — which would otherwise answer the bash wording // of this exact failure with the ENTRYPOINT-missing code. Real OCI // entrypoint errors never carry a shell prefix, so they still fall to (4). - case !toolchainSuppressed && shellToolNotFoundRe.MatchString(msg): + case !toolchainSuppressed && !builtinOnly && shellToolNotFoundRe.MatchString(msg): return DockerMissingToolchain // (4) in-container interpreter missing (image lacks uvx/node/python/…). - case strings.Contains(msg, "executable file not found"), - strings.Contains(msg, "no such file or directory"), - strings.Contains(msg, "command not found"): + // Split in two so the builtin carve-out applies only to the wording a shell + // builtin line can produce: an OCI "executable file not found" is never one + // of those, and must still classify even next to a benign `source` line. + case !toolchainSuppressed && (strings.Contains(msg, "executable file not found") || + strings.Contains(msg, "no such file or directory")): + return DockerExecNotFound + case !toolchainSuppressed && !builtinOnly && strings.Contains(msg, "command not found"): return DockerExecNotFound // (5) other OCI runtime failures (arch mismatch, runc start failure). case strings.Contains(msg, "oci runtime"), @@ -257,8 +277,9 @@ func classifyDockerIsolatedSpawn(err error) Code { // isStdioHandshakeTimeout reports whether the error is the "the child is alive // but silent" wrapper (connection_lifecycle.go) rather than a process that -// died. Kept in lockstep with the MCPX_STDIO_HANDSHAKE_TIMEOUT arm of -// classifyStdio below. +// died. It is the single source for the MCPX_STDIO_HANDSHAKE_TIMEOUT arm of +// classifyStdio below and for the suppression guard above, so the two cannot +// drift apart. func isStdioHandshakeTimeout(msg string) bool { return strings.Contains(msg, "did not respond to mcp initialize") || strings.Contains(msg, "handshake timeout") @@ -282,7 +303,39 @@ func isStdioHandshakeTimeout(msg string) bool { // NOT matched here — it has no space after the shell's colon, and the generic // "command not found" arm already covers it. var shellToolNotFoundRe = regexp.MustCompile( - `(?:^|\s)(?:[\w./+-]*/)?(?:sh|bash|dash|ash|ksh|zsh|busybox)(?:\[\d+\])?: (?:(?:line )?\d+: )?(?:exec: )?[\w.+-]+: (?:command )?not found`) + `(?:^|\s)(?:[\w./+-]*/)?(?:sh|bash|dash|ash|ksh|zsh|busybox)(?:\[\d+\])?: (?:(?:line )?\d+: )?(?:exec: )?([\w.+-]+): (?:command )?not found`) + +// shellBuiltins are names a shell resolves ITSELF, so a ": not found" +// line for one of them means the script was written for another shell (almost +// always bash-isms run under dash/ash) — not that the image is missing a +// binary. No normal image ships these as executables, so nothing is lost by +// refusing to read them as a missing toolchain. +var shellBuiltins = map[string]bool{ + "source": true, "shopt": true, "pushd": true, "popd": true, "dirs": true, + "declare": true, "typeset": true, "local": true, "let": true, "alias": true, + "unalias": true, "bind": true, "complete": true, "compgen": true, + "mapfile": true, "readarray": true, "history": true, "caller": true, + "suspend": true, "enable": true, "builtin": true, "logout": true, + "disown": true, "coproc": true, "select": true, "function": true, +} + +// onlyShellBuiltinsMissing reports whether a shell "missing command" line is +// present AND every command it names is a shell builtin. It is deliberately an +// ALL, not an ANY: a stderr tail carrying both `source: not found` and +// `cmake: not found` really is a missing toolchain, and the benign line must +// not cancel the real one. +func onlyShellBuiltinsMissing(msg string) bool { + matches := shellToolNotFoundRe.FindAllStringSubmatch(msg, -1) + if len(matches) == 0 { + return false + } + for _, m := range matches { + if !shellBuiltins[strings.ToLower(m[1])] { + return false + } + } + return true +} // gitCloneFailureCauses are causes of a failed git clone that are NOT a missing // git binary. `uv` collapses them all into "Git operation failed", so without @@ -406,9 +459,28 @@ func classifyStdio(err error, hints ClassifierHints) Code { case strings.Contains(lmsg, "exec format error") && !strings.Contains(lmsg, "oci runtime") && !strings.Contains(lmsg, "runc"): return STDIOSpawnExecFormat + // The handshake-timeout wrapper is mcpproxy's OWN phrasing and means + // the child is alive: it outranks every arm below, all of which read + // the attached stderr TAIL and would otherwise let a line the child + // logged and survived decide the diagnosis. Same reasoning as the + // toolchainSuppressed guard in classifyDockerIsolatedSpawn — and it + // has to sit here too, or suppressing the docker arm just hands the + // same stderr line to this one. + case isStdioHandshakeTimeout(lmsg): + return STDIOHandshakeTimeout + // A git/ssh CREDENTIAL failure during a dependency install. `git@host: + // Permission denied (publickey).` contains "permission denied", which + // the EACCES arm below reads as the server's own executable being + // unreadable — chmod advice for a file that is fine, while the real + // cause (no key for a private repo) sits in the stderr. git RAN and the + // child then died, so it belongs with the other git-clone failures on + // EXIT_BEFORE_INITIALIZE, whose remediation points at that stderr. + case strings.Contains(lmsg, "permission denied (publickey)"): + return STDIOExitBeforeInitialize case strings.Contains(lmsg, "no such file or directory"), - strings.Contains(lmsg, "executable file not found"), - strings.Contains(lmsg, "command not found"): + strings.Contains(lmsg, "executable file not found"): + return STDIOSpawnENOENT + case strings.Contains(lmsg, "command not found") && !onlyShellBuiltinsMissing(lmsg): return STDIOSpawnENOENT case strings.Contains(lmsg, "permission denied"): return STDIOSpawnEACCES @@ -423,9 +495,6 @@ func classifyStdio(err error, hints ClassifierHints) Code { strings.Contains(lmsg, "exited before completing the mcp initialize"), strings.Contains(lmsg, "exited before the mcp initialize"): return STDIOExitBeforeInitialize - case strings.Contains(lmsg, "did not respond to mcp initialize"), - strings.Contains(lmsg, "handshake timeout"): - return STDIOHandshakeTimeout case strings.Contains(lmsg, "invalid handshake"), strings.Contains(lmsg, "malformed"): return STDIOHandshakeInvalid diff --git a/internal/diagnostics/classifier_stderr_precedence_test.go b/internal/diagnostics/classifier_stderr_precedence_test.go new file mode 100644 index 000000000..38c6cf64d --- /dev/null +++ b/internal/diagnostics/classifier_stderr_precedence_test.go @@ -0,0 +1,115 @@ +package diagnostics + +import ( + "errors" + "testing" +) + +// The stderr tail mcpproxy attaches to a failure is a TAIL: it carries whatever +// the server logged before it stopped, most of it benign. Every arm that reads +// that tail for a "missing command" needs the same guard, or the guard is +// decoration — the one unguarded arm claims the failure exactly as the guarded +// ones would have. +// +// A handshake TIMEOUT is the case where this matters most: the container is +// still running, so nothing in the tail killed it and nothing in the tail may +// outrank MCPX_STDIO_HANDSHAKE_TIMEOUT. +func TestHandshakeTimeoutOutranksEveryStderrNoiseArm(t *testing.T) { + const wrapper = "server did not respond to MCP initialize within 30s (subprocess may have " + + "crashed or printed to stderr instead of stdout); recent stderr:\n" + + stderrTails := []string{ + "warn: /etc/mcp/profile.d/10-init: no such file or directory", + "mise warn: mise: executable file not found, continuing without it", + "/bin/sh: 1: source: not found", + "bash: line 3: shopt: command not found", + } + + for _, hints := range []ClassifierHints{ + {Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"}, + {Transport: "stdio"}, + } { + for _, tail := range stderrTails { + err := errors.New(wrapper + tail + "\n") + if got := Classify(err, hints); got != STDIOHandshakeTimeout { + t.Errorf("Classify(isolated=%v, tail=%q) = %q, want %q", + hints.DockerIsolated, tail, got, STDIOHandshakeTimeout) + } + } + } +} + +// A shell reporting a BUILTIN missing is a portability bug in the server's own +// startup script — dash has no `source`, no `shopt`, no `pushd` — and says +// nothing about what the image contains. Diagnosing it as a missing container +// toolchain sends the user rebuilding a Docker image over a `#!/bin/sh` line. +func TestShellBuiltinNotFoundIsNotAMissingToolchain(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + for _, line := range []string{ + "/bin/sh: 1: source: not found", + "sh: 1: shopt: not found", + "sh: 1: pushd: not found", + "dash: 1: declare: not found", + "bash: line 1: source: command not found", + } { + err := errors.New("server process exited before completing the MCP initialize handshake; " + + "recent stderr:\n" + line + "\n: transport closed") + got := Classify(err, hints) + if got == DockerMissingToolchain || got == DockerExecNotFound { + t.Errorf("Classify(%q) = %q — a shell builtin is not evidence the image lacks a toolchain", line, got) + } + if got != STDIOExitBeforeInitialize { + t.Errorf("Classify(%q) = %q, want %q", line, got, STDIOExitBeforeInitialize) + } + } +} + +// A real missing tool must still reach the toolchain code — the builtin guard +// is a carve-out, not an off switch. +func TestRealMissingToolStillReachesTheToolchainCode(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + for _, line := range []string{ + "sh: 1: cmake: not found", + "bash: line 1: gcc: command not found", + "/bin/sh: 1: exec: git: not found", + "sh: 1: source: not found\nsh: 1: cmake: not found", + } { + err := errors.New("server process exited before completing the MCP initialize handshake; " + + "recent stderr:\n" + line + "\n: transport closed") + if got := Classify(err, hints); got != DockerMissingToolchain { + t.Errorf("Classify(%q) = %q, want %q", line, got, DockerMissingToolchain) + } + } +} + +// `git@github.com: Permission denied (publickey).` is a git SSH CREDENTIAL +// failure. It contains "permission denied", which the generic stdio arm reads +// as the server's own executable being unreadable — so the user is told to fix +// file permissions on a binary that is fine, while the real cause (no deploy +// key for a private repo) is sitting in the stderr the code never points at. +// It must land where the other thirteen git-clone failure wordings land. +func TestGitSSHAuthFailureIsNotDiagnosedAsAFilePermissionProblem(t *testing.T) { + wrap := func(cause string) error { + return errors.New("server process exited before completing the MCP initialize handshake; recent stderr:\n" + + " × Failed to resolve `--with` requirement\n ╰─▶ Git operation failed\n ╰─▶ " + cause + + "\n: transport closed") + } + + for _, hints := range []ClassifierHints{ + {Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"}, + {Transport: "stdio"}, + } { + got := Classify(wrap("git@github.com: Permission denied (publickey)."), hints) + if got == STDIOSpawnEACCES { + t.Errorf("Classify(isolated=%v) = %q — blames file permissions for a git auth failure", + hints.DockerIsolated, got) + } + want := Classify(wrap("remote: Invalid username or password."), hints) + if got != want { + t.Errorf("Classify(publickey, isolated=%v) = %q, want %q — the same as its sibling git auth wordings", + hints.DockerIsolated, got, want) + } + } +} diff --git a/internal/diagnostics/remediation.go b/internal/diagnostics/remediation.go index 3e0100286..51c5877d8 100644 --- a/internal/diagnostics/remediation.go +++ b/internal/diagnostics/remediation.go @@ -120,6 +120,22 @@ func detectDockerRuntimeType(command string) string { // together. const gitCapableImageKey = "uvx-git" +// builtInGitCapableImage / builtInPythonRunnerImage mirror the VALUES config +// ships for the git-capable key and for every Python package runner. +// +// Values, not presence, are what say whether mcpproxy's automatic selection +// actually ran: a config file's `default_images` is merged INTO the built-in +// map, so both keys are populated in every install, and an operator who +// retargeted their runtime at a mirror keeps a shipped `uvx-git` they never +// chose. In that case core.IsolationManager.resolveDefaultImage deliberately +// does NOT substitute — it will not pull a public image behind a mirrored host +// — so claiming an automatic swap here would name an image the install never +// ran. TestMirroredBuiltInImagesMatchConfig pins these to config. +const ( + builtInGitCapableImage = "ghcr.io/astral-sh/uv:python3.13-bookworm" + builtInPythonRunnerImage = "ghcr.io/astral-sh/uv:python3.13-bookworm-slim" +) + // missingToolchainRemediation explains a DockerMissingToolchain failure: the // container ran, but the image lacks a tool the server calls. The git case is // special — mcpproxy now selects a git-capable image automatically (#1143), so @@ -149,13 +165,27 @@ func missingToolchainRemediation(hints ClassifierHints) string { return b.String() } - gitImage := hints.DockerDefaultImages[gitCapableImageKey] + rawGitImage, gitKeySet := hints.DockerDefaultImages[gitCapableImageKey] + gitImage := strings.TrimSpace(rawGitImage) + runtimeImage := strings.TrimSpace(hints.DockerDefaultImages[runtimeType]) + // An explicitly emptied key is the documented opt-out, not an absent one. + optedOut := gitKeySet && gitImage == "" + // The operator retargeted this runtime at their own registry and left the + // git key at the value mcpproxy ships: no substitution happened, and the + // server ran on their image. Mirrors the resolver's own rule. + deferredToRuntimeImage := !optedOut && runtimeImage != "" && runtimeImage != builtInPythonRunnerImage && + (gitImage == "" || gitImage == builtInGitCapableImage) + b.WriteString(" It installs from a git URL, so the image must contain `git`.") switch { case override != "" && gitImage != "": fmt.Fprintf(&b, " The per-server `isolation.image` override `%s` is the likely culprit: it opts out of the automatic git-capable image selection. Remove the override to inherit `%s`, or pin an image that ships git.", override, gitImage) case override != "": fmt.Fprintf(&b, " The per-server `isolation.image` override `%s` is the likely culprit: it opts out of the automatic git-capable image selection. Remove the override, or pin an image that ships git.", override) + case optedOut: + fmt.Fprintf(&b, " `docker_isolation.default_images.%s` is set to `\"\"`, which opts out of the automatic git-capable image selection, so this server runs on your `%s` image. Remove the empty value, or point that key at an image that ships git.", gitCapableImageKey, runtimeType) + case deferredToRuntimeImage: + fmt.Fprintf(&b, " No git-capable image was substituted here: your `%s` entry (`%s`) is not the image mcpproxy ships, so this install pulls from its own registry and mcpproxy kept the server on your image rather than reaching outside it for the public default. Set `docker_isolation.default_images.%s` to an image in your registry that ships git.", runtimeType, runtimeImage, gitCapableImageKey) case gitImage != "": fmt.Fprintf(&b, " mcpproxy selects a git-capable image (`%s`, from `docker_isolation.default_images.%s`) automatically for git dependencies — if this still fails, that key points at an image without git, or this server is running an older mcpproxy.", gitImage, gitCapableImageKey) default: diff --git a/internal/diagnostics/remediation_mirrored_registry_test.go b/internal/diagnostics/remediation_mirrored_registry_test.go new file mode 100644 index 000000000..9e8944bca --- /dev/null +++ b/internal/diagnostics/remediation_mirrored_registry_test.go @@ -0,0 +1,85 @@ +package diagnostics + +import ( + "strings" + "testing" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +// A mirrored install does NOT get the public git-capable image: mcpproxy leaves +// the server on the operator's own configured image rather than attempting a +// pull their host cannot make. The remediation must describe that, or it names +// an image this install never ran and calls it "automatic" — sending the +// operator looking for a pull that never happened instead of at the one key +// that fixes it. +func TestMissingToolchainRemediationDoesNotClaimASubstitutionThatDidNotHappen(t *testing.T) { + const mirrored = "mirror.internal/astral/uv:python3.13-bookworm-slim" + hints := ClassifierHints{ + Transport: "stdio", + DockerIsolated: true, + DockerCommand: "uvx", + DockerArgs: []string{"--from", "srv@git+https://github.com/o/r", "srv"}, + // Exactly what a mirrored config looks like after load: the operator's + // runtime entry, and the git key still holding its shipped value + // because the merge put it there. + DockerDefaultImages: map[string]string{ + "uvx": mirrored, + "uvx-git": config.DefaultGitCapableImage, + }, + } + + msg := RuntimeAwareRemediation(DockerMissingToolchain, hints) + if msg == "" { + t.Fatal("no runtime-aware remediation for a git-dependency server") + } + if strings.Contains(msg, config.DefaultGitCapableImage) { + t.Errorf("remediation names a public image this install never ran: %s", msg) + } + if !strings.Contains(msg, mirrored) { + t.Errorf("remediation does not name the image the server actually ran: %s", msg) + } + if !strings.Contains(msg, gitCapableImageKey) { + t.Errorf("remediation does not name the key that fixes it: %s", msg) + } +} + +// The mirrored built-in values this package compares against must match the +// ones config actually ships, or the "did mcpproxy substitute?" question is +// answered from stale strings. +func TestMirroredBuiltInImagesMatchConfig(t *testing.T) { + images := config.DefaultDockerIsolationConfig().DefaultImages + if builtInGitCapableImage != config.DefaultGitCapableImage { + t.Errorf("builtInGitCapableImage = %q, config ships %q", builtInGitCapableImage, config.DefaultGitCapableImage) + } + for runtimeType := range gitCapableRuntimeTypes { + if got := images[runtimeType]; got != builtInPythonRunnerImage { + t.Errorf("built-in default_images[%q] = %q, mirrored value is %q — the mirror is stale", + runtimeType, got, builtInPythonRunnerImage) + } + } +} + +// The documented opt-out (`uvx-git: ""`) is the one case where the key is +// present and empty. Telling that user mcpproxy "selects a git-capable image +// automatically" describes the behaviour they explicitly turned off. +func TestMissingToolchainRemediationNamesTheOptOut(t *testing.T) { + hints := ClassifierHints{ + Transport: "stdio", + DockerIsolated: true, + DockerCommand: "uvx", + DockerArgs: []string{"--from", "srv@git+https://github.com/o/r", "srv"}, + DockerDefaultImages: map[string]string{ + "uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", + "uvx-git": "", + }, + } + + msg := RuntimeAwareRemediation(DockerMissingToolchain, hints) + if !strings.Contains(msg, gitCapableImageKey) { + t.Errorf("remediation does not name the key that was emptied: %s", msg) + } + if !strings.Contains(strings.ToLower(msg), "opts out") { + t.Errorf("remediation does not say the selection is opted out: %s", msg) + } +} diff --git a/internal/upstream/core/isolation.go b/internal/upstream/core/isolation.go index 997cbb13f..0228d4586 100644 --- a/internal/upstream/core/isolation.go +++ b/internal/upstream/core/isolation.go @@ -262,7 +262,10 @@ func (im *IsolationManager) DetectRuntimeType(command string) string { // 1. the per-server `isolation.image` override — an explicit user choice // always wins; // 2. the git-capable image, when the server is a Python package runner -// installing from a git URL (#1143 — see resolveDefaultImage); +// installing from a git URL AND nothing in `default_images` has been +// retargeted at the operator's own registry (#1143 — see +// resolveDefaultImage, which explains why a mirrored install keeps its own +// image instead); // 3. the runtime type's entry in `default_images`; // 4. alpine, for unknown runtime types. func (im *IsolationManager) GetDockerImage(serverConfig *config.ServerConfig, runtimeType string) (string, error) { @@ -275,10 +278,27 @@ func (im *IsolationManager) GetDockerImage(serverConfig *config.ServerConfig, ru return image, nil } +// gitImageDecision records what the git-capable image selection did for a +// server, so the spawn path can log the right thing — and, for the case where +// the selection stands down, log anything at all. +type gitImageDecision int + +const ( + // gitImageNotApplicable: no git dependency, or the operator opted out by + // emptying the key. + gitImageNotApplicable gitImageDecision = iota + // gitImageSubstituted: a git-capable image was swapped in for this server. + gitImageSubstituted + // gitImageDeferredToRuntime: the server needs git, but the operator has + // retargeted this runtime at their own registry and named no git-capable + // image, so their image stands and they are told which key to set. + gitImageDeferredToRuntime +) + // resolveDefaultImage computes the image a server gets from the GLOBAL config // — per-server `isolation.image` overrides are handled by the caller. The -// second return value reports whether the git-capable image was substituted, -// so the spawn path can say why it is pulling a much larger image. +// second return value reports what the git-capable selection did, so the spawn +// path can say why it is pulling a much larger image, or why it is not. // // The substitution exists because the Python default is Astral's slim uv image, // which contains no git; a `uvx --from …git+https://…` server therefore died @@ -287,45 +307,59 @@ func (im *IsolationManager) GetDockerImage(serverConfig *config.ServerConfig, ru // ~1.5GB pull for a case many never hit, so the swap is scoped to the servers // whose args actually reference a git URL. // -// The operator's `default_images` map is authoritative throughout. In -// particular the substitution NEVER reaches past it to a hardcoded public -// image while the map has an answer: a mirrored or air-gapped install -// retargets these keys at its own registry, and pulling ghcr.io behind its back -// is an image that host cannot fetch at all. So: +// The operator's `default_images` map is authoritative throughout: the +// substitution never reaches past it to a PUBLIC image that a mirrored or +// air-gapped host cannot fetch at all. Key presence cannot express that, +// because a config file's `default_images` is decoded INTO the built-in map — +// the key is present in every install (TestDefaultImagesMergeOverBuiltInsOnLoad) +// — so the question asked is whose VALUE it holds (config.IsBuiltInDefaultImage): // -// - key set → use it (the operator retargeted the git image); -// - key set to "" → opt out, keep the runtime default (the lever for an -// operator who does not want a second large image); -// - key absent → the runtime's own configured image, exactly as before -// #1143. On the real upgrade path the key is never absent: a config file's -// `default_images` is decoded INTO the built-in map, so the built-in entry -// survives (TestDefaultImagesMergeOverBuiltInsOnLoad); -// - key absent AND no runtime image → the built-in git-capable image, because -// the only alternative there is the alpine fallback, which has neither git -// nor python. -func (im *IsolationManager) resolveDefaultImage(serverConfig *config.ServerConfig, runtimeType string) (image string, gitSubstituted bool) { +// - git key holds an operator value → use it, whatever else is configured; +// - git key emptied → opt out, keep the runtime default (the +// lever for an operator who does not want a second large image); +// - git key still mcpproxy's own value, and the runtime image is too → the +// built-in git-capable image. Nothing here is mirrored, so a public pull is +// what this install already does for every other image; +// - git key still mcpproxy's own value, but the operator retargeted the +// RUNTIME at their registry → their image stands. It may or may not contain +// git; that is diagnosable (MCPX_DOCKER_MISSING_TOOLCHAIN names the key to +// set, and BuildDockerArgs warns on spawn), whereas a pull their host +// cannot make is a failure with no path forward. +func (im *IsolationManager) resolveDefaultImage(serverConfig *config.ServerConfig, runtimeType string) (image string, decision gitImageDecision) { runtimeImage, runtimeExists := im.globalConfig.DefaultImages[runtimeType] + runtimeImage = strings.TrimSpace(runtimeImage) needsGit := serverConfig != nil && config.NeedsGitCapableImage(runtimeType, serverConfig.Args) if needsGit { gitImage, gitKeySet := im.globalConfig.DefaultImages[config.GitCapableImageKey] + gitImage = strings.TrimSpace(gitImage) + operatorChoseGitImage := gitImage != "" && + !config.IsBuiltInDefaultImage(config.GitCapableImageKey, gitImage) + operatorChoseRuntimeImage := runtimeExists && runtimeImage != "" && + !config.IsBuiltInDefaultImage(runtimeType, runtimeImage) + switch { - case strings.TrimSpace(gitImage) != "": - return im.buildFullImageName(gitImage), true - case gitKeySet: + case operatorChoseGitImage: + return im.buildFullImageName(gitImage), gitImageSubstituted + case gitKeySet && gitImage == "": // Explicitly emptied: the operator opted out of the substitution. - case !runtimeExists || strings.TrimSpace(runtimeImage) == "": - return im.buildFullImageName(config.DefaultGitCapableImage), true + case operatorChoseRuntimeImage: + return im.buildFullImageName(runtimeImage), gitImageDeferredToRuntime + default: + // Nothing is retargeted (or there is no runtime entry at all, where + // the only alternative is the alpine fallback, which has neither + // git nor python). + return im.buildFullImageName(config.DefaultGitCapableImage), gitImageSubstituted } } // Use default image from global config if runtimeExists { - return im.buildFullImageName(runtimeImage), false + return im.buildFullImageName(runtimeImage), gitImageNotApplicable } // Fallback to alpine for unknown runtime types - return im.buildFullImageName("alpine:3.18"), false + return im.buildFullImageName("alpine:3.18"), gitImageNotApplicable } // ResolvedIsolationDefaults captures the per-runtime default values that @@ -434,16 +468,30 @@ func (im *IsolationManager) BuildDockerArgs(serverConfig *config.ServerConfig, r // substitution ACTUALLY happened, not merely on the server qualifying for // it: an operator who emptied the key opted out, and logging a swap that // did not occur would send them looking for a pull that never runs. - gitSubstituted := false + decision := gitImageNotApplicable if !hasImageOverride(serverConfig) { - _, gitSubstituted = im.resolveDefaultImage(serverConfig, runtimeType) - } - if im.logger != nil && gitSubstituted { - im.logger.Info("using git-capable isolation image for a git dependency", - zap.String("server", serverConfig.Name), - zap.String("runtime", runtimeType), - zap.String("image", image), - zap.String("hint", "override docker_isolation.default_images."+config.GitCapableImageKey+" to use a different image")) + _, decision = im.resolveDefaultImage(serverConfig, runtimeType) + } + if im.logger != nil { + switch decision { + case gitImageSubstituted: + im.logger.Info("using git-capable isolation image for a git dependency", + zap.String("server", serverConfig.Name), + zap.String("runtime", runtimeType), + zap.String("image", image), + zap.String("hint", "override docker_isolation.default_images."+config.GitCapableImageKey+" to use a different image")) + case gitImageDeferredToRuntime: + // The operator's registry wins over a public image they may not be + // able to reach — but they get told which key makes the choice + // explicit, because their image may have no git either. + im.logger.Warn("git dependency running on the configured runtime image", + zap.String("server", serverConfig.Name), + zap.String("runtime", runtimeType), + zap.String("image", image), + zap.String("hint", "this server installs from a git URL; set docker_isolation.default_images."+ + config.GitCapableImageKey+" to an image in your registry that ships git if it fails to resolve")) + case gitImageNotApplicable: + } } args := []string{"run", "--rm", "-i"} diff --git a/internal/upstream/core/isolation_git_image_loadpath_test.go b/internal/upstream/core/isolation_git_image_loadpath_test.go new file mode 100644 index 000000000..c24abc95d --- /dev/null +++ b/internal/upstream/core/isolation_git_image_loadpath_test.go @@ -0,0 +1,124 @@ +package core + +import ( + "os" + "path/filepath" + "strings" + "testing" + + "go.uber.org/zap" + "go.uber.org/zap/zaptest/observer" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +const mirroredUvImage = "mirror.internal/astral/uv:python3.13-bookworm-slim" + +// THE REAL PATH. Everything else in this package builds the merged +// `default_images` map by hand, which is exactly where the previous fix hid: an +// operator's config file goes through LoadFromFile, whose decode merges INTO the +// built-in map, so the git-capable key is never absent and the "key absent → +// use the operator's own image" branch never runs. On that path a mirrored / +// air-gapped install still resolved a hardcoded public ghcr.io image — one its +// host cannot pull at all — while its own `default_images.uvx` sat unused. +func TestLoadedConfigWithMirroredImagesNeverResolvesAPublicGitImage(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, config.ConfigFileName) + // Note what is NOT here: `uvx-git`. This is what an operator who mirrored + // their registry before the key existed (or never heard of it) has on disk. + body := `{ + "listen": "127.0.0.1:8080", + "data_dir": "` + strings.ReplaceAll(dir, `\`, `\\`) + `", + "docker_isolation": { + "enabled": true, + "registry": "mirror.internal", + "default_images": { + "uvx": "` + mirroredUvImage + `", + "python": "` + mirroredUvImage + `", + "npx": "mirror.internal/library/node:22" + } + } + }` + if err := os.WriteFile(path, []byte(body), 0600); err != nil { + t.Fatal(err) + } + + cfg, err := config.LoadFromFile(path) + if err != nil { + t.Fatalf("LoadFromFile() error: %v", err) + } + + core, logs := observer.New(zap.InfoLevel) + im := NewIsolationManagerWithLogger(cfg.DockerIsolation, zap.New(core)) + srv := gitDepServer("uvx") + + got, err := im.GetDockerImage(srv, "uvx") + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if strings.Contains(got, "ghcr.io") { + t.Fatalf("GetDockerImage() = %q — a public image an air-gapped host cannot pull", got) + } + if got != mirroredUvImage { + t.Errorf("GetDockerImage() = %q, want the operator's own %q", got, mirroredUvImage) + } + + // Silently running a git dependency on an image that may not contain git is + // no better than the wrong pull if the operator is never told which knob + // fixes it. + if _, err := im.BuildDockerArgs(srv, "uvx"); err != nil { + t.Fatalf("BuildDockerArgs() error: %v", err) + } + warned := logs.FilterMessageSnippet("git").Len() > 0 + if !warned { + t.Error("no log line naming the git-capable image key for a git dependency left on the operator's own image") + } + for _, e := range logs.All() { + for _, f := range e.Context { + if s, ok := f.Interface.(string); ok && strings.Contains(s, "ghcr.io") { + t.Errorf("log advertises a public image to a mirrored install: %s=%s", f.Key, s) + } + if strings.Contains(f.String, "ghcr.io") { + t.Errorf("log advertises a public image to a mirrored install: %s=%s", f.Key, f.String) + } + } + } +} + +// The seeded key is the same trap seen from the other side: the built-in value +// being present in the merged map must not outrank an operator who retargeted +// the runtime at their own registry. +func TestSeededGitKeyDoesNotOutrankAMirroredRuntimeImage(t *testing.T) { + images := config.DefaultDockerIsolationConfig().DefaultImages + if images[config.GitCapableImageKey] == "" { + t.Fatal("precondition: the built-in map is expected to seed the git-capable key") + } + images["uvx"] = mirroredUvImage + images["python"] = mirroredUvImage + + im := gitTestManager(images) + got, err := im.GetDockerImage(gitDepServer("uvx"), "uvx") + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != mirroredUvImage { + t.Errorf("GetDockerImage() = %q, want the operator's %q", got, mirroredUvImage) + } +} + +// …but an operator who names their own git-capable image still wins outright: +// that is the documented knob, and the whole point of honouring their map. +func TestOperatorGitKeyWinsOverTheirRuntimeImage(t *testing.T) { + images := config.DefaultDockerIsolationConfig().DefaultImages + images["uvx"] = mirroredUvImage + images[config.GitCapableImageKey] = "mirror.internal/astral/uv:python3.13-bookworm" + + im := gitTestManager(images) + got, err := im.GetDockerImage(gitDepServer("uvx"), "uvx") + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != "mirror.internal/astral/uv:python3.13-bookworm" { + t.Errorf("GetDockerImage() = %q, want the operator's git-capable image", got) + } +} diff --git a/internal/upstream/core/isolation_git_image_test.go b/internal/upstream/core/isolation_git_image_test.go index 990ac4e27..e8ca8311c 100644 --- a/internal/upstream/core/isolation_git_image_test.go +++ b/internal/upstream/core/isolation_git_image_test.go @@ -103,16 +103,14 @@ func TestGetDockerImage_GitCapableKeyIsRetargetable(t *testing.T) { } } -// Upgrade path. A config written before this key existed persists its own -// default_images map, but that map is decoded INTO the built-in one, so the -// key is present after load and the substitution happens -// (config.TestDefaultImagesMergeOverBuiltInsOnLoad pins the merge). -// -// Here the key is genuinely absent — a hand-built or PATCH-replaced map — and -// the operator's own entry for the runtime is the answer, not a hardcoded -// public image. See TestGetDockerImage_AbsentGitKeyRespectsOperatorRuntimeDefault -// for why: a mirrored host cannot pull ghcr.io at all. -func TestGetDockerImage_MapWithoutGitKeyUsesTheConfiguredRuntimeImage(t *testing.T) { +// Upgrade path with the key genuinely absent — a hand-built or PATCH-replaced +// map. What decides the answer is not the key's presence but whether anything +// here is the OPERATOR's: this map holds mcpproxy's own public images, so the +// install already pulls from ghcr.io and the git-capable image is reachable. +// The mirrored variant of this map is the opposite answer, and the reason the +// decision is made on values rather than presence — +// see TestGetDockerImage_AbsentGitKeyRespectsOperatorRuntimeDefault. +func TestGetDockerImage_MapWithoutGitKeyStillSubstitutesForBuiltInImages(t *testing.T) { legacy := map[string]string{ "uvx": slimUvImage, "python": slimUvImage, @@ -130,8 +128,8 @@ func TestGetDockerImage_MapWithoutGitKeyUsesTheConfiguredRuntimeImage(t *testing if err != nil { t.Fatalf("GetDockerImage() error: %v", err) } - if got != slimUvImage { - t.Errorf("GetDockerImage() = %q, want the configured runtime image %q", got, slimUvImage) + if got != gitUvImage { + t.Errorf("GetDockerImage() = %q, want the git-capable %q — nothing in this map is mirrored", got, gitUvImage) } } From 1205e6f04867d83ab64b93b68eb43c660595385f Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Tue, 1 Sep 2026 08:50:42 +0300 Subject: [PATCH 4/7] fix(diagnostics): key the docker-permission arm on daemon evidence, not the word "docker" (#1144) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- internal/diagnostics/classifier.go | 99 ++++++++-- .../classifier_docker_layer_test.go | 172 ++++++++++++++++++ 2 files changed, 255 insertions(+), 16 deletions(-) create mode 100644 internal/diagnostics/classifier_docker_layer_test.go diff --git a/internal/diagnostics/classifier.go b/internal/diagnostics/classifier.go index 351170cb1..1633bf6e1 100644 --- a/internal/diagnostics/classifier.go +++ b/internal/diagnostics/classifier.go @@ -106,22 +106,10 @@ func classifyOAuth(err error, _ ClassifierHints) Code { // preferred; these string matches are the last-resort fallback. func classifyDocker(err error, _ ClassifierHints) Code { msg := strings.ToLower(err.Error()) + if c := dockerLayerCode(msg); c != "" { + return c + } switch { - case strings.Contains(msg, "cannot connect to the docker daemon"), - strings.Contains(msg, "is the docker daemon running"), - strings.Contains(msg, "docker daemon is not reachable"), - strings.Contains(msg, "docker.sock: connect: no such file"): - return DockerDaemonDown - case strings.Contains(msg, "snap") && strings.Contains(msg, "apparmor"), - strings.Contains(msg, "no-new-privileges") && strings.Contains(msg, "apparmor"): - return DockerSnapAppArmor - case strings.Contains(msg, "permission denied") && strings.Contains(msg, "docker"), - strings.Contains(msg, "got permission denied while trying to connect to the docker"): - return DockerNoPermission - case strings.Contains(msg, "pull access denied"), - strings.Contains(msg, "docker") && strings.Contains(msg, "image") && strings.Contains(msg, "pull") && strings.Contains(msg, "fail"), - strings.Contains(msg, "manifest unknown"): - return DockerImagePullFailed // docker CLI unresolved (#696). These shapes are unambiguous about the // docker BINARY being missing, so they classify even without the // DockerIsolated hint (e.g. shellwrap's resolution-failure error). @@ -144,6 +132,63 @@ func classifyDocker(err error, _ ClassifierHints) Code { return "" } +// dockerLayerCode maps a failure of the DOCKER LAYER ITSELF — the daemon +// refusing us, not running, or unable to fetch the image — to a DOCKER code. +// It is shared by classifyDocker and the docker-isolated stdio path so the two +// cannot drift, and so a real daemon failure is not claimed first by a generic +// stdio arm (a socket refusal used to land on MCPX_STDIO_SPAWN_EACCES, i.e. +// chmod advice for a server binary that is fine). +// +// Every arm requires evidence the daemon or its socket actually spoke. See +// dockerDaemonEvidence for why the bare substring "docker" is not evidence. +func dockerLayerCode(msg string) Code { + switch { + case strings.Contains(msg, "cannot connect to the docker daemon"), + strings.Contains(msg, "is the docker daemon running"), + strings.Contains(msg, "docker daemon is not reachable"), + strings.Contains(msg, "docker.sock: connect: no such file"): + return DockerDaemonDown + case strings.Contains(msg, "snap") && strings.Contains(msg, "apparmor"), + strings.Contains(msg, "no-new-privileges") && strings.Contains(msg, "apparmor"): + return DockerSnapAppArmor + case (strings.Contains(msg, "permission denied") || strings.Contains(msg, "access is denied")) && + dockerDaemonEvidence(msg): + return DockerNoPermission + case strings.Contains(msg, "pull access denied"), + strings.Contains(msg, "manifest unknown"), + dockerDaemonEvidence(msg) && strings.Contains(msg, "image") && + strings.Contains(msg, "pull") && strings.Contains(msg, "fail"): + return DockerImagePullFailed + } + return "" +} + +// dockerDaemonEvidence reports whether the message carries evidence that the +// docker DAEMON or its SOCKET is what spoke — as opposed to the bare substring +// "docker", which is worthless here: mcpproxy's own stdio wrapper injects it +// into EVERY isolated error it formats +// +// stdio transport (command="/usr/local/bin/docker", docker_isolation=true): … +// +// so `permission denied && docker` was near-unfalsifiable under isolation. Any +// "permission denied" anywhere in the captured container stderr — a git deploy +// key rejected, a non-executable entrypoint — was diagnosed as a Docker socket +// permission problem and sent the user to fix socket permissions that were +// never broken (#1144). +// +// Everything listed here is text only the docker CLI, the daemon or a socket +// dial can produce; none of it appears in mcpproxy's wrapper. +func dockerDaemonEvidence(msg string) bool { + return strings.Contains(msg, "docker daemon") || + strings.Contains(msg, "docker.sock") || + strings.Contains(msg, "docker%2esock") || // URL-escaped in Post "http://%2Fvar%2Frun%2Fdocker.sock/…" + strings.Contains(msg, "pipe/docker_engine") || + strings.Contains(msg, `pipe\docker_engine`) || + strings.Contains(msg, "pipe%2fdocker_engine") || + strings.Contains(msg, "dockerd") || + strings.Contains(msg, "error response from daemon") +} + // classifyConfig recognises configuration parsing / secret resolution failures. func classifyConfig(err error, _ ClassifierHints) Code { msg := strings.ToLower(err.Error()) @@ -229,6 +274,13 @@ func classifyDockerIsolatedSpawn(err error) Code { // pointed at the stderr where the real cause is. builtinOnly := onlyShellBuiltinsMissing(msg) + // The docker LAYER failing — daemon refusing, absent, or unable to fetch + // the image — is decided before any stderr-tail reading, and is exempt from + // toolchainSuppressed for the same reason arms (1) and (5) are: it means no + // container ever started, which cannot be true of one that is alive and + // merely silent. + layerCode := dockerLayerCode(msg) + switch { // (1) docker binary unresolved: shellwrap resolution failure, or the shell // / Go exec layer reporting `docker` itself missing. Cover both shell @@ -242,6 +294,13 @@ func classifyDockerIsolatedSpawn(err error) Code { strings.Contains(msg, "docker not found in path"), strings.Contains(msg, "docker not found in login shell"): return DockerCLINotFound + // (1b) the docker daemon/socket refused us, is down, or could not pull the + // image. Must precede every stderr-tail arm below: `docker: permission + // denied while trying to connect to the Docker daemon socket …` otherwise + // fell through to the generic stdio "permission denied" arm and came back + // as MCPX_STDIO_SPAWN_EACCES. + case layerCode != "": + return layerCode // (2) a TOOL the server shells out to is missing from the image. git is // the case that matters in practice: the Python default image is slim and // has no git, so every `--from …git+https://…` server fails here (#1143). @@ -448,7 +507,15 @@ func classifyStdio(err error, hints ClassifierHints) Code { // exec.Error being present. These matches are intentionally broad and // err toward MCPX_STDIO_SPAWN_ENOENT / MCPX_STDIO_HANDSHAKE_TIMEOUT — // both are strictly better than MCPX_UNKNOWN_UNCLASSIFIED for the user. - if hints.Transport == "stdio" { + // DockerIsolated implies stdio: config.ResolveIsolation only resolves to + // mode=docker for a server that HAS a Command, i.e. a stdio server, and the + // isolated launch is `docker run …` over the stdio transport. Accepting the + // hint on its own keeps a caller that filled only DockerIsolated from + // skipping every arm below — which left mcpproxy's own wrappers ("exited + // before completing the MCP initialize handshake", "did not respond to MCP + // initialize") on MCPX_UNKNOWN_UNCLASSIFIED and its "file a bug report" + // CTA, with the loose docker arms as the only thing that could fire. + if hints.Transport == "stdio" || hints.DockerIsolated { msg := err.Error() lmsg := strings.ToLower(msg) switch { diff --git a/internal/diagnostics/classifier_docker_layer_test.go b/internal/diagnostics/classifier_docker_layer_test.go new file mode 100644 index 000000000..28dea1046 --- /dev/null +++ b/internal/diagnostics/classifier_docker_layer_test.go @@ -0,0 +1,172 @@ +package diagnostics + +import ( + "errors" + "fmt" + "testing" +) + +// wrapIsolated reproduces the EXACT error shape a Docker-isolated stdio server +// produces in production. connection_stdio.go wraps every isolated failure as +// +// stdio transport (command=%q, docker_isolation=%t): %w +// +// with the RESOLVED argv[0] — so the literal substring "docker" is present in +// every isolated error mcpproxy formats, regardless of what actually failed. +// Tests written against bare stderr fragments cannot see the arms that key on +// that substring, which is how #1144's misdiagnosis survived a re-review. +func wrapIsolated(inner string) error { + return fmt.Errorf(`stdio transport (command=%q, docker_isolation=%t): %s`, + "/usr/local/bin/docker", true, inner) +} + +// exitedWith builds the "child died before initialize" wrapper with a stderr tail. +func exitedWith(stderrTail string) string { + return "server process exited before completing the MCP initialize handshake; recent stderr:\n | " + + stderrTail + ": transport error: transport closed" +} + +// isolatedHintShapes are the two hint shapes a caller can plausibly build for a +// Docker-isolated server. The supervisor fills Transport from the resolved +// protocol, but DockerIsolated alone already implies stdio (config.ResolveIsolation +// only returns mode=docker for a server with a Command), so the classification +// must not depend on the caller having filled both. +var isolatedHintShapes = map[string]ClassifierHints{ + "transport+isolated": {Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"}, + "isolated only": {DockerIsolated: true, DockerCommand: "uvx"}, +} + +// A git SSH credential failure inside the container is a missing/unauthorised +// deploy key. Diagnosing it as "Docker permission denied" sends the user to +// their Docker socket permissions — the exact class of misleading diagnosis +// #1144 exists to remove. +func TestGitSSHFailureUnderIsolationIsNotADockerPermissionProblem(t *testing.T) { + err := wrapIsolated(exitedWith("git@github.com: Permission denied (publickey).")) + + for name, hints := range isolatedHintShapes { + got := Classify(err, hints) + if got == DockerNoPermission { + t.Errorf("[%s] Classify(publickey) = %q — the docker socket is fine; the git key is not", name, got) + } + if got != STDIOExitBeforeInitialize { + t.Errorf("[%s] Classify(publickey) = %q, want %q", name, got, STDIOExitBeforeInitialize) + } + } +} + +// The docker-permission arm must key on evidence that the DAEMON or its SOCKET +// refused us. Keyed on the bare substring "docker" it is near-unfalsifiable +// under isolation, because mcpproxy's own wrapper injects that substring: ANY +// "permission denied" anywhere in the captured container stderr became a Docker +// socket diagnosis. +func TestContainerSidePermissionDeniedIsNotADockerSocketProblem(t *testing.T) { + tails := []string{ + "git@github.com: Permission denied (publickey).", + "/app/entrypoint.sh: line 3: /usr/local/bin/serve: Permission denied", + "fatal: could not read Username for 'https://github.com': Permission denied", + } + + for _, tail := range tails { + err := wrapIsolated(exitedWith(tail)) + for name, hints := range isolatedHintShapes { + if got := Classify(err, hints); got == DockerNoPermission { + t.Errorf("[%s] Classify(%q) = %q — nothing here says the docker daemon refused us", + name, tail, got) + } + } + } +} + +// The other half of the same contract: a REAL docker daemon/socket refusal must +// still reach MCPX_DOCKER_NO_PERMISSION — including on the stdio-hinted path, +// where the generic "permission denied" → MCPX_STDIO_SPAWN_EACCES arm used to +// claim it first and offer chmod advice for a server binary that is fine. +func TestRealDockerDaemonRefusalsClassifyAsDockerLayerFailures(t *testing.T) { + cases := []struct { + name string + tail string + want Code + }{ + { + name: "socket permission denied", + tail: `docker: permission denied while trying to connect to the Docker daemon socket at ` + + `unix:///var/run/docker.sock: Post "http://%2Fvar%2Frun%2Fdocker.sock/v1.43/containers/create": ` + + `dial unix /var/run/docker.sock: connect: permission denied.`, + want: DockerNoPermission, + }, + { + name: "windows named pipe access denied", + tail: `docker: error during connect: Post "http://%2F%2F.%2Fpipe%2Fdocker_engine/v1.43/containers/create": ` + + `open //./pipe/docker_engine: Access is denied.`, + want: DockerNoPermission, + }, + { + name: "daemon not running", + tail: "docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.", + want: DockerDaemonDown, + }, + { + name: "pull access denied", + tail: "docker: Error response from daemon: pull access denied for acme/private-mcp, " + + "repository does not exist or may require 'docker login'.", + want: DockerImagePullFailed, + }, + } + + for _, tc := range cases { + err := wrapIsolated(exitedWith(tc.tail)) + for name, hints := range isolatedHintShapes { + if got := Classify(err, hints); got != tc.want { + t.Errorf("[%s] %s: Classify() = %q, want %q", name, tc.name, got, tc.want) + } + } + } +} + +// Benign stderr noise under isolation must land on an honest, actionable code +// rather than MCPX_UNKNOWN_UNCLASSIFIED, whose CTA is "file a bug report". +// Both shapes here are mcpproxy's OWN wrappers: the cause is in the stderr the +// EXIT_BEFORE_INITIALIZE / HANDSHAKE_TIMEOUT remediation points at. +func TestBenignStderrUnderIsolationStillReachesAnHonestCode(t *testing.T) { + cases := []struct { + name string + msg string + want Code + }{ + { + name: "dash has no source builtin, child died", + msg: exitedWith("/bin/sh: 1: source: not found"), + want: STDIOExitBeforeInitialize, + }, + { + name: "child alive but silent, benign warning in the tail", + msg: "server did not respond to MCP initialize within 30s; recent stderr:\n | warn: /etc/foo: no such file or directory", + want: STDIOHandshakeTimeout, + }, + } + + for _, tc := range cases { + err := wrapIsolated(tc.msg) + for name, hints := range isolatedHintShapes { + got := Classify(err, hints) + if got == UnknownUnclassified { + t.Errorf("[%s] %s: Classify() = %q — mcpproxy wrote this wrapper itself, it is not an unknown failure", + name, tc.name, got) + } + if got != tc.want { + t.Errorf("[%s] %s: Classify() = %q, want %q", name, tc.name, got, tc.want) + } + } + } +} + +// The classifier is exported and its hints are advisory. DockerIsolated alone +// must be enough to reach the stdio rules: config.ResolveIsolation only reports +// mode=docker for a server that has a Command, i.e. a stdio server. +func TestDockerIsolatedHintImpliesStdioRules(t *testing.T) { + err := errors.New(`stdio transport (command="/usr/local/bin/docker", docker_isolation=true): ` + + "transport error: transport closed") + if got := Classify(err, ClassifierHints{DockerIsolated: true}); got != STDIOExitBeforeInitialize { + t.Errorf("Classify(transport closed, isolated only) = %q, want %q", got, STDIOExitBeforeInitialize) + } +} From 94e71453fe0363b8f0dce68764897ca0a42945a4 Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Tue, 1 Sep 2026 09:18:29 +0300 Subject: [PATCH 5/7] fix(diagnostics): don't let a live container's stderr claim the docker daemon is down MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- internal/diagnostics/classifier.go | 19 ++++++++--- .../classifier_docker_layer_timeout_test.go | 34 +++++++++++++++++++ 2 files changed, 48 insertions(+), 5 deletions(-) create mode 100644 internal/diagnostics/classifier_docker_layer_timeout_test.go diff --git a/internal/diagnostics/classifier.go b/internal/diagnostics/classifier.go index 1633bf6e1..b89bfdf65 100644 --- a/internal/diagnostics/classifier.go +++ b/internal/diagnostics/classifier.go @@ -275,11 +275,20 @@ func classifyDockerIsolatedSpawn(err error) Code { builtinOnly := onlyShellBuiltinsMissing(msg) // The docker LAYER failing — daemon refusing, absent, or unable to fetch - // the image — is decided before any stderr-tail reading, and is exempt from - // toolchainSuppressed for the same reason arms (1) and (5) are: it means no - // container ever started, which cannot be true of one that is alive and - // merely silent. - layerCode := dockerLayerCode(msg) + // the image — is decided before any stderr-tail reading. + // + // It IS subject to toolchainSuppressed, unlike arms (1) and (5). A layer + // failure means no container ever started, so it cannot coexist with a + // handshake timeout, which means the container is alive and merely silent. + // When both appear, the daemon wording came from the container's OWN stderr + // tail — an application log line — and reporting MCPX_DOCKER_DAEMON_DOWN + // sends the user restarting Docker over a message their server printed. + // A genuine daemon refusal is unaffected: it surfaces on the exit path, + // where isStdioHandshakeTimeout is false. + var layerCode Code + if !toolchainSuppressed { + layerCode = dockerLayerCode(msg) + } switch { // (1) docker binary unresolved: shellwrap resolution failure, or the shell diff --git a/internal/diagnostics/classifier_docker_layer_timeout_test.go b/internal/diagnostics/classifier_docker_layer_timeout_test.go new file mode 100644 index 000000000..d6c907437 --- /dev/null +++ b/internal/diagnostics/classifier_docker_layer_timeout_test.go @@ -0,0 +1,34 @@ +package diagnostics + +import ( + "errors" + "testing" +) + +// A handshake timeout means the container IS alive and merely silent. Docker +// daemon wording appearing in that container's own stderr tail is therefore the +// server's log line, not evidence that OUR docker layer failed — a real daemon +// refusal never produces a handshake timeout, because no container would exist +// to time out. Reporting MCPX_DOCKER_DAEMON_DOWN there sends the user restarting +// Docker over an application log message. +func TestClassify_DockerLayerWordingInLiveContainerStderrDoesNotHijackTimeout(t *testing.T) { + const prefix = `stdio transport (command="/usr/local/bin/docker", docker_isolation=true): ` + const timeout = "server did not respond to MCP initialize within 30s (subprocess may have crashed); recent stderr:\n | " + + t.Run("daemon wording from the container's own log is not a layer failure", func(t *testing.T) { + err := errors.New(prefix + timeout + + "app log: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?") + if got := Classify(err, ClassifierHints{DockerIsolated: true}); got == DockerDaemonDown { + t.Fatalf("live container's stderr hijacked the diagnosis: got %s, want anything but %s", got, DockerDaemonDown) + } + }) + + t.Run("a genuine daemon refusal still classifies", func(t *testing.T) { + err := errors.New(prefix + + "server process exited before completing the MCP initialize handshake; recent stderr:\n | " + + "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?: transport error: transport closed") + if got := Classify(err, ClassifierHints{DockerIsolated: true}); got != DockerDaemonDown { + t.Fatalf("genuine daemon failure lost its code: got %s, want %s", got, DockerDaemonDown) + } + }) +} From 4a50dfd4c5cf9953d6df0f5dba79b828e0d3de8f Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Tue, 1 Sep 2026 10:01:51 +0300 Subject: [PATCH 6/7] fix(docker): guard every stderr-derived classifier arm, and let a mirror own the git image MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/configuration.md | 3 +- docs/docker-isolation.md | 31 +- docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md | 9 +- docs/features/docker-isolation.md | 31 +- internal/config/config.go | 14 +- internal/config/isolation_git.go | 65 ++-- internal/config/isolation_git_seed_test.go | 14 +- internal/config/isolation_git_test.go | 23 +- internal/diagnostics/classifier.go | 292 ++++++++++++------ .../classifier_exit_evidence_test.go | 59 ++++ .../classifier_git_evidence_test.go | 65 ++++ .../classifier_timeout_arm_audit_test.go | 93 ++++++ internal/diagnostics/remediation.go | 33 +- .../remediation_mirrored_registry_test.go | 12 +- .../isolation_classification_test.go | 11 +- internal/upstream/core/isolation.go | 66 ++-- .../core/isolation_git_image_explicit_test.go | 42 +++ .../core/isolation_git_image_loadpath_test.go | 14 +- .../core/isolation_git_image_registry_test.go | 67 ++++ 19 files changed, 714 insertions(+), 230 deletions(-) create mode 100644 internal/diagnostics/classifier_exit_evidence_test.go create mode 100644 internal/diagnostics/classifier_git_evidence_test.go create mode 100644 internal/diagnostics/classifier_timeout_arm_audit_test.go create mode 100644 internal/upstream/core/isolation_git_image_explicit_test.go create mode 100644 internal/upstream/core/isolation_git_image_registry_test.go diff --git a/docs/configuration.md b/docs/configuration.md index ee6e5b47e..2ad9e4c55 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -927,7 +927,6 @@ See [Logging Documentation](logging.md) for complete details. "default_images": { "python": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", "uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", - "uvx-git": "ghcr.io/astral-sh/uv:python3.13-bookworm", "node": "node:22", "npx": "node:22" }, @@ -947,7 +946,7 @@ See [Logging Documentation](logging.md) for complete details. | Field | Type | Default | Description | |-------|------|---------|-------------| | `enabled` | boolean | `false` | Enable Docker isolation globally | -| `default_images` | object | See below | Map of runtime type to Docker image, merged over the built-in map (a partial map only overrides the keys it lists). The `uvx-git` entry is used instead of the Python default when a Python package runner installs from a `git+` URL (the slim uv image has no git); set it to `""` to opt out. If you retarget `uvx`/`python` at your own registry and leave `uvx-git` at its shipped value, your image is used rather than a public pull your host may not reach | +| `default_images` | object | See below | Map of runtime type to Docker image, merged over the built-in map (a partial map only overrides the keys it lists). The optional `uvx-git` key — **not** part of the built-in map — overrides the git-capable image used instead of the Python default when a Python package runner installs from a `git+` URL (the slim uv image has no git); set it to `""` to opt out. Setting it always wins, including at the value MCPProxy ships. Leave it unset and MCPProxy picks the image: your own `uvx`/`python` image if you retargeted it at your registry, otherwise `ghcr.io/astral-sh/uv:python3.13-bookworm` — qualified with `registry` when you set one | | `registry` | string | `"docker.io"` | Docker registry to use | | `network_mode` | string | `"bridge"` | Docker network mode | | `memory_limit` | string | `"512m"` | Memory limit for containers | diff --git a/docs/docker-isolation.md b/docs/docker-isolation.md index db42676bd..8c7ca7d46 100644 --- a/docs/docker-isolation.md +++ b/docs/docker-isolation.md @@ -101,7 +101,6 @@ Add to your `~/.mcpproxy/mcp_config.json`: "uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", "pip": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", "pipx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", - "uvx-git": "ghcr.io/astral-sh/uv:python3.13-bookworm", "node": "node:22", "npm": "node:22", "npx": "node:22", @@ -132,7 +131,7 @@ Add to your `~/.mcpproxy/mcp_config.json`: | `timeout` | Container startup timeout | `"30s"` | | `network_mode` | Docker network mode | `"bridge"` | | `registry` | Docker registry to use | `"docker.io"` | -| `default_images` | Runtime to image mappings (including `uvx-git`, used when a Python runner installs from a `git+` URL) | See above | +| `default_images` | Runtime to image mappings. The optional `uvx-git` key (not shipped in the defaults) overrides the git-capable image used when a Python runner installs from a `git+` URL | See above | | `extra_args` | Additional docker run arguments | `[]` | ### Git dependencies (`uvx-git`) @@ -147,10 +146,10 @@ The Python default image is Astral's **slim** `uv` image, which does not contain — cannot resolve without it, and fails with `Git executable not found` / `Git operation failed` ([`MCPX_DOCKER_MISSING_TOOLCHAIN`](errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md)). -MCPProxy detects the `git+` URL in a Python package runner's arguments and uses -the **`uvx-git`** image (`ghcr.io/astral-sh/uv:python3.13-bookworm`, which ships -git) for that server only — everyone else keeps the small slim image. Retarget -the key to use your own mirror or a custom build: +MCPProxy detects the `git+` URL in a Python package runner's arguments and runs +that server only on a git-capable image — everyone else keeps the small slim +image. By default that is `ghcr.io/astral-sh/uv:python3.13-bookworm`, which +ships git. Set the **`uvx-git`** key to use your own mirror or a custom build: ```json { "docker_isolation": { "default_images": { "uvx-git": "my-registry.example/uv-git:1" } } } @@ -160,14 +159,18 @@ the key to use your own mirror or a custom build: partial map like the one above only changes the keys it lists — every other runtime keeps its built-in image. -**Mirrored / air-gapped registries.** Because of that merge, `uvx-git` is -present in every install whether or not you wrote it, so MCPProxy decides by -*value*, not presence: if you have retargeted `uvx`/`python` at your own -registry and left `uvx-git` at its shipped `ghcr.io` value, that shipped value -is not treated as your choice — the server runs on **your** image instead of -pulling a public one your host may not be able to reach, and MCPProxy logs a -warning naming this key. Point `uvx-git` at a git-capable image in your registry -to get the substitution back: +**Mirrored / air-gapped registries.** `uvx-git` is deliberately *not* part of +the built-in map, so its presence in your config means exactly one thing: you +chose that image, and it is used — even if you set it to the same public value +MCPProxy ships. Two things follow: + +- If you set `registry`, the built-in git-capable image is pulled from **your** + registry (`/astral-sh/uv:python3.13-bookworm`) rather than from + `ghcr.io`. +- If you retargeted `uvx`/`python` at your own registry and never set + `uvx-git`, the server runs on **your** image instead of MCPProxy reaching + outside your registry for a public one, and a warning naming this key is + logged. Point `uvx-git` at a git-capable image to get the substitution back: ```json { "docker_isolation": { "default_images": { "uvx-git": "mirror.internal/astral/uv:python3.13-bookworm" } } } diff --git a/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md b/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md index 9309927ab..d10208aa0 100644 --- a/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md +++ b/docs/errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md @@ -59,9 +59,10 @@ git version 2.39.5 ## Is this handled automatically? **Yes, for git dependencies with no per-server image override.** MCPProxy -detects a `git+` URL in a Python package runner's arguments and swaps in the -git-capable image named by `docker_isolation.default_images.uvx-git` -(`ghcr.io/astral-sh/uv:python3.13-bookworm` by default). Servers without a git +detects a `git+` URL in a Python package runner's arguments and swaps in a +git-capable image: whatever `docker_isolation.default_images.uvx-git` names if +you set it, otherwise `ghcr.io/astral-sh/uv:python3.13-bookworm` (pulled from +`docker_isolation.registry` when you configured one). Servers without a git dependency keep the small slim image. So if you still see this code, one of these applies: @@ -71,7 +72,7 @@ So if you still see this code, one of these applies: | The server pins `isolation.image` | The override opts out of the automatic selection. Remove it, or pin an image that ships the tool. | | `default_images.uvx-git` was retargeted to an image without git | Point it at an image that has git. | | `default_images.uvx-git` was set to `""` | That is the opt-out — the server keeps your `uvx`/`python` image. Remove the empty value, or pin an image that ships git. | -| You retargeted `default_images.uvx`/`python` at your own registry and left `uvx-git` at its shipped `ghcr.io` value | MCPProxy will not pull a public image behind a mirrored install, so the server ran on **your** image (a warning naming this key is in the log). Point `uvx-git` at a git-capable image in your registry. | +| You retargeted `default_images.uvx`/`python` at your own registry and never set `uvx-git` | MCPProxy will not pull a public image behind a mirrored install, so the server ran on **your** image (a warning naming this key is in the log). Point `uvx-git` at a git-capable image in your registry. | | The server is a `node`/`npx` (or other non-Python) runner | The selection is Python-only, because `node:22` already ships git. Pin an `isolation.image` that has the tool. | | The missing tool is **not** git (e.g. `make`, `gcc`, `cargo`) | There is no automatic selection for it — pin an `isolation.image` that ships it. | | You are running an older MCPProxy | Upgrade, or set the image explicitly. | diff --git a/docs/features/docker-isolation.md b/docs/features/docker-isolation.md index 4489b953f..45d380178 100644 --- a/docs/features/docker-isolation.md +++ b/docs/features/docker-isolation.md @@ -94,7 +94,6 @@ Add to your `~/.mcpproxy/mcp_config.json`: "uvx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", "pip": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", "pipx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", - "uvx-git": "ghcr.io/astral-sh/uv:python3.13-bookworm", "node": "node:22", "npm": "node:22", "npx": "node:22", @@ -125,7 +124,7 @@ Add to your `~/.mcpproxy/mcp_config.json`: | `timeout` | Container startup timeout | `"30s"` | | `network_mode` | Docker network mode | `"bridge"` | | `registry` | Docker registry to use | `"docker.io"` | -| `default_images` | Runtime to image mappings (including `uvx-git`, used when a Python runner installs from a `git+` URL) | See above | +| `default_images` | Runtime to image mappings. The optional `uvx-git` key (not shipped in the defaults) overrides the git-capable image used when a Python runner installs from a `git+` URL | See above | | `extra_args` | Additional docker run arguments | `[]` | ### Git dependencies (`uvx-git`) @@ -140,10 +139,10 @@ The Python default image is Astral's **slim** `uv` image, which does not contain — cannot resolve without it, and fails with `Git executable not found` / `Git operation failed` ([`MCPX_DOCKER_MISSING_TOOLCHAIN`](../errors/MCPX_DOCKER_MISSING_TOOLCHAIN.md)). -MCPProxy detects the `git+` URL in a Python package runner's arguments and uses -the **`uvx-git`** image (`ghcr.io/astral-sh/uv:python3.13-bookworm`, which ships -git) for that server only — everyone else keeps the small slim image. Retarget -the key to use your own mirror or a custom build: +MCPProxy detects the `git+` URL in a Python package runner's arguments and runs +that server only on a git-capable image — everyone else keeps the small slim +image. By default that is `ghcr.io/astral-sh/uv:python3.13-bookworm`, which +ships git. Set the **`uvx-git`** key to use your own mirror or a custom build: ```json { "docker_isolation": { "default_images": { "uvx-git": "my-registry.example/uv-git:1" } } } @@ -153,14 +152,18 @@ the key to use your own mirror or a custom build: partial map like the one above only changes the keys it lists — every other runtime keeps its built-in image. -**Mirrored / air-gapped registries.** Because of that merge, `uvx-git` is -present in every install whether or not you wrote it, so MCPProxy decides by -*value*, not presence: if you have retargeted `uvx`/`python` at your own -registry and left `uvx-git` at its shipped `ghcr.io` value, that shipped value -is not treated as your choice — the server runs on **your** image instead of -pulling a public one your host may not be able to reach, and MCPProxy logs a -warning naming this key. Point `uvx-git` at a git-capable image in your registry -to get the substitution back: +**Mirrored / air-gapped registries.** `uvx-git` is deliberately *not* part of +the built-in map, so its presence in your config means exactly one thing: you +chose that image, and it is used — even if you set it to the same public value +MCPProxy ships. Two things follow: + +- If you set `registry`, the built-in git-capable image is pulled from **your** + registry (`/astral-sh/uv:python3.13-bookworm`) rather than from + `ghcr.io`. +- If you retargeted `uvx`/`python` at your own registry and never set + `uvx-git`, the server runs on **your** image instead of MCPProxy reaching + outside your registry for a public one, and a warning naming this key is + logged. Point `uvx-git` at a git-capable image to get the substitution back: ```json { "docker_isolation": { "default_images": { "uvx-git": "mirror.internal/astral/uv:python3.13-bookworm" } } } diff --git a/internal/config/config.go b/internal/config/config.go index 55cc75bcf..401bfc29b 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -1560,11 +1560,15 @@ func DefaultDockerIsolationConfig() *DockerIsolationConfig { "pip": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", "pipx": "ghcr.io/astral-sh/uv:python3.13-bookworm-slim", - // Python + git: the slim image above has no git, so a server - // installed from a git URL (`uvx --from …git+https://…`) cannot - // resolve at all. Selected per-server by NeedsGitCapableImage — - // see internal/config/isolation_git.go (#1143). - GitCapableImageKey: DefaultGitCapableImage, + // NOTE: no GitCapableImageKey ("uvx-git") entry. The slim image + // above has no git, so a server installed from a git URL + // (`uvx --from …git+https://…`) cannot resolve at all, and + // mcpproxy substitutes a git-capable image per-server — but that + // substitution is decided in code (core.resolveDefaultImage), not + // by seeding a value here. Seeding it would write a public ghcr.io + // URL into every operator's config file on the next save and make + // the key's presence unable to mean "the operator chose this". + // See internal/config/isolation_git.go (#1143). // Node.js environments - full image for git deps and native modules (LTS until Apr 2028) "node": "node:22", diff --git a/internal/config/isolation_git.go b/internal/config/isolation_git.go index ba102ef22..b1af7c046 100644 --- a/internal/config/isolation_git.go +++ b/internal/config/isolation_git.go @@ -22,19 +22,37 @@ import ( // which operators can retarget to a mirror or a custom build. const GitCapableImageKey = "uvx-git" -// DefaultGitCapableImage is the built-in value for GitCapableImageKey: the -// non-slim uv image, which ships git (verified: git version 2.39.5). +// DefaultGitCapableImage is mcpproxy's own git-capable image: the non-slim uv +// image, which ships git (verified: git version 2.39.5). // -// It is a PUBLIC ghcr.io URL, which makes it the wrong answer for a mirrored or -// air-gapped install: that host cannot pull it at all. Key absence is no -// protection either — a config file's `default_images` is decoded INTO the -// built-in map rather than replacing it, so this value is present in the merged -// map of every install, including one whose own `uvx` entry points at an -// internal registry (TestDefaultImagesMergeOverBuiltInsOnLoad). The resolver -// therefore treats "the key still holds this exact value" as "nobody chose it" -// and lets the operator's own runtime image win instead — see -// IsBuiltInDefaultImage and core.IsolationManager.resolveDefaultImage. -const DefaultGitCapableImage = "ghcr.io/astral-sh/uv:python3.13-bookworm" +// It is deliberately NOT seeded into `docker_isolation.default_images`. Every +// key that map ships is written back into the operator's config file verbatim +// on the next save (SaveConfig marshals the whole merged map), which makes +// presence meaningless for a seeded key and leaves value equality as the only +// signal of intent — and value equality cannot express "I explicitly chose the +// image mcpproxy ships". An operator mirroring `uvx` who deliberately pointed +// `uvx-git` at this public image had that choice read as "unset" and silently +// replaced by their git-less mirror. Because the key is never seeded, its +// presence now means exactly one thing: the operator typed it. +// +// The registry half is split out so a configured `docker_isolation.registry` +// can qualify it — an air-gapped host that set only `registry` cannot pull +// ghcr.io at all. See core.IsolationManager.builtInGitCapableImage. +const ( + // GitCapableImageRegistry is the public registry the built-in image lives + // on when the operator configured none of their own. + GitCapableImageRegistry = "ghcr.io" + // DefaultDockerRegistry is the value `docker_isolation.registry` ships + // with. It is Docker Hub, i.e. "the public default", so it says nothing + // about an operator running a mirror — and the built-in git-capable image + // is not published there, so rewriting it onto this host would turn a + // working pull into a guaranteed failure. + DefaultDockerRegistry = "docker.io" + // GitCapableImageRepo is DefaultGitCapableImage without its registry host. + GitCapableImageRepo = "astral-sh/uv:python3.13-bookworm" + // DefaultGitCapableImage is the fully-qualified built-in image. + DefaultGitCapableImage = GitCapableImageRegistry + "/" + GitCapableImageRepo +) var ( builtInImagesOnce sync.Once @@ -45,16 +63,21 @@ var ( // ships for that `default_images` key — i.e. whether the entry is still // mcpproxy's own choice rather than the operator's. // -// The comparison exists because the merge makes presence meaningless: every -// built-in key is present in every loaded config, so "is this key set?" cannot -// distinguish a deliberate operator choice from a shipped default, and treating -// a shipped default as a choice is how an air-gapped install ends up pulling a -// public image. Value equality is the distinction that survives the merge. +// It answers that question only for the RUNTIME keys mcpproxy actually seeds +// ("uvx", "npx", …). For those, the merge makes presence meaningless — every +// built-in key is present in every loaded config, and is written back on the +// next save — so value equality is the only distinction that survives, and +// treating a shipped default as a deliberate choice is how an air-gapped +// install ends up pulling a public image. +// +// It is NOT how GitCapableImageKey is decided: that key is never seeded, so +// its presence is the operator's intent (see DefaultGitCapableImage). // -// An operator who deliberately configures the shipped value is not harmed by -// being read as "unset": every branch that consults this then falls back to -// their other entries, which point at the same place the shipped value does -// unless they are mirroring — in which case the mirror is what they wanted. +// An operator who deliberately configures the shipped value for a runtime key +// is not harmed by being read as "unset": every branch that consults this then +// falls back to their other entries, which point at the same place the shipped +// value does unless they are mirroring — in which case the mirror is what they +// wanted. func IsBuiltInDefaultImage(key, image string) bool { builtInImagesOnce.Do(func() { builtInImages = DefaultDockerIsolationConfig().DefaultImages diff --git a/internal/config/isolation_git_seed_test.go b/internal/config/isolation_git_seed_test.go index 68af3b905..474569fd4 100644 --- a/internal/config/isolation_git_seed_test.go +++ b/internal/config/isolation_git_seed_test.go @@ -12,9 +12,11 @@ import ( // than replacing it. The built-in entry therefore survives the merge, and the // operator's own entries win where they overlap. // -// This is also why the resolver does not need to hardcode a public image as its -// upgrade fallback, and why a partial `default_images` in a config file does -// not blank out the runtimes it omits. +// It is also why a partial `default_images` in a config file does not blank out +// the runtimes it omits — and why the git-capable key is deliberately NOT part +// of the built-in map: a key the merge seeds is written straight back into the +// operator's file by the next SaveConfig, so its presence could never mean +// "the operator chose this". func TestDefaultImagesMergeOverBuiltInsOnLoad(t *testing.T) { dir := t.TempDir() path := filepath.Join(dir, ConfigFileName) @@ -43,9 +45,9 @@ func TestDefaultImagesMergeOverBuiltInsOnLoad(t *testing.T) { if got := images["uvx"]; got != "mirror.internal/astral/uv:slim" { t.Errorf("operator's uvx entry = %q, want it to win the merge", got) } - if got := images[GitCapableImageKey]; got != DefaultGitCapableImage { - t.Errorf("default_images[%q] = %q, want the built-in %q seeded by the merge", - GitCapableImageKey, got, DefaultGitCapableImage) + if got, ok := images[GitCapableImageKey]; ok { + t.Errorf("default_images[%q] = %q — the merge seeded a key the operator never wrote", + GitCapableImageKey, got) } if got := images["ruby"]; got == "" { t.Error("a runtime the config file omits lost its built-in image — the map was replaced, not merged") diff --git a/internal/config/isolation_git_test.go b/internal/config/isolation_git_test.go index 5b488009f..28805301d 100644 --- a/internal/config/isolation_git_test.go +++ b/internal/config/isolation_git_test.go @@ -12,19 +12,22 @@ import "testing" // So every `uvx --from …git+https://…` server fails under Docker isolation // (#1143). The git-capable image is named by its own default_images key so // operators can retarget it instead of us bumping a ~1.5GB image on everyone. -func TestDefaultDockerIsolationConfig_HasGitCapableKey(t *testing.T) { +// +// The key is NOT seeded into the shipped map. SaveConfig marshals the whole +// merged map back into the operator's file, so any key mcpproxy seeds reappears +// there as if they had typed it — which is why presence, not value equality, is +// what says "the operator chose this image" (see DefaultGitCapableImage). +func TestDefaultDockerIsolationConfig_DoesNotSeedGitCapableKey(t *testing.T) { images := DefaultDockerIsolationConfig().DefaultImages - got, ok := images[GitCapableImageKey] - if !ok { - t.Fatalf("default_images has no %q key; keys=%v", GitCapableImageKey, images) - } - if got != DefaultGitCapableImage { - t.Errorf("default_images[%q] = %q, want %q", GitCapableImageKey, got, DefaultGitCapableImage) + if got, ok := images[GitCapableImageKey]; ok { + t.Fatalf("default_images seeds %q = %q; presence can no longer mean operator intent", + GitCapableImageKey, got) } - // The git-capable default must not be the slim image it exists to replace. - if got == images["uvx"] { - t.Errorf("git-capable default equals the (git-less) uvx default %q", got) + // The built-in git-capable image must still not be the slim image it exists + // to replace. + if DefaultGitCapableImage == images["uvx"] { + t.Errorf("built-in git-capable image equals the (git-less) uvx default %q", images["uvx"]) } } diff --git a/internal/diagnostics/classifier.go b/internal/diagnostics/classifier.go index b89bfdf65..6abc4c62b 100644 --- a/internal/diagnostics/classifier.go +++ b/internal/diagnostics/classifier.go @@ -106,6 +106,14 @@ func classifyOAuth(err error, _ ClassifierHints) Code { // preferred; these string matches are the last-resort fallback. func classifyDocker(err error, _ ClassifierHints) Code { msg := strings.ToLower(err.Error()) + // The same guard classifyDockerIsolatedSpawn applies, on the sibling path a + // hint-less caller reaches: a handshake timeout means a container is alive, + // so every arm below is reading the container's own stderr tail rather than + // a docker-layer failure. classifyStdio has already answered such an error + // with MCPX_STDIO_HANDSHAKE_TIMEOUT, so nothing is left unclassified. + if isStdioHandshakeTimeout(msg) { + return "" + } if c := dockerLayerCode(msg); c != "" { return c } @@ -257,13 +265,25 @@ func classifyDockerIsolatedSpawn(err error) Code { // outrank MCPX_STDIO_HANDSHAKE_TIMEOUT. A missing toolchain makes the // process EXIT, which is the other wrapper and is unaffected here. // - // The guard covers EVERY arm that reads the stderr tail for a missing - // command — (2), (3) and (4) below. Guarding only some of them is - // decoration: the unguarded arm claims the failure exactly as the guarded - // ones would have. Arms (1) and (5) are exempt on purpose: "docker: command - // not found" and an OCI/runc failure describe the docker layer never - // starting a container, which cannot be true of a container that is alive - // and merely silent. + // The guard covers EVERY arm below that reads the stderr TAIL — which is + // all of them. The earlier rationale for exempting the docker-CLI and + // OCI/runc arms ("that wording means no container ever started, so it + // cannot coexist with a timeout") had the implication backwards: if the + // handshake timed out, a container IS alive, so the wording did not come + // from our docker layer at all — it came out of the container, which is + // free to print "docker: command not found" (docker-in-docker, a script + // that shells out to docker) or an "OCI runtime" / "exec format error" + // line of its own. Guarding some arms and not others is decoration: the + // unguarded arm claims the failure exactly as the guarded ones would have. + // + // EXEMPT, and why that is sound: + // - the typed *exec.Error check above: it is the host's own failed + // execve of `docker`, not text scraped from a child's stderr; + // - "docker not found in PATH" / "docker not found in login shell" + // (arm 1a): mcpproxy's OWN shellwrap resolution errors, emitted before + // any container exists and never present in a container's stderr. + // Both describe a launch that never happened, so no handshake could have + // timed out around them. toolchainSuppressed := isStdioHandshakeTimeout(msg) // A shell reporting a BUILTIN missing (`sh: 1: source: not found`) is a @@ -277,33 +297,35 @@ func classifyDockerIsolatedSpawn(err error) Code { // The docker LAYER failing — daemon refusing, absent, or unable to fetch // the image — is decided before any stderr-tail reading. // - // It IS subject to toolchainSuppressed, unlike arms (1) and (5). A layer - // failure means no container ever started, so it cannot coexist with a - // handshake timeout, which means the container is alive and merely silent. - // When both appear, the daemon wording came from the container's OWN stderr - // tail — an application log line — and reporting MCPX_DOCKER_DAEMON_DOWN - // sends the user restarting Docker over a message their server printed. - // A genuine daemon refusal is unaffected: it surfaces on the exit path, - // where isStdioHandshakeTimeout is false. + // It is subject to toolchainSuppressed for the same reason every other + // stderr-derived arm is: when both appear, the daemon wording came from the + // container's OWN stderr tail — an application log line — and reporting + // MCPX_DOCKER_DAEMON_DOWN sends the user restarting Docker over a message + // their server printed. A genuine daemon refusal is unaffected: it surfaces + // on the exit path, where isStdioHandshakeTimeout is false. var layerCode Code if !toolchainSuppressed { layerCode = dockerLayerCode(msg) } switch { - // (1) docker binary unresolved: shellwrap resolution failure, or the shell - // / Go exec layer reporting `docker` itself missing. Cover both shell - // wordings: bash/sh `docker: command not found` AND zsh's reversed - // `zsh:1: command not found: docker` (the common macOS login-shell shape) — - // the latter must beat the generic "command not found" → EXEC case below. - case strings.Contains(msg, `"docker": executable file not found`), - strings.Contains(msg, "docker: command not found"), - strings.Contains(msg, "command not found: docker"), - strings.Contains(msg, "docker: not found"), - strings.Contains(msg, "docker not found in path"), + // (1a) mcpproxy's OWN docker-resolution failure. Exempt from the guard: we + // write these ourselves when `docker` cannot be resolved, before any + // container exists, so they can never be stderr-tail noise. + case strings.Contains(msg, "docker not found in path"), strings.Contains(msg, "docker not found in login shell"): return DockerCLINotFound - // (1b) the docker daemon/socket refused us, is down, or could not pull the + // (1b) the shell / Go exec layer reporting `docker` itself missing. Cover + // both shell wordings: bash/sh `docker: command not found` AND zsh's + // reversed `zsh:1: command not found: docker` (the common macOS login-shell + // shape) — the latter must beat the generic "command not found" → EXEC case + // below. Read out of the stderr tail, so guarded. + case !toolchainSuppressed && (strings.Contains(msg, `"docker": executable file not found`) || + strings.Contains(msg, "docker: command not found") || + strings.Contains(msg, "command not found: docker") || + strings.Contains(msg, "docker: not found")): + return DockerCLINotFound + // (1c) the docker daemon/socket refused us, is down, or could not pull the // image. Must precede every stderr-tail arm below: `docker: permission // denied while trying to connect to the Docker daemon socket …` otherwise // fell through to the generic stdio "permission denied" arm and came back @@ -329,28 +351,68 @@ func classifyDockerIsolatedSpawn(err error) Code { // Split in two so the builtin carve-out applies only to the wording a shell // builtin line can produce: an OCI "executable file not found" is never one // of those, and must still classify even next to a benign `source` line. + // + // "no such file or directory" needs the exec/OCI context (see + // execNoSuchFileRe): on its own it is the most common line in ordinary + // stderr — an optional cache dir, a config file a server probes and + // survives — and the container-toolchain arms run before every generic + // stdio arm, so one such warning claimed a failure whose real cause was + // three lines further down. case !toolchainSuppressed && (strings.Contains(msg, "executable file not found") || - strings.Contains(msg, "no such file or directory")): + execNoSuchFileRe.MatchString(msg) || + (strings.Contains(msg, "oci runtime") && strings.Contains(msg, "no such file or directory"))): return DockerExecNotFound case !toolchainSuppressed && !builtinOnly && strings.Contains(msg, "command not found"): return DockerExecNotFound - // (5) other OCI runtime failures (arch mismatch, runc start failure). - case strings.Contains(msg, "oci runtime"), - strings.Contains(msg, "exec format error"), - strings.Contains(msg, "runc"): + // (5) other OCI runtime failures (arch mismatch, runc start failure). Read + // out of the stderr tail like everything above it, so guarded: a live + // container is free to log the word "runc" or an "exec format error" of its + // own while it keeps running. + case !toolchainSuppressed && (strings.Contains(msg, "oci runtime") || + strings.Contains(msg, "exec format error") || + strings.Contains(msg, "runc")): return DockerOCIRuntime } return "" } +// execNoSuchFileRe requires "no such file or directory" to be reported ABOUT an +// exec, which is the only shape that means the container's entrypoint is +// missing: +// +// exec /usr/local/bin/uvx: no such file or directory (docker ≥ 20.10) +// exec: "uvx": … no such file or directory (OCI create) +// +// A bare match is worthless — `warn: /var/cache/uv: no such file or directory` +// is a line thousands of programs print about a file they do not need. +var execNoSuchFileRe = regexp.MustCompile(`(?:^|[\s"'(])exec(?:ve)?\b[^\n]{0,200}no such file or directory`) + // isStdioHandshakeTimeout reports whether the error is the "the child is alive // but silent" wrapper (connection_lifecycle.go) rather than a process that // died. It is the single source for the MCPX_STDIO_HANDSHAKE_TIMEOUT arm of // classifyStdio below and for the suppression guard above, so the two cannot // drift apart. func isStdioHandshakeTimeout(msg string) bool { - return strings.Contains(msg, "did not respond to mcp initialize") || - strings.Contains(msg, "handshake timeout") + return isMCPProxyHandshakeTimeout(msg) || strings.Contains(msg, "handshake timeout") +} + +// isMCPProxyHandshakeTimeout matches only the sentence mcpproxy itself writes +// (connection_lifecycle.go). Unlike the looser "handshake timeout" substring — +// which Go's own `net/http: TLS handshake timeout` also carries — it is +// unambiguous enough to act on with no transport hint at all. +func isMCPProxyHandshakeTimeout(msg string) bool { + return strings.Contains(msg, "did not respond to mcp initialize") +} + +// isStdioExitBeforeInitialize reports whether the error is mcpproxy's OWN +// premature-exit wrapper (enrichTransportClosedError in connection_lifecycle.go) +// — the child STARTED and then died. It is the single source for the +// MCPX_STDIO_EXIT_BEFORE_INITIALIZE arm below and for the spawn-suppression +// guard, so the two cannot drift apart, exactly as isStdioHandshakeTimeout is +// for the timeout pair. +func isStdioExitBeforeInitialize(msg string) bool { + return strings.Contains(msg, "exited before completing the mcp initialize") || + strings.Contains(msg, "exited before the mcp initialize") } // shellToolNotFoundRe matches a shell's "missing command" line, and only that. @@ -405,68 +467,73 @@ func onlyShellBuiltinsMissing(msg string) bool { return true } -// gitCloneFailureCauses are causes of a failed git clone that are NOT a missing -// git binary. `uv` collapses them all into "Git operation failed", so without -// this guard a private-repo or offline clone would be diagnosed as a -// missing-toolchain problem and send the user changing images for nothing. +// gitBinaryMissingMarkers are wordings that name the missing `git` BINARY +// outright. They are positive evidence, and they classify on their own. +var gitBinaryMissingMarkers = []string{ + "git executable not found", // uv (older releases) + "ensure that git is installed", // uv (older releases) + "failed to spawn: `git`", // uv: exec of git itself failed + "failed to spawn `git`", // (spacing varies by uv version) + "git: not found", // dash/ash + "git: command not found", // bash + "command not found: git", // zsh + "\"git\": executable file not found", // Go exec +} + +// gitSpokeRe matches a diagnostic line git, ssh or curl emitted THEMSELVES. +// Its presence is proof the git binary ran, whatever it then failed at: // -// Every entry is text only git/ssh/curl can produce, which is itself the proof -// that git RAN. The list has to cover the wordings a private repository -// actually produces — an incomplete one is not a near-miss, it is the wrong -// diagnosis with a confident docs link attached. -var gitCloneFailureCauses = []string{ - // Credentials. - "authentication failed", - "could not read username", - "could not read password", - "terminal prompts disabled", - "invalid username or password", - "support for password authentication was removed", +// fatal: could not read from remote repository. +// error: RPC failed; HTTP 429 … +// remote: Invalid username or password. +// warning: redirecting to https://… +// +// This replaces an enumerated list of clone-failure causes. That list decided +// the DEFAULT — anything it did not name was reported as "the image has no +// git" — so every wording missing from it (a redirect, a 429, a protocol +// error, "could not read from remote repository") told the user to rebuild +// their Docker image over a failure that proves git ran. A list can never be +// complete; the burden of proof belongs on the claim that a binary is absent. +var gitSpokeRe = regexp.MustCompile(`(?:^|[\s|>─╰•])(?:fatal|error|remote|warning|hint|ssh|curl|usage):`) + +// gitSpokeUnprefixed are the diagnostics git's helpers print with no such +// prefix at all. They are the same evidence as gitSpokeRe, just unlabelled. +var gitSpokeUnprefixed = []string{ + "host key verification failed", "permission denied (publickey)", "no supported authentication methods available", - "host key verification failed", - "returned error: 401", - "returned error: 403", - // Repository addressing. - "repository not found", - "' not found", // git: fatal: repository 'https://…/' not found - "does not appear to be a git repository", - // Network / TLS. "unable to access" is git's own prefix for this whole - // family, so it catches the wordings not spelled out individually. - "unable to access", - "could not resolve host", - "temporary failure in name resolution", - "connection timed out", - "connection refused", - "network is unreachable", - "failed to connect to", - "ssl certificate problem", - "server certificate verification failed", "the remote end hung up unexpectedly", - "early eof", + "could not read from remote repository", } -// isContainerGitMissing reports whether the container stderr says git is absent -// from the image. It covers uv's own wording ("Git executable not found…" and -// the terser "Git operation failed" of newer releases) plus the shell wordings -// for a missing `git` binary. +// isContainerGitMissing reports whether the container stderr says the git +// BINARY is absent from the image. +// +// `uv` collapses every git failure — a missing binary, a private repo, an +// offline host — into the same "Git operation failed" headline, so that +// headline alone decides nothing. What separates the two is whether git itself +// said anything: when uv cannot execute git there is no git diagnostic to +// report, and when it can, git's own fatal:/error:/remote: line is right there +// in the tail (#1143 remains covered: the reported failure is exactly the +// headline with no git output under it). func isContainerGitMissing(msg string) bool { - switch { - case strings.Contains(msg, "git executable not found"), - strings.Contains(msg, "ensure that git is installed"), - strings.Contains(msg, "git: not found"), - strings.Contains(msg, "git: command not found"), - strings.Contains(msg, "command not found: git"): - return true - case strings.Contains(msg, "git operation failed"): - for _, cause := range gitCloneFailureCauses { - if strings.Contains(msg, cause) { - return false - } + for _, marker := range gitBinaryMissingMarkers { + if strings.Contains(msg, marker) { + return true } - return true } - return false + if !strings.Contains(msg, "git operation failed") { + return false + } + if gitSpokeRe.MatchString(msg) { + return false + } + for _, spoke := range gitSpokeUnprefixed { + if strings.Contains(msg, spoke) { + return false + } + } + return true } // classifyStdio handles os/exec spawn errors and handshake failures. @@ -481,6 +548,17 @@ func classifyStdio(err error, hints ClassifierHints) Code { } } + // mcpproxy's OWN handshake-timeout wrapper, matched without any hint. Only + // the stdio lifecycle writes this sentence, so it is unambiguous, and + // accepting it here is what lets classifyDocker suppress its stderr-derived + // arms on a timeout without dropping such a failure to + // MCPX_UNKNOWN_UNCLASSIFIED and its "file a bug report" CTA. The looser + // "handshake timeout" substring stays hint-gated below, because Go's own + // `net/http: TLS handshake timeout` shares it. + if isMCPProxyHandshakeTimeout(strings.ToLower(err.Error())) { + return STDIOHandshakeTimeout + } + var execErr *exec.Error if errors.As(err, &execErr) { // exec.Error wraps os.PathError which wraps syscall.Errno; ENOENT/EACCES @@ -527,23 +605,38 @@ func classifyStdio(err error, hints ClassifierHints) Code { if hints.Transport == "stdio" || hints.DockerIsolated { msg := err.Error() lmsg := strings.ToLower(msg) + + // mcpproxy's own EXIT wrapper is written only when the transport closed + // — i.e. the child process STARTED and then died. A spawn-class code + // (ENOENT / EACCES / ENOEXEC all mean "we never got the process off the + // ground") is therefore provably wrong whenever it is present, and the + // words that produce those codes — "no such file or directory", + // "permission denied" — are ordinary lines any program writes about its + // own optional files. Reading one out of the attached stderr TAIL let a + // warning the child logged and survived outrank the authoritative fact + // that it ran, and handed the user chmod advice for a binary that is + // fine. Same guard as toolchainSuppressed on the docker path, on the + // other wrapper. + spawnSuppressed := isStdioExitBeforeInitialize(lmsg) + switch { - // Wrong-arch / non-executable host binary (ENOEXEC). Guarded against - // docker OCI context ("oci runtime"/"runc") so a real containerized - // exec-format failure still falls through to classifyDocker → OCI; a - // BARE "exec format error" is a host stdio problem, not a Docker one. - case strings.Contains(lmsg, "exec format error") && - !strings.Contains(lmsg, "oci runtime") && !strings.Contains(lmsg, "runc"): - return STDIOSpawnExecFormat // The handshake-timeout wrapper is mcpproxy's OWN phrasing and means // the child is alive: it outranks every arm below, all of which read // the attached stderr TAIL and would otherwise let a line the child // logged and survived decide the diagnosis. Same reasoning as the // toolchainSuppressed guard in classifyDockerIsolatedSpawn — and it // has to sit here too, or suppressing the docker arm just hands the - // same stderr line to this one. + // same stderr line to this one. It leads the switch for that reason: + // "exec format error" below is stderr-tail evidence like the rest. case isStdioHandshakeTimeout(lmsg): return STDIOHandshakeTimeout + // Wrong-arch / non-executable host binary (ENOEXEC). Guarded against + // docker OCI context ("oci runtime"/"runc") so a real containerized + // exec-format failure still falls through to classifyDocker → OCI; a + // BARE "exec format error" is a host stdio problem, not a Docker one. + case !spawnSuppressed && strings.Contains(lmsg, "exec format error") && + !strings.Contains(lmsg, "oci runtime") && !strings.Contains(lmsg, "runc"): + return STDIOSpawnExecFormat // A git/ssh CREDENTIAL failure during a dependency install. `git@host: // Permission denied (publickey).` contains "permission denied", which // the EACCES arm below reads as the server's own executable being @@ -553,12 +646,12 @@ func classifyStdio(err error, hints ClassifierHints) Code { // EXIT_BEFORE_INITIALIZE, whose remediation points at that stderr. case strings.Contains(lmsg, "permission denied (publickey)"): return STDIOExitBeforeInitialize - case strings.Contains(lmsg, "no such file or directory"), - strings.Contains(lmsg, "executable file not found"): + case !spawnSuppressed && (strings.Contains(lmsg, "no such file or directory") || + strings.Contains(lmsg, "executable file not found")): return STDIOSpawnENOENT - case strings.Contains(lmsg, "command not found") && !onlyShellBuiltinsMissing(lmsg): + case !spawnSuppressed && strings.Contains(lmsg, "command not found") && !onlyShellBuiltinsMissing(lmsg): return STDIOSpawnENOENT - case strings.Contains(lmsg, "permission denied"): + case !spawnSuppressed && strings.Contains(lmsg, "permission denied"): return STDIOSpawnEACCES // Subprocess started but the transport closed before the MCP initialize // handshake completed — the child exited early (e.g. printed a fatal @@ -568,8 +661,7 @@ func classifyStdio(err error, hints ClassifierHints) Code { // Gated on the stdio hint so a "transport closed" from another transport // is not misattributed. case strings.Contains(lmsg, "transport closed"), - strings.Contains(lmsg, "exited before completing the mcp initialize"), - strings.Contains(lmsg, "exited before the mcp initialize"): + isStdioExitBeforeInitialize(lmsg): return STDIOExitBeforeInitialize case strings.Contains(lmsg, "invalid handshake"), strings.Contains(lmsg, "malformed"): diff --git a/internal/diagnostics/classifier_exit_evidence_test.go b/internal/diagnostics/classifier_exit_evidence_test.go new file mode 100644 index 000000000..c91e0b5d3 --- /dev/null +++ b/internal/diagnostics/classifier_exit_evidence_test.go @@ -0,0 +1,59 @@ +package diagnostics + +import ( + "errors" + "testing" +) + +// The EXIT wrapper is mcpproxy's own: it is written only when the transport +// closed, i.e. the child process STARTED and then died. A spawn-class code +// (ENOENT / EACCES / ENOEXEC — "we never got the process off the ground") is +// therefore provably wrong there, and the words that produce it — "no such +// file or directory", "permission denied" — are ordinary lines any program +// writes about its own optional files. Reading one out of the stderr tail +// outranks the authoritative fact that the child ran, and hands the user chmod +// advice for a binary that is fine. +func TestExitWrapperOutranksStderrNoiseSpawnArms(t *testing.T) { + wrap := func(tail string) error { + return errors.New("server process exited before completing the MCP initialize handshake; " + + "recent stderr:\n" + tail + "\n: transport closed") + } + + tails := []string{ + "warn: optional cache /var/cache/uv: no such file or directory\nfatal: config key `api_key` is required", + "warn: could not read /etc/mcp/extra.toml: permission denied\nfatal: config key `api_key` is required", + "[server] WARN plugin dir /opt/plugins: no such file or directory", + } + + for _, hints := range []ClassifierHints{ + {Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"}, + {Transport: "stdio"}, + } { + for _, tail := range tails { + got := Classify(wrap(tail), hints) + if got != STDIOExitBeforeInitialize { + t.Errorf("Classify(isolated=%v, tail=%q) = %q, want %q", + hints.DockerIsolated, tail, got, STDIOExitBeforeInitialize) + } + } + } +} + +// The tightening must not cost the failures the arms exist for: a container +// whose ENTRYPOINT interpreter is genuinely absent reports it with exec/OCI +// context, and that still has to reach MCPX_DOCKER_EXEC_NOT_FOUND. +func TestRealEntrypointMissingWordingsStillClassify(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + for _, tail := range []string{ + `docker: Error response from daemon: failed to create task: OCI runtime create failed: runc create failed: exec: "uvx": executable file not found in $PATH: unknown`, + "exec /usr/local/bin/uvx: no such file or directory", + "docker: Error response from daemon: failed to create task for container: OCI runtime create failed: no such file or directory: unknown", + } { + err := errors.New("server process exited before completing the MCP initialize handshake; recent stderr:\n" + + tail + "\n: transport closed") + if got := Classify(err, hints); got != DockerExecNotFound { + t.Errorf("Classify(%q) = %q, want %q", tail, got, DockerExecNotFound) + } + } +} diff --git a/internal/diagnostics/classifier_git_evidence_test.go b/internal/diagnostics/classifier_git_evidence_test.go new file mode 100644 index 000000000..2e237e68f --- /dev/null +++ b/internal/diagnostics/classifier_git_evidence_test.go @@ -0,0 +1,65 @@ +package diagnostics + +import ( + "errors" + "testing" +) + +// `uv` collapses every git failure into "Git operation failed". Defaulting +// that to "the image has no git" unless the cause appears on a finite +// exclusion list inverts the burden of proof: the list can never be complete, +// and every wording missing from it tells the user to rebuild their Docker +// image over a failure that PROVES git ran. +// +// Anything git itself reported — a fatal:/error:/remote:/warning: line, an ssh +// or curl diagnostic — is that proof. +func TestGitReportedFailuresAreNeverAMissingBinary(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + wrap := func(cause string) error { + return errors.New("server process exited before completing the MCP initialize handshake; recent stderr:\n" + + " × Failed to resolve `--with` requirement\n ╰─▶ Git operation failed\n ╰─▶ " + cause + + "\n: transport closed") + } + + for _, cause := range []string{ + "fatal: could not read from remote repository.", + "fatal: unable to update url base from redirection", + "error: RPC failed; HTTP 429 curl 22 The requested URL returned error: 429", + "fatal: protocol error: bad pack header", + "warning: redirecting to https://github.com/o/r.git/\nfatal: expected flush after ref listing", + "remote: Repository moved permanently", + "error: 503 Service Unavailable while accessing the git mirror", + "Host key verification failed.", + "git@github.com: Permission denied (publickey).", + } { + got := Classify(wrap(cause), hints) + if got == DockerMissingToolchain { + t.Errorf("cause %q classified as %q — git demonstrably ran", cause, got) + } + if got == UnknownUnclassified { + t.Errorf("cause %q classified as %q — the bug-report CTA is back", cause, got) + } + } +} + +// The inversion must keep the #1143 case it was built for: uv reporting a git +// operation with NO diagnostic of git's own, and every wording that names the +// missing binary outright. +func TestMissingGitBinaryEvidenceStillClassifies(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + for _, tail := range []string{ + " × Failed to resolve `--with` requirement\n ╰─▶ Git operation failed", + "Git executable not found. Ensure that Git is installed and available.", + " × Failed to spawn: `git`\n ╰─▶ No such file or directory (os error 2)", + "sh: 1: git: not found", + "bash: line 1: git: command not found", + } { + err := errors.New("server process exited before completing the MCP initialize handshake; recent stderr:\n" + + tail + "\n: transport closed") + if got := Classify(err, hints); got != DockerMissingToolchain { + t.Errorf("Classify(%q) = %q, want %q", tail, got, DockerMissingToolchain) + } + } +} diff --git a/internal/diagnostics/classifier_timeout_arm_audit_test.go b/internal/diagnostics/classifier_timeout_arm_audit_test.go new file mode 100644 index 000000000..a8bef01cf --- /dev/null +++ b/internal/diagnostics/classifier_timeout_arm_audit_test.go @@ -0,0 +1,93 @@ +package diagnostics + +import ( + "errors" + "testing" +) + +// Every arm of classifyDockerIsolatedSpawn that reads the captured stderr TAIL +// needs the handshake-timeout guard, not just the ones a review happened to +// name. A handshake timeout means the container is ALIVE and merely silent, so +// nothing it logged can be the terminal cause — including wordings about the +// docker layer itself, which the container is perfectly able to print (a +// docker-in-docker server, a script that shells out to `docker`, an SDK that +// logs "OCI runtime" warnings). +// +// This table walks the whole switch: one stderr line per arm. +func TestHandshakeTimeoutOutranksEveryDockerArm(t *testing.T) { + const wrapper = "server did not respond to MCP initialize within 30s (subprocess may have " + + "crashed or printed to stderr instead of stdout); recent stderr:\n" + + // One line per arm of classifyDockerIsolatedSpawn, in switch order. + tails := map[string]string{ + "(1) docker cli, sh wording": "app: docker: command not found", + "(1) docker cli, zsh wording": "app: zsh:1: command not found: docker", + "(1) docker cli, dash wording": "app: sh: 1: docker: not found", + "(1) docker cli, go exec wording": `app: exec: "docker": executable file not found in $PATH`, + "(1b) daemon down": "app: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?", + "(1b) daemon permission": "app: dial unix /var/run/docker.sock: connect: permission denied", + "(1b) image pull": "app: Error response from daemon: pull access denied for acme/x", + "(2) container git missing": "app: Git executable not found. Ensure that Git is installed and available.", + "(3) shell tool missing": "app: sh: 1: cmake: not found", + "(4) exec not found": `app: exec: "uvx": executable file not found in $PATH`, + "(5) oci runtime": "app: OCI runtime warning ignored", + "(5) exec format": "app: exec format error while probing plugin", + "(5) runc": "app: runc reported a stale bundle", + } + + for _, hints := range []ClassifierHints{ + {Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"}, + {DockerIsolated: true}, + } { + for arm, tail := range tails { + err := errors.New(wrapper + tail + "\n") + if got := Classify(err, hints); got != STDIOHandshakeTimeout { + t.Errorf("%s (isolated hints %+v): Classify() = %q, want %q — a live container's stderr hijacked the timeout", + arm, hints, got, STDIOHandshakeTimeout) + } + } + } +} + +// The guard is a guard, not an off switch: the same wordings on the EXIT +// wrapper (the child really died) must still reach their specific code. +func TestDockerArmsStillClassifyOnTheExitPath(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true, DockerCommand: "uvx"} + + cases := []struct { + tail string + want Code + }{ + {"docker: command not found", DockerCLINotFound}, + {"zsh:1: command not found: docker", DockerCLINotFound}, + {"docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?", DockerDaemonDown}, + {"docker: Error response from daemon: pull access denied for acme/x", DockerImagePullFailed}, + {"Git executable not found. Ensure that Git is installed and available.", DockerMissingToolchain}, + {"sh: 1: cmake: not found", DockerMissingToolchain}, + {`docker: Error response from daemon: OCI runtime create failed: exec: "uvx": executable file not found in $PATH`, DockerExecNotFound}, + {"docker: Error response from daemon: OCI runtime create failed: exec format error", DockerOCIRuntime}, + } + + for _, tc := range cases { + err := errors.New("server process exited before completing the MCP initialize handshake; recent stderr:\n" + + tc.tail + "\n: transport closed") + if got := Classify(err, hints); got != tc.want { + t.Errorf("Classify(%q) = %q, want %q", tc.tail, got, tc.want) + } + } +} + +// mcpproxy's OWN resolution failures are the arms that stay exempt: it emits +// them itself when it cannot resolve `docker` before any container exists, so +// they can never appear in a container's stderr tail. +func TestMCPProxyOwnDockerResolutionFailuresStayExempt(t *testing.T) { + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true} + for _, msg := range []string{ + "docker not found in PATH", + "docker not found in login shell", + } { + if got := Classify(errors.New(msg), hints); got != DockerCLINotFound { + t.Errorf("Classify(%q) = %q, want %q", msg, got, DockerCLINotFound) + } + } +} diff --git a/internal/diagnostics/remediation.go b/internal/diagnostics/remediation.go index 51c5877d8..cda0942fb 100644 --- a/internal/diagnostics/remediation.go +++ b/internal/diagnostics/remediation.go @@ -120,21 +120,16 @@ func detectDockerRuntimeType(command string) string { // together. const gitCapableImageKey = "uvx-git" -// builtInGitCapableImage / builtInPythonRunnerImage mirror the VALUES config -// ships for the git-capable key and for every Python package runner. +// builtInPythonRunnerImage mirrors the VALUE config ships for every Python +// package runner. A runtime entry that differs from it is one the operator +// retargeted — for the seeded runtime keys, value inequality is the only signal +// that survives the merge (config.IsBuiltInDefaultImage says why). // -// Values, not presence, are what say whether mcpproxy's automatic selection -// actually ran: a config file's `default_images` is merged INTO the built-in -// map, so both keys are populated in every install, and an operator who -// retargeted their runtime at a mirror keeps a shipped `uvx-git` they never -// chose. In that case core.IsolationManager.resolveDefaultImage deliberately -// does NOT substitute — it will not pull a public image behind a mirrored host -// — so claiming an automatic swap here would name an image the install never -// ran. TestMirroredBuiltInImagesMatchConfig pins these to config. -const ( - builtInGitCapableImage = "ghcr.io/astral-sh/uv:python3.13-bookworm" - builtInPythonRunnerImage = "ghcr.io/astral-sh/uv:python3.13-bookworm-slim" -) +// There is deliberately no mirrored value for the git-capable key: mcpproxy +// does not seed it, so its PRESENCE is the operator's choice and no value +// comparison is involved. TestMirroredBuiltInImagesMatchConfig pins this to +// config. +const builtInPythonRunnerImage = "ghcr.io/astral-sh/uv:python3.13-bookworm-slim" // missingToolchainRemediation explains a DockerMissingToolchain failure: the // container ran, but the image lacks a tool the server calls. The git case is @@ -170,11 +165,11 @@ func missingToolchainRemediation(hints ClassifierHints) string { runtimeImage := strings.TrimSpace(hints.DockerDefaultImages[runtimeType]) // An explicitly emptied key is the documented opt-out, not an absent one. optedOut := gitKeySet && gitImage == "" - // The operator retargeted this runtime at their own registry and left the - // git key at the value mcpproxy ships: no substitution happened, and the - // server ran on their image. Mirrors the resolver's own rule. - deferredToRuntimeImage := !optedOut && runtimeImage != "" && runtimeImage != builtInPythonRunnerImage && - (gitImage == "" || gitImage == builtInGitCapableImage) + // The operator retargeted this runtime at their own registry and never set + // the git key: no substitution happened, and the server ran on their image. + // Mirrors the resolver's own rule — including that a git key the operator + // DID set wins outright, whatever its value, so it can never be a deferral. + deferredToRuntimeImage := !gitKeySet && runtimeImage != "" && runtimeImage != builtInPythonRunnerImage b.WriteString(" It installs from a git URL, so the image must contain `git`.") switch { diff --git a/internal/diagnostics/remediation_mirrored_registry_test.go b/internal/diagnostics/remediation_mirrored_registry_test.go index 9e8944bca..56d590fa4 100644 --- a/internal/diagnostics/remediation_mirrored_registry_test.go +++ b/internal/diagnostics/remediation_mirrored_registry_test.go @@ -21,11 +21,10 @@ func TestMissingToolchainRemediationDoesNotClaimASubstitutionThatDidNotHappen(t DockerCommand: "uvx", DockerArgs: []string{"--from", "srv@git+https://github.com/o/r", "srv"}, // Exactly what a mirrored config looks like after load: the operator's - // runtime entry, and the git key still holding its shipped value - // because the merge put it there. + // runtime entry, and no git key at all (mcpproxy does not seed one, so + // an unset key really is unset). DockerDefaultImages: map[string]string{ - "uvx": mirrored, - "uvx-git": config.DefaultGitCapableImage, + "uvx": mirrored, }, } @@ -49,8 +48,9 @@ func TestMissingToolchainRemediationDoesNotClaimASubstitutionThatDidNotHappen(t // answered from stale strings. func TestMirroredBuiltInImagesMatchConfig(t *testing.T) { images := config.DefaultDockerIsolationConfig().DefaultImages - if builtInGitCapableImage != config.DefaultGitCapableImage { - t.Errorf("builtInGitCapableImage = %q, config ships %q", builtInGitCapableImage, config.DefaultGitCapableImage) + if got, ok := images[gitCapableImageKey]; ok { + t.Errorf("config seeds default_images[%q] = %q — this package assumes presence means operator intent", + gitCapableImageKey, got) } for runtimeType := range gitCapableRuntimeTypes { if got := images[runtimeType]; got != builtInPythonRunnerImage { diff --git a/internal/runtime/supervisor/isolation_classification_test.go b/internal/runtime/supervisor/isolation_classification_test.go index 8f54e6bc6..54a6d9d1f 100644 --- a/internal/runtime/supervisor/isolation_classification_test.go +++ b/internal/runtime/supervisor/isolation_classification_test.go @@ -162,7 +162,14 @@ func TestClassifierHints_CarryArgsForGitDependencies(t *testing.T) { if len(hints.DockerArgs) != len(srv.Args) { t.Fatalf("classifierHints().DockerArgs = %v, want %v", hints.DockerArgs, srv.Args) } - if got := hints.DockerDefaultImages[config.GitCapableImageKey]; got != config.DefaultGitCapableImage { - t.Errorf("hints do not carry the git-capable default image: %q", got) + // The whole default_images map has to reach the remediation layer, which + // reads both the runtime entry and whether the operator set the git key at + // all. (mcpproxy does not seed the git key, so its absence here is the + // point: an unset key must arrive unset.) + if got := hints.DockerDefaultImages["uvx"]; got == "" { + t.Error("hints do not carry the runtime default image") + } + if got, ok := hints.DockerDefaultImages[config.GitCapableImageKey]; ok { + t.Errorf("hints carry a git-capable key the operator never set: %q", got) } } diff --git a/internal/upstream/core/isolation.go b/internal/upstream/core/isolation.go index 0228d4586..73c1ed268 100644 --- a/internal/upstream/core/isolation.go +++ b/internal/upstream/core/isolation.go @@ -308,23 +308,24 @@ const ( // whose args actually reference a git URL. // // The operator's `default_images` map is authoritative throughout: the -// substitution never reaches past it to a PUBLIC image that a mirrored or -// air-gapped host cannot fetch at all. Key presence cannot express that, -// because a config file's `default_images` is decoded INTO the built-in map — -// the key is present in every install (TestDefaultImagesMergeOverBuiltInsOnLoad) -// — so the question asked is whose VALUE it holds (config.IsBuiltInDefaultImage): +// substitution never reaches past it to an image a mirrored or air-gapped host +// cannot fetch at all. // -// - git key holds an operator value → use it, whatever else is configured; -// - git key emptied → opt out, keep the runtime default (the -// lever for an operator who does not want a second large image); -// - git key still mcpproxy's own value, and the runtime image is too → the -// built-in git-capable image. Nothing here is mirrored, so a public pull is -// what this install already does for every other image; -// - git key still mcpproxy's own value, but the operator retargeted the -// RUNTIME at their registry → their image stands. It may or may not contain -// git; that is diagnosable (MCPX_DOCKER_MISSING_TOOLCHAIN names the key to -// set, and BuildDockerArgs warns on spawn), whereas a pull their host -// cannot make is a failure with no path forward. +// - git key PRESENT with a value → the operator's explicit choice, used +// whatever else is configured. Presence is trustworthy here because +// mcpproxy never seeds this key (config.DefaultGitCapableImage explains +// why that matters: every seeded key is written back into the operator's +// file on save, so a seeded key's presence would say nothing). This is +// what lets an operator name mcpproxy's own public image on purpose; +// - git key present and EMPTY → opt out, keep the runtime default (the lever +// for an operator who does not want a second large image); +// - git key absent, and the operator retargeted the RUNTIME at their own +// registry → their image stands. It may or may not contain git; that is +// diagnosable (MCPX_DOCKER_MISSING_TOOLCHAIN names the key to set, and +// BuildDockerArgs warns on spawn), whereas a pull their host cannot make +// is a failure with no path forward; +// - git key absent, nothing retargeted → mcpproxy's own git-capable image, +// qualified with `docker_isolation.registry` when one is configured. func (im *IsolationManager) resolveDefaultImage(serverConfig *config.ServerConfig, runtimeType string) (image string, decision gitImageDecision) { runtimeImage, runtimeExists := im.globalConfig.DefaultImages[runtimeType] runtimeImage = strings.TrimSpace(runtimeImage) @@ -333,15 +334,13 @@ func (im *IsolationManager) resolveDefaultImage(serverConfig *config.ServerConfi if needsGit { gitImage, gitKeySet := im.globalConfig.DefaultImages[config.GitCapableImageKey] gitImage = strings.TrimSpace(gitImage) - operatorChoseGitImage := gitImage != "" && - !config.IsBuiltInDefaultImage(config.GitCapableImageKey, gitImage) operatorChoseRuntimeImage := runtimeExists && runtimeImage != "" && !config.IsBuiltInDefaultImage(runtimeType, runtimeImage) switch { - case operatorChoseGitImage: + case gitKeySet && gitImage != "": return im.buildFullImageName(gitImage), gitImageSubstituted - case gitKeySet && gitImage == "": + case gitKeySet: // Explicitly emptied: the operator opted out of the substitution. case operatorChoseRuntimeImage: return im.buildFullImageName(runtimeImage), gitImageDeferredToRuntime @@ -349,7 +348,7 @@ func (im *IsolationManager) resolveDefaultImage(serverConfig *config.ServerConfi // Nothing is retargeted (or there is no runtime entry at all, where // the only alternative is the alpine fallback, which has neither // git nor python). - return im.buildFullImageName(config.DefaultGitCapableImage), gitImageSubstituted + return im.builtInGitCapableImage(), gitImageSubstituted } } @@ -362,6 +361,31 @@ func (im *IsolationManager) resolveDefaultImage(serverConfig *config.ServerConfi return im.buildFullImageName("alpine:3.18"), gitImageNotApplicable } +// builtInGitCapableImage returns mcpproxy's OWN git-capable image, qualified +// with `docker_isolation.registry` when the operator configured one. +// +// The shipped constant names a public ghcr.io host, and buildFullImageName +// hands any already-qualified reference straight back — so an operator who set +// only `registry` (the one knob an air-gapped install is guaranteed to set, and +// the whole point of the field) still had every git-dependency server try to +// pull ghcr.io from a host that cannot reach it. Earlier rounds fixed only the +// `default_images` path; nothing covered a bare `registry`. +// +// Only the built-in image is rewritten this way. An operator's own +// `default_images` value goes through buildFullImageName unchanged, because a +// fully-qualified value they wrote already says which host they meant. +func (im *IsolationManager) builtInGitCapableImage() string { + registry := strings.TrimSpace(im.globalConfig.Registry) + // "" and the shipped "docker.io" both mean "the public default": neither + // is an operator telling us where their images live, and the built-in + // image is not on Docker Hub, so rewriting it there would break a pull + // that works today. + if registry == "" || registry == config.DefaultDockerRegistry || registry == config.GitCapableImageRegistry { + return config.DefaultGitCapableImage + } + return registry + "/" + config.GitCapableImageRepo +} + // ResolvedIsolationDefaults captures the per-runtime default values that // would be used for a server when no per-server overrides are set. It is // used by the REST API to expose contextual placeholders to UI clients diff --git a/internal/upstream/core/isolation_git_image_explicit_test.go b/internal/upstream/core/isolation_git_image_explicit_test.go new file mode 100644 index 000000000..2250e210b --- /dev/null +++ b/internal/upstream/core/isolation_git_image_explicit_test.go @@ -0,0 +1,42 @@ +package core + +import ( + "testing" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +// Operator intent used to be inferred by comparing the configured value with +// the one mcpproxy ships, which cannot express "I explicitly chose the shipped +// image". An operator who mirrors `uvx` but deliberately points `uvx-git` at +// the public git-capable image had that choice read as "unset" and silently +// overridden by their mirrored runtime image — which has no git, so the server +// fails, and the remediation tells them to set the very key they did set. +func TestGetDockerImage_ExplicitGitKeyWinsEvenAtTheShippedValue(t *testing.T) { + images := map[string]string{ + "uvx": "mirror.internal/astral/uv:python3.13-bookworm-slim", + "python": "mirror.internal/astral/uv:python3.13-bookworm-slim", + config.GitCapableImageKey: config.DefaultGitCapableImage, + } + im := gitTestManager(images) + + got, err := im.GetDockerImage(gitDepServer("uvx"), "uvx") + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != config.DefaultGitCapableImage { + t.Errorf("GetDockerImage() = %q, want the operator's explicit %q", got, config.DefaultGitCapableImage) + } +} + +// The distinction only works if mcpproxy never writes that value into the +// operator's config itself: `default_images` is serialized back to disk in +// full on every config save, so any key mcpproxy seeds is indistinguishable +// from one the operator typed. +func TestShippedDefaultImagesDoNotSeedTheGitKey(t *testing.T) { + images := config.DefaultDockerIsolationConfig().DefaultImages + if v, ok := images[config.GitCapableImageKey]; ok { + t.Errorf("default_images ships %q = %q; presence can no longer mean the operator chose it", + config.GitCapableImageKey, v) + } +} diff --git a/internal/upstream/core/isolation_git_image_loadpath_test.go b/internal/upstream/core/isolation_git_image_loadpath_test.go index c24abc95d..2afd39564 100644 --- a/internal/upstream/core/isolation_git_image_loadpath_test.go +++ b/internal/upstream/core/isolation_git_image_loadpath_test.go @@ -85,13 +85,15 @@ func TestLoadedConfigWithMirroredImagesNeverResolvesAPublicGitImage(t *testing.T } } -// The seeded key is the same trap seen from the other side: the built-in value -// being present in the merged map must not outrank an operator who retargeted -// the runtime at their own registry. -func TestSeededGitKeyDoesNotOutrankAMirroredRuntimeImage(t *testing.T) { +// The same trap seen from the other side: the built-in map must never carry a +// git-capable value of its own that outranks an operator who retargeted the +// runtime at their own registry. (mcpproxy no longer seeds the key at all — +// TestShippedDefaultImagesDoNotSeedTheGitKey pins that — so this is the shape a +// mirrored install really has after load.) +func TestUnsetGitKeyDoesNotOutrankAMirroredRuntimeImage(t *testing.T) { images := config.DefaultDockerIsolationConfig().DefaultImages - if images[config.GitCapableImageKey] == "" { - t.Fatal("precondition: the built-in map is expected to seed the git-capable key") + if v, ok := images[config.GitCapableImageKey]; ok { + t.Fatalf("precondition: the built-in map must not seed %q (got %q)", config.GitCapableImageKey, v) } images["uvx"] = mirroredUvImage images["python"] = mirroredUvImage diff --git a/internal/upstream/core/isolation_git_image_registry_test.go b/internal/upstream/core/isolation_git_image_registry_test.go new file mode 100644 index 000000000..ea49978b6 --- /dev/null +++ b/internal/upstream/core/isolation_git_image_registry_test.go @@ -0,0 +1,67 @@ +package core + +import ( + "strings" + "testing" + + "go.uber.org/zap" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" +) + +func registryOnlyManager(registry string, images map[string]string) *IsolationManager { + global := config.DefaultDockerIsolationConfig() + global.Enabled = true + global.Registry = registry + if images != nil { + global.DefaultImages = images + } + return NewIsolationManagerWithLogger(global, zap.NewNop()) +} + +// `docker_isolation.registry` is the one knob an air-gapped operator is +// guaranteed to set, and it is the whole point of the field. The built-in +// git-capable image was a fully-qualified public ghcr.io reference, and +// buildFullImageName hands any already-qualified reference back untouched — so +// an operator who set ONLY `registry` still had mcpproxy try to pull ghcr.io +// for every git-dependency server, from a host that cannot reach it. +func TestGetDockerImage_BuiltInGitImageHonoursConfiguredRegistry(t *testing.T) { + const registry = "registry.airgap.local" + + cases := map[string]map[string]string{ + // The operator wrote nothing but `registry`. + "no default_images at all": {}, + // The realistic shape after load: the built-in map merged in, still + // entirely mcpproxy's own values. + "built-in default_images merged in": config.DefaultDockerIsolationConfig().DefaultImages, + } + + for name, images := range cases { + t.Run(name, func(t *testing.T) { + im := registryOnlyManager(registry, images) + got, err := im.GetDockerImage(gitDepServer("uvx"), "uvx") + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if strings.Contains(got, "ghcr.io") { + t.Fatalf("GetDockerImage() = %q — a public pull this host cannot make", got) + } + if !strings.HasPrefix(got, registry+"/") { + t.Errorf("GetDockerImage() = %q, want it inside the configured registry %q", got, registry) + } + }) + } +} + +// With no registry configured, the built-in image is unchanged: the shipped +// public reference is the right answer for an ordinary install. +func TestGetDockerImage_BuiltInGitImageUnchangedWithoutRegistry(t *testing.T) { + im := registryOnlyManager("", nil) + got, err := im.GetDockerImage(gitDepServer("uvx"), "uvx") + if err != nil { + t.Fatalf("GetDockerImage() error: %v", err) + } + if got != config.DefaultGitCapableImage { + t.Errorf("GetDockerImage() = %q, want %q", got, config.DefaultGitCapableImage) + } +} From d5b21d476de65d372f37aac930085deb8cac7312 Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Tue, 1 Sep 2026 10:22:41 +0300 Subject: [PATCH 7/7] fix(diagnostics): don't let child stderr claim the handshake-timeout 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. --- internal/diagnostics/classifier.go | 15 ++++- .../classifier_timeout_key_evidence_test.go | 62 +++++++++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 internal/diagnostics/classifier_timeout_key_evidence_test.go diff --git a/internal/diagnostics/classifier.go b/internal/diagnostics/classifier.go index 6abc4c62b..7cf889ae1 100644 --- a/internal/diagnostics/classifier.go +++ b/internal/diagnostics/classifier.go @@ -393,7 +393,20 @@ var execNoSuchFileRe = regexp.MustCompile(`(?:^|[\s"'(])exec(?:ve)?\b[^\n]{0,200 // classifyStdio below and for the suppression guard above, so the two cannot // drift apart. func isStdioHandshakeTimeout(msg string) bool { - return isMCPProxyHandshakeTimeout(msg) || strings.Contains(msg, "handshake timeout") + if isMCPProxyHandshakeTimeout(msg) { + return true + } + // The loose substring is unbounded CHILD STDERR — Go's own + // `net/http: TLS handshake timeout` carries it, and a docker image pull over + // TLS prints exactly that. mcpproxy never writes both of its wrappers, so + // when the premature-exit wrapper is present the child provably DIED and the + // timeout reading (child alive, merely silent) is impossible: the text came + // from the tail. Letting it win there suppressed every docker arm and turned + // a real image-pull failure into "raise your timeout". + if isStdioExitBeforeInitialize(msg) { + return false + } + return strings.Contains(msg, "handshake timeout") } // isMCPProxyHandshakeTimeout matches only the sentence mcpproxy itself writes diff --git a/internal/diagnostics/classifier_timeout_key_evidence_test.go b/internal/diagnostics/classifier_timeout_key_evidence_test.go new file mode 100644 index 000000000..3c9d8bf79 --- /dev/null +++ b/internal/diagnostics/classifier_timeout_key_evidence_test.go @@ -0,0 +1,62 @@ +package diagnostics + +import ( + "errors" + "testing" +) + +// The loose "handshake timeout" substring is unbounded child stderr — Go's own +// `net/http: TLS handshake timeout` carries it, and a docker image pull over +// TLS prints exactly that. When mcpproxy's OWN premature-exit wrapper is also +// present the child provably died, so the timeout reading is impossible: the +// text came from the stderr tail. mcpproxy never writes both wrappers, so their +// co-occurrence is proof, not ambiguity. +// +// Letting the loose key win there both suppressed every docker arm and claimed +// the leading arm of classifyStdio, turning a real image-pull failure into +// "raise your timeout". +func TestClassify_LooseHandshakeTimeoutInStderrDoesNotBeatTheExitWrapper(t *testing.T) { + const pfx = `stdio transport (command="/usr/local/bin/docker", docker_isolation=true): ` + const exited = "server process exited before completing the MCP initialize handshake; recent stderr:\n | " + hints := ClassifierHints{Transport: "stdio", DockerIsolated: true} + + for _, tc := range []struct { + name, stderr string + want Code + }{ + { + // Falls through to the premature-exit code rather than an image-pull + // one: this wording carries no image/pull/fail evidence for + // dockerLayerCode to key on. That is the same answer clean main + // gives, so no diagnosis is lost — the point here is only that the + // stderr's "TLS handshake timeout" must not claim the timeout code. + name: "TLS handshake timeout pulling the image", + stderr: `docker: Error response from daemon: Get "https://ghcr.io/v2/": net/http: TLS handshake timeout.`, + want: STDIOExitBeforeInitialize, + }, + { + name: "app-level handshake timeout next to a real exec failure", + stderr: `app: websocket handshake timeout` + "\n | " + `docker: OCI runtime create failed: exec: "uvx": executable file not found in $PATH`, + want: DockerExecNotFound, + }, + } { + t.Run(tc.name, func(t *testing.T) { + got := Classify(errors.New(pfx+exited+tc.stderr+": transport closed"), hints) + if got == STDIOHandshakeTimeout { + t.Fatalf("stderr text won the timeout guard on the EXIT path: got %s, want %s", got, tc.want) + } + if got != tc.want { + t.Fatalf("got %s, want %s", got, tc.want) + } + }) + } +} + +// mcpproxy's own timeout wrapper must still classify as a timeout. +func TestClassify_RealHandshakeTimeoutStillClassifies(t *testing.T) { + const pfx = `stdio transport (command="/usr/local/bin/docker", docker_isolation=true): ` + err := errors.New(pfx + "server did not respond to MCP initialize within 30s (subprocess may have crashed); recent stderr:\n | still loading") + if got := Classify(err, ClassifierHints{Transport: "stdio", DockerIsolated: true}); got != STDIOHandshakeTimeout { + t.Fatalf("real timeout lost its code: got %s, want %s", got, STDIOHandshakeTimeout) + } +}