fix(mcp): persist npx package cache across daemon restarts

config.docker.toml launches MCP servers with `npx -y <pkg>@<version>`,
and the container has no persistent npm cache, so every daemon restart
re-resolved and re-downloaded the package from the registry -- slow,
and it turns a registry outage or a yanked version into a daemon
outage. It directly amplified the crash loop observed on 2026-07-30,
since each restart repeated the whole download.

configuredMCPProvider now points npx-launched servers (matched by base
name, so an absolute-path npx still qualifies) at NPM_CONFIG_CACHE
under the daemon's own persistent work_dir, plus
NPM_CONFIG_PREFER_OFFLINE=true so a warm cache skips the registry
round trip entirely. Does not cover a package's own separate
downloads (e.g. Playwright/Puppeteer fetching a browser binary via
its postinstall script).

Closes archie-core-1786637490923-43-d4bb914b.

The identical, arguably worse instance in
internal/app/agentworker/mcp_providers.go (every per-task ephemeral
container, not just daemon restarts) needs a persistent Docker volume
that doesn't exist yet, so it's filed separately as
archie-core-qk8m rather than folded into this scoped fix.
This commit is contained in:
sam committed 2026-08-19 02:08:33 +10:00
1 parent f1b65c0ef9
commit d4e343b694
4 files changed
+125 -4

No files matched your search

+1 -1
View File
@@ -805,7 +805,7 @@ func (b *boot) registerTools() error {
log.Info("workspace tools disabled (chat.workspace is unset)")
}
for _, srv := range cfg.Tools.MCPServers {
provider, err := configuredMCPProvider(srv)
provider, err := configuredMCPProvider(srv, cfg.WorkDir)
if err != nil {
log.Warn("mcp tool provider skipped", "name", srv.Name, "err", err)
continue
+38 -1
View File
@@ -175,7 +175,43 @@ func (a chatTaskListerAdapter) ListChatTasks(ctx context.Context, identity strin
return out, nil
}
func configuredMCPProvider(server config.MCPServer) (toolprovider.Engine, error) {
// npmCacheServerEnv returns environment variables that make an
// npx-launched MCP server reuse a persistent package cache across daemon
// 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.
//
// workDir is unconditionally defaulted before registerTools runs
// (internal/infrastructure/configuration's applyGeneralDefaults), but
// filepath.Join silently accepts an empty string and would then put the
// cache in the daemon's current working directory instead of its
// 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 == "" {
return nil
}
return []string{
"NPM_CONFIG_CACHE=" + filepath.Join(workDir, "mcp-npm-cache"),
"NPM_CONFIG_PREFER_OFFLINE=true",
}
}
func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovider.Engine, error) {
name := strings.TrimSpace(server.Name)
if name == "" {
return nil, fmt.Errorf("MCP server name is required")
@@ -195,6 +231,7 @@ func configuredMCPProvider(server config.MCPServer) (toolprovider.Engine, error)
Command: command,
Args: append([]string(nil), server.Args...),
Dir: server.WorkDir,
Env: npmCacheServerEnv(command, workDir),
})
return mcptoolprovider.New(name, transport), nil
+78 -1
View File
@@ -8,6 +8,7 @@ import (
"log/slog"
"os"
"path/filepath"
"slices"
"strings"
"sync"
"testing"
@@ -362,7 +363,7 @@ func TestConfiguredMCPProviderSupportsAllTransportTypes(t *testing.T) {
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
provider, err := configuredMCPProvider(tt.server)
provider, err := configuredMCPProvider(tt.server, t.TempDir())
if (err != nil) != tt.wantErr {
t.Fatalf("configuredMCPProvider() error = %v, wantErr %t", err, tt.wantErr)
}
@@ -379,6 +380,82 @@ func TestConfiguredMCPProviderSupportsAllTransportTypes(t *testing.T) {
}
}
// TestNpmCacheServerEnvPersistsCacheAcrossRestarts: config.docker.toml
// launched an MCP server with `npx -y @pkg@version`, and the container has
// no persistent npm cache, so every daemon restart re-resolved and
// re-downloaded the package (and its dependency tree) from the registry --
// slow, and it turns a registry outage or yanked version into a daemon
// outage. It amplified the crash loop observed on 2026-07-30, since each
// restart repeated the whole download. Pointing NPM_CONFIG_CACHE at the
// daemon's own persistent work dir means the second and later starts hit a
// warm cache regardless of whether the daemon itself runs in an ephemeral
// container. NPM_CONFIG_PREFER_OFFLINE keeps npm from making a registry
// round trip at all when the cache already has what it needs.
func TestNpmCacheServerEnvPersistsCacheAcrossRestarts(t *testing.T) {
cases := []struct {
name string
command string
workDir string
want []string
}{
{
name: "npx gets a persistent cache under the daemon's work dir",
command: "npx",
workDir: "/var/lib/archie",
want: []string{
"NPM_CONFIG_CACHE=/var/lib/archie/mcp-npm-cache",
"NPM_CONFIG_PREFER_OFFLINE=true",
},
},
{
name: "a non-npx command has no npm registry dependency to fix",
command: "/usr/local/bin/my-mcp-server",
workDir: "/var/lib/archie",
want: nil,
},
{
name: "empty command is left alone (configuredMCPProvider rejects it separately)",
command: "",
workDir: "/var/lib/archie",
want: nil,
},
{
// This repo's own config.example.toml uses absolute paths for
// other daemon-launched commands (update_check_command,
// update_install_command), so an operator pinning npx the same
// way must still get the fix -- an exact "npx" match would
// silently skip it with no error, leaving the original bug in
// place unnoticed.
name: "an absolute path to npx still gets the persistent cache",
command: "/usr/local/bin/npx",
workDir: "/var/lib/archie",
want: []string{
"NPM_CONFIG_CACHE=/var/lib/archie/mcp-npm-cache",
"NPM_CONFIG_PREFER_OFFLINE=true",
},
},
{
// workDir is unconditionally defaulted before this ever runs
// in production, but filepath.Join silently accepts an empty
// string -- defend explicitly rather than trust that
// invariant here too, matching memoryProvider's own guard
// against the same possibility.
name: "an empty workDir is refused rather than caching into the daemon's CWD",
command: "npx",
workDir: "",
want: nil,
},
}
for _, c := range cases {
t.Run(c.name, func(t *testing.T) {
got := npmCacheServerEnv(c.command, c.workDir)
if !slices.Equal(got, c.want) {
t.Errorf("npmCacheServerEnv(%q, %q) = %v, want %v", c.command, c.workDir, got, c.want)
}
})
}
}
func TestManualRequeueTaskUsesPersistedStatus(t *testing.T) {
tests := []string{store.StatusParked, store.StatusWaitingHuman}
for index, status := range tests {
+8 -1
View File
@@ -114,7 +114,14 @@ class = "ollama"
# update_check_command = ["/usr/local/bin/archie-update-check"]
# update_install_command = ["/usr/local/bin/archie-update-install"]
# External MCP tools are launched and managed by Archie's MCP client.
# External MCP tools are launched and managed by Archie's MCP client. A
# command of "npx" gets a persistent package cache under work_dir
# (top of this file) automatically, so a daemon restart reuses it instead
# of re-resolving and re-downloading the package from the npm registry
# every time. This does not cover a package's own separate downloads (e.g.
# a Playwright/Puppeteer-based server fetching a browser binary from a CDN
# via its postinstall script) -- consult that package's own env vars for
# those.
# [[tools.mcp_servers]]
# name = "desktop-commander"
# transport = "stdio"