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.mdindex 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 asstill 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=VALUEgraff 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 ishow you remove a server (drop its key) or rename one. Do not commit a secretinto it: prefer `graff mcp login` (OAuth credentials are stored outside thediff --git a/build.zig b/build.zigindex 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.pynew file mode 100644index 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.pyindex 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.zigindex 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.zigindex 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 cacheconst 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.zigindex 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 bydiff --git a/src/mcp_cache.zig b/src/mcp_cache.zigindex 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)elsedefault_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.zignew file mode 100644index 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.zigindex 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_alloconst 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, mdefer 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) !vhttp.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;