Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

MCP: start local servers on first use

justrachb732612d2dad
diff --git a/assets/skills/mcp-config.md b/assets/skills/mcp-config.md
index 0de3a484..aefaed3f 100644
--- a/assets/skills/mcp-config.md
+++ b/assets/skills/mcp-config.md
@@ -39,6 +39,10 @@ global one with the same name. Their tools reach the model as
still loads. If tools vanished after an edit, check the file parses first.
- `~/.mcpconfig.json` is not read - that path belongs to other MCP clients.
Startup says so once if it exists.
+- A local server starts on first use once graff has seen its tools (they are
+ cached): the session lists its tools but spawns the process only when a tool
+ is called. `"startup": "eager"` on an entry starts it with every session;
+ `GRAFF_MCP_EAGER=1` does that for all of them.
## Prefer the CLI for writes
@@ -51,8 +55,9 @@ graff mcp add <name> --url https://host/mcp --header KEY=VALUE
graff mcp login <name> # OAuth for a remote server
```
-`graff mcp add` and `/mcp add` always write the project `.mcp.json`, never the
-global file - adding a server to one repository must not edit every other one.
+`graff mcp add` and `/mcp add` write the project `.mcp.json`; only
+`graff mcp add … --everywhere` writes the global file - adding a server to one
+repository must not edit every other one.
Editing either file with `edit_file` or `write_file` is equally valid, and it is
how you remove a server (drop its key) or rename one. Do not commit a secret
into it: prefer `graff mcp login` (OAuth credentials are stored outside the
diff --git a/build.zig b/build.zig
index 6c304068..ba3d454b 100644
--- a/build.zig
+++ b/build.zig
@@ -156,6 +156,9 @@ pub fn build(b: *std.Build) void {
const mcp_client_spec_test = b.addSystemCommand(&.{ "python3", "scripts/test-mcp-client-spec.py" });
mcp_client_spec_test.addArtifactArg(exe);
test_step.dependOn(&mcp_client_spec_test.step);
+ const mcp_lazy_test = b.addSystemCommand(&.{ "python3", "scripts/test-mcp-lazy.py" });
+ mcp_lazy_test.addArtifactArg(exe);
+ test_step.dependOn(&mcp_lazy_test.step);
const mcp_add_test = b.addSystemCommand(&.{ "python3", "scripts/test-mcp-add.py" });
mcp_add_test.addArtifactArg(exe);
test_step.dependOn(&mcp_add_test.step);
diff --git a/scripts/test-mcp-lazy.py b/scripts/test-mcp-lazy.py
new file mode 100644
index 00000000..4480b295
--- /dev/null
+++ b/scripts/test-mcp-lazy.py
@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Local MCP servers start on first use, not with every session.
+
+- the first session with a new server starts it (its tools are learned and cached)
+- later sessions advertise the cached tools and never spawn the process
+- the first tool call spawns it once, runs the legacy handshake, answers, and
+ re-lists tools to refresh the cache
+- GRAFF_MCP_EAGER=1, and "startup": "eager" on one entry, start at boot
+- a server that fails to start on first use gives the model an error; the
+ session keeps going
+"""
+import json, os, shutil, subprocess, sys, tempfile, time
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parent / 'eval'))
+from mock_model import ScriptedModel
+
+SERVER = r"""
+import json, os, sys, time
+log = sys.argv[1]
+def rec(o):
+ with open(log, "a") as f: f.write(json.dumps(o) + "\n")
+if os.environ.get("LAZY_FAIL_FILE") and os.path.exists(os.environ["LAZY_FAIL_FILE"]):
+ rec({"event": "start-refused", "pid": os.getpid()}); sys.exit(3)
+rec({"event": "start", "pid": os.getpid()})
+def out(o): sys.stdout.write(json.dumps(o) + "\n"); sys.stdout.flush()
+for line in sys.stdin:
+ try: m = json.loads(line)
+ except ValueError: continue
+ meth = m.get("method"); mid = m.get("id")
+ rec({"event": "method", "method": meth, "pid": os.getpid()})
+ if mid is None: continue
+ if meth == "initialize":
+ out({"jsonrpc": "2.0", "id": mid, "result": {"protocolVersion": "2025-11-25", "capabilities": {"tools": {}}, "serverInfo": {"name": "lazy", "version": "1"}}})
+ elif meth == "server/discover":
+ out({"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": "Method not found"}})
+ elif meth == "tools/list":
+ out({"jsonrpc": "2.0", "id": mid, "result": {"tools": [
+ {"name": "echo", "description": "echo back", "inputSchema": {"type": "object", "properties": {}}}]}})
+ elif meth == "tools/call":
+ out({"jsonrpc": "2.0", "id": mid, "result": {"content": [{"type": "text", "text": "echo from pid %d" % os.getpid()}]}})
+ else:
+ out({"jsonrpc": "2.0", "id": mid, "result": {}})
+"""
+
+
+def events(log, name):
+ if not log.exists():
+ return []
+ return [json.loads(l) for l in log.read_text().splitlines() if l.strip() and json.loads(l).get('server', name) == name]
+
+
+class Slow(ScriptedModel):
+ # --yolo joins MCP in the background after the first request; a short
+ # delay plus a todo_read warm-up lets the join land before MCP is needed.
+ def next_reply(self, body):
+ time.sleep(1.5)
+ return super().next_reply(body)
+
+
+WARM = {'tool': 'todo_read', 'arguments': {}}
+
+
+def run(binary, work, env, script, extra_env=None):
+ model = Slow([WARM] + script)
+ port = model.start(0)
+ e = dict(env, GRAFF_VERCEL_URL=f'http://127.0.0.1:{port}/v1/chat/completions', **(extra_env or {}))
+ try:
+ r = subprocess.run([binary, '--model', 'vercel', '--old', '--no-lean', '--yolo', '-p', 'go'], cwd=work, env=e,
+ capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=180)
+ model.stderr = r.stderr
+ finally:
+ model.stop()
+ return model
+
+
+def main():
+ binary = str(Path(sys.argv[1] if len(sys.argv) > 1 else 'zig-out/bin/graff').resolve())
+ temp = Path(tempfile.mkdtemp(prefix='graff-mcp-lazy-'))
+ try:
+ (temp / 'server.py').write_text(SERVER)
+ work = temp / 'proj'
+ work.mkdir()
+ logs = {n: temp / f'{n}.log' for n in ('lazy', 'pinned')}
+ fail_flag = temp / 'refuse-start'
+ cfg = {'mcpServers': {
+ 'lazy': {'command': sys.executable, 'args': [str(temp / 'server.py'), str(logs['lazy'])], 'env': {'LAZY_FAIL_FILE': str(fail_flag)}},
+ 'pinned': {'command': sys.executable, 'args': [str(temp / 'server.py'), str(logs['pinned'])], 'startup': 'eager'},
+ }}
+ (work / '.mcp.json').write_text(json.dumps(cfg))
+ env = {k: v for k, v in os.environ.items() if not k.endswith('_API_KEY')}
+ # No GRAFF_MCP_CONFIG: an empty override is MCP's off-switch (#549). HOME is private.
+ env.update(HOME=str(temp), AI_GATEWAY_API_KEY='local', GRAFF_NO_TELEMETRY='1', GRAFF_FLEET='off',
+ GRAFF_NO_SMOLIFY='1', GRAFF_NO_CODEDB_GUARD='1', GRAFF_REPL_DEBUG='1')
+
+ def starts(name):
+ return [e for e in events(logs[name], name) if e['event'] == 'start']
+
+ # 1. First session ever: nothing cached, so the server starts to learn its tools.
+ run(binary, work, env, [{'text': 'hello'}])
+ assert len(starts('lazy')) == 1, events(logs['lazy'], 'lazy')
+ cache = json.loads((temp / '.codegraff/mcp-list-cache.json').read_text())
+ assert any(str(temp / 'server.py') in k for k in cache['servers']), cache
+ print('PASS a new server starts once so its tools can be learned and cached', flush=True)
+
+ # 2. Later session, no MCP call: tools advertised from cache, process never spawned.
+ before = len(starts('lazy'))
+ model = run(binary, work, env, [{'text': 'hello again'}])
+ assert len(starts('lazy')) == before, 'the lazy server started without being used'
+ assert '[mcp:lazy] ready — 1 tool(s), starts on first use' in model.stderr, model.stderr[-800:]
+ assert len(starts('pinned')) == 2, 'a "startup":"eager" server must still start with every session'
+ print('PASS a cached server is registered from its cached tools but not spawned; "startup": "eager" still starts at boot', flush=True)
+
+ # 3. First use spawns it once, handshakes (legacy), answers, and refreshes the cache.
+ logs['lazy'].write_text('')
+ stamp_before = json.loads((temp / '.codegraff/mcp-list-cache.json').read_text())
+ model = run(binary, work, env, [
+ {'tool': 'mcp__lazy__echo', 'arguments': {}},
+ {'tool': 'mcp__lazy__echo', 'arguments': {}},
+ {'text': 'done'},
+ ])
+ ev = events(logs['lazy'], 'lazy')
+ assert len([e for e in ev if e['event'] == 'start']) == 1, ev
+ methods = [e['method'] for e in ev if e['event'] == 'method']
+ assert methods[:2] == ['initialize', 'notifications/initialized'], methods
+ assert methods.count('tools/call') == 2 and 'tools/list' in methods, methods
+ results = [m.get('content') for r in model.requests for m in r.get('messages', []) if m.get('role') == 'tool']
+ assert any('echo from pid' in str(r) for r in results), results
+ stamp_after = json.loads((temp / '.codegraff/mcp-list-cache.json').read_text())
+ key = next(k for k in stamp_after['servers'] if str(logs['lazy']) in k)
+ assert stamp_after['servers'][key]['fetched_unix_ms'] > stamp_before['servers'][key]['fetched_unix_ms'], 'cache not refreshed on wake'
+ print('PASS the first call spawns it once, runs initialize before tools/call, answers both calls, refreshes the cache', flush=True)
+
+ # 4. GRAFF_MCP_EAGER=1 starts every server at boot.
+ logs['lazy'].write_text('')
+ m4 = run(binary, work, env, [{'text': 'eager'}], {'GRAFF_MCP_EAGER': '1'})
+ assert len(starts('lazy')) == 1, 'GRAFF_MCP_EAGER=1 did not start the server at boot: ' + m4.stderr[-600:]
+ print('PASS GRAFF_MCP_EAGER=1 starts servers with the session', flush=True)
+
+ # 5. A server that cannot start on first use: the model gets an error, the turn goes on.
+ logs['lazy'].write_text('')
+ fail_flag.write_text('1')
+ model = run(binary, work, env, [
+ {'tool': 'mcp__lazy__echo', 'arguments': {}},
+ {'text': 'carried on'},
+ ])
+ results = [str(m.get('content')) for r in model.requests for m in r.get('messages', []) if m.get('role') == 'tool']
+ assert any('MCP server lazy failed to start' in r for r in results), results
+ assert any(e['event'] == 'start-refused' for e in events(logs['lazy'], 'lazy')), 'the wake was never attempted'
+ assert len(model.requests) >= 2, 'the turn stopped at the failed start'
+ print('PASS a server that fails to start on first use returns an error and the turn continues', flush=True)
+ finally:
+ shutil.rmtree(temp, ignore_errors=True)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/scripts/test-mcp-stdio-probe.py b/scripts/test-mcp-stdio-probe.py
index d2044ed5..14042929 100644
--- a/scripts/test-mcp-stdio-probe.py
+++ b/scripts/test-mcp-stdio-probe.py
@@ -170,6 +170,9 @@ def run_graff(graff: Path, fixture: Path, probe: bool) -> subprocess.CompletedPr
# so explicitly — merely unsetting the variable ran scenario 1 with the
# probe enabled and asserted nothing it claimed to.
env["GRAFF_MCP_PROBE"] = "1" if probe else "0"
+ # The probe runs when a server connects. Keep the fixture from starting
+ # on first use (a cached catalog from the first scenario would).
+ env["GRAFF_MCP_EAGER"] = "1"
return subprocess.run(
[str(graff), "--json", "--yolo", "--model", "claude"],
cwd=workspace,
diff --git a/src/mcp.zig b/src/mcp.zig
index 0f3da30a..ebc9d567 100644
--- a/src/mcp.zig
+++ b/src/mcp.zig
@@ -86,6 +86,9 @@ pub const Registry = struct {
/// opted out of the probe by `GRAFF_MCP_PROBE=0` — the env var reaches
/// only the config-file path.
stdio_probe: bool = true,
+ /// Cached stdio servers start on first use (mcp_lazy.zig). Only
+ /// `Registry.init` reads `GRAFF_MCP_EAGER`; verification paths set false.
+ lazy_stdio: bool = true,
/// An image an MCP tool returned, waiting for the next turn to collect it
/// (#249). Written under `mutex` by `call`, drained by
/// `vision.mcpImageHandoff` — the registry cannot reach the agent itself.
@@ -272,7 +275,7 @@ pub const Registry = struct {
/// time: some legacy SDK servers close stdout on an unrecognized
/// pre-`initialize` message (`server/discover`), and the only fix is a
/// fresh process — the closed one can't be un-closed.
- fn spawnStdio(reg: *Registry, a: Allocator, argv: []const []const u8, env_map: ?*std.process.Environ.Map, cwd: ?[]const u8) !Transport {
+ pub fn spawnStdio(reg: *Registry, a: Allocator, argv: []const []const u8, env_map: ?*std.process.Environ.Map, cwd: ?[]const u8) !Transport {
var child = try std.process.spawn(reg.io, .{
.argv = argv,
.stdin = .pipe,
@@ -302,6 +305,15 @@ pub const Registry = struct {
const command_v = cfg.get("command");
const url_v = cfg.get("url");
if ((command_v == null) == (url_v == null)) return error.BadMcpConfig;
+ const mcp_lazy = @import("mcp_lazy.zig");
+ if (reg.lazy_stdio) if (try mcp_lazy.dormantFromCache(reg.io, a, reg.home, name, cfg)) |d| {
+ const tools_before = tools.items.len;
+ errdefer tools.shrinkRetainingCapacity(tools_before);
+ try @import("mcp_pages.zig").appendTools(a, tools, servers.items.len, d.server, d.tools);
+ try servers.append(a, d.server);
+ if (reg.show_diagnostics) std.debug.print(" [mcp:{s}] ready — {d} tool(s), starts on first use\n", .{ name, d.tools.array.items.len });
+ return;
+ };
const server = try a.create(Server);
// Hoisted out of the `else` branch below (rather than local to it)
@@ -343,34 +355,10 @@ pub const Registry = struct {
} },
};
} else {
- const command = if (command_v.? == .string) command_v.?.string else return error.BadMcpConfig;
- try stdio_argv.append(a, command);
- if (cfg.get("args")) |args| {
- if (args != .array) return error.BadMcpConfig;
- for (args.array.items) |arg| {
- if (arg != .string) return error.BadMcpConfig;
- try stdio_argv.append(a, arg.string);
- }
- }
-
- if (cfg.get("cwd")) |cwd| {
- if (cwd != .string or cwd.string.len == 0) return error.BadMcpConfig;
- stdio_cwd = cwd.string;
- }
-
- // Optional per-server env overlaid on the parent environment.
- if (cfg.get("env")) |env| {
- if (env != .object) return error.BadMcpConfig;
- const m = try a.create(std.process.Environ.Map);
- m.* = std.process.Environ.Map.init(reg.gpa);
- var env_it = env.object.iterator();
- while (env_it.next()) |entry| {
- if (entry.value_ptr.* != .string) return error.BadMcpConfig;
- try m.put(entry.key_ptr.*, entry.value_ptr.*.string);
- }
- stdio_env_map = m;
- }
-
+ const spec = try mcp_lazy.stdioSpec(reg.gpa, a, cfg);
+ try stdio_argv.appendSlice(a, spec.argv);
+ stdio_env_map = spec.env;
+ stdio_cwd = spec.cwd;
server.* = .{ .name = name, .transport = try spawnStdio(reg, a, stdio_argv.items, stdio_env_map, stdio_cwd) };
}
@@ -401,6 +389,7 @@ pub const Registry = struct {
break :blk hit.tools;
} else blk: {
const listed = switch (server.transport) {
+ .dormant => unreachable, // only built above, from a cache hit
.http => try mcp_rpc.connectHttp(server, a, a, era_hint),
.stdio => stdio_listed: {
if (!reg.stdio_probe) break :stdio_listed try mcp_rpc.connectStdio(server, a, a, reg.io);
@@ -483,6 +472,8 @@ pub const Registry = struct {
var response_arena_state = std.heap.ArenaAllocator.init(reg.gpa);
defer response_arena_state.deinit();
const response_alloc = response_arena_state.allocator();
+ if (server.transport == .dormant) @import("mcp_lazy.zig").wake(reg, server) catch |err|
+ return .{ .text = try std.fmt.allocPrint(out_alloc, "MCP server {s} failed to start: {t}", .{ server.name, err }), .is_error = true };
if (!server.initialized) try initializeServer(server, response_alloc, reg.arena(), null);
server.elicit_source = params;
defer server.elicit_source = "";
diff --git a/src/mcp_add.zig b/src/mcp_add.zig
index 54efb963..5f5d37af 100644
--- a/src/mcp_add.zig
+++ b/src/mcp_add.zig
@@ -197,6 +197,7 @@ pub fn verify(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, entry:
defer rpc.stdio_handshake_timeout_ms = saved_timeout;
var reg = mcp.Registry.emptyWithOAuthHome(gpa, io, home);
defer reg.deinit();
+ reg.lazy_stdio = false; // verifying means really connecting, not reading the cache
const a = reg.arena();
var servers: std.ArrayList(*rpc.Server) = .empty;
var tools: std.ArrayList(mcp.Tool) = .empty;
diff --git a/src/mcp_boot.zig b/src/mcp_boot.zig
index 92fa310b..f833f03b 100644
--- a/src/mcp_boot.zig
+++ b/src/mcp_boot.zig
@@ -62,6 +62,7 @@ const StartCtx = struct {
home: []const u8,
show_diagnostics: bool,
stdio_probe: bool,
+ lazy_stdio: bool = true,
ready: ?*std.atomic.Value(bool) = null,
};
@@ -80,6 +81,7 @@ fn startServerTask(ctx: StartCtx, name: []const u8, cfg: std.json.ObjectMap) Sta
.home = ctx.home,
.arena_state = std.heap.ArenaAllocator.init(ctx.gpa),
.stdio_probe = ctx.stdio_probe,
+ .lazy_stdio = ctx.lazy_stdio,
.show_diagnostics = ctx.show_diagnostics,
};
defer tmp.arena_state.deinit();
@@ -105,6 +107,7 @@ pub fn init(gpa: Allocator, io: Io, config_path: []const u8, global_path: ?[]con
.home = home,
.arena_state = std.heap.ArenaAllocator.init(gpa),
.stdio_probe = if (environ_map.get("GRAFF_MCP_PROBE")) |v| !std.mem.eql(u8, v, "0") else true,
+ .lazy_stdio = environ_map.get("GRAFF_MCP_EAGER") == null,
.show_diagnostics = show_diagnostics,
.global_config_path = global_path,
.global_is_override = mcp_config.isEnvOverride(environ_map),
@@ -174,13 +177,7 @@ fn alreadyStartingLocked(reg: *const Registry, name: []const u8) bool {
}
fn startCtx(reg: *const Registry) StartCtx {
- return .{
- .gpa = reg.gpa,
- .io = reg.io,
- .home = reg.home,
- .show_diagnostics = reg.show_diagnostics,
- .stdio_probe = reg.stdio_probe,
- };
+ return .{ .gpa = reg.gpa, .io = reg.io, .home = reg.home, .show_diagnostics = reg.show_diagnostics, .stdio_probe = reg.stdio_probe, .lazy_stdio = reg.lazy_stdio };
}
/// Queue a stdio server onto `pending_starts` without waiting. Used by
diff --git a/src/mcp_cache.zig b/src/mcp_cache.zig
index d8f2f28f..5326e2d3 100644
--- a/src/mcp_cache.zig
+++ b/src/mcp_cache.zig
@@ -80,6 +80,16 @@ pub const Lookup = struct {
/// One disk read: fresh `tools/list` if the TTL still holds, plus the era even
/// when the catalog is stale (so Auto can skip the modern probe).
pub fn lookup(io: Io, arena: Allocator, home: []const u8, key: []const u8, now_ms: i64) Lookup {
+ return lookupWith(io, arena, home, key, now_ms, false);
+}
+
+/// The last catalog regardless of TTL: enough to advertise a local server
+/// that starts on first use (mcp_lazy.zig), which refreshes it when it wakes.
+pub fn lookupAnyAge(io: Io, arena: Allocator, home: []const u8, key: []const u8) ?Hit {
+ return lookupWith(io, arena, home, key, 0, true).hit;
+}
+
+fn lookupWith(io: Io, arena: Allocator, home: []const u8, key: []const u8, now_ms: i64, any_age: bool) Lookup {
var out: Lookup = .{};
if (key.len == 0) return out;
const data = readFile(io, arena, home) orelse return out;
@@ -98,8 +108,10 @@ pub fn lookup(io: Io, arena: Allocator, home: []const u8, key: []const u8, now_m
(if (v == .integer and v.integer > 0) @as(u64, @intCast(v.integer)) else default_ttl_ms)
else
default_ttl_ms;
- if (fetched <= 0 or now_ms < fetched) return out;
- if (@as(u64, @intCast(now_ms - fetched)) > ttl) return out;
+ if (!any_age) {
+ if (fetched <= 0 or now_ms < fetched) return out;
+ if (@as(u64, @intCast(now_ms - fetched)) > ttl) return out;
+ }
if (out.era == .unknown) return out;
const ver = if (entry.object.get("protocol_version")) |v| (if (v == .string) v.string else "?") else "?";
const tools = entry.object.get("tools") orelse return out;
diff --git a/src/mcp_lazy.zig b/src/mcp_lazy.zig
new file mode 100644
index 00000000..e0c085ab
--- /dev/null
+++ b/src/mcp_lazy.zig
@@ -0,0 +1,181 @@
+//! Local (stdio) MCP servers start on first use.
+//!
+//! Every configured stdio server used to be spawned at session start, so a
+//! chat with twenty servers ran twenty processes whether or not it ever called
+//! one. When the tool catalog for a server is already cached (mcp_cache.zig,
+//! keyed by command + args), the session advertises those tools from the cache
+//! and keeps only the launch config: the process is spawned, and handshaken
+//! for a legacy server, on the first `tools/call` that needs it. Once awake it
+//! re-lists its tools to refresh the cache for later sessions.
+//!
+//! Processes are never shared between sessions: a stdio server holds state for
+//! the agent using it (a browser, a working directory, credentials). A server
+//! with no cached catalog yet starts at once so its tools can be learned; an
+//! entry can opt out with `"startup": "eager"`, and `GRAFF_MCP_EAGER=1` turns
+//! lazy starts off for the whole process.
+
+const std = @import("std");
+const Io = std.Io;
+const Value = std.json.Value;
+const ObjectMap = std.json.ObjectMap;
+const Allocator = std.mem.Allocator;
+const mcp_rpc = @import("mcp_rpc.zig");
+const mcp_cache = @import("mcp_cache.zig");
+const mcp_stdio = @import("mcp_stdio.zig");
+const util = @import("util.zig");
+
+/// How a stdio entry is launched. `env` owns gpa copies of its strings: the
+/// caller deinits it once the child has been spawned.
+pub const Spec = struct {
+ argv: []const []const u8,
+ env: ?*std.process.Environ.Map = null,
+ cwd: ?[]const u8 = null,
+};
+
+pub fn stdioSpec(gpa: Allocator, a: Allocator, cfg: ObjectMap) !Spec {
+ const command_v = cfg.get("command") orelse return error.BadMcpConfig;
+ if (command_v != .string) return error.BadMcpConfig;
+ var argv: std.ArrayList([]const u8) = .empty;
+ try argv.append(a, command_v.string);
+ if (cfg.get("args")) |args| {
+ if (args != .array) return error.BadMcpConfig;
+ for (args.array.items) |arg| {
+ if (arg != .string) return error.BadMcpConfig;
+ try argv.append(a, arg.string);
+ }
+ }
+ var spec: Spec = .{ .argv = argv.items };
+ if (cfg.get("cwd")) |cwd| {
+ if (cwd != .string or cwd.string.len == 0) return error.BadMcpConfig;
+ spec.cwd = cwd.string;
+ }
+ // Optional per-server env overlaid on the parent environment.
+ if (cfg.get("env")) |env| {
+ if (env != .object) return error.BadMcpConfig;
+ const m = try a.create(std.process.Environ.Map);
+ m.* = std.process.Environ.Map.init(gpa);
+ errdefer m.deinit();
+ var it = env.object.iterator();
+ while (it.next()) |entry| {
+ if (entry.value_ptr.* != .string) return error.BadMcpConfig;
+ try m.put(entry.key_ptr.*, entry.value_ptr.*.string);
+ }
+ spec.env = m;
+ }
+ return spec;
+}
+
+/// A stdio entry that did not ask to start with the session.
+pub fn wantsLazy(cfg: ObjectMap) bool {
+ if (cfg.get("command") == null) return false;
+ if (cfg.get("startup")) |s| if (s == .string and std.ascii.eqlIgnoreCase(s.string, "eager")) return false;
+ return true;
+}
+
+fn cloneValue(a: Allocator, v: Value) Allocator.Error!Value {
+ return switch (v) {
+ .string => |s| .{ .string = try a.dupe(u8, s) },
+ .number_string => |s| .{ .number_string = try a.dupe(u8, s) },
+ .array => |arr| blk: {
+ var out = std.json.Array.init(a);
+ for (arr.items) |item| try out.append(try cloneValue(a, item));
+ break :blk .{ .array = out };
+ },
+ .object => |o| .{ .object = try cloneMap(a, o) },
+ else => v,
+ };
+}
+
+/// A deep copy: the config an ACP client sent lives in its request's arena.
+pub fn cloneMap(a: Allocator, m: ObjectMap) Allocator.Error!ObjectMap {
+ var out: ObjectMap = .empty;
+ var it = m.iterator();
+ while (it.next()) |e| try out.put(a, try a.dupe(u8, e.key_ptr.*), try cloneValue(a, e.value_ptr.*));
+ return out;
+}
+
+/// A dormant server built from a cached catalog, or null when this entry must
+/// start now (not stdio, opted out, or never listed before).
+pub fn dormantFromCache(io: Io, a: Allocator, home: []const u8, name: []const u8, cfg: ObjectMap) !?struct { server: *mcp_rpc.Server, tools: Value } {
+ if (!wantsLazy(cfg)) return null;
+ const hit = mcp_cache.lookupAnyAge(io, a, home, mcp_cache.keyFor(a, cfg)) orelse return null;
+ const server = try a.create(mcp_rpc.Server);
+ server.* = .{
+ .name = name,
+ .transport = .{ .dormant = .{ .cfg = try cloneMap(a, cfg) } },
+ .era = hit.era,
+ .protocol_version = try a.dupe(u8, hit.protocol_version),
+ .initialized = false,
+ };
+ return .{ .server = server, .tools = hit.tools };
+}
+
+/// Spawn and handshake a dormant server before its first request. On failure
+/// it stays dormant, so a later call tries again.
+pub fn wake(reg: anytype, server: *mcp_rpc.Server) !void {
+ const cfg = server.transport.dormant.cfg;
+ const a = reg.arena();
+ const spec = try stdioSpec(reg.gpa, a, cfg);
+ defer if (spec.env) |m| m.deinit();
+ server.transport = try reg.spawnStdio(a, spec.argv, spec.env, spec.cwd);
+ errdefer {
+ mcp_stdio.stopChild(reg.io, &server.transport.stdio.child);
+ server.transport = .{ .dormant = .{ .cfg = cfg } };
+ server.initialized = false;
+ }
+ // Same rule as a cache hit at connect: legacy needs `initialize` on the
+ // live child; a modern server takes any request first.
+ if (mcp_cache.handshakeOnCacheHit(server.era, false)) {
+ try mcp_rpc.initializeServer(server, a, a, reg.io);
+ } else {
+ server.initialized = server.era == .modern;
+ }
+ mcp_rpc.bindNotes(server);
+ @import("mcp_pages.zig").listen(server, a);
+ if (reg.show_diagnostics) std.debug.print(" [mcp:{s}] started on first use\n", .{server.name});
+ refreshCache(reg, server, cfg);
+}
+
+/// Re-list the tools of a server that just woke and store them, so the next
+/// session advertises its current catalog. The live session keeps the list
+/// it started with. Best effort: a failure costs nothing but freshness.
+fn refreshCache(reg: anytype, server: *mcp_rpc.Server, cfg: ObjectMap) void {
+ if (!server.initialized or reg.home.len == 0) return;
+ var arena_state = std.heap.ArenaAllocator.init(reg.gpa);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ const listed = mcp_rpc.request(server, a, "{}", "tools/list", null) catch return;
+ const result = if (listed == .object) listed.object.get("result") orelse return else return;
+ mcp_cache.store(reg.io, a, reg.home, mcp_cache.keyFor(a, cfg), server.era, server.protocol_version, result, util.unixMs(reg.io));
+}
+
+test "wantsLazy: stdio entries, unless they ask to start with the session" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const parse = struct {
+ fn f(al: Allocator, s: []const u8) ObjectMap {
+ return (std.json.parseFromSliceLeaky(Value, al, s, .{}) catch unreachable).object;
+ }
+ }.f;
+ try std.testing.expect(wantsLazy(parse(a, "{\"command\":\"npx\",\"args\":[\"-y\",\"x\"]}")));
+ try std.testing.expect(!wantsLazy(parse(a, "{\"command\":\"npx\",\"startup\":\"eager\"}")));
+ try std.testing.expect(!wantsLazy(parse(a, "{\"url\":\"https://example.com/mcp\"}")));
+}
+
+test "cloneMap survives the source arena" {
+ var src = std.heap.ArenaAllocator.init(std.testing.allocator);
+ const original = (try std.json.parseFromSliceLeaky(Value, src.allocator(),
+ \\{"command":"node","args":["server.js","--port","9"],"env":{"TOKEN":"t"},"cwd":"/tmp"}
+ , .{ .allocate = .alloc_always })).object;
+ var dst = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer dst.deinit();
+ const copy = try cloneMap(dst.allocator(), original);
+ src.deinit(); // the request arena an ACP client's config came from is gone
+ const spec = try stdioSpec(std.testing.allocator, dst.allocator(), copy);
+ defer if (spec.env) |m| m.deinit();
+ try std.testing.expectEqualStrings("node", spec.argv[0]);
+ try std.testing.expectEqualStrings("9", spec.argv[3]);
+ try std.testing.expectEqualStrings("/tmp", spec.cwd.?);
+ try std.testing.expectEqualStrings("t", spec.env.?.get("TOKEN").?);
+}
diff --git a/src/mcp_rpc.zig b/src/mcp_rpc.zig
index 6e47a636..73c68132 100644
--- a/src/mcp_rpc.zig
+++ b/src/mcp_rpc.zig
@@ -26,9 +26,13 @@ pub const StdioTransport = struct {
stdout_reader: Io.File.Reader,
};
+/// A cached stdio server not spawned yet; woken before any request (mcp_lazy.zig).
+pub const DormantStdio = struct { cfg: std.json.ObjectMap };
+
pub const Transport = union(enum) {
stdio: StdioTransport,
http: mcp_http.HttpTransport,
+ dormant: DormantStdio,
};
/// A property of the server, not the request (versioning § Backward
@@ -69,6 +73,7 @@ pub fn deinitServer(server: *Server, io: Io, budget: mcp_teardown.Budget) void {
finishInitialized(server);
switch (server.transport) {
.stdio => |*stdio| mcp_stdio.stopChild(io, &stdio.child),
+ .dormant => {},
.http => |*http| { // never waits on a peer: bounded by `budget` (#305)
if (http.session_id) |session_id| http.client.allocator.free(session_id);
http.session_id = null;
@@ -159,6 +164,7 @@ pub fn initializeServer(server: *Server, response_alloc: Allocator, session_allo
const protocol_transport: mcp_protocol.Transport = switch (server.transport) {
.stdio => .stdio,
.http => .streamable_http,
+ .dormant => return error.McpServerNotStarted,
};
const protocol_version = try mcp_protocol.negotiatedProtocol(init_resp, protocol_transport);
server.protocol_version = try session_alloc.dupe(u8, protocol_version);
@@ -221,6 +227,7 @@ pub fn request(server: *Server, response_alloc: Allocator, params: []const u8, m
defer http.client.allocator.free(response_body);
return mcp_http.parseHttpResponse(response_alloc, response_body, id) orelse error.BadMcpResponse;
},
+ .dormant => return error.McpServerNotStarted,
}
}
@@ -248,6 +255,7 @@ pub fn notify(server: *Server, response_alloc: Allocator, method: []const u8) !v
http.client.allocator.free(response_body);
}
},
+ .dormant => return error.McpServerNotStarted,
}
}
@@ -279,7 +287,7 @@ pub fn finishInitialized(server: *Server) void {
if (server.pending_initialized) |*fut| {
const io = switch (server.transport) {
.http => |*http| http.client.io,
- .stdio => return,
+ .stdio, .dormant => return,
};
fut.await(io);
server.pending_initialized = null;