Skip to content

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

Python
5.1 KB
Raw Blame
//! `graff mcp serve` as a 2026-07-28 (stateless) server, beside the legacy
//! `initialize` path in mcp_server.zig.
//!
//! A request is modern when its `params._meta` names a protocol version. It
//! needs no handshake: the version and client capabilities ride every
//! request. Results carry `resultType`, and the cacheable ones (`server/
//! discover`, the list methods, `resources/read`) carry `ttlMs` and
//! `cacheScope`. An unknown version gets -32022 with `supported` and
//! `requested`, which is also what tells a dual-era client this server is
//! modern at all.

const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const Value = std.json.Value;
const mcp_protocol = @import("mcp_protocol.zig");

pub const version = mcp_protocol.modern_protocol;
const version_key = "io.modelcontextprotocol/protocolVersion";
const capabilities_key = "io.modelcontextprotocol/clientCapabilities";

/// Every revision this server answers: the modern one, then the legacy
/// `initialize` revisions in preference order.
pub const supported_versions = [_][]const u8{ version, "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05" };

/// The catalog and the task-result view only change with the binary, and
/// neither holds user data.
pub const ttl_ms: u64 = 5 * 60 * 1000;

pub const unsupported_code: i32 = -32022;
pub const header_mismatch_code: i32 = -32020;

fn meta(params: Value) ?std.json.ObjectMap {
    if (params != .object) return null;
    const m = params.object.get("_meta") orelse return null;
    return if (m == .object) m.object else null;
}

/// The protocol version a modern request names, or null for a legacy one.
pub fn requestedVersion(params: Value) ?[]const u8 {
    const m = meta(params) orelse return null;
    const v = m.get(version_key) orelse return null;
    return if (v == .string) v.string else null;
}

pub fn isSupported(requested: []const u8) bool {
    return std.mem.eql(u8, requested, version);
}

/// `{capabilities: <clientCapabilities>}` — the shape mcp_server_app.supported
/// reads from a legacy `initialize`, so both eras share one check.
pub fn capabilityParams(a: Allocator, params: Value) !Value {
    var wrapped: std.json.ObjectMap = .empty;
    if (meta(params)) |m| if (m.get(capabilities_key)) |caps| try wrapped.put(a, "capabilities", caps);
    return .{ .object = wrapped };
}

/// `result` with the modern envelope fields added.
pub fn envelope(a: Allocator, result: anytype, cacheable: bool) !Value {
    const text = try std.json.Stringify.valueAlloc(a, result, .{});
    var value = try std.json.parseFromSliceLeaky(Value, a, text, .{ .allocate = .alloc_always });
    if (value != .object) return error.BadResult;
    try value.object.put(a, "resultType", .{ .string = "complete" });
    if (cacheable) {
        try value.object.put(a, "ttlMs", .{ .integer = ttl_ms });
        try value.object.put(a, "cacheScope", .{ .string = "public" });
    }
    return value;
}

pub fn unsupported(out: *Io.Writer, id: Value, requested: []const u8) !void {
    var json: std.json.Stringify = .{ .writer = out };
    try json.write(.{ .jsonrpc = "2.0", .id = id, .@"error" = .{
        .code = unsupported_code,
        .message = "Unsupported protocol version",
        .data = .{ .supported = supported_versions, .requested = requested },
    } });
    try out.writeByte('\n');
}

/// Why a modern Streamable HTTP request's headers disagree with its body, or
/// null when they agree. `protocol_header`, `method_header` and `name_header`
/// are the raw header values (null when absent).
pub fn headerMismatch(a: Allocator, body: Value, protocol_header: ?[]const u8, method_header: ?[]const u8, name_header: ?[]const u8) !?[]const u8 {
    const params = if (body == .object) body.object.get("params") orelse Value.null else Value.null;
    const requested = requestedVersion(params) orelse return null;
    if (!std.mem.eql(u8, protocol_header orelse "", requested)) return "MCP-Protocol-Version header does not match _meta protocolVersion";
    const method = if (body == .object) body.object.get("method") orelse Value.null else Value.null;
    if (method != .string or !std.mem.eql(u8, method_header orelse "", method.string)) return "Mcp-Method header does not match the request method";
    const name_field: ?[]const u8 = if (std.mem.eql(u8, method.string, "tools/call") or std.mem.eql(u8, method.string, "prompts/get"))
        "name"
    else if (std.mem.eql(u8, method.string, "resources/read")) "uri" else null;
    const field = name_field orelse return null;
    const v = if (params == .object) params.object.get(field) orelse Value.null else Value.null;
    if (v != .string) return null; // the handler reports the missing argument
    const expected = try mcp_protocol.headerValue(a, v.string);
    if (!std.mem.eql(u8, name_header orelse "", expected)) return "Mcp-Name header does not match the request";
    return null;
}

pub fn mismatch(out: *Io.Writer, id: Value, why: []const u8) !void {
    var json: std.json.Stringify = .{ .writer = out };
    try json.write(.{ .jsonrpc = "2.0", .id = id, .@"error" = .{ .code = header_mismatch_code, .message = why } });
    try out.writeByte('\n');
}

test {
    _ = @import("mcp_server_modern_tests.zig");
}