graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! `graff mcp add <anything>`: infer an entry from a URL, an npm/uvx package, or
//! a pasted Claude/Cursor/VS Code JSON snippet, then verify it connects.
//!
//! The explicit forms (`add <name> --url …`, `add <name> -- <command> …`) stay
//! in mcp_cli.zig; this module only decides what an unlabeled argument means
//! and checks the saved entry by connecting to it and listing its tools.
const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const Allocator = std.mem.Allocator;
/// One server to save: the name and its `.mcp.json` entry
/// (`command`/`args`/`env` or `url`/`headers`).
pub const Named = struct { name: []const u8, cfg: std.json.ObjectMap };
fn lowerSlug(a: Allocator, raw: []const u8) ![]const u8 {
var out: std.ArrayList(u8) = .empty;
for (raw) |c| {
const l = std.ascii.toLower(c);
if (std.ascii.isAlphanumeric(l)) {
try out.append(a, l);
} else if ((l == '-' or l == '_' or l == '.') and out.items.len > 0 and out.items[out.items.len - 1] != '-') {
try out.append(a, '-');
}
}
while (out.items.len > 0 and out.items[out.items.len - 1] == '-') out.items.len -= 1;
return out.items;
}
pub fn isUrl(token: []const u8) bool {
return std.mem.startsWith(u8, token, "https://") or std.mem.startsWith(u8, token, "http://");
}
/// `https://mcp.linear.app/sse` → "linear"; `http://localhost:8931/mcp` → "local-8931".
pub fn nameFromUrl(a: Allocator, url: []const u8) ![]const u8 {
const after = url[(std.mem.indexOf(u8, url, "://") orelse return error.InvalidUrl) + 3 ..];
const authority = after[0 .. std.mem.indexOfAny(u8, after, "/?#") orelse after.len];
const host_start = if (std.mem.lastIndexOfScalar(u8, authority, '@')) |at| at + 1 else 0;
const host_port = authority[host_start..];
const bracketed = std.mem.startsWith(u8, host_port, "[");
const colon = if (bracketed) std.mem.indexOf(u8, host_port, "]:") else std.mem.lastIndexOfScalar(u8, host_port, ':');
const host = if (colon) |c| host_port[0 .. c + @intFromBool(bracketed)] else host_port;
const port = if (colon) |c| host_port[c + 1 + @intFromBool(bracketed) ..] else "";
if (std.mem.eql(u8, host, "localhost") or std.mem.startsWith(u8, host, "127.") or std.mem.eql(u8, host, "[::1]"))
return if (port.len > 0) std.fmt.allocPrint(a, "local-{s}", .{port}) else "local";
var labels = std.mem.splitScalar(u8, host, '.');
while (labels.next()) |label| {
if (labels.peek() == null) break; // never the TLD
const generic = [_][]const u8{ "mcp", "api", "www", "server", "app", "remote" };
const skip = for (generic) |g| {
if (std.ascii.eqlIgnoreCase(label, g)) break true;
} else false;
if (!skip) return lowerSlug(a, label);
}
return lowerSlug(a, host);
}
pub const Runner = enum { npx, uvx };
pub const Package = struct { runner: Runner, pkg: []const u8 };
/// An npm package (`@scope/name`, a bare `*mcp*` name, or `npx:name`), or a
/// Python one with an explicit `uvx:` prefix. Paths and plain commands are not.
pub fn packageSpec(token: []const u8) ?Package {
if (std.mem.startsWith(u8, token, "uvx:")) return if (token.len > 4) .{ .runner = .uvx, .pkg = token[4..] } else null;
if (std.mem.startsWith(u8, token, "npx:")) return if (token.len > 4) .{ .runner = .npx, .pkg = token[4..] } else null;
if (token.len > 2 and token[0] == '@' and std.mem.indexOfScalar(u8, token, '/') != null and std.mem.indexOfAny(u8, token, " \\") == null)
return .{ .runner = .npx, .pkg = token };
if (std.mem.indexOf(u8, token, "mcp") == null) return null;
for (token) |c| if (!(std.ascii.isLower(c) or std.ascii.isDigit(c) or c == '-' or c == '.' or c == '_' or c == '@')) return null;
return .{ .runner = .npx, .pkg = token };
}
/// `@modelcontextprotocol/server-github` → "github", `@playwright/mcp` →
/// "playwright", `@upstash/context7-mcp@latest` → "context7".
pub fn nameFromPackage(a: Allocator, pkg: []const u8) ![]const u8 {
var body = pkg;
// A version pin: the last '@' past the scope marker.
if (std.mem.lastIndexOfScalar(u8, body, '@')) |at| if (at > 0) {
body = body[0..at];
};
const slash = std.mem.lastIndexOfScalar(u8, body, '/');
var seg = if (slash) |s| body[s + 1 ..] else body;
const scope = if (slash) |s| std.mem.trimStart(u8, body[0..s], "@") else "";
for ([_][]const u8{ "mcp-server-", "server-", "mcp-" }) |p| if (std.mem.startsWith(u8, seg, p) and seg.len > p.len) {
seg = seg[p.len..];
break;
};
for ([_][]const u8{ "-mcp-server", "-server-mcp", "-mcp", "-server" }) |s| if (std.mem.endsWith(u8, seg, s) and seg.len > s.len) {
seg = seg[0 .. seg.len - s.len];
break;
};
if ((std.mem.eql(u8, seg, "mcp") or std.mem.eql(u8, seg, "server")) and scope.len > 0) seg = scope;
return lowerSlug(a, seg);
}
fn putStrings(a: Allocator, cfg: *std.json.ObjectMap, key: []const u8, items: []const []const u8) !void {
var arr = std.json.Array.init(a);
for (items) |s| try arr.append(.{ .string = s });
try cfg.put(a, key, .{ .array = arr });
}
/// The entry for one unlabeled token (URL or package), or null when the token
/// is neither: the caller then treats it as an explicit command.
pub fn infer(a: Allocator, token: []const u8, name_override: ?[]const u8) !?Named {
var cfg: std.json.ObjectMap = .empty;
if (isUrl(token)) {
try cfg.put(a, "url", .{ .string = token });
return .{ .name = name_override orelse try nameFromUrl(a, token), .cfg = cfg };
}
const spec = packageSpec(token) orelse return null;
switch (spec.runner) {
.npx => {
try cfg.put(a, "command", .{ .string = "npx" });
try putStrings(a, &cfg, "args", &.{ "-y", spec.pkg });
},
.uvx => {
try cfg.put(a, "command", .{ .string = "uvx" });
try putStrings(a, &cfg, "args", &.{spec.pkg});
},
}
return .{ .name = name_override orelse try nameFromPackage(a, spec.pkg), .cfg = cfg };
}
/// Keep only what graff's config reads; map the URL spellings other clients use.
pub fn normalize(a: Allocator, raw: Value) !std.json.ObjectMap {
if (raw != .object) return error.UnsupportedEntry;
var cfg: std.json.ObjectMap = .empty;
const o = raw.object;
if (o.get("command")) |c| {
if (c != .string) return error.UnsupportedEntry;
try cfg.put(a, "command", c);
if (o.get("args")) |args| {
if (args != .array) return error.UnsupportedEntry;
for (args.array.items) |arg| if (arg != .string) return error.UnsupportedEntry;
try cfg.put(a, "args", args);
}
if (o.get("env")) |env| if (env == .object) try cfg.put(a, "env", env);
return cfg;
}
for ([_][]const u8{ "url", "serverUrl", "httpUrl" }) |key| if (o.get(key)) |u| if (u == .string) {
try cfg.put(a, "url", u);
if (o.get("headers")) |h| if (h == .object) try cfg.put(a, "headers", h);
return cfg;
};
return error.UnsupportedEntry;
}
fn isEntry(v: Value) bool {
return v == .object and (v.object.get("command") != null or v.object.get("url") != null or v.object.get("serverUrl") != null or v.object.get("httpUrl") != null);
}
/// Servers in a pasted snippet: `{"mcpServers":{…}}` (Claude, Cursor),
/// `{"servers":{…}}` or `{"mcp":{"servers":{…}}}` (VS Code), a bare
/// `{name: entry}` map, or one entry (named by `name_override` or its URL).
pub fn fromJson(a: Allocator, text: []const u8, name_override: ?[]const u8) ![]Named {
const root = std.json.parseFromSliceLeaky(Value, a, text, .{ .allocate = .alloc_always }) catch return error.InvalidJson;
if (root != .object) return error.InvalidJson;
var out: std.ArrayList(Named) = .empty;
if (isEntry(root)) {
const cfg = try normalize(a, root);
const name = name_override orelse blk: {
if (cfg.get("url")) |u| break :blk try nameFromUrl(a, u.string);
if (cfg.get("args")) |args| for (args.array.items) |arg| if (packageSpec(arg.string)) |p| break :blk try nameFromPackage(a, p.pkg);
return error.NameRequired;
};
try out.append(a, .{ .name = name, .cfg = cfg });
return out.items;
}
const map = if (root.object.get("mcpServers")) |m| m else if (root.object.get("servers")) |m| m else if (root.object.get("mcp")) |m|
(if (m == .object) (m.object.get("servers") orelse return error.NoServers) else return error.NoServers)
else
root;
if (map != .object) return error.NoServers;
var it = map.object.iterator();
while (it.next()) |e| {
if (!isEntry(e.value_ptr.*)) continue;
try out.append(a, .{ .name = try lowerSlug(a, e.key_ptr.*), .cfg = try normalize(a, e.value_ptr.*) });
}
if (out.items.len == 0) return error.NoServers;
return out.items;
}
pub const Checked = union(enum) {
ok: struct { tools: usize, sample: []const u8 },
needs_login,
failed: anyerror,
};
/// Connect to one saved entry, list its tools, and disconnect.
pub fn verify(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, entry: Named) Checked {
const mcp = @import("mcp.zig");
const rpc = @import("mcp_rpc.zig");
// A first `npx -y` or `uvx` run downloads the package before it can answer.
const saved_timeout = rpc.stdio_handshake_timeout_ms;
rpc.stdio_handshake_timeout_ms = @max(saved_timeout, 120_000);
defer rpc.stdio_handshake_timeout_ms = saved_timeout;
var reg = mcp.Registry.emptyWithOAuthHome(gpa, io, home);
defer reg.deinit();
reg.lazy_stdio = false; // verifying means really connecting, not reading the cache
const a = reg.arena();
var servers: std.ArrayList(*rpc.Server) = .empty;
var tools: std.ArrayList(mcp.Tool) = .empty;
reg.startServer(a, &servers, &tools, entry.name, entry.cfg) catch |err| {
reg.servers = servers.items;
return if (err == error.McpAuthenticationRequired) .needs_login else .{ .failed = err };
};
reg.servers = servers.items;
reg.tools = tools.items;
var sample: std.ArrayList(u8) = .empty;
for (tools.items, 0..) |t, i| {
if (i == 5) {
sample.appendSlice(arena, ", …") catch break;
break;
}
if (i > 0) sample.appendSlice(arena, ", ") catch break;
sample.appendSlice(arena, t.original_name) catch break;
}
return .{ .ok = .{ .tools = tools.items.len, .sample = sample.items } };
}
/// One line a person can act on for a failed connection.
pub fn failureHint(err: anyerror, cfg: std.json.ObjectMap) []const u8 {
const command = if (cfg.get("command")) |c| (if (c == .string) c.string else "") else "";
return switch (err) {
error.FileNotFound => if (std.mem.eql(u8, command, "npx"))
"`npx` was not found; install Node.js, or add the server with an explicit command"
else if (std.mem.eql(u8, command, "uvx"))
"`uvx` was not found; install uv, or add the server with an explicit command"
else
"the command was not found on PATH",
error.BadMcpUrl => "the URL must use HTTPS (HTTP only for localhost)",
error.EndOfStream, error.BrokenPipe => "the server exited during startup; it may need an environment variable (`--env KEY=VALUE`) or a different package (`uvx:` for Python servers)",
else => "the server did not complete the MCP handshake",
};
}
test "names come from the host or the package, not boilerplate" {
var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena.deinit();
const a = arena.allocator();
try std.testing.expectEqualStrings("linear", try nameFromUrl(a, "https://mcp.linear.app/sse"));
try std.testing.expectEqualStrings("mobbin", try nameFromUrl(a, "https://api.mobbin.com/mcp"));
try std.testing.expectEqualStrings("local-8931", try nameFromUrl(a, "http://localhost:8931/mcp"));
try std.testing.expectEqualStrings("example", try nameFromUrl(a, "https://[email protected]:8443/x"));
try std.testing.expectEqualStrings("github", try nameFromPackage(a, "@modelcontextprotocol/server-github"));
try std.testing.expectEqualStrings("playwright", try nameFromPackage(a, "@playwright/mcp"));
try std.testing.expectEqualStrings("context7", try nameFromPackage(a, "@upstash/context7-mcp@latest"));
try std.testing.expectEqualStrings("fetch", try nameFromPackage(a, "mcp-server-fetch"));
}
test "infer maps URLs and packages; other tokens stay commands" {
var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena.deinit();
const a = arena.allocator();
const url = (try infer(a, "https://mcp.linear.app/sse", null)).?;
try std.testing.expectEqualStrings("https://mcp.linear.app/sse", url.cfg.get("url").?.string);
const npm = (try infer(a, "@playwright/mcp", null)).?;
try std.testing.expectEqualStrings("npx", npm.cfg.get("command").?.string);
try std.testing.expectEqualStrings("-y", npm.cfg.get("args").?.array.items[0].string);
const py = (try infer(a, "uvx:mcp-server-fetch", "fetch")).?;
try std.testing.expectEqualStrings("uvx", py.cfg.get("command").?.string);
try std.testing.expectEqualStrings("fetch", py.name);
try std.testing.expect((try infer(a, "node", null)) == null);
try std.testing.expect((try infer(a, "./server.js", null)) == null);
}
test "fromJson reads Claude, VS Code, bare-map, and single-entry snippets" {
var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena.deinit();
const a = arena.allocator();
const claude = try fromJson(a,
\\{"mcpServers":{"Sentry":{"command":"npx","args":["-y","@sentry/mcp-server"],"env":{"TOKEN":"x"}},"linear":{"url":"https://mcp.linear.app/sse"}}}
, null);
try std.testing.expectEqual(@as(usize, 2), claude.len);
var saw_sentry_env = false;
for (claude) |n| if (std.mem.eql(u8, n.name, "sentry")) {
saw_sentry_env = n.cfg.get("env") != null;
};
try std.testing.expect(saw_sentry_env);
const vscode = try fromJson(a,
\\{"mcp":{"servers":{"gh":{"type":"http","url":"https://api.githubcopilot.com/mcp/"}}}}
, null);
try std.testing.expectEqualStrings("https://api.githubcopilot.com/mcp/", vscode[0].cfg.get("url").?.string);
try std.testing.expect(vscode[0].cfg.get("type") == null);
const windsurf = try fromJson(a,
\\{"deepwiki":{"serverUrl":"https://mcp.deepwiki.com/mcp"}}
, null);
try std.testing.expectEqualStrings("https://mcp.deepwiki.com/mcp", windsurf[0].cfg.get("url").?.string);
const single = try fromJson(a,
\\{"command":"npx","args":["-y","@upstash/context7-mcp"]}
, null);
try std.testing.expectEqualStrings("context7", single[0].name);
try std.testing.expectError(error.NoServers, fromJson(a, "{\"x\":1}", null));
}