From 1c975b83486325894b6285fe29be3bdd91533140 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 22 Aug 2026 21:13:33 +1000 Subject: [PATCH] fix(container): persist npm cache for per-task MCP servers Ephemeral task containers re-resolve and re-download npx-launched MCP server packages from the npm registry on every task, since each task gets a fresh container with no persistent cache -- a worse amplifier of a registry outage than the daemon-restart case d4bb914b already fixed. Extract the daemon's npm-cache env logic into mcp.NpmCacheEnv, shared by both the daemon's own long-lived npx MCP servers and archie-agent's per-task ones. Mount a new archie-cache-mcp-npm Docker volume at /data/cache/mcp-npm on every task container regardless of ecosystem (MCP servers are daemon-wide config, not tied to the task repo's language), and point npx-launched per-task stdio transports at it. Closes archie-core-qk8m. --- cmd/archied/main.go | 25 ++----- internal/app/agentworker/mcp_providers.go | 9 +++ .../app/agentworker/mcp_providers_test.go | 43 ++++++++++- internal/storage/storage.go | 44 ++++++++--- internal/storage/storage_test.go | 73 +++++++++++++++++-- internal/tools/mcp/npm_cache.go | 29 ++++++++ internal/tools/mcp/npm_cache_test.go | 60 +++++++++++++++ 7 files changed, 246 insertions(+), 37 deletions(-) create mode 100644 internal/tools/mcp/npm_cache.go create mode 100644 internal/tools/mcp/npm_cache_test.go diff --git a/cmd/archied/main.go b/cmd/archied/main.go index 398420ff0..202dbeb79 100644 --- a/cmd/archied/main.go +++ b/cmd/archied/main.go @@ -180,20 +180,10 @@ func (a chatTaskListerAdapter) ListChatTasks(ctx context.Context, identity strin // restarts, instead of npm re-resolving and re-downloading the package // from the registry every time the daemon starts. Rooted under the // daemon's own work dir so it persists regardless of whether the daemon -// itself runs in an ephemeral container. Empty for any command other than -// npx, which has no such registry dependency to begin with. -// -// This covers the npm package itself, not a package's own separate -// download path -- e.g. Playwright/Puppeteer-based servers fetch browser -// binaries from a CDN via a postinstall script, gated by their own env -// vars, which this does not touch. -// -// Matched by base name, not exact string: this repo's own -// config.example.toml uses absolute paths for other daemon-launched -// commands (update_check_command, update_install_command), so an operator -// who pins npx the same way ("/usr/local/bin/npx") must still get the -// fix -- an exact match would skip it silently, with no error logged, -// leaving the original bug in place unnoticed. +// itself runs in an ephemeral container. See mcp.NpmCacheEnv for the +// command-matching and env var details shared with archie-agent's +// per-task equivalent (internal/app/agentworker/mcp_providers.go), which +// points at a mounted cache volume instead of a work-dir subdirectory. // // workDir is unconditionally defaulted before registerTools runs // (internal/infrastructure/configuration's applyGeneralDefaults), but @@ -202,13 +192,10 @@ func (a chatTaskListerAdapter) ListChatTasks(ctx context.Context, identity strin // persistent data directory -- guard it explicitly rather than trust that // invariant here too, the way memoryProvider already does nearby. func npmCacheServerEnv(command, workDir string) []string { - if filepath.Base(command) != "npx" || workDir == "" { + if workDir == "" { return nil } - return []string{ - "NPM_CONFIG_CACHE=" + filepath.Join(workDir, "mcp-npm-cache"), - "NPM_CONFIG_PREFER_OFFLINE=true", - } + return mcp.NpmCacheEnv(command, filepath.Join(workDir, "mcp-npm-cache")) } func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovider.Engine, error) { diff --git a/internal/app/agentworker/mcp_providers.go b/internal/app/agentworker/mcp_providers.go index 9c8b8670e..da98e684c 100644 --- a/internal/app/agentworker/mcp_providers.go +++ b/internal/app/agentworker/mcp_providers.go @@ -8,6 +8,7 @@ import ( "strings" "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/storage" "github.com/samcharles93/archie-core/internal/tools" "github.com/samcharles93/archie-core/internal/tools/mcp" toolprovider "github.com/samcharles93/archie-core/internal/tools/provider" @@ -102,9 +103,17 @@ func mcpTransportForServer( if command == "" { return nil, fmt.Errorf("MCP stdio server %q requires a command", name) } + // storage.MCPNPMCacheMountDir is a shared Docker volume mounted on + // every task container (internal/storage's alwaysOnCacheVolumes), + // so an npx-launched MCP server reuses a warm npm cache across + // tasks instead of re-resolving/re-downloading from the registry + // in each fresh ephemeral container. Mirrors the daemon's own + // npx MCP servers (cmd/archied/main.go's npmCacheServerEnv), + // which persists across daemon restarts the same way. return mcp.NewStdioTransport(mcp.StdioTransportConfig{ Command: command, Args: append([]string(nil), server.Args...), + Env: mcp.NpmCacheEnv(command, storage.MCPNPMCacheMountDir), }), nil case "http", "streamablehttp": url := strings.TrimSpace(server.URL) diff --git a/internal/app/agentworker/mcp_providers_test.go b/internal/app/agentworker/mcp_providers_test.go index e76c7aaf4..f0a540f5f 100644 --- a/internal/app/agentworker/mcp_providers_test.go +++ b/internal/app/agentworker/mcp_providers_test.go @@ -10,6 +10,7 @@ import ( "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/plugin" + "github.com/samcharles93/archie-core/internal/storage" "github.com/samcharles93/archie-core/internal/tools" protocolmcp "github.com/samcharles93/archie-core/internal/tools/mcp" toolprovider "github.com/samcharles93/archie-core/internal/tools/provider" @@ -72,6 +73,7 @@ func TestBuildMCPProviderSelectsTransport(t *testing.T) { wantType any wantCommand string wantArgs []string + wantEnv []string wantEndpoint string wantMessageEndpoint string wantHeaders map[string]string @@ -93,6 +95,29 @@ func TestBuildMCPProviderSelectsTransport(t *testing.T) { wantType: (*protocolmcp.StdioTransport)(nil), wantCommand: "server", }, + { + // Task containers are ephemeral, so an npx-launched MCP server + // must be pointed at the shared mcp-npm cache volume mounted on + // every container -- otherwise it re-resolves/re-downloads from + // the registry on every single task. + name: "npx stdio server gets the persistent npm cache", + server: config.MCPServer{Name: "local", Command: "npx", Args: []string{"-y", "some-mcp-server"}}, + wantTransport: "stdio", + wantType: (*protocolmcp.StdioTransport)(nil), + wantCommand: "npx", + wantArgs: []string{"-y", "some-mcp-server"}, + wantEnv: []string{ + "NPM_CONFIG_CACHE=" + storage.MCPNPMCacheMountDir, + "NPM_CONFIG_PREFER_OFFLINE=true", + }, + }, + { + name: "non-npx stdio server gets no npm cache env", + server: config.MCPServer{Name: "local", Command: "/usr/local/bin/my-mcp-server"}, + wantTransport: "stdio", + wantType: (*protocolmcp.StdioTransport)(nil), + wantCommand: "/usr/local/bin/my-mcp-server", + }, { name: "http", server: config.MCPServer{Name: "remote", Transport: "http", URL: " https://example.test/mcp ", Headers: map[string]string{"Authorization": "Bearer test"}}, @@ -175,7 +200,7 @@ func TestBuildMCPProviderSelectsTransport(t *testing.T) { if got, want := transport.Elem().Type(), reflect.TypeOf(tc.wantType); got != want { t.Fatalf("transport type = %v, want %v", got, want) } - assertMCPTransportConfig(t, transport.Elem(), tc.wantCommand, tc.wantArgs, tc.wantEndpoint, tc.wantMessageEndpoint, tc.wantHeaders) + assertMCPTransportConfig(t, transport.Elem(), tc.wantCommand, tc.wantArgs, tc.wantEnv, tc.wantEndpoint, tc.wantMessageEndpoint, tc.wantHeaders) }) } } @@ -185,6 +210,7 @@ func assertMCPTransportConfig( transport reflect.Value, wantCommand string, wantArgs []string, + wantEnv []string, wantEndpoint string, wantMessageEndpoint string, wantHeaders map[string]string, @@ -228,6 +254,21 @@ func assertMCPTransportConfig( } } } + + // Env only exists on StdioTransportConfig; other transports have no + // registry-fetch dependency for this check to apply to. + if envField := config.FieldByName("Env"); envField.Kind() != reflect.Invalid { + got := make([]string, envField.Len()) + for i := range envField.Len() { + got[i] = envField.Index(i).String() + } + if len(got) == 0 { + got = nil + } + if !reflect.DeepEqual(got, wantEnv) { + t.Errorf("transport config Env = %v, want %v", got, wantEnv) + } + } } func TestStartMCPProviderLifecycle(t *testing.T) { diff --git a/internal/storage/storage.go b/internal/storage/storage.go index 01ab9c2b0..8bff5cf26 100644 --- a/internal/storage/storage.go +++ b/internal/storage/storage.go @@ -21,6 +21,9 @@ // bun/ -- Bun package cache (shared) // pip/ -- pip cache (shared) // cargo/ -- Rust cargo cache (shared) +// mcp-npm/ -- npm cache for npx-launched per-task MCP +// servers (shared, mounted regardless of the +// task repo's ecosystem -- see MCPNPMCacheMountDir) // // Cache volumes are named Docker volumes created once and shared across all // tasks. They are never deleted -- the daemon operator manages them. @@ -134,6 +137,15 @@ const ( PluginsDir = PersistentMountDir + "/plugins" ) +// MCPNPMCacheMountDir is the fixed container path where the npm package +// cache for npx-launched per-task MCP servers is mounted. Unlike the +// ecosystem caches below, this is mounted on every task container +// regardless of the task repo's language: per-task MCP servers come from +// daemon-wide config (config.MCPServer), not from anything specific to the +// checked-out repo, so an npx-based server needs the cache warm whether the +// task is a Go repo, a Python repo, or anything else. +const MCPNPMCacheMountDir = "/data/cache/mcp-npm" + // Backend prepares container storage. Each container runtime backend // (Docker, future containerd, etc.) implements this interface. type Backend interface { @@ -155,6 +167,16 @@ type cacheVolume struct { MountPath string // container destination path } +// alwaysOnCacheVolumes are shared cache volumes mounted on every task +// container regardless of the task repo's ecosystem, because what they +// cache isn't tied to the repo being worked on. The npx package cache for +// per-task MCP servers is the only current instance: MCP servers are +// daemon-wide config, not per-repo, so an npx-based one needs a warm cache +// no matter which repo the task happens to be against. +var alwaysOnCacheVolumes = []cacheVolume{ + {Name: "archie-cache-mcp-npm", MountPath: MCPNPMCacheMountDir}, +} + // cacheVolumesByEcosystem maps ecosystem names to their shared cache volumes. // Volumes are created once by the pool and never deleted. var cacheVolumesByEcosystem = map[string][]cacheVolume{ @@ -183,14 +205,15 @@ var cacheVolumesByEcosystem = map[string][]cacheVolume{ }, } -// cacheMounts returns the cache mount specs for an ecosystem, sorted by -// destination path for deterministic container configuration. -// Ecosystem is case-insensitive -- "Python" and "python" are equivalent. +// cacheMounts returns the cache mount specs for an ecosystem -- the +// always-on volumes plus any matched by ecosystem -- sorted by destination +// path for deterministic container configuration. Ecosystem is +// case-insensitive -- "Python" and "python" are equivalent. An unknown or +// empty ecosystem still returns the always-on volumes. func cacheMounts(ecosystem string) []Mount { - vols, ok := cacheVolumesByEcosystem[strings.ToLower(ecosystem)] - if !ok { - return nil - } + vols := append([]cacheVolume(nil), alwaysOnCacheVolumes...) + vols = append(vols, cacheVolumesByEcosystem[strings.ToLower(ecosystem)]...) + mounts := make([]Mount, len(vols)) for i, v := range vols { mounts[i] = Mount{ @@ -279,9 +302,10 @@ func repoVolumeName(owner, repo string) string { } // Setup returns the mount list for a task container. Mounts are ordered: -// 1. /data/worktree bind mount (always first) -// 2. /data/repo volume mount (only when PersistentStorage is true) -// 3. /data/cache/ volume mounts (sorted by destination) +// 1. /data/worktree bind mount (always first) +// 2. /data/repo volume mount (only when PersistentStorage is true) +// 3. cache volume mounts: the always-on volumes plus /data/cache/ +// (sorted together by destination) func (d *DockerBackend) Setup(ctx context.Context, task TaskRef) ([]Mount, error) { mounts := []Mount{ { diff --git a/internal/storage/storage_test.go b/internal/storage/storage_test.go index cc2728991..cf7414ade 100644 --- a/internal/storage/storage_test.go +++ b/internal/storage/storage_test.go @@ -88,10 +88,27 @@ func TestMountListForEcosystemRust(t *testing.T) { } } -func TestMountListUnknownEcosystemReturnsBaseOnly(t *testing.T) { +func TestMountListUnknownEcosystemReturnsAlwaysOnOnly(t *testing.T) { mounts := cacheMounts("custom") - if len(mounts) != 0 { - t.Errorf("custom ecosystem returned %d mounts, want 0", len(mounts)) + names := mountDestinations(mounts) + if !contains(names, MCPNPMCacheMountDir) { + t.Errorf("unknown ecosystem missing always-on mcp-npm cache in %v", names) + } + if len(mounts) != len(alwaysOnCacheVolumes) { + t.Errorf("custom ecosystem returned %d mounts, want %d (always-on only)", len(mounts), len(alwaysOnCacheVolumes)) + } +} + +func TestMountListAlwaysIncludesMCPNPMCache(t *testing.T) { + // The npm cache for per-task MCP servers isn't tied to the task repo's + // ecosystem, so it must be present regardless of which ecosystem (or + // none) is requested. + for _, eco := range []string{"go", "node", "python", "rust", "custom", ""} { + mounts := cacheMounts(eco) + names := mountDestinations(mounts) + if !contains(names, MCPNPMCacheMountDir) { + t.Errorf("ecosystem %q missing always-on mcp-npm cache in %v", eco, names) + } } } @@ -183,6 +200,42 @@ func TestDockerBackendSetupIncludesCacheMounts(t *testing.T) { } } +func TestDockerBackendSetupIncludesMCPNPMCacheRegardlessOfEcosystem(t *testing.T) { + // The npx package cache for per-task MCP servers must be mounted on + // every task container, not just ones matching an ecosystem with its + // own cache volumes: MCP servers are daemon-wide config, unrelated to + // the repo the task happens to run against. + dir := t.TempDir() + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + + backend := &DockerBackend{} + mounts, err := backend.Setup(context.Background(), TaskRef{ + WorktreeDir: dir, + Ecosystem: "rust", + }) + if err != nil { + t.Fatal(err) + } + + found := false + for _, m := range mounts { + if m.Destination == MCPNPMCacheMountDir { + found = true + if m.Type != MountTypeVolume { + t.Errorf("mcp-npm cache mount type = %q, want volume", m.Type) + } + if m.Source != "archie-cache-mcp-npm" { + t.Errorf("mcp-npm cache mount source = %q, want archie-cache-mcp-npm", m.Source) + } + } + } + if !found { + t.Error("Setup did not include the mcp-npm cache mount") + } +} + func TestDockerBackendSetupWorktreeMountIsFirst(t *testing.T) { // Worktree bind mount must be the first entry -- container create // depends on this order for overlay semantics. @@ -266,7 +319,8 @@ func TestDockerBackendSetupEmptyEcosystem(t *testing.T) { } func TestDockerBackendSetupUnknownEcosystemSkipped(t *testing.T) { - // Unknown ecosystem must not add cache mounts, but must not error. + // Unknown ecosystem must not add ecosystem-specific cache mounts (only + // the always-on ones), but must not error. dir := t.TempDir() if err := os.MkdirAll(dir, 0o755); err != nil { t.Fatal(err) @@ -281,7 +335,7 @@ func TestDockerBackendSetupUnknownEcosystemSkipped(t *testing.T) { t.Fatal("Setup errored on unknown ecosystem:", err) } for _, m := range mounts { - if m.Destination != "/data/worktree" { + if m.Destination != "/data/worktree" && m.Destination != MCPNPMCacheMountDir { t.Errorf("unexpected mount %s for unknown ecosystem", m.Destination) } } @@ -437,7 +491,11 @@ func TestRepoVolumeName(t *testing.T) { } func TestDockerBackendLabelsPersistentRepoVolumes(t *testing.T) { - var createBody string + // Setup also ensures the always-on mcp-npm cache volume (and any + // ecosystem-specific ones) alongside the per-repo volume, so every + // /volumes/create body must be collected rather than captured into a + // single variable that the last request would overwrite. + var createBodies []string cli := dockerTestClient(t, func(req *http.Request) (*http.Response, error) { path := dockerAPIPath(req.URL.Path) switch { @@ -448,7 +506,7 @@ func TestDockerBackendLabelsPersistentRepoVolumes(t *testing.T) { if readErr != nil { return nil, readErr } - createBody = string(data) + createBodies = append(createBodies, string(data)) return dockerResponse(http.StatusCreated, `{"Name":"archie-repo-alice-demo","Driver":"local","Labels":{}}`), nil default: return dockerResponse(http.StatusNotFound, `{"message":"unexpected request"}`), nil @@ -465,6 +523,7 @@ func TestDockerBackendLabelsPersistentRepoVolumes(t *testing.T) { }); err != nil { t.Fatal(err) } + createBody := strings.Join(createBodies, "\n") if !strings.Contains(createBody, `"com.samcharles93.archie.storage":"repo"`) { t.Fatalf("persistent volume create body lacks Archie repo label: %s", createBody) } diff --git a/internal/tools/mcp/npm_cache.go b/internal/tools/mcp/npm_cache.go new file mode 100644 index 000000000..8efa49b73 --- /dev/null +++ b/internal/tools/mcp/npm_cache.go @@ -0,0 +1,29 @@ +package mcp + +import "path/filepath" + +// NpmCacheEnv returns environment variables that make an npx-launched MCP +// server reuse a persistent package cache at cacheDir, instead of npm +// re-resolving and re-downloading the package from the registry on every +// launch. Empty for any command other than npx, or an empty cacheDir -- +// npx has a registry dependency other commands don't, and an empty cacheDir +// means the caller has no persistent location to point npm at. +// +// This covers the npm package itself, not a package's own separate +// download path -- e.g. Playwright/Puppeteer-based servers fetch browser +// binaries from a CDN via a postinstall script, gated by their own env +// vars, which this does not touch. +// +// Matched by base name, not exact string: a command may be pinned via an +// absolute path (an operator's daemon config, or a container image's PATH), +// and an exact "npx" match would skip the fix silently, with no error +// logged, leaving the underlying registry re-fetch in place unnoticed. +func NpmCacheEnv(command, cacheDir string) []string { + if filepath.Base(command) != "npx" || cacheDir == "" { + return nil + } + return []string{ + "NPM_CONFIG_CACHE=" + cacheDir, + "NPM_CONFIG_PREFER_OFFLINE=true", + } +} diff --git a/internal/tools/mcp/npm_cache_test.go b/internal/tools/mcp/npm_cache_test.go new file mode 100644 index 000000000..2105c0b91 --- /dev/null +++ b/internal/tools/mcp/npm_cache_test.go @@ -0,0 +1,60 @@ +package mcp + +import ( + "slices" + "testing" +) + +func TestNpmCacheEnv(t *testing.T) { + cases := []struct { + name string + command string + cacheDir string + want []string + }{ + { + name: "npx gets a persistent cache", + command: "npx", + cacheDir: "/data/cache/mcp-npm", + want: []string{ + "NPM_CONFIG_CACHE=/data/cache/mcp-npm", + "NPM_CONFIG_PREFER_OFFLINE=true", + }, + }, + { + name: "an absolute path to npx still gets the persistent cache", + command: "/usr/local/bin/npx", + cacheDir: "/data/cache/mcp-npm", + want: []string{ + "NPM_CONFIG_CACHE=/data/cache/mcp-npm", + "NPM_CONFIG_PREFER_OFFLINE=true", + }, + }, + { + name: "a non-npx command has no npm registry dependency to fix", + command: "/usr/local/bin/my-mcp-server", + cacheDir: "/data/cache/mcp-npm", + want: nil, + }, + { + name: "empty command is left alone", + command: "", + cacheDir: "/data/cache/mcp-npm", + want: nil, + }, + { + name: "empty cacheDir is refused rather than caching into the process CWD", + command: "npx", + cacheDir: "", + want: nil, + }, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + got := NpmCacheEnv(c.command, c.cacheDir) + if !slices.Equal(got, c.want) { + t.Errorf("NpmCacheEnv(%q, %q) = %v, want %v", c.command, c.cacheDir, got, c.want) + } + }) + } +}