Skip to content

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

Python

MCP client: pagination, list_changed, progress, cancellation, MRTR, SSE resume

justrachcb57d373d378
diff --git a/build.zig b/build.zig
index 6a129d9e..069cb6ea 100644
--- a/build.zig
+++ b/build.zig
@@ -150,6 +150,9 @@ pub fn build(b: *std.Build) void {
const acp_ask_user_test = b.addSystemCommand(&.{ "python3", "scripts/test-acp-ask-user.py" });
acp_ask_user_test.addArtifactArg(exe);
test_step.dependOn(&acp_ask_user_test.step);
+ 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 acp_v2_test = b.addSystemCommand(&.{ "python3", "scripts/test-acp-v2.py" });
acp_v2_test.addArtifactArg(exe);
test_step.dependOn(&acp_v2_test.step);
diff --git a/scripts/test-mcp-client-spec.py b/scripts/test-mcp-client-spec.py
new file mode 100644
index 00000000..e19d39fa
--- /dev/null
+++ b/scripts/test-mcp-client-spec.py
@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""MCP client behavior against scripted servers (stdio and Streamable HTTP).
+
+- tools/list pagination: every page's tools are registered (nextCursor)
+- tools/call carries _meta.progressToken
+- notifications/tools/list_changed during a call re-lists before the next request
+- input_required (MRTR): the call is retried with inputResponses + requestState
+- a dropped SSE stream is resumed with GET + Last-Event-ID
+- ACP session/cancel during a hung MCP call ends the turn at once and sends
+ notifications/cancelled (stdio and legacy HTTP)
+"""
+import json, os, queue, shutil, signal, subprocess, sys, tempfile, threading, time
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parent / 'eval'))
+from mock_model import ScriptedModel
+
+DELAY = 0.6 # model latency: deferred MCP boot joins after the first request
+
+STDIO_SERVER = r'''
+import sys, json, os, time
+LOG = os.environ['FAKE_MCP_LOG']
+def log(x):
+ with open(LOG, 'a') as f: f.write(json.dumps(x) + "\n")
+def out(o): sys.stdout.write(json.dumps(o) + "\n"); sys.stdout.flush()
+def tool(n): return {"name": n, "description": "fake " + n, "inputSchema": {"type": "object", "properties": {}}}
+added = False
+for line in sys.stdin:
+ try: m = json.loads(line)
+ except ValueError: continue
+ log(m)
+ mid = m.get('id'); meth = m.get('method')
+ if mid is None: continue
+ if meth == 'initialize':
+ out({"jsonrpc": "2.0", "id": mid, "result": {"protocolVersion": "2025-11-25", "capabilities": {"tools": {"listChanged": True}}, "serverInfo": {"name": "fake", "version": "1"}}})
+ elif meth == 'server/discover':
+ out({"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": "Method not found"}})
+ elif meth == 'tools/list':
+ if (m.get('params') or {}).get('cursor') is None:
+ out({"jsonrpc": "2.0", "id": mid, "result": {"tools": [tool("slow"), tool("ask"), tool("hang")], "nextCursor": "p2"}})
+ else:
+ out({"jsonrpc": "2.0", "id": mid, "result": {"tools": [tool("page2tool")] + ([tool("added")] if added else [])}})
+ elif meth == 'tools/call':
+ p = m.get('params') or {}; name = p.get('name'); tok = (p.get('_meta') or {}).get('progressToken')
+ if name == 'slow':
+ out({"jsonrpc": "2.0", "method": "notifications/progress", "params": {"progressToken": tok, "progress": 1, "total": 2}})
+ added = True
+ out({"jsonrpc": "2.0", "method": "notifications/tools/list_changed", "params": {}})
+ out({"jsonrpc": "2.0", "id": mid, "result": {"content": [{"type": "text", "text": "slow done"}]}})
+ elif name == 'ask':
+ if 'inputResponses' in p:
+ out({"jsonrpc": "2.0", "id": mid, "result": {"content": [{"type": "text", "text": "ask done state=" + str(p.get('requestState'))}]}})
+ else:
+ out({"jsonrpc": "2.0", "id": mid, "result": {"resultType": "input_required", "inputRequests": {"q": {"method": "elicitation/create", "params": {"mode": "form", "message": "Name?", "requestedSchema": {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}}}}, "requestState": "st-1"}})
+ else:
+ out({"jsonrpc": "2.0", "id": mid, "result": {}})
+'''
+
+HTTP_SERVER = r'''
+import json, os, time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+LOG = os.environ['FAKE_MCP_LOG']; SID = 'sess-1'; state = {'added': False}
+def log(x):
+ with open(LOG, 'a') as f: f.write(json.dumps(x) + "\n")
+def tool(n): return {"name": n, "description": "fake " + n, "inputSchema": {"type": "object", "properties": {}}}
+class H(BaseHTTPRequestHandler):
+ protocol_version = 'HTTP/1.1'
+ def log_message(self, *a): pass
+ def _json(self, code, obj, extra=None):
+ b = json.dumps(obj).encode(); self.send_response(code); self.send_header('content-type', 'application/json'); self.send_header('content-length', str(len(b)))
+ for k, v in (extra or {}).items(): self.send_header(k, v)
+ self.end_headers(); self.wfile.write(b)
+ def _sse(self):
+ self.send_response(200); self.send_header('content-type', 'text/event-stream'); self.send_header('connection', 'close'); self.end_headers()
+ def _event(self, eid, obj):
+ self.wfile.write(("id: %s\ndata: %s\n\n" % (eid, json.dumps(obj))).encode()); self.wfile.flush()
+ def do_GET(self):
+ log({'GET': True, 'last_event_id': self.headers.get('last-event-id')})
+ if self.headers.get('last-event-id') == '2':
+ self._sse(); self._event('3', {"jsonrpc": "2.0", "id": state.get('slow_id', 0), "result": {"content": [{"type": "text", "text": "slowhttp done via resume"}]}}); self.close_connection = True
+ else:
+ self._json(405, {"error": "no"})
+ def do_POST(self):
+ m = json.loads(self.rfile.read(int(self.headers.get('content-length', 0)))); log(m)
+ meth = m.get('method'); mid = m.get('id')
+ if meth == 'initialize':
+ return self._json(200, {"jsonrpc": "2.0", "id": mid, "result": {"protocolVersion": "2025-11-25", "capabilities": {"tools": {"listChanged": True}}, "serverInfo": {"name": "fakehttp", "version": "1"}}}, {'mcp-session-id': SID})
+ if self.headers.get('mcp-session-id') != SID:
+ return self._json(400, {"jsonrpc": "2.0", "id": mid, "error": {"code": -32000, "message": "no session"}})
+ if mid is None:
+ self.send_response(202); self.send_header('content-length', '0'); self.end_headers(); return
+ if meth == 'tools/list':
+ return self._json(200, {"jsonrpc": "2.0", "id": mid, "result": {"tools": [tool('slowhttp'), tool('hanghttp')] + ([tool('addedhttp')] if state['added'] else [])}})
+ if meth == 'tools/call':
+ name = (m.get('params') or {}).get('name')
+ if name == 'slowhttp':
+ state['slow_id'] = mid; state['added'] = True
+ self._sse()
+ self._event('1', {"jsonrpc": "2.0", "method": "notifications/progress", "params": {"progressToken": mid, "progress": 1}})
+ self._event('2', {"jsonrpc": "2.0", "method": "notifications/tools/list_changed", "params": {}})
+ self.close_connection = True; return # dropped before the reply
+ if name == 'hanghttp':
+ self._sse(); time.sleep(20); self.close_connection = True; return
+ return self._json(200, {"jsonrpc": "2.0", "id": mid, "result": {}})
+srv = ThreadingHTTPServer(('127.0.0.1', 0), H); print(srv.server_address[1], flush=True); srv.serve_forever()
+'''
+
+
+class SlowModel(ScriptedModel):
+ def next_reply(self, body):
+ time.sleep(DELAY)
+ return super().next_reply(body)
+
+
+def read_log(path):
+ if not os.path.exists(path):
+ return []
+ return [json.loads(l) for l in open(path) if l.strip()]
+
+
+class Env:
+ def __init__(self, servers):
+ self.temp = tempfile.mkdtemp(prefix='mcp-client-spec-')
+ cfg = Path(self.temp) / 'mcp.json'
+ cfg.write_text(json.dumps({"mcpServers": servers}))
+ self.env = {k: v for k, v in os.environ.items() if not k.endswith('_API_KEY')}
+ self.env.update(HOME=self.temp, AI_GATEWAY_API_KEY='local', GRAFF_MCP_CONFIG=str(cfg), GRAFF_NO_TELEMETRY='1',
+ GRAFF_FLEET='off', GRAFF_NO_SMOLIFY='1', GRAFF_NO_CODEDB_GUARD='1')
+
+ def model(self, script):
+ m = SlowModel(script)
+ self.env['GRAFF_VERCEL_URL'] = f'http://127.0.0.1:{m.start(0)}/v1/chat/completions'
+ return m
+
+ def cleanup(self):
+ shutil.rmtree(self.temp, ignore_errors=True)
+
+
+def tool_results(model):
+ last = model.requests[-1] if model.requests else {}
+ return [m.get('content') for m in last.get('messages', []) if m.get('role') == 'tool']
+
+
+def oneshot(binary, e):
+ subprocess.run([binary, '--model', 'vercel', '--old', '--no-lean', '--yolo', '-p', 'use the fake tools'],
+ cwd=e.temp, env=e.env, capture_output=True, text=True, timeout=120)
+
+
+def acp_cancel(binary, e, log_path, hung_name):
+ proc = subprocess.Popen([binary, 'acp', '--model', 'vercel', '--old', '--no-lean', '--yolo'], cwd=e.temp, env=e.env,
+ stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True,
+ start_new_session=os.name == 'posix')
+ messages = queue.Queue()
+
+ def read():
+ for line in proc.stdout:
+ try:
+ messages.put(json.loads(line))
+ except ValueError:
+ pass
+ messages.put(None)
+ threading.Thread(target=read, daemon=True).start()
+
+ def send(obj):
+ proc.stdin.write(json.dumps({'jsonrpc': '2.0', **obj}) + '\n')
+ proc.stdin.flush()
+
+ def wait(i, timeout):
+ deadline = time.monotonic() + timeout
+ while time.monotonic() < deadline:
+ try:
+ m = messages.get(timeout=max(.01, deadline - time.monotonic()))
+ except queue.Empty:
+ return None
+ if m is None:
+ return None
+ if m.get('id') == i and 'method' not in m:
+ return m
+ return None
+ try:
+ send({'id': 1, 'method': 'initialize', 'params': {'protocolVersion': 1, 'clientCapabilities': {}}})
+ assert wait(1, 30), 'initialize'
+ send({'id': 2, 'method': 'session/new', 'params': {'cwd': e.temp, 'mcpServers': []}})
+ sid = wait(2, 30)['result']['sessionId']
+ send({'id': 3, 'method': 'session/prompt', 'params': {'sessionId': sid, 'prompt': [{'type': 'text', 'text': 'go'}]}})
+ deadline = time.monotonic() + 30
+ while time.monotonic() < deadline and not any((m.get('params') or {}).get('name') == hung_name for m in read_log(log_path)):
+ time.sleep(0.1)
+ time.sleep(1.0)
+ started = time.monotonic()
+ send({'method': 'session/cancel', 'params': {'sessionId': sid}})
+ done = wait(3, 10)
+ elapsed = time.monotonic() - started
+ assert done and done.get('result', {}).get('stopReason') == 'cancelled', done
+ assert elapsed < 5, f'cancel took {elapsed:.1f}s'
+ time.sleep(0.5)
+ cancelled = [m for m in read_log(log_path) if m.get('method') == 'notifications/cancelled']
+ call_ids = [m.get('id') for m in read_log(log_path) if (m.get('params') or {}).get('name') == hung_name]
+ assert cancelled and cancelled[0]['params']['requestId'] in call_ids, (cancelled, call_ids)
+ finally:
+ if os.name == 'posix':
+ os.killpg(proc.pid, signal.SIGKILL)
+ else:
+ proc.kill()
+ proc.wait(timeout=10)
+
+
+def stdio_cases(binary, server_py):
+ log_path = str(Path(tempfile.mkdtemp()) / 'stdio.log')
+ e = Env({"fake": {"command": sys.executable, "args": [server_py], "env": {"FAKE_MCP_LOG": log_path}}})
+ try:
+ model = e.model([{'tool': 'todo_read', 'arguments': {}}, {'tool': 'mcp__fake__slow', 'arguments': {}},
+ {'tool': 'mcp__fake__ask', 'arguments': {}}, {'text': 'Done.'}])
+ oneshot(binary, e)
+ model.stop()
+ log = read_log(log_path)
+ lists = [m for m in log if m.get('method') == 'tools/list']
+ assert any((m.get('params') or {}).get('cursor') == 'p2' for m in lists), 'second page was never requested'
+ calls = [m for m in log if m.get('method') == 'tools/call']
+ assert calls and all(((m.get('params') or {}).get('_meta') or {}).get('progressToken') is not None for m in calls), calls
+ assert len(lists) >= 4, 'list_changed did not trigger a re-list (both pages again)'
+ results = tool_results(model)
+ assert any('slow done' in str(r) for r in results), results
+ assert any('ask done state=st-1' in str(r) for r in results), results
+ assert any('inputResponses' in (m.get('params') or {}) for m in calls), 'MRTR retry missing'
+ print('PASS MCP stdio: pagination, progress token, list_changed refresh, input_required retry', flush=True)
+
+ open(log_path, 'w').close()
+ e.model([{'tool': 'todo_read', 'arguments': {}}, {'tool': 'mcp__fake__hang', 'arguments': {}}, {'text': 'after'}])
+ acp_cancel(binary, e, log_path, 'hang')
+ print('PASS MCP stdio: ACP cancel stops a hung call and sends notifications/cancelled', flush=True)
+ finally:
+ e.cleanup()
+
+
+def http_cases(binary, server_py):
+ log_path = str(Path(tempfile.mkdtemp()) / 'http.log')
+ srv = subprocess.Popen([sys.executable, server_py], stdout=subprocess.PIPE, text=True, env=dict(os.environ, FAKE_MCP_LOG=log_path))
+ try:
+ port = int(srv.stdout.readline())
+ e = Env({"fakehttp": {"url": f"http://127.0.0.1:{port}/mcp"}})
+ try:
+ model = e.model([{'tool': 'todo_read', 'arguments': {}}, {'tool': 'mcp__fakehttp__slowhttp', 'arguments': {}}, {'text': 'Done.'}])
+ oneshot(binary, e)
+ model.stop()
+ log = read_log(log_path)
+ assert any(m.get('GET') and m.get('last_event_id') == '2' for m in log), 'no Last-Event-ID resume'
+ assert any('slowhttp done via resume' in str(r) for r in tool_results(model)), tool_results(model)
+ assert sum(1 for m in log if m.get('method') == 'tools/list') >= 2, 'SSE list_changed did not trigger a re-list'
+ print('PASS MCP HTTP: dropped SSE resumed with Last-Event-ID; list_changed from the stream re-lists', flush=True)
+
+ open(log_path, 'w').close()
+ e.model([{'tool': 'todo_read', 'arguments': {}}, {'tool': 'mcp__fakehttp__hanghttp', 'arguments': {}}, {'text': 'after'}])
+ acp_cancel(binary, e, log_path, 'hanghttp')
+ print('PASS MCP HTTP: ACP cancel stops a hung call and sends notifications/cancelled', flush=True)
+ finally:
+ e.cleanup()
+ finally:
+ srv.kill()
+ srv.wait(timeout=10)
+
+
+if __name__ == '__main__':
+ binary = str(Path(sys.argv[1] if len(sys.argv) > 1 else 'zig-out/bin/graff').resolve())
+ work = Path(tempfile.mkdtemp(prefix='mcp-fakes-'))
+ try:
+ (work / 'stdio_server.py').write_text(STDIO_SERVER)
+ (work / 'http_server.py').write_text(HTTP_SERVER)
+ stdio_cases(binary, str(work / 'stdio_server.py'))
+ http_cases(binary, str(work / 'http_server.py'))
+ finally:
+ shutil.rmtree(work, ignore_errors=True)
diff --git a/src/agent_request.zig b/src/agent_request.zig
index c538d804..c10343e5 100644
--- a/src/agent_request.zig
+++ b/src/agent_request.zig
@@ -101,7 +101,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
http.waitForClientReady(self.io);
if (http.takeCaWarmFailure()) if (self.tracer) |tr| tr.note("ca_prewarm_failed", "CA bundle rescan failed; request will use lazy TLS initialization");
if (self.registry) |reg| {
- if (@import("mcp_boot.zig").joinBeforeRequest(reg)) {
+ if (@import("mcp_pages.zig").beforeRequest(reg)) { // joins deferred starts, re-lists changed servers
self.invalidateRootTools();
try self.ensureRootTools(self.provider.kind);
}
diff --git a/src/main.zig b/src/main.zig
index 448a6f04..81734e23 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("ask_user_args.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig") };
+ _ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_elicit.zig"), @import("mcp_notify.zig"), @import("mcp_wait.zig"), @import("mcp_pages.zig"), @import("mcp_mrtr.zig"), @import("ask_user_args.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.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 808f84f5..0f3da30a 100644
--- a/src/mcp.zig
+++ b/src/mcp.zig
@@ -52,6 +52,15 @@ pub const Tool = struct {
}
};
+/// One server/tool for MRTR retries (mcp_mrtr.resolve).
+const McpCall = struct {
+ server: *Server,
+ name: []const u8,
+ fn send(self: McpCall, a: Allocator, params: []const u8) anyerror!Value {
+ return request(self.server, a, params, "tools/call", self.name);
+ }
+};
+
pub const Registry = struct {
last_app_path: ?[]const u8 = null,
gpa: Allocator,
@@ -411,38 +420,14 @@ pub const Registry = struct {
},
};
const result_v = listed.object.get("result") orelse return error.BadMcpResponse;
- if (result_v != .object) return error.BadMcpResponse;
- const tv = result_v.object.get("tools") orelse return error.BadMcpResponse;
- if (tv != .array) return error.BadMcpResponse;
- listed_result = result_v;
- break :blk tv;
+ // Every page of a paginated catalog, not only the first.
+ const all = try @import("mcp_pages.zig").complete(server, a, reg.io, result_v);
+ listed_result = all.result;
+ break :blk all.tools;
};
- for (tools_v.array.items) |t| {
- if (t != .object) continue;
- if (!@import("mcp_apps.zig").modelVisible(t)) continue;
- const name_v = t.object.get("name") orelse continue;
- if (name_v != .string) continue;
- const orig = try a.dupe(u8, name_v.string);
- const qualified = try @import("mcp_names.zig").qualify(a, name, orig);
- // Prefer description; fall back to the 2025-06-18+ human-readable
- // title so a metadata-only tool isn't blank to the model.
- const desc = if (t.object.get("description")) |d| (if (d == .string) d.string else "") else if (t.object.get("title")) |ti| (if (ti == .string) ti.string else "") else "";
- var schema = t.object.get("inputSchema") orelse Value{ .object = .empty };
- try rewriteOneOf(a, &schema);
- // ...then lower any TOP-LEVEL combinator: Anthropic rejects the
- // whole request over one, so a single server advertising it would
- // break every turn (codedbpro's `replace`, "path or paths").
- try mcp_protocol.flattenTopLevel(a, &schema);
- try tools.append(a, .{
- .server_index = server_index,
- .server_name = server.name,
- .original_name = orig,
- .qualified_name = qualified,
- .description = try a.dupe(u8, desc),
- .input_schema = schema,
- .ui_resource_uri = if (@import("mcp_apps.zig").resourceUri(t)) |uri| try a.dupe(u8, uri) else null,
- });
- }
+ try @import("mcp_pages.zig").appendTools(a, tools, server_index, server, tools_v);
+ mcp_rpc.bindNotes(server);
+ @import("mcp_pages.zig").listen(server, a); // modern stdio: ask for tools/list_changed
try servers.append(a, server);
registry_owns_server = true;
if (listed_result) |rv| mcp_cache.store(reg.io, a, reg.home, cache_key, server.era, server.protocol_version, rv, now_ms);
@@ -501,7 +486,7 @@ pub const Registry = struct {
if (!server.initialized) try initializeServer(server, response_alloc, reg.arena(), null);
server.elicit_source = params;
defer server.elicit_source = "";
- const resp = request(server, response_alloc, params, "tools/call", tool.original_name) catch |err| switch (err) {
+ const first_resp = request(server, response_alloc, params, "tools/call", tool.original_name) catch |err| switch (err) {
// Streamable HTTP servers use 404 to expire a session. Re-run the
// MCP handshake once, then retry the call without the stale ID.
// A modern-era server never carries a session id in the first
@@ -516,6 +501,10 @@ pub const Registry = struct {
},
else => return err,
};
+ // 2026-07-28 input_required: answer and retry (bounded) until complete.
+ const call_ctx: McpCall = .{ .server = server, .name = tool.original_name };
+ const resp = try @import("mcp_mrtr.zig").resolve(response_alloc, params, first_resp, call_ctx, McpCall.send);
+ if (resp != .object) return error.BadMcpResponse;
if (resp.object.get("error")) |e| {
// Protocol-level failure (unknown tool, invalid args, server
@@ -546,12 +535,10 @@ pub const Registry = struct {
if (result_val != .object)
return .{ .text = try out_alloc.dupe(u8, "MCP response result was not an object"), .is_error = true };
const result = result_val.object;
- // resultType absent MUST read as "complete" (every server graff has
- // ever talked to). MRTR (inputRequests/inputResponses) is not
- // implemented — surface a clear error instead of silently returning
- // "" with is_error=false, which is what fell through here before.
+ // resultType absent MUST read as "complete". input_required was
+ // resolved above; any other type is surfaced, never returned as "".
if (!mcp_protocol.resultIsComplete(result))
- return .{ .text = try out_alloc.dupe(u8, "MCP server returned an input_required result (MRTR); codegraff does not implement it"), .is_error = true };
+ return .{ .text = try out_alloc.dupe(u8, "MCP server returned an unsupported resultType"), .is_error = true };
const is_error = if (result.get("isError")) |v| (v == .bool and v.bool) else false;
var ow: Io.Writer.Allocating = .init(out_alloc);
diff --git a/src/mcp_http.zig b/src/mcp_http.zig
index 80489e7d..5bc679c6 100644
--- a/src/mcp_http.zig
+++ b/src/mcp_http.zig
@@ -6,6 +6,7 @@ const Value = std.json.Value;
const Allocator = std.mem.Allocator;
const mcp_oauth = @import("mcp_oauth.zig");
const mcp_protocol = @import("mcp_protocol.zig");
+const mcp_notify = @import("mcp_notify.zig");
const max_http_response = 1 << 20;
@@ -15,6 +16,8 @@ pub const HttpTransport = struct {
headers: []const std.http.Header = &.{},
oauth_home: ?[]const u8 = null,
session_id: ?[]const u8 = null,
+ /// The owning server's sink: SSE notifications and the resume point.
+ notes: ?*mcp_notify.Sink = null,
};
fn validRemoteUri(uri: std.Uri) bool {
@@ -98,7 +101,7 @@ fn jsonResponseMatches(gpa: Allocator, bytes: []const u8, expected_id: i64) bool
/// response arrives. This is important for servers that keep the POST stream
/// open after emitting the response. Multiple `data:` fields are joined with
/// newlines per the SSE specification.
-fn readSseResponse(gpa: Allocator, reader: *Io.Reader, expected_id: ?i64) !?[]u8 {
+fn readSseResponse(gpa: Allocator, reader: *Io.Reader, expected_id: ?i64, notes: ?*mcp_notify.Sink, io: Io) !?[]u8 {
const line_buf = try gpa.alloc(u8, max_http_response);
defer gpa.free(line_buf);
var event_data: std.ArrayList(u8) = .empty;
@@ -128,7 +131,9 @@ fn readSseResponse(gpa: Allocator, reader: *Io.Reader, expected_id: ?i64) !?[]u8
consumed += 1;
}
- if (std.mem.startsWith(u8, line, "data:")) {
+ if (std.mem.startsWith(u8, line, "id:")) {
+ if (notes) |sink| sink.noteEventId(std.mem.trim(u8, line["id:".len..], " \t"));
+ } else if (std.mem.startsWith(u8, line, "data:")) {
const data = std.mem.trimStart(u8, line["data:".len..], " \t");
if (event_data.items.len > 0) try event_data.append(gpa, '\n');
if (event_data.items.len + data.len > max_http_response) return error.McpResponseTooLarge;
@@ -139,6 +144,7 @@ fn readSseResponse(gpa: Allocator, reader: *Io.Reader, expected_id: ?i64) !?[]u8
if (event_data.items.len > 0) {
const matches = if (expected_id) |id| jsonResponseMatches(gpa, event_data.items, id) else true;
if (matches) return try gpa.dupe(u8, event_data.items);
+ if (notes) |sink| _ = mcp_notify.observe(sink, io, event_data.items);
event_data.clearRetainingCapacity();
}
}
@@ -223,20 +229,60 @@ fn httpPostUnwatched(http: *HttpTransport, body: []const u8, meta: RequestMeta,
}
}
- return readResponseBody(http.client.allocator, &response, expected_id);
+ if (http.notes) |sink| sink.clearEventId();
+ const got = try readResponseBody(http.client.allocator, &response, expected_id, http.notes, http.client.io);
+ if (got != null or expected_id == null or meta.modern) return got;
+ // The SSE stream closed before the reply arrived (legacy sessions).
+ return resumeStream(http, meta, expected_id.?);
+}
+
+/// Streamable HTTP lets a client reopen a dropped SSE stream with GET and
+/// `Last-Event-ID`; the server replays events after that one. At most two
+/// attempts, and only when the stream carried event ids.
+fn resumeStream(http: *HttpTransport, meta: RequestMeta, id: i64) !?[]u8 {
+ const sink = http.notes orelse return null;
+ var attempt: u8 = 0;
+ while (attempt < 2) : (attempt += 1) {
+ const last = sink.lastEventId() orelse return null;
+ var arena_state = std.heap.ArenaAllocator.init(http.client.allocator);
+ defer arena_state.deinit();
+ const a = arena_state.allocator();
+ var extra: std.ArrayList(std.http.Header) = .empty;
+ try extra.appendSlice(a, try buildHeaders(a, http, meta, loadBearer(http, a)));
+ try extra.append(a, .{ .name = "last-event-id", .value = try a.dupe(u8, last) });
+ var req = try http.client.request(.GET, try std.Uri.parse(http.url), .{
+ .redirect_behavior = .unhandled,
+ .headers = .{ .user_agent = .{ .override = "codegraff-mcp/1" } },
+ .extra_headers = extra.items,
+ });
+ defer req.deinit();
+ errdefer {
+ if (req.connection) |connection| connection.closing = true;
+ }
+ try req.sendBodiless();
+ var response = try req.receiveHead(&.{});
+ const status = @intFromEnum(response.head.status);
+ if (status < 200 or status >= 300) {
+ if (req.connection) |connection| connection.closing = true;
+ return null;
+ }
+ if (try readResponseBody(http.client.allocator, &response, id, sink, http.client.io)) |body| return body;
+ }
+ return null;
}
const HttpPostDone = union(enum) {
posted: anyerror!?[]u8,
timeout,
+ cancelled,
};
fn httpPostTask(http: *HttpTransport, body: []const u8, meta: RequestMeta, expected_id: ?i64) anyerror!?[]u8 {
return httpPostUnwatched(http, body, meta, expected_id);
}
-fn httpPostTimeout(io: Io) void {
- io.sleep(.fromSeconds(15), .awake) catch {};
+fn httpPostTimeout(io: Io, seconds: i64) void {
+ io.sleep(.fromSeconds(seconds), .awake) catch {};
}
fn freeLateHttpPost(allocator: Allocator, result: anyerror!?[]u8) void {
@@ -248,45 +294,75 @@ fn freeLateHttpPost(allocator: Allocator, result: anyerror!?[]u8) void {
fn cancelHttpPost(select: *Io.Select(HttpPostDone), allocator: Allocator) void {
while (select.cancel()) |late| switch (late) {
.posted => |result| freeLateHttpPost(allocator, result),
- .timeout => {},
+ .timeout, .cancelled => {},
};
}
-/// Race network I/O against a hard deadline. Cancellation unwinds the request,
-/// whose errdefer poisons the connection so a timed-out socket is never pooled.
+pub const PostOptions = struct {
+ /// Stop when the user cancels the turn (error.McpCancelled).
+ watch_cancel: bool = true,
+ timeout_s: i64 = 15,
+};
+
+/// Race network I/O against a hard deadline and the user's cancel.
+/// Cancellation unwinds the request, whose errdefer poisons the connection so
+/// a timed-out socket is never pooled.
pub fn post(http: *HttpTransport, body: []const u8, meta: RequestMeta, expected_id: ?i64) !?[]u8 {
- var done_buf: [2]HttpPostDone = undefined;
+ return postWith(http, body, meta, expected_id, .{});
+}
+
+pub fn postWith(http: *HttpTransport, body: []const u8, meta: RequestMeta, expected_id: ?i64, opts: PostOptions) !?[]u8 {
+ var done_buf: [3]HttpPostDone = undefined;
var select: Io.Select(HttpPostDone) = .init(http.client.io, &done_buf);
select.concurrent(.posted, httpPostTask, .{ http, body, meta, expected_id }) catch
return error.McpRequestTimedOut;
- select.concurrent(.timeout, httpPostTimeout, .{http.client.io}) catch {
+ var watch_done = std.atomic.Value(bool).init(false);
+ defer watch_done.store(true, .release);
+ if (opts.watch_cancel) select.concurrent(.cancelled, @import("mcp_wait.zig").watchCancel, .{ http.client.io, &watch_done }) catch {};
+ select.concurrent(.timeout, httpPostTimeout, .{ http.client.io, opts.timeout_s }) catch {
const only = select.await() catch |err| {
cancelHttpPost(&select, http.client.allocator);
return err;
};
- select.cancelDiscard();
- return only.posted;
+ cancelHttpPost(&select, http.client.allocator);
+ return switch (only) {
+ .posted => |result| result,
+ .timeout => error.McpRequestTimedOut,
+ .cancelled => error.McpCancelled,
+ };
};
const first = select.await() catch |err| {
cancelHttpPost(&select, http.client.allocator);
return err;
};
+ watch_done.store(true, .release);
switch (first) {
.posted => |result| {
- select.cancelDiscard();
+ cancelHttpPost(&select, http.client.allocator);
return result;
},
.timeout => {
- while (select.cancel()) |late| switch (late) {
- .posted => |result| freeLateHttpPost(http.client.allocator, result),
- .timeout => {},
- };
+ cancelHttpPost(&select, http.client.allocator);
return error.McpRequestTimedOut;
},
+ .cancelled => {
+ cancelHttpPost(&select, http.client.allocator);
+ return error.McpCancelled;
+ },
}
}
+/// Tell a legacy session to stop request `id`. Best effort: bounded, and the
+/// turn's cancel flag (still set) must not abort this send.
+pub fn notifyCancelled(http: *HttpTransport, protocol_version: []const u8, id: i64) void {
+ var buf: [256]u8 = undefined;
+ var fba = std.heap.FixedBufferAllocator.init(&buf);
+ const line = mcp_notify.cancelledLine(fba.allocator(), id) catch return;
+ const reply = postWith(http, line, .{ .protocol_version = protocol_version, .method = "notifications/cancelled", .modern = false }, null, .{ .watch_cancel = false, .timeout_s = 3 }) catch return;
+ if (reply) |bytes| http.client.allocator.free(bytes);
+}
+
/// A probe reply: the raw status and (if any) body, on ANY status — unlike
/// `post`, a probe never errors on a non-2xx status, since the whole point
/// is to hand the caller the error body so `mcp_protocol.classifyProbe` can
@@ -332,7 +408,7 @@ fn probeUnwatched(http: *HttpTransport, body: []const u8, meta: RequestMeta) !Pr
if (req.connection) |connection| connection.closing = true;
}
- return .{ .status = status, .body = try readResponseBody(http.client.allocator, &response, null) };
+ return .{ .status = status, .body = try readResponseBody(http.client.allocator, &response, null, null, http.client.io) };
}
fn decompressWindow(gpa: Allocator, encoding: std.http.ContentEncoding) ![]u8 {
@@ -346,7 +422,7 @@ fn decompressWindow(gpa: Allocator, encoding: std.http.ContentEncoding) ![]u8 {
/// Decode the HTTP body, honoring Content-Encoding (gzip/deflate/zstd).
/// Callers used to omit Accept-Encoding so catalogs crossed the wire raw.
-fn readResponseBody(gpa: Allocator, response: *std.http.Client.Response, expected_id: ?i64) !?[]u8 {
+fn readResponseBody(gpa: Allocator, response: *std.http.Client.Response, expected_id: ?i64, notes: ?*mcp_notify.Sink, io: Io) !?[]u8 {
if (response.head.content_length == 0) return null;
const is_sse = if (response.head.content_type) |content_type|
std.ascii.startsWithIgnoreCase(content_type, "text/event-stream")
@@ -357,7 +433,7 @@ fn readResponseBody(gpa: Allocator, response: *std.http.Client.Response, expecte
var transfer_buf: [4096]u8 = undefined;
var decompress: std.http.Decompress = undefined;
const reader = response.readerDecompressing(&transfer_buf, &decompress, window);
- if (is_sse) return readSseResponse(gpa, reader, expected_id);
+ if (is_sse) return readSseResponse(gpa, reader, expected_id, notes, io);
const response_buf = try gpa.alloc(u8, max_http_response);
errdefer gpa.free(response_buf);
@@ -405,7 +481,7 @@ pub fn probe(http: *HttpTransport, body: []const u8, meta: RequestMeta) !ProbeRe
var select: Io.Select(ProbeDone) = .init(http.client.io, &done_buf);
select.concurrent(.probed, probeTask, .{ http, body, meta }) catch
return error.McpRequestTimedOut;
- select.concurrent(.timeout, httpPostTimeout, .{http.client.io}) catch {
+ select.concurrent(.timeout, httpPostTimeout, .{ http.client.io, 15 }) catch {
const only = select.await() catch |err| {
cancelProbe(&select, http.client.allocator);
return err;
diff --git a/src/mcp_mrtr.zig b/src/mcp_mrtr.zig
new file mode 100644
index 00000000..74c346e9
--- /dev/null
+++ b/src/mcp_mrtr.zig
@@ -0,0 +1,130 @@
+//! MCP 2026-07-28 multi round-trip requests (MRTR) for `tools/call`.
+//!
+//! A modern server that needs client input mid-call no longer sends an
+//! `elicitation/create` request; it returns `resultType: "input_required"`
+//! with `inputRequests` (and optionally `requestState`). The client answers
+//! each request and retries the same `tools/call` with `inputResponses` and
+//! the echoed `requestState`. graff used to stop with "does not implement
+//! MRTR". Answers follow the same policy as a legacy elicitation
+//! (mcp_elicitation.decide): accept only what graff can fill safely,
+//! decline the rest. `roots/list` gets no roots.
+
+const std = @import("std");
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+const mcp_elicitation = @import("mcp_elicitation.zig");
+const mcp_protocol = @import("mcp_protocol.zig");
+
+pub const max_rounds = 4;
+
+/// The `inputResponses` object for one `input_required` result.
+pub fn responses(a: Allocator, source: []const u8, requests: std.json.ObjectMap) !Value {
+ var out: std.json.ObjectMap = .empty;
+ var it = requests.iterator();
+ while (it.next()) |e| {
+ const req = e.value_ptr.*;
+ const method = if (req == .object) (if (req.object.get("method")) |m| (if (m == .string) m.string else "") else "") else "";
+ const params = if (req == .object) req.object.get("params") orelse Value.null else Value.null;
+ var answer: std.json.ObjectMap = .empty;
+ if (std.mem.eql(u8, method, "elicitation/create")) {
+ const schema = if (params == .object) params.object.get("requestedSchema") else null;
+ const filled = if (mcp_elicitation.decide(source, params) == .accept) mcp_elicitation.acceptContent(a, schema) else null;
+ if (filled) |content| {
+ try answer.put(a, "action", .{ .string = "accept" });
+ try answer.put(a, "content", try std.json.parseFromSliceLeaky(Value, a, content, .{ .allocate = .alloc_always }));
+ } else try answer.put(a, "action", .{ .string = "decline" });
+ } else if (std.mem.eql(u8, method, "roots/list")) {
+ try answer.put(a, "roots", .{ .array = std.json.Array.init(a) });
+ } else {
+ try answer.put(a, "action", .{ .string = "decline" });
+ }
+ try out.put(a, e.key_ptr.*, .{ .object = answer });
+ }
+ return .{ .object = out };
+}
+
+/// The retry params: the original `tools/call` params plus
+/// `inputResponses` and the echoed `requestState`.
+pub fn retryParams(a: Allocator, params: []const u8, result: std.json.ObjectMap, source: []const u8) ![]const u8 {
+ const original = try std.json.parseFromSliceLeaky(Value, a, params, .{ .allocate = .alloc_always });
+ if (original != .object) return error.BadMcpParams;
+ var next = try original.object.clone(a);
+ if (result.get("inputRequests")) |reqs| if (reqs == .object) try next.put(a, "inputResponses", try responses(a, source, reqs.object));
+ if (result.get("requestState")) |state| try next.put(a, "requestState", state);
+ return std.json.Stringify.valueAlloc(a, Value{ .object = next }, .{});
+}
+
+fn inputRequired(resp: Value) ?std.json.ObjectMap {
+ if (resp != .object) return null;
+ const r = resp.object.get("result") orelse return null;
+ if (r != .object or mcp_protocol.resultIsComplete(r.object)) return null;
+ const t = r.object.get("resultType") orelse return null;
+ return if (t == .string and std.mem.eql(u8, t.string, "input_required")) r.object else null;
+}
+
+/// Drive `input_required` results to completion. `send` performs one
+/// `tools/call` with the given params; `first` is the reply to the original.
+pub fn resolve(a: Allocator, params: []const u8, first: Value, ctx: anytype, send: fn (@TypeOf(ctx), Allocator, []const u8) anyerror!Value) !Value {
+ var resp = first;
+ var round: usize = 0;
+ while (inputRequired(resp)) |result| : (round += 1) {
+ if (round == max_rounds) return error.McpInputRequiredLoop;
+ resp = try send(ctx, a, try retryParams(a, params, result, params));
+ }
+ return resp;
+}
+
+const testing = std.testing;
+
+test "responses decline an unfillable form and answer roots/list" {
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const reqs = try std.json.parseFromSliceLeaky(Value, a,
+ \\{"login":{"method":"elicitation/create","params":{"mode":"form","message":"GitHub username?","requestedSchema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}},
+ \\ "roots":{"method":"roots/list","params":{}}}
+ , .{});
+ const out = try responses(a, "{\"name\":\"t\"}", reqs.object);
+ try testing.expectEqualStrings("decline", out.object.get("login").?.object.get("action").?.string);
+ try testing.expectEqual(@as(usize, 0), out.object.get("roots").?.object.get("roots").?.array.items.len);
+}
+
+test "retryParams keeps the call and adds inputResponses and requestState" {
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const result = try std.json.parseFromSliceLeaky(Value, a,
+ \\{"resultType":"input_required","inputRequests":{"q":{"method":"elicitation/create","params":{"message":"?"}}},"requestState":"s1"}
+ , .{});
+ const p = try retryParams(a, "{\"name\":\"get_weather\",\"arguments\":{\"location\":\"NYC\"}}", result.object, "");
+ const v = try std.json.parseFromSliceLeaky(Value, a, p, .{});
+ try testing.expectEqualStrings("get_weather", v.object.get("name").?.string);
+ try testing.expectEqualStrings("s1", v.object.get("requestState").?.string);
+ try testing.expect(v.object.get("inputResponses").?.object.get("q") != null);
+}
+
+const Fake = struct {
+ calls: usize = 0,
+ fn send(self: *Fake, a: Allocator, params: []const u8) anyerror!Value {
+ self.calls += 1;
+ const v = try std.json.parseFromSliceLeaky(Value, a, params, .{});
+ try testing.expect(v.object.get("inputResponses") != null);
+ return std.json.parseFromSliceLeaky(Value, a, "{\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"done\"}]}}", .{});
+ }
+};
+
+test "resolve retries once and returns the completed result" {
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const first = try std.json.parseFromSliceLeaky(Value, a,
+ \\{"jsonrpc":"2.0","id":1,"result":{"resultType":"input_required","inputRequests":{"q":{"method":"elicitation/create","params":{"message":"?"}}}}}
+ , .{});
+ var fake: Fake = .{};
+ const done = try resolve(a, "{\"name\":\"t\",\"arguments\":{}}", first, &fake, Fake.send);
+ try testing.expectEqual(@as(usize, 1), fake.calls);
+ try testing.expect(mcp_protocol.resultIsComplete(done.object.get("result").?.object));
+ const plain = try std.json.parseFromSliceLeaky(Value, a, "{\"result\":{\"content\":[]}}", .{});
+ _ = try resolve(a, "{}", plain, &fake, Fake.send);
+ try testing.expectEqual(@as(usize, 1), fake.calls); // a complete result is not retried
+}
diff --git a/src/mcp_notify.zig b/src/mcp_notify.zig
new file mode 100644
index 00000000..3894a3d0
--- /dev/null
+++ b/src/mcp_notify.zig
@@ -0,0 +1,166 @@
+//! Server-to-client MCP notifications that arrive while graff waits for a
+//! reply: on a stdio pipe between response lines, or as extra events in a
+//! Streamable HTTP SSE response. Before this they were read and dropped.
+//!
+//! - `notifications/tools/list_changed` marks the server's catalog stale;
+//! `mcp_pages.refreshStale` re-lists it before the next model request.
+//! - `notifications/progress` for a call graff tagged with a progress token
+//! becomes a transient progress line, like a long shell job's pulse.
+//! - An SSE `id:` field is remembered so a stream that drops before the
+//! reply can be resumed with `Last-Event-ID` (mcp_http.resume).
+
+const std = @import("std");
+const Io = std.Io;
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+
+pub const Sink = struct {
+ server: []const u8 = "",
+ tools_stale: std.atomic.Value(bool) = .init(false),
+ last_event_id: [128]u8 = undefined,
+ last_event_len: u8 = 0,
+
+ pub fn noteEventId(self: *Sink, id: []const u8) void {
+ const n: u8 = @intCast(@min(id.len, self.last_event_id.len));
+ @memcpy(self.last_event_id[0..n], id[0..n]);
+ self.last_event_len = n;
+ }
+
+ pub fn lastEventId(self: *const Sink) ?[]const u8 {
+ return if (self.last_event_len == 0) null else self.last_event_id[0..self.last_event_len];
+ }
+
+ pub fn clearEventId(self: *Sink) void {
+ self.last_event_len = 0;
+ }
+};
+
+/// Where progress lines go: a transient notice like a shell job's pulse.
+/// Null drops them.
+pub var on_progress: ?*const fn (io: Io, server: []const u8, text: []const u8) void = pulse;
+
+fn pulse(io: Io, server: []const u8, text: []const u8) void {
+ @import("tool_pulse.zig").emitNotice(io, "· mcp:{s} · {s}", .{ server, text });
+}
+
+pub const Kind = enum { none, tools_changed, progress };
+
+/// Inspect one JSON-RPC message that is not the awaited reply. Returns what
+/// it was so callers and tests can tell.
+pub fn observe(sink: *Sink, io: Io, bytes: []const u8) Kind {
+ var buf: [16 * 1024]u8 = undefined;
+ var fba = std.heap.FixedBufferAllocator.init(&buf);
+ const trimmed = std.mem.trim(u8, bytes, " \t\r\n");
+ if (trimmed.len == 0 or trimmed.len > 8 * 1024) return .none;
+ const v = std.json.parseFromSliceLeaky(Value, fba.allocator(), trimmed, .{}) catch return .none;
+ if (v != .object) return .none;
+ const method = v.object.get("method") orelse return .none;
+ if (method != .string or v.object.get("id") != null) return .none; // requests are answered elsewhere
+ if (std.mem.eql(u8, method.string, "notifications/tools/list_changed")) {
+ sink.tools_stale.store(true, .release);
+ return .tools_changed;
+ }
+ if (std.mem.eql(u8, method.string, "notifications/progress")) {
+ const params = v.object.get("params") orelse return .progress;
+ if (params != .object) return .progress;
+ var line: [256]u8 = undefined;
+ const text = progressText(&line, params.object);
+ if (on_progress) |emit| if (text.len > 0) emit(io, sink.server, text);
+ return .progress;
+ }
+ return .none;
+}
+
+fn number(v: ?Value) ?f64 {
+ const x = v orelse return null;
+ return switch (x) {
+ .integer => |i| @floatFromInt(i),
+ .float => |f| f,
+ else => null,
+ };
+}
+
+/// `3/10 indexing files`, `3 indexing files`, or `3/10`.
+pub fn progressText(buf: []u8, params: std.json.ObjectMap) []const u8 {
+ const done = number(params.get("progress")) orelse return "";
+ const message = if (params.get("message")) |m| (if (m == .string) m.string else "") else "";
+ const msg = message[0..@min(message.len, 160)];
+ if (number(params.get("total"))) |total|
+ return std.fmt.bufPrint(buf, "{d}/{d}{s}{s}", .{ done, total, if (msg.len > 0) " " else "", msg }) catch "";
+ return std.fmt.bufPrint(buf, "{d}{s}{s}", .{ done, if (msg.len > 0) " " else "", msg }) catch "";
+}
+
+/// Tag a built JSON-RPC request line with `_meta.progressToken` = its id so
+/// the server may report progress. Only for `tools/call`; every other request
+/// keeps its exact bytes.
+pub fn withProgressToken(a: Allocator, line: []const u8, id: i64) ![]const u8 {
+ const key = "\"params\":{";
+ const at = std.mem.indexOf(u8, line, key) orelse return line;
+ const after = at + key.len;
+ const rest = line[after..];
+ if (std.mem.startsWith(u8, rest, "\"_meta\":{"))
+ return std.fmt.allocPrint(a, "{s}\"_meta\":{{\"progressToken\":{d},{s}", .{ line[0..after], id, rest["\"_meta\":{".len..] });
+ const sep: []const u8 = if (std.mem.startsWith(u8, rest, "}")) "" else ",";
+ return std.fmt.allocPrint(a, "{s}\"_meta\":{{\"progressToken\":{d}}}{s}{s}", .{ line[0..after], id, sep, rest });
+}
+
+/// `notifications/cancelled` for request `id` (one line, no trailing newline).
+pub fn cancelledLine(a: Allocator, id: i64) ![]const u8 {
+ return std.fmt.allocPrint(a,
+ \\{{"jsonrpc":"2.0","method":"notifications/cancelled","params":{{"requestId":{d},"reason":"cancelled by the user"}}}}
+ , .{id});
+}
+
+const testing = std.testing;
+
+test "observe marks the catalog stale and reports progress" {
+ var sink: Sink = .{ .server = "demo" };
+ try testing.expectEqual(Kind.tools_changed, observe(&sink, testing.io,
+ \\{"jsonrpc":"2.0","method":"notifications/tools/list_changed","params":{}}
+ ));
+ try testing.expect(sink.tools_stale.load(.acquire));
+ try testing.expectEqual(Kind.progress, observe(&sink, testing.io,
+ \\{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":4,"progress":3,"total":10,"message":"indexing"}}
+ ));
+ try testing.expectEqual(Kind.none, observe(&sink, testing.io,
+ \\{"jsonrpc":"2.0","id":9,"method":"roots/list"}
+ ));
+ try testing.expectEqual(Kind.none, observe(&sink, testing.io, "not json"));
+}
+
+test "progressText formats with and without a total" {
+ var buf: [256]u8 = undefined;
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const p1 = try std.json.parseFromSliceLeaky(Value, a, "{\"progress\":3,\"total\":10,\"message\":\"indexing\"}", .{});
+ try testing.expectEqualStrings("3/10 indexing", progressText(&buf, p1.object));
+ const p2 = try std.json.parseFromSliceLeaky(Value, a, "{\"progress\":7}", .{});
+ try testing.expectEqualStrings("7", progressText(&buf, p2.object));
+}
+
+test "withProgressToken merges into an existing _meta or adds one" {
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const legacy = try withProgressToken(a, "{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"t\",\"arguments\":{}}}", 5);
+ const lv = try std.json.parseFromSliceLeaky(Value, a, legacy, .{});
+ try testing.expectEqual(@as(i64, 5), lv.object.get("params").?.object.get("_meta").?.object.get("progressToken").?.integer);
+ try testing.expectEqualStrings("t", lv.object.get("params").?.object.get("name").?.string);
+ const modern = try withProgressToken(a, "{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"tools/call\",\"params\":{\"_meta\":{\"io.modelcontextprotocol/protocolVersion\":\"2026-07-28\"},\"name\":\"t\"}}", 6);
+ const mv = try std.json.parseFromSliceLeaky(Value, a, modern, .{});
+ const meta = mv.object.get("params").?.object.get("_meta").?.object;
+ try testing.expectEqual(@as(i64, 6), meta.get("progressToken").?.integer);
+ try testing.expect(meta.get("io.modelcontextprotocol/protocolVersion") != null);
+ const empty = try withProgressToken(a, "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/call\",\"params\":{}}", 7);
+ _ = try std.json.parseFromSliceLeaky(Value, a, empty, .{});
+}
+
+test "sink remembers the last SSE event id" {
+ var sink: Sink = .{};
+ try testing.expect(sink.lastEventId() == null);
+ sink.noteEventId("evt-42");
+ try testing.expectEqualStrings("evt-42", sink.lastEventId().?);
+ sink.clearEventId();
+ try testing.expect(sink.lastEventId() == null);
+}
diff --git a/src/mcp_pages.zig b/src/mcp_pages.zig
new file mode 100644
index 00000000..30d95914
--- /dev/null
+++ b/src/mcp_pages.zig
@@ -0,0 +1,135 @@
+//! Complete, current MCP tool catalogs.
+//!
+//! - `tools/list` is paginated: a server may return `nextCursor` and expect
+//! the client to ask again. graff read only the first page, so a large
+//! server's later tools never reached the model. `complete` follows the
+//! cursor (bounded) and merges every page.
+//! - A server can change its tools mid-session and say so with
+//! `notifications/tools/list_changed` (mcp_notify marks it stale). A
+//! 2026-07-28 stdio server only sends that after `subscriptions/listen`,
+//! which `listen` requests at connect. `refreshStale` re-lists each stale
+//! server before the next model request so the catalog is not frozen at
+//! connect time.
+
+const std = @import("std");
+const Io = std.Io;
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+const mcp = @import("mcp.zig");
+const mcp_rpc = @import("mcp_rpc.zig");
+const mcp_protocol = @import("mcp_protocol.zig");
+const mcp_stdio = @import("mcp_stdio.zig");
+const Server = mcp_rpc.Server;
+const Tool = mcp.Tool;
+
+pub const max_pages = 32;
+
+pub const Listed = struct { result: Value, tools: Value };
+
+fn nextCursor(o: std.json.ObjectMap) ?[]const u8 {
+ const c = o.get("nextCursor") orelse return null;
+ return if (c == .string and c.string.len > 0) c.string else null;
+}
+
+/// `first` is the first `tools/list` result. Follows `nextCursor` and
+/// returns one result whose `tools` holds every page. A failed later page
+/// ends the listing with what was already read.
+pub fn complete(server: *Server, a: Allocator, io: ?Io, first: Value) !Listed {
+ if (first != .object) return error.BadMcpResponse;
+ const tv = first.object.get("tools") orelse return error.BadMcpResponse;
+ if (tv != .array) return error.BadMcpResponse;
+ var cursor = nextCursor(first.object) orelse return .{ .result = first, .tools = tv };
+ var all = std.json.Array.init(a);
+ try all.appendSlice(tv.array.items);
+ var pages: usize = 1;
+ while (pages < max_pages) : (pages += 1) {
+ const params = try std.json.Stringify.valueAlloc(a, .{ .cursor = cursor }, .{});
+ const resp = mcp_rpc.handshakeRequest(server, a, io, params, "tools/list") catch break;
+ if (resp != .object) break;
+ const r = resp.object.get("result") orelse break;
+ if (r != .object) break;
+ const page = r.object.get("tools") orelse break;
+ if (page != .array) break;
+ try all.appendSlice(page.array.items);
+ const next = nextCursor(r.object) orelse break;
+ if (std.mem.eql(u8, next, cursor)) break; // a server repeating itself
+ cursor = next;
+ }
+ var merged = try first.object.clone(a);
+ _ = merged.orderedRemove("nextCursor");
+ try merged.put(a, "tools", .{ .array = all });
+ return .{ .result = .{ .object = merged }, .tools = .{ .array = all } };
+}
+
+/// The registry's tool records for one server's `tools` array.
+pub fn appendTools(a: Allocator, tools: *std.ArrayList(Tool), server_index: usize, server: *const Server, tools_v: Value) !void {
+ for (tools_v.array.items) |t| {
+ if (t != .object) continue;
+ if (!@import("mcp_apps.zig").modelVisible(t)) continue;
+ const name_v = t.object.get("name") orelse continue;
+ if (name_v != .string) continue;
+ const orig = try a.dupe(u8, name_v.string);
+ const qualified = try @import("mcp_names.zig").qualify(a, server.name, orig);
+ // Prefer description; fall back to the 2025-06-18+ human-readable
+ // title so a metadata-only tool isn't blank to the model.
+ const desc = if (t.object.get("description")) |d| (if (d == .string) d.string else "") else if (t.object.get("title")) |ti| (if (ti == .string) ti.string else "") else "";
+ var schema = t.object.get("inputSchema") orelse Value{ .object = .empty };
+ try mcp_protocol.rewriteOneOf(a, &schema);
+ // ...then lower any TOP-LEVEL combinator: Anthropic rejects the
+ // whole request over one, so a single server advertising it would
+ // break every turn (codedbpro's `replace`, "path or paths").
+ try mcp_protocol.flattenTopLevel(a, &schema);
+ try tools.append(a, .{
+ .server_index = server_index,
+ .server_name = server.name,
+ .original_name = orig,
+ .qualified_name = qualified,
+ .description = try a.dupe(u8, desc),
+ .input_schema = schema,
+ .ui_resource_uri = if (@import("mcp_apps.zig").resourceUri(t)) |uri| try a.dupe(u8, uri) else null,
+ });
+ }
+}
+
+/// Ask a 2026-07-28 stdio server for `notifications/tools/list_changed`.
+/// Fire and forget: the acknowledgement and later notifications are read
+/// (and observed) by the next request's wait, and the id never matches a
+/// real request. A server without subscriptions answers with an error that
+/// is skipped the same way.
+pub fn listen(server: *Server, a: Allocator) void {
+ if (server.era != .modern or server.transport != .stdio) return;
+ const id = server.next_id;
+ server.next_id += 1;
+ const line = mcp_protocol.buildRequest(a, id, "subscriptions/listen", "{\"notifications\":{\"toolsListChanged\":true}}", true) catch return;
+ mcp_stdio.writeRequest(&server.transport.stdio.stdin_writer.interface, line) catch {};
+}
+
+/// Before each model request: merge finished deferred handshakes, then
+/// re-list servers whose tools changed. True when the catalog must rebuild.
+pub fn beforeRequest(reg: *mcp.Registry) bool {
+ const joined = @import("mcp_boot.zig").joinBeforeRequest(reg);
+ const refreshed = refreshStale(reg);
+ return joined or refreshed;
+}
+
+/// Re-list every server that announced a tool change. True when the
+/// registry's tools changed, so the caller rebuilds the model's catalog.
+pub fn refreshStale(reg: *mcp.Registry) bool {
+ reg.mutex.lockUncancelable(reg.io);
+ defer reg.mutex.unlock(reg.io);
+ var changed = false;
+ for (reg.servers, 0..) |server, i| {
+ if (!server.notes.tools_stale.swap(false, .acq_rel)) continue;
+ const a = reg.arena();
+ const resp = mcp_rpc.handshakeRequest(server, a, reg.io, "{}", "tools/list") catch continue;
+ if (resp != .object) continue;
+ const first = resp.object.get("result") orelse continue;
+ const listed = complete(server, a, reg.io, first) catch continue;
+ var tools: std.ArrayList(Tool) = .empty;
+ for (reg.tools) |t| if (t.server_index != i) tools.append(a, t) catch return changed;
+ appendTools(a, &tools, i, server, listed.tools) catch continue;
+ reg.tools = tools.items;
+ changed = true;
+ }
+ return changed;
+}
diff --git a/src/mcp_rpc.zig b/src/mcp_rpc.zig
index 4c0c187f..6e47a636 100644
--- a/src/mcp_rpc.zig
+++ b/src/mcp_rpc.zig
@@ -14,6 +14,8 @@ const mcp_http = @import("mcp_http.zig");
const mcp_protocol = @import("mcp_protocol.zig");
const mcp_stdio = @import("mcp_stdio.zig");
const mcp_teardown = @import("mcp_teardown.zig");
+const mcp_notify = @import("mcp_notify.zig");
+const mcp_wait = @import("mcp_wait.zig");
const legacy_protocol = mcp_protocol.legacy_protocol;
const modern_protocol = mcp_protocol.modern_protocol;
@@ -53,8 +55,16 @@ pub const Server = struct {
/// Borrowed `tools/call` JSON while `request` is in flight; used to accept
/// read-only Computer Use `get_app_state` elicitation (#768).
elicit_source: []const u8 = "",
+ /// Notifications seen while waiting: stale catalog, SSE resume point.
+ notes: mcp_notify.Sink = .{},
};
+/// Point the notification sink at this server (after `transport` is set).
+pub fn bindNotes(server: *Server) void {
+ server.notes.server = server.name;
+ if (server.transport == .http) server.transport.http.notes = &server.notes;
+}
+
pub fn deinitServer(server: *Server, io: Io, budget: mcp_teardown.Budget) void {
finishInitialized(server);
switch (server.transport) {
@@ -139,7 +149,7 @@ fn stdioRequestBounded(server: *Server, a: Allocator, io: Io, params: []const u8
/// A handshake round trip, bounded when the caller supplied an Io and the
/// transport is stdio. HTTP is already bounded by the client's own timeouts.
-fn handshakeRequest(server: *Server, a: Allocator, bound_io: ?Io, params: []const u8, method: []const u8) !Value {
+pub fn handshakeRequest(server: *Server, a: Allocator, bound_io: ?Io, params: []const u8, method: []const u8) !Value {
if (bound_io) |io| if (server.transport == .stdio) return stdioRequestBounded(server, a, io, params, method);
return request(server, a, params, method, null);
}
@@ -181,27 +191,33 @@ pub fn request(server: *Server, response_alloc: Allocator, params: []const u8, m
const id = server.next_id;
server.next_id += 1;
const modern = server.era == .modern;
- const body = try mcp_protocol.buildRequest(response_alloc, id, method, params, modern);
+ const built = try mcp_protocol.buildRequest(response_alloc, id, method, params, modern);
+ // A tool call carries a progress token so the server may report progress.
+ const body = if (std.mem.eql(u8, method, "tools/call")) try mcp_notify.withProgressToken(response_alloc, built, id) else built;
switch (server.transport) {
.stdio => |*stdio| {
try mcp_stdio.writeRequest(&stdio.stdin_writer.interface, body);
-
- const r = &stdio.stdout_reader.interface;
- while (true) {
- const line = try mcp_stdio.takeLine(r);
- if (try mcp_elicitation.replyStdio(&stdio.stdin_writer.interface, response_alloc, line, server.elicit_source)) continue;
- if (mcp_http.matchingResponse(response_alloc, line, id)) |parsed| return parsed;
- }
+ return mcp_wait.awaitStdio(.{
+ .writer = &stdio.stdin_writer.interface,
+ .reader = &stdio.stdout_reader.interface,
+ .sink = &server.notes,
+ .elicit_source = server.elicit_source,
+ }, stdio.stdout_reader.io, response_alloc, id);
},
.http => |*http| {
const protocol_version = if (modern) modern_protocol else if (std.mem.eql(u8, method, "initialize")) legacy_protocol else server.protocol_version;
- const response_body = (try mcp_http.post(http, body, .{
+ const response_body = (mcp_http.post(http, body, .{
.protocol_version = protocol_version,
.method = method,
.name = name,
.modern = modern,
- }, id)) orelse return error.BadMcpResponse;
+ }, id) catch |err| {
+ // A modern request is cancelled by dropping it; a legacy
+ // session is told which request to stop.
+ if (err == error.McpCancelled and !modern) mcp_http.notifyCancelled(http, server.protocol_version, id);
+ return err;
+ }) orelse return error.BadMcpResponse;
defer http.client.allocator.free(response_body);
return mcp_http.parseHttpResponse(response_alloc, response_body, id) orelse error.BadMcpResponse;
},
diff --git a/src/mcp_wait.zig b/src/mcp_wait.zig
new file mode 100644
index 00000000..72e94bcc
--- /dev/null
+++ b/src/mcp_wait.zig
@@ -0,0 +1,134 @@
+//! Waiting for one MCP reply without leaving the user stuck.
+//!
+//! A `tools/call` over stdio used to block on the pipe until the server
+//! answered: Esc set the turn's cancel flag but nothing looked at it, so a
+//! slow or hung server held the turn, and the server kept working on a
+//! request nobody wanted. The read now races a watcher on the cancel flag.
+//! On cancel graff stops reading, tells the server with
+//! `notifications/cancelled`, and returns `error.McpCancelled`. A late reply
+//! to that id is skipped by the next request's id match.
+
+const std = @import("std");
+const Io = std.Io;
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+const mcp_elicitation = @import("mcp_elicitation.zig");
+const mcp_http = @import("mcp_http.zig");
+const mcp_notify = @import("mcp_notify.zig");
+const mcp_stdio = @import("mcp_stdio.zig");
+
+/// Whether the user asked to stop the current turn. The engine points this
+/// at its cancel flag; tests replace it.
+pub var cancel_requested: *const fn () bool = escPressed;
+
+fn escPressed() bool {
+ return @import("agent.zig").Agent.esc_cancel.load(.acquire);
+}
+
+const poll_ms = 50;
+
+/// Returns when cancel is requested or `done` is set.
+pub fn watchCancel(io: Io, done: *std.atomic.Value(bool)) void {
+ while (!done.load(.acquire)) {
+ if (cancel_requested()) return;
+ io.sleep(.fromMilliseconds(poll_ms), .awake) catch return;
+ }
+ // `done` wins: park until the select cancels this task.
+ while (true) io.sleep(.fromSeconds(3600), .awake) catch return;
+}
+
+pub const Stdio = struct {
+ writer: *Io.Writer,
+ reader: *Io.Reader,
+ sink: *mcp_notify.Sink,
+ elicit_source: []const u8,
+};
+
+fn readReply(s: Stdio, io: Io, a: Allocator, id: i64) !Value {
+ while (true) {
+ const line = try mcp_stdio.takeLine(s.reader);
+ if (try mcp_elicitation.replyStdio(s.writer, a, line, s.elicit_source)) continue;
+ if (mcp_http.matchingResponse(a, line, id)) |parsed| return parsed;
+ _ = mcp_notify.observe(s.sink, io, line);
+ }
+}
+
+const Done = union(enum) {
+ replied: anyerror!Value,
+ cancelled,
+};
+
+/// Await the reply to `id` on a stdio server, honoring cancel.
+pub fn awaitStdio(s: Stdio, io: Io, a: Allocator, id: i64) !Value {
+ if (cancel_requested()) return cancelStdio(s, a, id);
+ var done = std.atomic.Value(bool).init(false);
+ var buf: [2]Done = undefined;
+ var select: Io.Select(Done) = .init(io, &buf);
+ select.concurrent(.replied, readReply, .{ s, io, a, id }) catch return readReply(s, io, a, id);
+ select.concurrent(.cancelled, watchCancel, .{ io, &done }) catch {
+ const only = select.await() catch return error.McpCancelled;
+ select.cancelDiscard();
+ return only.replied;
+ };
+ const first = select.await() catch return error.McpCancelled;
+ done.store(true, .release);
+ switch (first) {
+ .replied => |result| {
+ select.cancelDiscard();
+ return result;
+ },
+ .cancelled => {
+ _ = select.cancel(); // blocks until the read task has stopped
+ return cancelStdio(s, a, id);
+ },
+ }
+}
+
+fn cancelStdio(s: Stdio, a: Allocator, id: i64) error{McpCancelled} {
+ const line = mcp_notify.cancelledLine(a, id) catch return error.McpCancelled;
+ mcp_stdio.writeRequest(s.writer, line) catch {};
+ return error.McpCancelled;
+}
+
+const testing = std.testing;
+
+var test_cancel = std.atomic.Value(bool).init(false);
+fn testCancelled() bool {
+ return test_cancel.load(.acquire);
+}
+
+test "awaitStdio: notifications are observed and the matching reply returns" {
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ var in: Io.Reader = .fixed(
+ \\{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":3,"progress":1}}
+ \\{"jsonrpc":"2.0","method":"notifications/tools/list_changed"}
+ \\{"jsonrpc":"2.0","id":2,"result":{"stale":true}}
+ \\{"jsonrpc":"2.0","id":3,"result":{"ok":true}}
+ \\
+ );
+ var out_buf: [512]u8 = undefined;
+ var out: Io.Writer = .fixed(&out_buf);
+ var sink: mcp_notify.Sink = .{ .server = "demo" };
+ const got = try readReply(.{ .writer = &out, .reader = &in, .sink = &sink, .elicit_source = "" }, testing.io, a, 3);
+ try testing.expect(got.object.get("result").?.object.get("ok").?.bool);
+ try testing.expect(sink.tools_stale.load(.acquire));
+}
+
+test "awaitStdio: a cancel already requested sends notifications/cancelled" {
+ const saved = cancel_requested;
+ defer cancel_requested = saved;
+ cancel_requested = testCancelled;
+ test_cancel.store(true, .release);
+ defer test_cancel.store(false, .release);
+ var arena = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena.deinit();
+ var in: Io.Reader = .fixed("");
+ var out_buf: [512]u8 = undefined;
+ var out: Io.Writer = .fixed(&out_buf);
+ var sink: mcp_notify.Sink = .{};
+ try testing.expectError(error.McpCancelled, awaitStdio(.{ .writer = &out, .reader = &in, .sink = &sink, .elicit_source = "" }, testing.io, arena.allocator(), 11));
+ try testing.expect(std.mem.indexOf(u8, out.buffered(), "\"notifications/cancelled\"") != null);
+ try testing.expect(std.mem.indexOf(u8, out.buffered(), "\"requestId\":11") != null);
+}