Skip to content

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

Python

MCP: share a stateless local server between sessions ("shared": true)

justrach3ada235e4b7d
diff --git a/assets/skills/mcp-config.md b/assets/skills/mcp-config.md
index aefaed3f..3e271d94 100644
--- a/assets/skills/mcp-config.md
+++ b/assets/skills/mcp-config.md
@@ -43,6 +43,10 @@ global one with the same name. Their tools reach the model as
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.
+- `"shared": true` on a stateless local server (time, fetch, a docs search)
+ runs one process per machine for every session, through a broker graff
+ starts on demand and stops after a minute idle. Leave it off for servers that
+ keep per-agent state: a browser, a working directory, credentials. POSIX only.
## Prefer the CLI for writes
diff --git a/build.zig b/build.zig
index ba3d454b..eb211478 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_shared_test = b.addSystemCommand(&.{ "python3", "scripts/test-mcp-shared.py" });
+ mcp_shared_test.addArtifactArg(exe);
+ test_step.dependOn(&mcp_shared_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);
diff --git a/scripts/test-mcp-shared.py b/scripts/test-mcp-shared.py
new file mode 100644
index 00000000..d07ca8d4
--- /dev/null
+++ b/scripts/test-mcp-shared.py
@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""A "shared": true MCP server runs once per machine for every session.
+
+- two concurrent sessions calling the shared server reach ONE process: one
+ start, one initialize (the second is answered by the broker), every call
+ answered with that process's pid, each session getting its own replies
+- an ordinary server beside it still runs once per session
+- when the sessions end, the broker exits on its idle timer: the server
+ process is gone and its socket file removed
+"""
+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
+log = sys.argv[1]
+def rec(o):
+ with open(log, "a") as f: f.write(json.dumps(o) + "\n")
+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})
+ if mid is None: continue
+ if meth == "initialize":
+ out({"jsonrpc": "2.0", "id": mid, "result": {"protocolVersion": "2025-11-25", "capabilities": {"tools": {}}, "serverInfo": {"name": "s", "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", "inputSchema": {"type": "object", "properties": {"tag": {"type": "string"}}}}]}})
+ elif meth == "tools/call":
+ tag = (m.get("params") or {}).get("arguments", {}).get("tag", "")
+ out({"jsonrpc": "2.0", "id": mid, "result": {"content": [{"type": "text", "text": "pid %d tag %s" % (os.getpid(), tag)}]}})
+ else:
+ out({"jsonrpc": "2.0", "id": mid, "result": {}})
+"""
+
+
+class Slow(ScriptedModel):
+ def next_reply(self, body):
+ time.sleep(1.5) # --yolo joins MCP after the first request; keep the sessions overlapping
+ return super().next_reply(body)
+
+
+def events(log):
+ return [json.loads(l) for l in log.read_text().splitlines() if l.strip()] if log.exists() else []
+
+
+def alive(pid):
+ try:
+ os.kill(pid, 0)
+ return True
+ except OSError:
+ return False
+
+
+def main():
+ if os.name == 'nt':
+ print('SKIP shared MCP servers are POSIX-only')
+ return
+ binary = str(Path(sys.argv[1] if len(sys.argv) > 1 else 'zig-out/bin/graff').resolve())
+ temp = Path(tempfile.mkdtemp(prefix='graff-mcp-shared-'))
+ try:
+ (temp / 'server.py').write_text(SERVER)
+ shared_log, solo_log = temp / 'shared.log', temp / 'solo.log'
+ cfg = {'mcpServers': {
+ 'clock': {'command': sys.executable, 'args': [str(temp / 'server.py'), str(shared_log)], 'shared': True},
+ 'solo': {'command': sys.executable, 'args': [str(temp / 'server.py'), str(solo_log)]},
+ }}
+ env = {k: v for k, v in os.environ.items() if not k.endswith('_API_KEY')}
+ 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_MCP_SHARED_IDLE_S='2')
+ sock_dir = Path(f'/tmp/graff-{os.getuid()}')
+ pre = set(sock_dir.glob('mcp-*.sock'))
+ procs, models = [], []
+ for name in ('a', 'b'):
+ work = temp / name
+ work.mkdir()
+ (work / '.mcp.json').write_text(json.dumps(cfg))
+ model = Slow([
+ {'tool': 'todo_read', 'arguments': {}},
+ {'tool': 'mcp__clock__echo', 'arguments': {'tag': f'{name}1'}},
+ {'tool': 'mcp__clock__echo', 'arguments': {'tag': f'{name}2'}},
+ {'tool': 'mcp__solo__echo', 'arguments': {'tag': name}},
+ {'text': 'done'},
+ ])
+ port = model.start(0)
+ e = dict(env, GRAFF_VERCEL_URL=f'http://127.0.0.1:{port}/v1/chat/completions')
+ procs.append(subprocess.Popen([binary, '--model', 'vercel', '--old', '--no-lean', '--yolo', '-p', 'go'], cwd=work, env=e,
+ stdout=subprocess.DEVNULL, stderr=open(temp / f'{name}.err', 'w')))
+ models.append((name, model))
+ for p in procs:
+ p.wait(timeout=240)
+ for _, m in models:
+ m.stop()
+
+ ev = events(shared_log)
+ starts = [e for e in ev if e['event'] == 'start']
+ methods = [e['method'] for e in ev if e['event'] == 'method']
+ errs = {n: (temp / f'{n}.err').read_text()[:600] for n, _ in models}
+ assert len(starts) == 1, f'shared server started {len(starts)} times: {ev} {errs}'
+ assert methods.count('initialize') == 1, f'initialize reached the server {methods.count("initialize")} times'
+ assert methods.count('tools/call') == 4, methods
+ pid = starts[0]['pid']
+ for name, m in models:
+ results = [str(x.get('content')) for r in m.requests for x in r.get('messages', []) if x.get('role') == 'tool']
+ clock = [r for r in results if f'pid {pid} tag {name}' in r]
+ assert len(clock) >= 2, f'session {name} did not get both of its own shared replies: {results}'
+ other = 'b' if name == 'a' else 'a'
+ assert not any(f'tag {other}1' in r or f'tag {other}2' in r for r in results), f'session {name} received the other session\'s reply'
+ print('PASS two concurrent sessions share one process: one start, one initialize, each gets its own replies', flush=True)
+
+ solo_starts = [e for e in events(solo_log) if e['event'] == 'start']
+ assert len(solo_starts) == 2, f'an ordinary server should run once per session: {len(solo_starts)}'
+ print('PASS an ordinary server beside it still runs once per session', flush=True)
+
+ ours = set(sock_dir.glob('mcp-*.sock')) - pre
+ assert ours, 'no broker socket was created'
+ deadline = time.time() + 15
+ while time.time() < deadline and alive(pid):
+ time.sleep(0.5)
+ time.sleep(0.5)
+ assert not alive(pid), 'the shared server outlived its idle timeout'
+ assert oct(sock_dir.stat().st_mode & 0o777) == '0o700', 'the socket directory must be private'
+ assert not (set(sock_dir.glob('mcp-*.sock')) & ours), 'the broker left its socket behind'
+ print('PASS the broker exits on its idle timer and cleans up', flush=True)
+ finally:
+ shutil.rmtree(temp, ignore_errors=True)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/src/main.zig b/src/main.zig
index 39a4193e..fab25bbc 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -579,7 +579,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = .{ @import("http2_pool.zig"), @import("agent_stream_h2.zig"), @import("agent_stream_h2_transport_test.zig") }; // h2 stream path, and graff's request/response contract over the pinned http-zig
_ = @import("tui_acp_updates.zig");
_ = @import("acp_preauth.zig"); // credential-free ACP loop must stay in the test root
- _ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_elicit.zig"), @import("hot_context.zig"), @import("history_translate.zig"), @import("mcp_notify.zig"), @import("mcp_wait.zig"), @import("mcp_pages.zig"), @import("mcp_mrtr.zig"), @import("ask_user_args.zig"), @import("mcp_add.zig"), @import("acp_room.zig"), @import("mcp_catalog.zig"), @import("mcp_watch.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig"), @import("ask_user_answers.zig"), @import("job_class.zig"), @import("startup_claim.zig") };
+ _ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_elicit.zig"), @import("hot_context.zig"), @import("history_translate.zig"), @import("mcp_notify.zig"), @import("mcp_wait.zig"), @import("mcp_pages.zig"), @import("mcp_mrtr.zig"), @import("ask_user_args.zig"), @import("mcp_add.zig"), @import("mcp_lazy.zig"), @import("mcp_share.zig"), @import("acp_room.zig"), @import("mcp_catalog.zig"), @import("mcp_watch.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig"), @import("ask_user_answers.zig"), @import("job_class.zig"), @import("startup_claim.zig") };
_ = @import("task_outcome.zig"); // goal-outcome telemetry events
_ = @import("learn_delete.zig"); // #303: its tests were dead until listed here
_ = .{ @import("additional_tests.zig"), @import("req_stats.zig"), @import("exact_reply.zig"), @import("rlm_order_tests.zig"), @import("async_tool_policy.zig"), @import("agent_async_tools.zig"), @import("request_usage_attempts.zig"), @import("learn_formal.zig") };
diff --git a/src/mcp.zig b/src/mcp.zig
index ebc9d567..b81b49d8 100644
--- a/src/mcp.zig
+++ b/src/mcp.zig
@@ -355,7 +355,7 @@ pub const Registry = struct {
} },
};
} else {
- const spec = try mcp_lazy.stdioSpec(reg.gpa, a, cfg);
+ const spec = try mcp_lazy.stdioSpec(reg.io, reg.gpa, a, cfg);
try stdio_argv.appendSlice(a, spec.argv);
stdio_env_map = spec.env;
stdio_cwd = spec.cwd;
diff --git a/src/mcp_cli.zig b/src/mcp_cli.zig
index 8c4cec8f..c9e44dc7 100644
--- a/src/mcp_cli.zig
+++ b/src/mcp_cli.zig
@@ -343,6 +343,15 @@ pub fn mcpCommand(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, en
return;
}
+ if (std.mem.eql(u8, args[0], "attach") or std.mem.eql(u8, args[0], "broker")) {
+ // Internal: the relay and the per-machine broker of a `"shared": true` server.
+ const share = @import("mcp_share.zig");
+ const idle_s = std.fmt.parseInt(u32, environ_map.get("GRAFF_MCP_SHARED_IDLE_S") orelse "60", 10) catch 60;
+ const run = if (args[0][0] == 'a') share.attach(io, gpa, arena, home, args[1..]) else share.broker(io, gpa, arena, home, idle_s, args[1..]);
+ run catch |err| std.process.fatal("mcp {s}: {t}", .{ args[0], err });
+ return;
+ }
+
if (std.mem.eql(u8, args[0], "login")) {
if (args.len != 2) {
try out.interface.writeAll("usage: graff mcp login <name>\n");
diff --git a/src/mcp_lazy.zig b/src/mcp_lazy.zig
index e0c085ab..7496ae79 100644
--- a/src/mcp_lazy.zig
+++ b/src/mcp_lazy.zig
@@ -32,7 +32,7 @@ pub const Spec = struct {
cwd: ?[]const u8 = null,
};
-pub fn stdioSpec(gpa: Allocator, a: Allocator, cfg: ObjectMap) !Spec {
+pub fn stdioSpec(io: Io, 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;
@@ -45,6 +45,12 @@ pub fn stdioSpec(gpa: Allocator, a: Allocator, cfg: ObjectMap) !Spec {
}
}
var spec: Spec = .{ .argv = argv.items };
+ // `"shared": true`: run through the per-machine broker (mcp_share.zig).
+ const share = @import("mcp_share.zig");
+ if (share.wantsShared(cfg)) {
+ const key = share.keyFor(cfg);
+ spec.argv = try share.attachArgv(a, try std.process.executablePathAlloc(io, a), try a.dupe(u8, &key), argv.items);
+ }
if (cfg.get("cwd")) |cwd| {
if (cwd != .string or cwd.string.len == 0) return error.BadMcpConfig;
spec.cwd = cwd.string;
@@ -115,7 +121,7 @@ pub fn dormantFromCache(io: Io, a: Allocator, home: []const u8, name: []const u8
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);
+ const spec = try stdioSpec(reg.io, reg.gpa, a, cfg);
defer if (spec.env) |m| m.deinit();
server.transport = try reg.spawnStdio(a, spec.argv, spec.env, spec.cwd);
errdefer {
@@ -172,7 +178,7 @@ test "cloneMap survives the source arena" {
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);
+ const spec = try stdioSpec(std.testing.io, 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]);
diff --git a/src/mcp_share.zig b/src/mcp_share.zig
new file mode 100644
index 00000000..8289e7a0
--- /dev/null
+++ b/src/mcp_share.zig
@@ -0,0 +1,491 @@
+//! One process per machine for a stateless MCP server (`"shared": true`).
+//!
+//! Most stdio servers hold per-agent state (a browser, a working directory,
+//! credentials) and stay one process per session. A stateless one (time,
+//! fetch, sequential-thinking, a docs search) can serve every session: its
+//! entry is launched as `graff mcp attach --key K -- <command…>`, a relay that
+//! connects to a per-machine broker over a Unix socket and starts it when it
+//! is not running. The broker runs the real server once and multiplexes
+//! JSON-RPC: request ids are rewritten per client and restored on the reply,
+//! a repeated `initialize` is answered from the first one, server
+//! notifications go to every client, and server-to-client requests are
+//! refused (a shared server has no single client to ask). It exits once no
+//! client has been connected for `GRAFF_MCP_SHARED_IDLE_S` (default 60).
+//!
+//! POSIX only; on Windows the entry runs as an ordinary per-session server.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const Io = std.Io;
+const net = Io.net;
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+
+pub const supported = builtin.os.tag != .windows;
+
+/// Whether an entry asks to be shared (and can be, on this OS).
+pub fn wantsShared(cfg: std.json.ObjectMap) bool {
+ if (!supported or cfg.get("command") == null) return false;
+ const v = cfg.get("shared") orelse return false;
+ return v == .bool and v.bool;
+}
+
+/// The broker a config maps to: command, args, env overlay and cwd, so two
+/// entries share a process only when they would launch the same one.
+pub fn keyFor(cfg: std.json.ObjectMap) [16]u8 {
+ var h = std.hash.Wyhash.init(0x6d6370);
+ const parts = [_][]const u8{ "command", "args", "env", "cwd" };
+ for (parts) |p| {
+ h.update(p);
+ if (cfg.get(p)) |v| hashValue(&h, v);
+ }
+ return std.fmt.bytesToHex(std.mem.asBytes(&h.final()), .lower);
+}
+
+fn hashValue(h: *std.hash.Wyhash, v: Value) void {
+ switch (v) {
+ .string => |s| {
+ h.update("s");
+ h.update(s);
+ },
+ .array => |arr| {
+ h.update("[");
+ for (arr.items) |x| hashValue(h, x);
+ h.update("]");
+ },
+ .object => |o| {
+ // Key order must not change the key: fold entries order-independently.
+ var acc: u64 = 0;
+ var it = o.iterator();
+ while (it.next()) |e| {
+ var eh = std.hash.Wyhash.init(1);
+ eh.update(e.key_ptr.*);
+ hashValue(&eh, e.value_ptr.*);
+ acc +%= eh.final();
+ }
+ h.update("{");
+ h.update(std.mem.asBytes(&acc));
+ },
+ .bool => |b| h.update(if (b) "t" else "f"),
+ .integer => |i| h.update(std.mem.asBytes(&i)),
+ else => h.update("?"),
+ }
+}
+
+/// argv for a shared entry: the relay, keyed, followed by the real command.
+pub fn attachArgv(a: Allocator, self_exe: []const u8, key: []const u8, argv: []const []const u8) ![]const []const u8 {
+ var out: std.ArrayList([]const u8) = .empty;
+ try out.appendSlice(a, &.{ self_exe, "mcp", "attach", "--key", key, "--" });
+ try out.appendSlice(a, argv);
+ return out.items;
+}
+
+/// `/tmp/graff-<uid>/mcp-<hash>.sock`: short enough for the 104-byte socket
+/// path limit whatever HOME is, and the home is folded into the name so two
+/// homes never share a broker. The directory must be ours and private, or a
+/// local user could plant a socket that answers our agents' tool calls.
+pub fn socketPath(a: Allocator, home: []const u8, key: []const u8) ![]const u8 {
+ const uid = std.c.getuid();
+ const dir = try std.fmt.allocPrint(a, "/tmp/graff-{d}", .{uid});
+ try privateDir(a, dir, uid);
+ var h = std.hash.Wyhash.init(0x736f636b);
+ h.update(home);
+ h.update(key);
+ return std.fmt.allocPrint(a, "{s}/mcp-{s}.sock", .{ dir, &std.fmt.bytesToHex(std.mem.asBytes(&h.final()), .lower) });
+}
+
+fn privateDir(a: Allocator, dir: []const u8, uid: std.c.uid_t) !void {
+ const z = try a.dupeSentinel(u8, dir, 0);
+ _ = std.c.mkdir(z, 0o700);
+ var st: std.c.Stat = undefined;
+ if (std.c.fstatat(std.c.AT.FDCWD, z, &st, std.c.AT.SYMLINK_NOFOLLOW) != 0) return error.SharedMcpDirUnavailable;
+ const is_dir = (st.mode & std.c.S.IFMT) == std.c.S.IFDIR;
+ if (!is_dir or st.uid != uid or (st.mode & 0o077) != 0) return error.SharedMcpDirNotPrivate;
+}
+
+// ── JSON-RPC id plumbing (pure; unit-tested) ──────────────────────────────
+
+pub const Kind = enum { request, notification, response, server_request, other };
+
+pub fn classify(msg: Value) Kind {
+ if (msg != .object) return .other;
+ const has_id = msg.object.get("id") != null;
+ const has_method = msg.object.get("method") != null;
+ if (has_method and has_id) return .request;
+ if (has_method) return .notification;
+ if (has_id and (msg.object.get("result") != null or msg.object.get("error") != null)) return .response;
+ return .other;
+}
+
+/// The same message with its `id` replaced, serialized as one line.
+pub fn withId(a: Allocator, msg: Value, id: Value) ![]const u8 {
+ var copy = msg.object;
+ copy = try copy.clone(a);
+ try copy.put(a, "id", id);
+ var aw: Io.Writer.Allocating = .init(a);
+ var js: std.json.Stringify = .{ .writer = &aw.writer };
+ try js.write(Value{ .object = copy });
+ return aw.writer.buffered();
+}
+
+// ── relay: graff mcp attach --key K -- command… ───────────────────────────
+
+pub fn attach(io: Io, gpa: Allocator, a: Allocator, home: []const u8, args: []const []const u8) !void {
+ if (!supported) return error.SharedMcpUnsupported;
+ if (args.len < 4 or !std.mem.eql(u8, args[0], "--key") or !std.mem.eql(u8, args[2], "--")) return error.Usage;
+ const key = args[1];
+ const command = args[3..];
+ const path = try socketPath(a, home, key);
+ const stream = connectOrStart(io, a, path, key, command) orelse return error.SharedMcpUnavailable;
+ defer stream.close(io);
+ const up = try std.Thread.spawn(.{}, pump, .{ io, Io.File.stdin(), stream });
+ up.detach();
+ // Down: broker → stdout until the broker closes the connection.
+ var rbuf: [64 * 1024]u8 = undefined;
+ var reader = stream.reader(io, &rbuf);
+ var wbuf: [64 * 1024]u8 = undefined;
+ var w = Io.File.stdout().writerStreaming(io, &wbuf);
+ while (true) {
+ const line = reader.interface.takeDelimiterInclusive('\n') catch break;
+ w.interface.writeAll(line) catch break;
+ w.interface.flush() catch break;
+ }
+ _ = gpa;
+}
+
+fn pump(io: Io, from: Io.File, to: net.Stream) void {
+ var rbuf: [64 * 1024]u8 = undefined;
+ var r = from.readerStreaming(io, &rbuf);
+ var wbuf: [64 * 1024]u8 = undefined;
+ var w = to.writer(io, &wbuf);
+ while (true) {
+ const line = r.interface.takeDelimiterInclusive('\n') catch break;
+ w.interface.writeAll(line) catch break;
+ w.interface.flush() catch break;
+ }
+ // The session closed its end: tell the broker this client is gone.
+ to.shutdown(io, .send) catch {};
+}
+
+fn connect(io: Io, path: []const u8) ?net.Stream {
+ const addr = net.UnixAddress.init(path) catch return null;
+ return addr.connect(io) catch null;
+}
+
+fn connectOrStart(io: Io, a: Allocator, path: []const u8, key: []const u8, command: []const []const u8) ?net.Stream {
+ if (connect(io, path)) |s| return s;
+ const self_exe = std.process.executablePathAlloc(io, a) catch return null;
+ var argv: std.ArrayList([]const u8) = .empty;
+ argv.appendSlice(a, &.{ self_exe, "mcp", "broker", "--key", key, "--" }) catch return null;
+ argv.appendSlice(a, command) catch return null;
+ // Its own process group: the broker outlives the session that started it.
+ _ = std.process.spawn(io, .{ .argv = argv.items, .stdin = .ignore, .stdout = .ignore, .stderr = .ignore, .pgid = 0 }) catch return null;
+ var waited: u32 = 0;
+ while (waited < 200) : (waited += 1) { // up to ~10 s for the server to start
+ if (connect(io, path)) |s| return s;
+ io.sleep(.fromMilliseconds(50), .awake) catch {};
+ }
+ return null;
+}
+
+// ── broker: graff mcp broker --key K -- command… ──────────────────────────
+
+const Client = struct {
+ stream: net.Stream,
+ writer: net.Stream.Writer,
+ wbuf: [64 * 1024]u8 = undefined,
+ alive: bool = true,
+};
+
+const Pending = struct { client: *Client, id: Value, is_initialize: bool };
+
+const Broker = struct {
+ io: Io,
+ gpa: Allocator,
+ mutex: Io.Mutex = .init,
+ clients: std.ArrayList(*Client) = .empty,
+ pending: std.AutoHashMapUnmanaged(i64, Pending) = .empty,
+ next_id: i64 = 1,
+ init_result: ?[]const u8 = null, // the first initialize result, as JSON
+ initialized_sent: bool = false,
+ server_in: Io.File.Writer,
+ last_client_left_ms: i64 = 0,
+ ids_arena: std.heap.ArenaAllocator,
+
+ fn toServer(b: *Broker, line: []const u8) void {
+ b.server_in.interface.writeAll(line) catch return;
+ b.server_in.interface.writeByte('\n') catch return;
+ b.server_in.interface.flush() catch {};
+ }
+
+ fn toClient(b: *Broker, c: *Client, line: []const u8) void {
+ _ = b;
+ if (!c.alive) return;
+ c.writer.interface.writeAll(line) catch {
+ c.alive = false;
+ return;
+ };
+ c.writer.interface.writeByte('\n') catch {};
+ c.writer.interface.flush() catch {
+ c.alive = false;
+ };
+ }
+
+ /// One line from a client.
+ fn fromClient(b: *Broker, c: *Client, line: []const u8) void {
+ var arena = std.heap.ArenaAllocator.init(b.gpa);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const msg = std.json.parseFromSliceLeaky(Value, a, line, .{ .allocate = .alloc_always }) catch return;
+ b.mutex.lockUncancelable(b.io);
+ defer b.mutex.unlock(b.io);
+ switch (classify(msg)) {
+ .request => {
+ const method = msg.object.get("method").?;
+ const is_init = method == .string and std.mem.eql(u8, method.string, "initialize");
+ if (is_init) if (b.init_result) |cached| {
+ const id_json = std.json.Stringify.valueAlloc(a, msg.object.get("id").?, .{}) catch return;
+ const reply = std.fmt.allocPrint(a, "{{\"jsonrpc\":\"2.0\",\"id\":{s},\"result\":{s}}}", .{ id_json, cached }) catch return;
+ b.toClient(c, reply);
+ return;
+ };
+ const id = b.next_id;
+ b.next_id += 1;
+ const orig = cloneId(b.ids_arena.allocator(), msg.object.get("id").?) catch return;
+ b.pending.put(b.gpa, id, .{ .client = c, .id = orig, .is_initialize = is_init }) catch return;
+ b.toServer(withId(a, msg, .{ .integer = id }) catch return);
+ },
+ .notification => {
+ const method = msg.object.get("method").?;
+ const name = if (method == .string) method.string else "";
+ if (std.mem.eql(u8, name, "notifications/initialized")) {
+ if (b.initialized_sent) return;
+ b.initialized_sent = true;
+ } else if (std.mem.eql(u8, name, "notifications/cancelled")) {
+ return; // its requestId is the client's, not the server's
+ }
+ b.toServer(line);
+ },
+ else => {},
+ }
+ }
+
+ /// One line from the server.
+ fn fromServer(b: *Broker, line: []const u8) void {
+ var arena = std.heap.ArenaAllocator.init(b.gpa);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const msg = std.json.parseFromSliceLeaky(Value, a, line, .{ .allocate = .alloc_always }) catch return;
+ b.mutex.lockUncancelable(b.io);
+ defer b.mutex.unlock(b.io);
+ switch (classify(msg)) {
+ .response => {
+ const idv = msg.object.get("id").?;
+ if (idv != .integer) return;
+ const p = b.pending.fetchRemove(idv.integer) orelse return;
+ if (p.value.is_initialize and b.init_result == null) if (msg.object.get("result")) |r| {
+ var aw: Io.Writer.Allocating = .init(b.ids_arena.allocator());
+ var js: std.json.Stringify = .{ .writer = &aw.writer };
+ js.write(r) catch {};
+ b.init_result = aw.writer.buffered();
+ };
+ b.toClient(p.value.client, withId(a, msg, p.value.id) catch return);
+ },
+ .notification => for (b.clients.items) |c| b.toClient(c, line),
+ .request => {
+ // Sampling, elicitation, roots: no single client to ask.
+ const id_json = std.json.Stringify.valueAlloc(a, msg.object.get("id").?, .{}) catch return;
+ const reply = std.fmt.allocPrint(a, "{{\"jsonrpc\":\"2.0\",\"id\":{s},\"error\":{{\"code\":-32601,\"message\":\"not available through a shared MCP server\"}}}}", .{id_json}) catch return;
+ b.toServer(reply);
+ },
+ else => {},
+ }
+ }
+
+ fn dropClient(b: *Broker, c: *Client) void {
+ b.mutex.lockUncancelable(b.io);
+ defer b.mutex.unlock(b.io);
+ c.alive = false;
+ for (b.clients.items, 0..) |x, i| if (x == c) {
+ _ = b.clients.swapRemove(i);
+ break;
+ };
+ // Its unanswered requests: the replies have nowhere to go.
+ var it = b.pending.iterator();
+ var stale: std.ArrayList(i64) = .empty;
+ defer stale.deinit(b.gpa);
+ while (it.next()) |e| if (e.value_ptr.client == c) stale.append(b.gpa, e.key_ptr.*) catch {};
+ for (stale.items) |k| _ = b.pending.remove(k);
+ if (b.clients.items.len == 0) b.last_client_left_ms = nowMs(b.io);
+ c.stream.close(b.io);
+ }
+};
+
+fn cloneId(a: Allocator, v: Value) !Value {
+ return switch (v) {
+ .string => |s| .{ .string = try a.dupe(u8, s) },
+ .number_string => |s| .{ .number_string = try a.dupe(u8, s) },
+ else => v,
+ };
+}
+
+fn nowMs(io: Io) i64 {
+ return @import("util.zig").unixMs(io);
+}
+
+fn serveClient(b: *Broker, c: *Client) void {
+ var rbuf: [64 * 1024]u8 = undefined;
+ var r = c.stream.reader(b.io, &rbuf);
+ while (true) {
+ const raw = r.interface.takeDelimiterInclusive('\n') catch break;
+ const line = std.mem.trimEnd(u8, raw, "\r\n");
+ if (line.len == 0) continue;
+ b.fromClient(c, line);
+ }
+ b.dropClient(c);
+}
+
+fn serveServer(b: *Broker, reader: *Io.File.Reader, done: *std.atomic.Value(bool)) void {
+ while (true) {
+ const raw = reader.interface.takeDelimiterInclusive('\n') catch break;
+ const line = std.mem.trimEnd(u8, raw, "\r\n");
+ if (line.len == 0) continue;
+ b.fromServer(line);
+ }
+ done.store(true, .release);
+}
+
+fn acceptLoop(b: *Broker, listener: *net.Server) void {
+ while (true) {
+ const stream = listener.accept(b.io) catch return;
+ const c = b.gpa.create(Client) catch {
+ stream.close(b.io);
+ continue;
+ };
+ c.* = .{ .stream = stream, .writer = undefined };
+ c.writer = stream.writer(b.io, &c.wbuf);
+ b.mutex.lockUncancelable(b.io);
+ b.clients.append(b.gpa, c) catch {};
+ b.mutex.unlock(b.io);
+ const t = std.Thread.spawn(.{}, serveClient, .{ b, c }) catch {
+ b.dropClient(c);
+ continue;
+ };
+ t.detach();
+ }
+}
+
+pub fn broker(io: Io, gpa: Allocator, a: Allocator, home: []const u8, idle_s: u32, args: []const []const u8) !void {
+ if (!supported) return error.SharedMcpUnsupported;
+ if (args.len < 4 or !std.mem.eql(u8, args[0], "--key") or !std.mem.eql(u8, args[2], "--")) return error.Usage;
+ const path = try socketPath(a, home, args[1]);
+ // One broker per socket: whoever holds the lock owns it for its lifetime.
+ // A second broker (two sessions starting at once) leaves quietly instead
+ // of deleting the first one's socket.
+ const lock_path = try std.fmt.allocPrint(a, "{s}.lock", .{path});
+ const lock = Io.Dir.cwd().createFile(io, lock_path, .{ .truncate = false, .lock = .exclusive, .lock_nonblocking = true }) catch return;
+ defer lock.close(io);
+ Io.Dir.cwd().deleteFile(io, path) catch {}; // a dead broker's socket
+ const addr = try net.UnixAddress.init(path);
+ var listener = addr.listen(io, .{}) catch return; // lost a race to another broker
+ defer {
+ listener.deinit(io);
+ Io.Dir.cwd().deleteFile(io, path) catch {};
+ }
+
+ var child = try std.process.spawn(io, .{ .argv = args[3..], .stdin = .pipe, .stdout = .pipe, .stderr = .ignore });
+ defer @import("mcp_stdio.zig").stopChild(io, &child);
+ var in_buf: [64 * 1024]u8 = undefined;
+ var out_buf: [1 << 20]u8 = undefined;
+ var b: Broker = .{
+ .io = io,
+ .gpa = gpa,
+ .server_in = child.stdin.?.writerStreaming(io, &in_buf),
+ .ids_arena = std.heap.ArenaAllocator.init(gpa),
+ .last_client_left_ms = nowMs(io),
+ };
+ var server_out = child.stdout.?.readerStreaming(io, &out_buf);
+ var server_done = std.atomic.Value(bool).init(false);
+ const st = try std.Thread.spawn(.{}, serveServer, .{ &b, &server_out, &server_done });
+ st.detach();
+ const at = try std.Thread.spawn(.{}, acceptLoop, .{ &b, &listener });
+ at.detach();
+
+ while (!server_done.load(.acquire)) {
+ io.sleep(.fromMilliseconds(250), .awake) catch {};
+ b.mutex.lockUncancelable(io);
+ const idle = b.clients.items.len == 0 and nowMs(io) - b.last_client_left_ms >= @as(i64, idle_s) * 1000;
+ b.mutex.unlock(io);
+ if (idle) break;
+ }
+}
+
+test "keyFor: same launch shares, any difference does not, env order does not matter" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const p = struct {
+ fn f(al: Allocator, s: []const u8) std.json.ObjectMap {
+ return (std.json.parseFromSliceLeaky(Value, al, s, .{}) catch unreachable).object;
+ }
+ }.f;
+ const one = keyFor(p(a, "{\"command\":\"uvx\",\"args\":[\"mcp-server-time\"],\"env\":{\"A\":\"1\",\"B\":\"2\"}}"));
+ const same = keyFor(p(a, "{\"command\":\"uvx\",\"args\":[\"mcp-server-time\"],\"env\":{\"B\":\"2\",\"A\":\"1\"},\"shared\":true}"));
+ const other_env = keyFor(p(a, "{\"command\":\"uvx\",\"args\":[\"mcp-server-time\"],\"env\":{\"A\":\"9\",\"B\":\"2\"}}"));
+ const other_args = keyFor(p(a, "{\"command\":\"uvx\",\"args\":[\"mcp-server-fetch\"]}"));
+ try std.testing.expectEqualSlices(u8, &one, &same);
+ try std.testing.expect(!std.mem.eql(u8, &one, &other_env));
+ try std.testing.expect(!std.mem.eql(u8, &one, &other_args));
+}
+
+test "classify and withId: requests get the broker's id, replies get the client's back" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const req = try std.json.parseFromSliceLeaky(Value, a, "{\"jsonrpc\":\"2.0\",\"id\":\"c-7\",\"method\":\"tools/call\",\"params\":{\"name\":\"now\"}}", .{});
+ try std.testing.expectEqual(Kind.request, classify(req));
+ const out = try withId(a, req, .{ .integer = 42 });
+ const back = try std.json.parseFromSliceLeaky(Value, a, out, .{});
+ try std.testing.expectEqual(@as(i64, 42), back.object.get("id").?.integer);
+ try std.testing.expectEqualStrings("now", back.object.get("params").?.object.get("name").?.string);
+ try std.testing.expectEqualStrings("c-7", req.object.get("id").?.string); // the original is untouched
+
+ const resp = try std.json.parseFromSliceLeaky(Value, a, "{\"jsonrpc\":\"2.0\",\"id\":42,\"result\":{}}", .{});
+ try std.testing.expectEqual(Kind.response, classify(resp));
+ const restored = try std.json.parseFromSliceLeaky(Value, a, try withId(a, resp, .{ .string = "c-7" }), .{});
+ try std.testing.expectEqualStrings("c-7", restored.object.get("id").?.string);
+ const note = try std.json.parseFromSliceLeaky(Value, a, "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/progress\"}", .{});
+ try std.testing.expectEqual(Kind.notification, classify(note));
+ const srv_req = try std.json.parseFromSliceLeaky(Value, a, "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"sampling/createMessage\"}", .{});
+ try std.testing.expectEqual(Kind.request, classify(srv_req));
+}
+
+test "socketPath fits the socket limit for any HOME, in a private directory" {
+ if (!supported) return error.SkipZigTest;
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const long_home = "/private/var/folders/t3/zjm3hgy56l551q_ygry8mbjm0000gn/T/graff-mcp-shared-abcdefgh/and/deeper/still";
+ const p1 = try socketPath(a, long_home, "0123456789abcdef");
+ try std.testing.expect(p1.len < 104); // sockaddr_un sun_path on macOS
+ const p2 = try socketPath(a, "/home/other", "0123456789abcdef");
+ try std.testing.expect(!std.mem.eql(u8, p1, p2)); // two homes never share a broker
+ var st: std.c.Stat = undefined;
+ const dir = try a.dupeSentinel(u8, std.fs.path.dirname(p1).?, 0);
+ try std.testing.expectEqual(@as(c_int, 0), std.c.fstatat(std.c.AT.FDCWD, dir, &st, std.c.AT.SYMLINK_NOFOLLOW));
+ try std.testing.expectEqual(@as(@TypeOf(st.mode), 0), st.mode & 0o077);
+}
+
+test "wantsShared: only an explicit true on a stdio entry" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const p = struct {
+ fn f(al: Allocator, s: []const u8) std.json.ObjectMap {
+ return (std.json.parseFromSliceLeaky(Value, al, s, .{}) catch unreachable).object;
+ }
+ }.f;
+ try std.testing.expectEqual(supported, wantsShared(p(a, "{\"command\":\"uvx\",\"shared\":true}")));
+ try std.testing.expect(!wantsShared(p(a, "{\"command\":\"uvx\"}")));
+ try std.testing.expect(!wantsShared(p(a, "{\"url\":\"https://x/mcp\",\"shared\":true}")));
+}