Skip to content

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

Python
23.8 KB
Raw Blame
//! Minimal MCP (Model Context Protocol) client over stdio and Streamable HTTP.
//!
//! A config entry — from the workspace `.mcp.json`, from the user-level
//! `~/.codegraff/mcp.json`, or from the two merged (mcp_config.zig) — may
//! contain either `command`/`args` (a child process using newline-delimited
//! JSON-RPC on stdio) or `url` (JSON-RPC POSTs using MCP's Streamable HTTP
//! transport). Both run the initialize -> initialized -> tools/list handshake
//! and expose discovered tools to the agent.
//!
//! Concurrency: tool calls arrive from agent pool threads, but transport state
//! (stdio pipes, HTTP session IDs) is sequential, so every request/response
//! round trip holds `mutex`. MCP calls are rare relative to LLM calls, so
//! registry-wide serialization is fine.

const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const Allocator = std.mem.Allocator;
const mcp_config = @import("mcp_config.zig"); // #345: .mcp.json merged with the user-level ~/.codegraff/mcp.json
const mcp_boot = @import("mcp_boot.zig"); // parallel connect fan-out; Registry.init re-exports it
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 shutdown_trace = @import("shutdown_trace.zig"); // #364: teardown phase stamps
const mcp_rpc = @import("mcp_rpc.zig");
const mcp_cache = @import("mcp_cache.zig");
const util = @import("util.zig");
const vision = @import("vision.zig"); // #249: MCP image results become staged vision blocks

const rewriteOneOf = mcp_protocol.rewriteOneOf;
const HttpTransport = mcp_http.HttpTransport;
pub const validRemoteUrl = mcp_http.validRemoteUrl;
const Server = mcp_rpc.Server;
const Transport = mcp_rpc.Transport;
const deinitServer = mcp_rpc.deinitServer;

pub const Tool = struct {
    server_name: ?[]const u8 = null, // raw configuration identity; null for legacy fixtures
    ui_resource_uri: ?[]const u8 = null,
    server_index: usize,
    original_name: []const u8, // name as the server knows it
    qualified_name: []const u8, // "mcp__<server>__<tool>" shown to the model
    description: []const u8,
    input_schema: Value, // arena-owned parsed JSON Schema
    read_only: bool = false, // the server's `readOnlyHint` (ADR 0228)
    pub fn serverName(tool: Tool) []const u8 {
        return tool.server_name orelse @import("mcp_names.zig").serverOf(tool.qualified_name);
    }
};

pub const Registry = struct {
    last_app_path: ?[]const u8 = null,
    gpa: Allocator,
    io: Io,
    home: []const u8,
    arena_state: std.heap.ArenaAllocator,
    mutex: Io.Mutex = .init,
    servers: []*Server = &.{},
    tools: []Tool = &.{},
    /// Tools withdrawn after their connection closed (#1523, mcp_call.zig).
    withdrawn: []const @import("mcp_call.zig").Withdrawn = &.{},
    /// Transport failure withdrew tools; owner thread rebuilds its next catalog.
    catalog_dirty: std.atomic.Value(bool) = .init(false),
    /// Startup connection/failure lines are developer diagnostics, not normal REPL output.
    show_diagnostics: bool = false,
    /// The stdio spec's backward-compatibility SHOULD: a dual-era client
    /// probes `server/discover` before assuming legacy. ON by default;
    /// `GRAFF_MCP_PROBE=0` opts out.
    /// The cost was measured against the stdio server this repo actually
    /// ships with, timing to the "connected" line rather than to process
    /// exit: probe on and off are within run-to-run noise, because a legacy
    /// server either answers the unknown method with an error at once or
    /// closes stdout and is respawned. Only a server that SILENTLY IGNORES it
    /// pays the timeout above, and it pays it once per process.
    /// Only `Registry.init` reads the environment, so a `Registry.empty*`-
    /// constructed registry keeps this field default (true) and cannot be
    /// opted out of the probe by `GRAFF_MCP_PROBE=0` — the env var reaches
    /// only the config-file path.
    stdio_probe: bool = true,
    /// Cached stdio servers start on first use (mcp_lazy.zig). Only
    /// `Registry.init` reads `GRAFF_MCP_EAGER`; verification paths set false.
    lazy_stdio: bool = true,
    /// An image an MCP tool returned, waiting for the next turn to collect it
    /// (#249). Written under `mutex` by `call`, drained by
    /// `vision.mcpImageHandoff` — the registry cannot reach the agent itself.
    pending_image: ?vision.PendingImage = null,
    /// Whether the active model accepts image blocks. The registry cannot see
    /// the provider, so the same per-turn handoff refreshes it; false until it
    /// does, so a result explains the drop rather than promising an attachment.
    vision_capable: bool = false,
    /// Resolved user-level MCP config (`~/.codegraff/mcp.json` or the
    /// `GRAFF_MCP_CONFIG` override), borrowed from the caller. Null when there
    /// is no global config. Kept on the registry because `/mcp trust` re-reads
    /// it mid-session — including on the consent-declined path, where the
    /// registry came from `empty*` and `init` never ran, so session_start sets
    /// this field either way.
    global_config_path: ?[]const u8 = null,
    /// True when `global_config_path` came from `GRAFF_MCP_CONFIG`. `/mcp trust`
    /// re-reads through the same wholesale-off rule `init` used (#549).
    global_is_override: bool = false,
    /// Per-server arenas from mcp_boot's parallel connect fan-out (the
    /// registry arena is not thread-safe, so each task allocated its own).
    /// Freed in deinit AFTER the transports referencing them are torn down.
    task_arenas: []std.heap.ArenaAllocator = &.{},
    /// Unjoined startServer futures from a deferred --yolo boot.
    pending_starts: []mcp_boot.PendingStart = &.{},
    /// Names paired with `pending_starts` so companion auto-connect can skip
    /// a second spawn of a server the deferred fan-out already queued.
    pending_names: []const []const u8 = &.{},
    /// First model call already declined to wait on `pending_starts` (ADR 0035).
    first_request_join_skipped: bool = false,
    /// Background connects to report on the next root request (ADR 0230).
    connect_notices: @import("mcp_connect_notice.zig").Joined = .{},

    pub fn arena(self: *Registry) Allocator {
        return self.arena_state.allocator();
    }

    /// Load the workspace `.mcp.json` merged with the user-level global config
    /// at `global_path` (see mcp_config.zig; project entries win on a name
    /// clash), where an entry holds either `command`/`args`/`env` or a
    /// Streamable HTTP `url`; handshake each server and collect their tools.
    /// Returns null (no error) when NEITHER file exists — MCP is optional.
    /// `global_path` is borrowed, not copied: it must outlive the registry,
    /// which re-reads it on `/mcp trust`.
    /// The fan-out lives in mcp_boot.zig (600-line ceiling): servers connect
    /// CONCURRENTLY and merge in config order, so startup pays the slowest
    /// handshake, not the sum of them.
    pub const init = mcp_boot.init;

    /// An empty registry (no config file present), so the harness can still
    /// accept servers added at runtime via `addServer`.
    pub fn empty(gpa: Allocator, io: Io) Registry {
        return emptyWithOAuthHome(gpa, io, "");
    }

    /// An empty registry that can load OAuth tokens rooted under `home`.
    pub fn emptyWithOAuthHome(gpa: Allocator, io: Io, home: []const u8) Registry {
        return .{ .gpa = gpa, .io = io, .home = home, .arena_state = std.heap.ArenaAllocator.init(gpa) };
    }

    /// Spawn + handshake a server at runtime and append its tools. Returns the
    /// number of tools it exposed. The servers/tools slices are rebuilt (arena);
    /// callers must re-render their tool list afterward. Run between turns only
    /// (no tool calls in flight).
    pub fn addServer(reg: *Registry, name: []const u8, command: []const u8, args: []const []const u8) !usize {
        reg.mutex.lockUncancelable(reg.io);
        defer reg.mutex.unlock(reg.io);
        for (reg.servers) |server| if (std.mem.eql(u8, server.name, name)) return error.McpServerAlreadyConnected;
        const a = reg.arena();
        var servers: std.ArrayList(*Server) = .empty;
        try servers.appendSlice(a, reg.servers);
        var tools: std.ArrayList(Tool) = .empty;
        try tools.appendSlice(a, reg.tools);
        const before = tools.items.len;

        var cfg: std.json.ObjectMap = .empty;
        try cfg.put(a, "command", .{ .string = try a.dupe(u8, command) });
        var argv = std.json.Array.init(a);
        for (args) |arg| try argv.append(.{ .string = try a.dupe(u8, arg) });
        try cfg.put(a, "args", .{ .array = argv });

        try reg.startServer(a, &servers, &tools, try a.dupe(u8, name), cfg);
        reg.servers = try a.dupe(*Server, servers.items);
        reg.tools = try a.dupe(Tool, tools.items);
        return tools.items.len - before;
    }

    /// Connect a Streamable HTTP server at runtime. `headers` are copied into
    /// registry storage and sent on every request (for example Authorization).
    pub fn addRemoteServer(reg: *Registry, name: []const u8, url: []const u8, headers: []const std.http.Header) !usize {
        reg.mutex.lockUncancelable(reg.io);
        defer reg.mutex.unlock(reg.io);
        for (reg.servers) |server| if (std.mem.eql(u8, server.name, name)) return error.McpServerAlreadyConnected;
        const a = reg.arena();
        var servers: std.ArrayList(*Server) = .empty;
        try servers.appendSlice(a, reg.servers);
        var tools: std.ArrayList(Tool) = .empty;
        try tools.appendSlice(a, reg.tools);
        const before = tools.items.len;

        var cfg: std.json.ObjectMap = .empty;
        try cfg.put(a, "url", .{ .string = try a.dupe(u8, url) });
        if (headers.len > 0) {
            var header_obj: std.json.ObjectMap = .empty;
            for (headers) |header| try header_obj.put(a, try a.dupe(u8, header.name), .{ .string = try a.dupe(u8, header.value) });
            try cfg.put(a, "headers", .{ .object = header_obj });
        }

        try reg.startServer(a, &servers, &tools, try a.dupe(u8, name), cfg);
        reg.servers = try a.dupe(*Server, servers.items);
        reg.tools = try a.dupe(Tool, tools.items);
        return tools.items.len - before;
    }

    /// Connect any configured server not already running — the in-session
    /// equivalent of having started with `--yolo`, so a user who declined the
    /// startup consent prompt can opt in later without a restart. Reads the
    /// same merged project + global set `init` does, so a `~/.codegraff/mcp.json`
    /// entry is trusted here too. Replays the `init` connect path (so
    /// per-server `env` is preserved, which `addServer` drops), skipping
    /// servers already in the registry by name (idempotent: won't double-spawn
    /// an auto-activated muonry). Returns the number of servers newly
    /// connected. Caller must re-render its tool list. Run between turns only
    /// (no tool calls in flight).
    pub fn trustWorkspace(reg: *Registry, config_path: []const u8) !usize {
        reg.mutex.lockUncancelable(reg.io);
        defer reg.mutex.unlock(reg.io);
        const a = reg.arena();
        const merged = mcp_config.load(reg.io, a, Io.Dir.cwd(), config_path, reg.global_config_path, reg.home, reg.global_is_override);

        var servers: std.ArrayList(*Server) = .empty;
        try servers.appendSlice(a, reg.servers);
        var tools: std.ArrayList(Tool) = .empty;
        try tools.appendSlice(a, reg.tools);
        const before = servers.items.len;

        const state = @import("mcp_state.zig").load(reg.io, a, reg.home);
        var it = merged.servers.iterator();
        while (it.next()) |entry| {
            const name = entry.key_ptr.*;
            if (entry.value_ptr.* != .object or state.isDisabled(name)) continue; // switched off: graff mcp disable
            if (!state.isEnabled(name) and @import("mcp_state.zig").offInConfig(entry.value_ptr.*.object)) continue; // off in its own file
            // Already connected (auto-activated muonry, or a prior /mcp trust)? skip.
            var present = false;
            for (reg.servers) |s| if (std.mem.eql(u8, s.name, name)) {
                present = true;
                break;
            };
            if (present) continue;
            reg.startServer(a, &servers, &tools, try a.dupe(u8, name), entry.value_ptr.*.object) catch |err| {
                if (reg.show_diagnostics) std.debug.print("  [mcp:{s}] failed to start: {t}\n", .{ name, err });
                @import("mcp_start.zig").note(name, err); // /mcp says why
            };
        }
        reg.servers = try a.dupe(*Server, servers.items);
        reg.tools = try a.dupe(Tool, tools.items);
        return servers.items.len - before;
    }

    /// Number of tools a given server (by index) contributed — for `/mcp`.
    pub fn toolCount(reg: *Registry, server_index: usize) usize {
        var n: usize = 0;
        for (reg.tools) |t| if (t.server_index == server_index) {
            n += 1;
        };
        return n;
    }
    /// Whether the server declared this qualified tool read-only (ADR 0228).
    pub fn declaresReadOnly(reg: *Registry, qualified: []const u8) bool {
        reg.mutex.lockUncancelable(reg.io);
        defer reg.mutex.unlock(reg.io);
        for (reg.tools) |t| if (std.mem.eql(u8, t.qualified_name, qualified)) return t.read_only;
        return false;
    }

    pub fn snapshotTools(reg: *Registry, allocator: Allocator) ![]Tool {
        reg.mutex.lockUncancelable(reg.io);
        defer reg.mutex.unlock(reg.io);
        return allocator.dupe(Tool, reg.tools);
    }
    /// Spawn a stdio child and wire up its transport. Factored out of
    /// `startServer` so the `GRAFF_MCP_PROBE` path can call it a second
    /// time: some legacy SDK servers close stdout on an unrecognized
    /// pre-`initialize` message (`server/discover`), and the only fix is a
    /// fresh process — the closed one can't be un-closed.
    pub fn spawnStdio(reg: *Registry, a: Allocator, argv: []const []const u8, env_map: ?*std.process.Environ.Map, cwd: ?[]const u8) !Transport {
        var child = try std.process.spawn(reg.io, .{
            .argv = argv,
            .stdin = .pipe,
            .stdout = .pipe,
            .stderr = .ignore,
            .environ_map = env_map,
            .cwd = if (cwd) |path| .{ .path = path } else .inherit,
        });
        errdefer mcp_stdio.stopChild(reg.io, &child);
        const in_buf = try a.alloc(u8, 64 * 1024);
        const out_buf = try a.alloc(u8, 1 << 20);
        return .{ .stdio = .{
            .child = child,
            .stdin_writer = child.stdin.?.writerStreaming(reg.io, in_buf),
            .stdout_reader = child.stdout.?.readerStreaming(reg.io, out_buf),
        } };
    }

    pub fn startServer(
        reg: *Registry,
        a: Allocator,
        servers: *std.ArrayList(*Server),
        tools: *std.ArrayList(Tool),
        name: []const u8,
        cfg: std.json.ObjectMap,
    ) !void {
        const command_v = cfg.get("command");
        const url_v = cfg.get("url");
        if ((command_v == null) == (url_v == null)) return error.BadMcpConfig;
        const mcp_lazy = @import("mcp_lazy.zig");
        if (reg.lazy_stdio) if (try mcp_lazy.dormantFromCache(reg.io, a, reg.home, name, cfg)) |d| {
            const tools_before = tools.items.len;
            errdefer tools.shrinkRetainingCapacity(tools_before);
            try @import("mcp_pages.zig").appendTools(a, tools, servers.items.len, d.server, d.tools);
            try servers.append(a, d.server);
            if (reg.show_diagnostics) std.debug.print("  [mcp:{s}] ready — {d} tool(s), starts on first use\n", .{ name, d.tools.array.items.len });
            return;
        };

        const server = try a.create(Server);
        // Hoisted out of the `else` branch below (rather than local to it)
        // so the GRAFF_MCP_PROBE respawn path -- which runs after this
        // if/else, once the era-detection dispatch below finds a closed
        // stdio child -- can spawn a fresh process with the same argv/env.
        var stdio_argv: std.ArrayList([]const u8) = .empty;
        var stdio_env_map: ?*std.process.Environ.Map = null;
        var stdio_cwd: ?[]const u8 = null;
        // Environ.Map owns its key/value copies with reg.gpa even though the
        // map struct itself is arena-backed. Spawn consumes the environment;
        // keep it through the possible probe respawn below, then release it.
        defer if (stdio_env_map) |map| map.deinit();
        if (url_v) |url| {
            if (url != .string) return error.BadMcpConfig;
            if (!validRemoteUrl(url.string)) return error.BadMcpUrl;

            var headers: std.ArrayList(std.http.Header) = .empty;
            var has_authorization = false;
            if (cfg.get("headers")) |headers_v| {
                if (headers_v != .object) return error.BadMcpConfig;
                var header_it = headers_v.object.iterator();
                while (header_it.next()) |entry| {
                    if (entry.value_ptr.* != .string) return error.BadMcpConfig;
                    if (std.ascii.eqlIgnoreCase(entry.key_ptr.*, "authorization")) has_authorization = true;
                    try headers.append(a, .{
                        .name = try a.dupe(u8, entry.key_ptr.*),
                        .value = try a.dupe(u8, entry.value_ptr.*.string),
                    });
                }
            }
            server.* = .{
                .name = name,
                .transport = .{ .http = .{
                    .url = try a.dupe(u8, url.string),
                    .client = .{ .allocator = reg.gpa, .io = reg.io },
                    .headers = try a.dupe(std.http.Header, headers.items),
                    .oauth_home = if (!has_authorization and reg.home.len != 0) try a.dupe(u8, reg.home) else null,
                } },
            };
        } else {
            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;
            server.* = .{ .name = name, .transport = try spawnStdio(reg, a, stdio_argv.items, stdio_env_map, stdio_cwd) };
        }

        var registry_owns_server = false;
        errdefer if (!registry_owns_server) deinitServer(server, reg.io, .init(reg.io, mcp_teardown.teardown_grace)); // fresh window: not the exit path (#305)
        const server_index = servers.items.len;
        const tools_before = tools.items.len;
        errdefer tools.shrinkRetainingCapacity(tools_before);

        // A fresh process can reuse last session's tools/list (MCP 2026-07-28
        // CacheableResult). HTTP hits skip the network; call() initializes a
        // 2025-11-25 session on first tools/call. Live stdio still handshakes.
        const cache_key = mcp_cache.keyFor(a, cfg);
        const now_ms = util.unixMs(reg.io);
        const looked = mcp_cache.lookup(reg.io, a, reg.home, cache_key, now_ms);
        const era_hint = looked.era;
        var listed_result: ?Value = null;
        const tools_v: Value = if (looked.hit) |hit| blk: {
            server.era = hit.era;
            server.protocol_version = try a.dupe(u8, hit.protocol_version);
            // HTTP: advertise the cached catalog and let call() initialize.
            // stdio legacy: the child is already live, so complete the session.
            if (mcp_cache.handshakeOnCacheHit(hit.era, server.transport == .http)) {
                try mcp_rpc.initializeServer(server, a, a, reg.io);
            } else {
                server.initialized = hit.era == .modern;
            }
            break :blk hit.tools;
        } else blk: {
            const listed = switch (server.transport) {
                .dormant => unreachable, // only built above, from a cache hit
                .http => try mcp_rpc.connectHttp(server, a, a, era_hint),
                .stdio => stdio_listed: {
                    if (!reg.stdio_probe) break :stdio_listed try mcp_rpc.connectStdio(server, a, a, reg.io);
                    switch (try mcp_rpc.probeStdioResilient(server, a, reg.io)) {
                        .modern => break :stdio_listed try mcp_rpc.finishModernStdio(server, a, a, reg.io),
                        .legacy => |reason| {
                            server.probe_fallback = reason;
                            break :stdio_listed try mcp_rpc.connectStdio(server, a, a, reg.io);
                        },
                        .closed => {
                            server.probe_fallback = .server_exited;
                            mcp_stdio.stopChild(reg.io, &server.transport.stdio.child);
                            server.transport = try spawnStdio(reg, a, stdio_argv.items, stdio_env_map, stdio_cwd);
                            break :stdio_listed try mcp_rpc.connectStdio(server, a, a, reg.io);
                        },
                    }
                },
            };
            const result_v = listed.object.get("result") orelse return error.BadMcpResponse;
            // 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;
        };
        try @import("mcp_pages.zig").appendTools(a, tools, server_index, server, tools_v);
        if (server.transport == .stdio) server.transport.stdio.relaunch = .{ .cfg = try mcp_lazy.cloneMap(a, cfg) }; // ADR 0270
        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);
        const probe_note = if (server.probe_fallback) |reason| reason.note() else ""; // #327: a downgrade is never silent
        if (reg.show_diagnostics) std.debug.print("  [mcp:{s}] connected (mcp {s}) — {d} tool(s){s}\n", .{ name, server.protocol_version, tools_v.array.items.len, probe_note });
    }

    /// One shared window bounds the whole teardown: the loop is sequential, so
    /// a per-server grace cost N graces for N stalled peers (#305).
    /// Registry teardown for the EXIT path. If any transport was abandoned, a
    /// detached thread still holds this Io, so leave immediately rather than let
    /// a later defer tear that Io down underneath it (#325). Kept separate from
    /// `deinit` because tests and mid-session callers must never exit.
    pub fn deinitAtExit(reg: *Registry) void {
        shutdown_trace.mark("mcp-teardown"); // #364
        reg.deinit();
        mcp_teardown.exitIfAbandoned();
    }

    pub fn deinit(reg: *Registry) void {
        _ = mcp_boot.joinPending(reg);
        const budget: mcp_teardown.Budget = .init(reg.io, mcp_teardown.teardown_grace);
        for (reg.servers) |server| deinitServer(server, reg.io, budget);
        for (reg.task_arenas) |*ta| ta.deinit();
        reg.arena_state.deinit();
    }

    pub fn isMcp(name: []const u8) bool {
        return std.mem.startsWith(u8, name, "mcp__");
    }

    /// Calls and runtime registration share one lock, including tool lookup.
    pub fn call(reg: *Registry, out_alloc: Allocator, qualified: []const u8, input: Value) !@import("mcp_call.zig").CallResult {
        reg.mutex.lockUncancelable(reg.io);
        defer reg.mutex.unlock(reg.io);
        return @import("mcp_call.zig").call(reg, out_alloc, qualified, input);
    }
};

test {
    _ = @import("mcp_restart.zig"); // ADR 0270
    _ = @import("mcp_cache.zig");
    _ = @import("mcp_boot.zig");
    _ = @import("mcp_elicitation.zig");
    _ = @import("mcp_start.zig");
    _ = @import("mcp_state.zig");
    _ = @import("mcp_status.zig");
    _ = @import("mcp_status_cli.zig");
    _ = @import("mcp_reconnect.zig");
    _ = @import("mcp_listing.zig");
    _ = @import("mcp_failures.zig");
    _ = @import("mcp_list_json.zig");
}