Skip to content

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

Python
10.4 KB
Raw Blame
//! Local (stdio) MCP servers start on first use.
//!
//! Every configured stdio server used to be spawned at session start, so a
//! chat with twenty servers ran twenty processes whether or not it ever called
//! one. When the tool catalog for a server is already cached (mcp_cache.zig,
//! keyed by command + args), the session advertises those tools from the cache
//! and keeps only the launch config: the process is spawned, and handshaken
//! for a legacy server, on the first `tools/call` that needs it. Once awake it
//! re-lists its tools to refresh the cache for later sessions.
//!
//! Processes are never shared between sessions: a stdio server holds state for
//! the agent using it (a browser, a working directory, credentials). A server
//! with no cached catalog yet starts at once so its tools can be learned; an
//! entry can opt out with `"startup": "eager"`, and `GRAFF_MCP_EAGER=1` turns
//! lazy starts off for the whole process.

const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const ObjectMap = std.json.ObjectMap;
const Allocator = std.mem.Allocator;
const mcp_rpc = @import("mcp_rpc.zig");
const mcp_cache = @import("mcp_cache.zig");
const mcp_stdio = @import("mcp_stdio.zig");
const util = @import("util.zig");

/// How a stdio entry is launched. `env` owns gpa copies of its strings: the
/// caller deinits it once the child has been spawned.
pub const Spec = struct {
    argv: []const []const u8,
    env: ?*std.process.Environ.Map = null,
    cwd: ?[]const u8 = null,
};

pub fn stdioSpec(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;
    try argv.append(a, command_v.string);
    if (cfg.get("args")) |args| {
        if (args != .array) return error.BadMcpConfig;
        for (args.array.items) |arg| {
            if (arg != .string) return error.BadMcpConfig;
            try argv.append(a, arg.string);
        }
    }
    var spec: Spec = .{ .argv = argv.items };
    // `"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;
    }
    // Optional per-server env overlaid on the parent environment. A spawn's
    // `environ_map` REPLACES the child's environment, so the overlay starts
    // from a copy of graff's own: an entry that sets one token must not lose
    // PATH and HOME (an `npx` server then cannot find `node` and exits).
    if (cfg.get("env")) |env| {
        if (env != .object) return error.BadMcpConfig;
        const m = try a.create(std.process.Environ.Map);
        m.* = if (parent_env) |p| try p.clone(gpa) else std.process.Environ.Map.init(gpa);
        errdefer m.deinit();
        var it = env.object.iterator();
        while (it.next()) |entry| {
            if (entry.value_ptr.* != .string) return error.BadMcpConfig;
            try m.put(entry.key_ptr.*, entry.value_ptr.*.string);
        }
        spec.env = m;
    }
    return spec;
}

/// graff's own environment, the base every per-server `env` overlays. Set
/// where MCP is set up (`remember`); null in unit tests.
pub var parent_env: ?*const std.process.Environ.Map = null;

pub fn remember(environ_map: anytype) void {
    const T = @TypeOf(environ_map);
    if (T == *std.process.Environ.Map or T == *const std.process.Environ.Map) parent_env = environ_map;
}

/// A stdio entry that did not ask to start with the session.
pub fn wantsLazy(cfg: ObjectMap) bool {
    if (cfg.get("command") == null) return false;
    if (cfg.get("startup")) |s| if (s == .string and std.ascii.eqlIgnoreCase(s.string, "eager")) return false;
    return true;
}

fn cloneValue(a: Allocator, v: Value) Allocator.Error!Value {
    return switch (v) {
        .string => |s| .{ .string = try a.dupe(u8, s) },
        .number_string => |s| .{ .number_string = try a.dupe(u8, s) },
        .array => |arr| blk: {
            var out = std.json.Array.init(a);
            for (arr.items) |item| try out.append(try cloneValue(a, item));
            break :blk .{ .array = out };
        },
        .object => |o| .{ .object = try cloneMap(a, o) },
        else => v,
    };
}

/// A deep copy: the config an ACP client sent lives in its request's arena.
pub fn cloneMap(a: Allocator, m: ObjectMap) Allocator.Error!ObjectMap {
    var out: ObjectMap = .empty;
    var it = m.iterator();
    while (it.next()) |e| try out.put(a, try a.dupe(u8, e.key_ptr.*), try cloneValue(a, e.value_ptr.*));
    return out;
}

/// A dormant server built from a cached catalog, or null when this entry must
/// start now (not stdio, opted out, or never listed before).
pub fn dormantFromCache(io: Io, a: Allocator, home: []const u8, name: []const u8, cfg: ObjectMap) !?struct { server: *mcp_rpc.Server, tools: Value } {
    if (!wantsLazy(cfg)) return null;
    const hit = mcp_cache.lookupAnyAge(io, a, home, mcp_cache.keyFor(a, cfg)) orelse return null;
    const server = try a.create(mcp_rpc.Server);
    server.* = .{
        .name = name,
        .transport = .{ .dormant = .{ .cfg = try cloneMap(a, cfg) } },
        .era = hit.era,
        .protocol_version = try a.dupe(u8, hit.protocol_version),
        .initialized = false,
    };
    return .{ .server = server, .tools = hit.tools };
}

/// Spawn and handshake a dormant server before its first request. On failure
/// it stays dormant, so a later call tries again.
pub fn wake(reg: anytype, server: *mcp_rpc.Server) !void {
    const cfg = server.transport.dormant.cfg;
    wakeInner(reg, server) catch |err| {
        @import("mcp_failures.zig").recordErr(reg.io, reg.gpa, reg.home, cfg, err, null); // `graff mcp status` says why
        return err;
    };
}

fn wakeInner(reg: anytype, server: *mcp_rpc.Server) !void {
    const dormant = server.transport.dormant;
    const cfg = dormant.cfg;
    const a = reg.arena();
    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);
    server.transport.stdio.relaunch = dormant;
    errdefer {
        mcp_stdio.stopChild(reg.io, &server.transport.stdio.child);
        server.transport = .{ .dormant = dormant };
        server.initialized = false;
    }
    // Same rule as a cache hit at connect: legacy needs `initialize` on the
    // live child; a modern server takes any request first.
    if (mcp_cache.handshakeOnCacheHit(server.era, false)) {
        try mcp_rpc.initializeServer(server, a, a, reg.io);
    } else {
        server.initialized = server.era == .modern;
    }
    mcp_rpc.bindNotes(server);
    @import("mcp_pages.zig").listen(server, a);
    if (reg.show_diagnostics) std.debug.print("  [mcp:{s}] started on first use\n", .{server.name});
    @import("mcp_failures.zig").clearCfg(reg.io, reg.gpa, reg.home, cfg);
    refreshCache(reg, server, cfg);
}

/// Re-list the tools of a server that just woke and store them, so the next
/// session advertises its current catalog. The live session keeps the list
/// it started with. Best effort: a failure costs nothing but freshness.
fn refreshCache(reg: anytype, server: *mcp_rpc.Server, cfg: ObjectMap) void {
    if (!server.initialized or reg.home.len == 0) return;
    var arena_state = std.heap.ArenaAllocator.init(reg.gpa);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    const listed = mcp_rpc.request(server, a, "{}", "tools/list", null) catch return;
    const result = if (listed == .object) listed.object.get("result") orelse return else return;
    mcp_cache.store(reg.io, a, reg.home, mcp_cache.keyFor(a, cfg), server.era, server.protocol_version, result, util.unixMs(reg.io));
}

test "wantsLazy: stdio entries, unless they ask to start with the session" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    const a = arena.allocator();
    const parse = struct {
        fn f(al: Allocator, s: []const u8) ObjectMap {
            return (std.json.parseFromSliceLeaky(Value, al, s, .{}) catch unreachable).object;
        }
    }.f;
    try std.testing.expect(wantsLazy(parse(a, "{\"command\":\"npx\",\"args\":[\"-y\",\"x\"]}")));
    try std.testing.expect(!wantsLazy(parse(a, "{\"command\":\"npx\",\"startup\":\"eager\"}")));
    try std.testing.expect(!wantsLazy(parse(a, "{\"url\":\"https://example.com/mcp\"}")));
}

test "cloneMap survives the source arena" {
    var src = std.heap.ArenaAllocator.init(std.testing.allocator);
    const original = (try std.json.parseFromSliceLeaky(Value, src.allocator(),
        \\{"command":"node","args":["server.js","--port","9"],"env":{"TOKEN":"t"},"cwd":"/tmp"}
    , .{ .allocate = .alloc_always })).object;
    var dst = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer dst.deinit();
    const copy = try cloneMap(dst.allocator(), original);
    src.deinit(); // the request arena an ACP client's config came from is gone
    const spec = try stdioSpec(std.testing.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]);
    try std.testing.expectEqualStrings("/tmp", spec.cwd.?);
    try std.testing.expectEqualStrings("t", spec.env.?.get("TOKEN").?);
}

test "a server's env overlays graff's own environment instead of replacing it" {
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    var parent = std.process.Environ.Map.init(std.testing.allocator);
    defer parent.deinit();
    try parent.put("PATH", "/usr/bin:/bin");
    try parent.put("TOKEN", "from-parent");
    const saved = parent_env;
    defer parent_env = saved;
    remember(&parent);
    const cfg = (try std.json.parseFromSliceLeaky(Value, a, "{\"command\":\"npx\",\"env\":{\"TOKEN\":\"from-entry\"}}", .{})).object;
    const spec = try stdioSpec(std.testing.io, std.testing.allocator, a, cfg);
    const env = spec.env.?;
    defer env.deinit();
    try std.testing.expectEqualStrings("/usr/bin:/bin", env.get("PATH").?);
    try std.testing.expectEqualStrings("from-entry", env.get("TOKEN").?);
}