Skip to content

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

Python

graff mcp add <name>: look it up on codegraff.com/mcp, then the MCP registry

justrach041207365fb1
diff --git a/README.md b/README.md
index c94c7828..be20c94b 100644
--- a/README.md
+++ b/README.md
@@ -179,7 +179,7 @@ graff [flags] REPL
graff -p "prompt" one-shot (answer on stdout)
graff login [codegraff|codex|kimi|xai|zai]
graff key set <provider> <key>
-graff mcp add <url | @scope/pkg | uvx:pkg | json> save + verify an MCP server
+graff mcp add <name | url | @scope/pkg | uvx:pkg | json> save + verify an MCP server (names: codegraff.com/mcp)
graff mcp add <name> -- <cmd>
graff learn <command>
graff --schema
diff --git a/assets/skills/mcp.md b/assets/skills/mcp.md
index eff15bf4..1c36d060 100644
--- a/assets/skills/mcp.md
+++ b/assets/skills/mcp.md
@@ -15,6 +15,7 @@ only when you need field-level detail. Do the add here.
and lists the tools:
```sh
+graff mcp add linear # a name → codegraff.com/mcp, then the MCP registry
graff mcp add https://mcp.deepwiki.com/mcp # URL → HTTP, named "deepwiki"
graff mcp add @playwright/mcp # npm package → npx -y
graff mcp add uvx:mcp-server-fetch # Python package → uvx
@@ -22,6 +23,9 @@ graff mcp add '{"mcpServers":{...}}' # a pasted Claude/Cursor/VS
graff mcp add <name> --env KEY=VALUE -- <command> [args...]
```
+ A name is looked up in the list at codegraff.com/mcp, then in the official
+ MCP registry, where graff only picks a publisher that owns the name. If it
+ lists registry candidates instead, show them to the user; do not pick one.
`--name <name>` overrides the inferred name. Never write the global file
unless the user said "every project". Do not put secrets in the chat.
@@ -29,6 +33,8 @@ graff mcp add <name> --env KEY=VALUE -- <command> [args...]
- `✓ <name> works: N tool(s) — …`: done.
- `needs sign-in: run graff mcp login <name>`: ask the user to run it
(it opens a browser; you cannot finish it for them).
+ - `<server> needs KEY: …` / `nothing was saved`: ask the user for that key
+ or token, then re-run with the `--env KEY=…` / `--header "K=…"` it shows.
- `✗ saved <name>, but it did not connect (…): <hint>`: follow the hint
(install Node or uv, add `--env`, fix the package name), then re-run
the same `graff mcp add`.
@@ -60,4 +66,4 @@ User: "using the MCP skill, add this MCP: https://mcp.deepwiki.com/mcp"
User: "add playwright MCP"
-- `graff mcp add @playwright/mcp`
+- `graff mcp add playwright`
diff --git a/scripts/test-mcp-add.py b/scripts/test-mcp-add.py
index a1abbea6..6b5f8171 100644
--- a/scripts/test-mcp-add.py
+++ b/scripts/test-mcp-add.py
@@ -6,6 +6,8 @@
- a missing command is saved but reported with an actionable hint
- a server that answers 401 points at `graff mcp login` (no TTY here)
- a server added by the agent mid-session is callable on its next request
+- a bare name resolves from the curated list, then from the registry only
+ when the publisher owns the name; needs and limitations stop the save
"""
import json, os, shutil, subprocess, sys, tempfile, threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -46,6 +48,42 @@ class Unauthorized(BaseHTTPRequestHandler):
def log_message(self, *a): pass
+def directory(server_py):
+ """codegraff.com/mcp.json and the MCP registry search, served locally."""
+ catalog = {"version": 1, "servers": [
+ {"slug": "demo-cat", "name": "Demo Cat", "aliases": ["kitty"], "config": {"command": sys.executable, "args": [server_py]}},
+ {"slug": "keyed", "name": "Keyed", "config": {"command": sys.executable, "args": [server_py]},
+ "needs": [{"env": "DEMO_KEY", "hint": "a demo key"}]},
+ {"slug": "blocked", "name": "Blocked", "config": {"url": "https://example.invalid/mcp"}, "limitation": "sign-in is not supported yet."},
+ ]}
+ registry = {
+ "acme": [{"server": {"name": "io.github.acme/acme", "packages": [
+ {"registryType": "npm", "identifier": "@acme/mcp", "version": "2.1.0", "transport": {"type": "stdio"}}]}}],
+ "lookalike": [{"server": {"name": "io.github.someone/lookalike-tools", "packages": [
+ {"registryType": "npm", "identifier": "lookalike-tools"}]}}],
+ }
+
+ class Directory(BaseHTTPRequestHandler):
+ def do_GET(self):
+ path, _, query = self.path.partition('?')
+ if path == '/mcp.json':
+ body = catalog
+ else:
+ search = dict(p.split('=', 1) for p in query.split('&') if '=' in p).get('search', '')
+ body = {"servers": registry.get(search, []), "metadata": {}}
+ data = json.dumps(body).encode()
+ self.send_response(200)
+ self.send_header('Content-Type', 'application/json')
+ self.send_header('Content-Length', str(len(data)))
+ self.end_headers()
+ self.wfile.write(data)
+ def log_message(self, *a): pass
+
+ httpd = ThreadingHTTPServer(('127.0.0.1', 0), Directory)
+ threading.Thread(target=httpd.serve_forever, daemon=True).start()
+ return httpd
+
+
def run(binary, cwd, env, *args, stdin=None):
r = subprocess.run([binary, 'mcp', *args], cwd=cwd, env=env, input=stdin, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=180)
return r.stdout + r.stderr
@@ -64,6 +102,9 @@ def main():
env = {k: v for k, v in os.environ.items() if not k.endswith('_API_KEY')}
env.update(HOME=temp, GRAFF_NO_TELEMETRY='1', GRAFF_FLEET='off', GRAFF_MCP_CONFIG=str(Path(temp) / 'global.json'))
(Path(temp) / 'global.json').write_text('{"mcpServers":{}}')
+ lookup = directory(str(server))
+ base = f'http://127.0.0.1:{lookup.server_address[1]}'
+ env.update(GRAFF_MCP_CATALOG_URL=f'{base}/mcp.json', GRAFF_MCP_REGISTRY_URL=f'{base}/v0.1/servers')
work = Path(temp) / 'proj'
work.mkdir()
@@ -92,6 +133,23 @@ def main():
httpd.shutdown()
print('PASS mcp add: a URL is named from its host; a 401 points at graff mcp login', flush=True)
+ names = Path(temp) / 'names'
+ names.mkdir()
+ text = run(binary, names, env, 'add', 'kitty')
+ assert 'found Demo Cat via codegraff.com/mcp' in text and '✓ demo-cat works: 2 tool(s)' in text, text
+ text = run(binary, names, env, 'add', 'keyed')
+ assert 'DEMO_KEY: a demo key' in text and 'nothing was saved' in text and 'keyed' not in saved(names), text
+ text = run(binary, names, env, 'add', 'keyed', '--env', 'DEMO_KEY=abc')
+ assert saved(names)['keyed']['env'] == {'DEMO_KEY': 'abc'} and '✓ keyed works' in text, text
+ text = run(binary, names, env, 'add', 'blocked')
+ assert 'sign-in is not supported yet' in text and 'blocked' not in saved(names), text
+ text = run(binary, names, env, 'add', 'acme', '--no-verify')
+ assert 'found io.github.acme/acme via the MCP registry' in text, text
+ assert saved(names)['acme'] == {'command': 'npx', 'args': ['-y', '@acme/[email protected]']}, saved(names)
+ text = run(binary, names, env, 'add', 'lookalike')
+ assert 'io.github.someone/lookalike-tools' in text and 'will not pick one' in text and 'lookalike' not in saved(names), text
+ print('PASS mcp add <name>: the curated list first, the registry only for a publisher that owns the name', flush=True)
+
live = Path(temp) / 'live'
live.mkdir()
add_cmd = f'{binary} mcp add livedemo --no-verify -- {sys.executable} {server}'
diff --git a/src/main.zig b/src/main.zig
index c0542034..653b636d 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("hot_context.zig"), @import("history_translate.zig"), @import("mcp_notify.zig"), @import("mcp_wait.zig"), @import("mcp_pages.zig"), @import("mcp_mrtr.zig"), @import("ask_user_args.zig"), @import("mcp_add.zig"), @import("mcp_watch.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig"), @import("ask_user_answers.zig"), @import("job_class.zig"), @import("startup_claim.zig") };
+ _ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_elicit.zig"), @import("hot_context.zig"), @import("history_translate.zig"), @import("mcp_notify.zig"), @import("mcp_wait.zig"), @import("mcp_pages.zig"), @import("mcp_mrtr.zig"), @import("ask_user_args.zig"), @import("mcp_add.zig"), @import("mcp_catalog.zig"), @import("mcp_watch.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig"), @import("ask_user_answers.zig"), @import("job_class.zig"), @import("startup_claim.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_add.zig b/src/mcp_add.zig
index 493b8da6..54efb963 100644
--- a/src/mcp_add.zig
+++ b/src/mcp_add.zig
@@ -123,7 +123,7 @@ pub fn infer(a: Allocator, token: []const u8, name_override: ?[]const u8) !?Name
}
/// Keep only what graff's config reads; map the URL spellings other clients use.
-fn normalize(a: Allocator, raw: Value) !std.json.ObjectMap {
+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;
diff --git a/src/mcp_catalog.zig b/src/mcp_catalog.zig
new file mode 100644
index 00000000..8034b32f
--- /dev/null
+++ b/src/mcp_catalog.zig
@@ -0,0 +1,423 @@
+//! `graff mcp add <name>`: resolve a bare server name to a `.mcp.json` entry.
+//!
+//! The curated list codegraff.com/mcp publishes as JSON is asked first; every
+//! entry there was connected with graff before it was listed. A name it does
+//! not know goes to the official MCP registry, where only a publisher that owns
+//! the name is picked automatically: a verified domain namespace (`com.stripe`)
+//! or GitHub account (`io.github.stripe`) whose label equals it. Anyone can
+//! publish `io.github.someone/stripe-mcp`, so a match on the server's own name
+//! is listed for the person to choose, never run.
+
+const std = @import("std");
+const Io = std.Io;
+const Value = std.json.Value;
+const Allocator = std.mem.Allocator;
+
+pub const default_catalog_url = "https://codegraff.com/mcp.json";
+pub const default_registry_url = "https://registry.modelcontextprotocol.io/v0.1/servers";
+
+/// Something a person must supply before the entry can work: an environment
+/// variable for a local server, or a request header for a hosted one.
+pub const Need = struct {
+ env: ?[]const u8 = null,
+ header: ?[]const u8 = null,
+ prefix: []const u8 = "",
+ hint: []const u8 = "",
+};
+
+pub const Found = struct {
+ name: []const u8,
+ title: []const u8,
+ cfg: std.json.ObjectMap,
+ needs: []const Need = &.{},
+ limitation: ?[]const u8 = null,
+ /// Where it came from, for the line graff prints before saving.
+ source: []const u8,
+};
+
+pub const Lookup = union(enum) {
+ found: Found,
+ /// Registry servers with the name that graff will not pick on its own.
+ candidates: []const []const u8,
+ not_found,
+};
+
+/// A server name as someone would type it: `linear`, `brave-search`. Not a
+/// URL, a scoped package, a path, or a `uvx:` spec.
+pub fn isBareName(token: []const u8) bool {
+ if (token.len == 0 or token.len > 64 or !std.ascii.isAlphanumeric(token[0])) return false;
+ for (token) |c| if (!(std.ascii.isAlphanumeric(c) or c == '-' or c == '_' or c == '.')) return false;
+ return true;
+}
+
+fn str(obj: std.json.ObjectMap, key: []const u8) ?[]const u8 {
+ const v = obj.get(key) orelse return null;
+ return if (v == .string) v.string else null;
+}
+
+fn eqlLower(a: []const u8, b: []const u8) bool {
+ return std.ascii.eqlIgnoreCase(a, b);
+}
+
+/// The curated entry for `query` (its slug or an alias).
+pub fn fromCatalog(a: Allocator, root: Value, query: []const u8) !?Found {
+ if (root != .object) return error.BadCatalog;
+ const servers = root.object.get("servers") orelse return error.BadCatalog;
+ if (servers != .array) return error.BadCatalog;
+ for (servers.array.items) |s| {
+ if (s != .object) continue;
+ const slug = str(s.object, "slug") orelse continue;
+ var hit = eqlLower(slug, query);
+ if (!hit) if (s.object.get("aliases")) |al| if (al == .array) for (al.array.items) |x| {
+ if (x == .string and eqlLower(x.string, query)) hit = true;
+ };
+ if (!hit) continue;
+ const raw = s.object.get("config") orelse return error.BadCatalog;
+ var needs: std.ArrayList(Need) = .empty;
+ if (s.object.get("needs")) |ns| if (ns == .array) for (ns.array.items) |n| {
+ if (n != .object) continue;
+ try needs.append(a, .{
+ .env = str(n.object, "env"),
+ .header = str(n.object, "header"),
+ .prefix = str(n.object, "prefix") orelse "",
+ .hint = str(n.object, "hint") orelse "",
+ });
+ };
+ return .{
+ .name = slug,
+ .title = str(s.object, "name") orelse slug,
+ .cfg = try @import("mcp_add.zig").normalize(a, raw),
+ .needs = needs.items,
+ .limitation = str(s.object, "limitation"),
+ .source = "codegraff.com/mcp",
+ };
+ }
+ return null;
+}
+
+/// Who published a registry server: `com.stripe/mcp` → "stripe",
+/// `io.github.getsentry/sentry-mcp` → "getsentry".
+pub fn ownerOf(server_name: []const u8) []const u8 {
+ const ns = server_name[0 .. std.mem.indexOfScalar(u8, server_name, '/') orelse server_name.len];
+ if (std.mem.startsWith(u8, ns, "io.github.")) return ns["io.github.".len..];
+ var labels = std.mem.splitScalar(u8, ns, '.');
+ _ = labels.next();
+ return labels.next() orelse ns;
+}
+
+fn leafOf(server_name: []const u8) []const u8 {
+ const slash = std.mem.indexOfScalar(u8, server_name, '/') orelse return server_name;
+ return server_name[slash + 1 ..];
+}
+
+fn putArgs(a: Allocator, cfg: *std.json.ObjectMap, command: []const u8, args: []const []const u8) !void {
+ try cfg.put(a, "command", .{ .string = command });
+ var arr = std.json.Array.init(a);
+ for (args) |s| try arr.append(.{ .string = s });
+ try cfg.put(a, "args", .{ .array = arr });
+}
+
+fn required(v: Value) bool {
+ if (v != .object) return false;
+ const r = v.object.get("isRequired") orelse return false;
+ return r == .bool and r.bool;
+}
+
+/// A `.mcp.json` entry graff can run for one registry server: a Streamable
+/// HTTP remote first, else an npm or PyPI stdio package pinned to its version.
+fn registryEntry(a: Allocator, server: std.json.ObjectMap) !?struct { cfg: std.json.ObjectMap, needs: []const Need } {
+ var needs: std.ArrayList(Need) = .empty;
+ var cfg: std.json.ObjectMap = .empty;
+ if (server.get("remotes")) |remotes| if (remotes == .array) for (remotes.array.items) |r| {
+ if (r != .object) continue;
+ const kind = str(r.object, "type") orelse continue;
+ const url = str(r.object, "url") orelse continue;
+ if (!std.mem.eql(u8, kind, "streamable-http") or std.mem.indexOfScalar(u8, url, '{') != null) continue;
+ try cfg.put(a, "url", .{ .string = url });
+ if (r.object.get("headers")) |hs| if (hs == .array) for (hs.array.items) |h| if (required(h)) {
+ try needs.append(a, .{ .header = str(h.object, "name"), .hint = str(h.object, "description") orelse "" });
+ };
+ return .{ .cfg = cfg, .needs = needs.items };
+ };
+ if (server.get("packages")) |pkgs| if (pkgs == .array) for (pkgs.array.items) |p| {
+ if (p != .object) continue;
+ const reg_type = str(p.object, "registryType") orelse continue;
+ const id = str(p.object, "identifier") orelse continue;
+ if (p.object.get("transport")) |t| if (t == .object) if (str(t.object, "type")) |tt| if (!std.mem.eql(u8, tt, "stdio")) continue;
+ const needs_args = if (p.object.get("packageArguments")) |pa| blk: {
+ if (pa == .array) for (pa.array.items) |x| if (required(x)) break :blk true;
+ break :blk false;
+ } else false;
+ if (needs_args) continue;
+ const pinned = if (str(p.object, "version")) |v| try std.fmt.allocPrint(a, "{s}@{s}", .{ id, v }) else id;
+ if (std.mem.eql(u8, reg_type, "npm")) {
+ try putArgs(a, &cfg, "npx", &.{ "-y", pinned });
+ } else if (std.mem.eql(u8, reg_type, "pypi")) {
+ try putArgs(a, &cfg, "uvx", &.{pinned});
+ } else continue;
+ if (p.object.get("environmentVariables")) |envs| if (envs == .array) for (envs.array.items) |e| if (required(e)) {
+ try needs.append(a, .{ .env = str(e.object, "name"), .hint = str(e.object, "description") orelse "" });
+ };
+ return .{ .cfg = cfg, .needs = needs.items };
+ };
+ return null;
+}
+
+/// Pick from a registry search response (`{"servers":[{"server":{…}}]}`).
+pub fn fromRegistry(a: Allocator, root: Value, query: []const u8) !Lookup {
+ if (root != .object) return error.BadRegistry;
+ const list = root.object.get("servers") orelse return error.BadRegistry;
+ if (list != .array) return error.BadRegistry;
+ var owned: std.ArrayList(Found) = .empty;
+ // Not picked, only listed: publishers whose account contains the name
+ // (`getsentry` for sentry) ahead of servers that merely mention it.
+ var close: std.ArrayList([]const u8) = .empty;
+ var others: std.ArrayList([]const u8) = .empty;
+ for (list.array.items) |item| {
+ if (item != .object) continue;
+ const sv = item.object.get("server") orelse continue;
+ if (sv != .object) continue;
+ const name = str(sv.object, "name") orelse continue;
+ if (item.object.get("_meta")) |meta| if (meta == .object) if (meta.object.get("io.modelcontextprotocol.registry/official")) |off| if (off == .object) {
+ if (off.object.get("isLatest")) |l| if (l == .bool and !l.bool) continue;
+ if (str(off.object, "status")) |st| if (!std.mem.eql(u8, st, "active")) continue;
+ };
+ const entry = if (eqlLower(ownerOf(name), query)) try registryEntry(a, sv.object) else null;
+ if (entry) |e| {
+ try owned.append(a, .{ .name = try a.dupe(u8, query), .title = name, .cfg = e.cfg, .needs = e.needs, .source = "the MCP registry" });
+ } else if (std.ascii.findIgnoreCase(ownerOf(name), query) != null) {
+ try close.append(a, name);
+ } else if (std.ascii.findIgnoreCase(leafOf(name), query) != null or std.ascii.findIgnoreCase(str(sv.object, "title") orelse "", query) != null) {
+ try others.append(a, name);
+ }
+ }
+ if (owned.items.len == 1) return .{ .found = owned.items[0] };
+ if (owned.items.len > 1) {
+ // One publisher, several servers: the one named for the product, or
+ // its generic `/mcp`, else let the person choose.
+ for ([_][]const u8{ query, "mcp" }) |want| for (owned.items) |f| {
+ if (eqlLower(leafOf(f.title), want)) return .{ .found = f };
+ };
+ for (owned.items) |f| try close.append(a, f.title);
+ }
+ try close.appendSlice(a, others.items);
+ return if (close.items.len > 0) .{ .candidates = close.items[0..@min(close.items.len, 6)] } else .not_found;
+}
+
+fn fetchJson(io: Io, gpa: Allocator, arena: Allocator, url: []const u8) !Value {
+ if (!std.mem.startsWith(u8, url, "https://") and !@import("mcp.zig").validRemoteUrl(url)) return error.InsecureUrl;
+ var client: std.http.Client = .{ .allocator = gpa, .io = io };
+ defer client.deinit();
+ var body: Io.Writer.Allocating = .init(arena);
+ const headers = [_]std.http.Header{
+ .{ .name = "Accept", .value = "application/json" },
+ .{ .name = "User-Agent", .value = "graff-mcp-add" },
+ };
+ const res = try client.fetch(.{
+ .location = .{ .url = url },
+ .method = .GET,
+ .response_writer = &body.writer,
+ .extra_headers = &headers,
+ });
+ if (@intFromEnum(res.status) < 200 or @intFromEnum(res.status) >= 300) return error.HttpFailure;
+ return std.json.parseFromSliceLeaky(Value, arena, body.writer.buffered(), .{ .allocate = .alloc_always });
+}
+
+/// The curated entry, or null when the catalog is unreachable or lacks it.
+pub fn lookupCatalog(io: Io, gpa: Allocator, arena: Allocator, catalog_url: []const u8, query: []const u8) ?Found {
+ if (catalog_url.len == 0) return null;
+ const root = fetchJson(io, gpa, arena, catalog_url) catch return null;
+ return fromCatalog(arena, root, query) catch null;
+}
+
+pub fn lookupRegistry(io: Io, gpa: Allocator, arena: Allocator, registry_url: []const u8, query: []const u8) !Lookup {
+ if (registry_url.len == 0) return .not_found;
+ const url = try std.fmt.allocPrint(arena, "{s}?search={s}&version=latest&limit=100", .{ registry_url, query });
+ return fromRegistry(arena, try fetchJson(io, gpa, arena, url), query);
+}
+
+pub const Pair = struct { key: []const u8, value: []const u8 };
+pub const Given = struct { env: []const Pair = &.{}, headers: []const Pair = &.{} };
+
+/// What follows `add <name>`: only `--env K=V` and `--header K=V` pairs, or
+/// null so the caller parses an explicit form (`-- <command>`, `--url`).
+pub fn parseGiven(a: Allocator, rest: []const []const u8) !?Given {
+ var env: std.ArrayList(Pair) = .empty;
+ var headers: std.ArrayList(Pair) = .empty;
+ var i: usize = 0;
+ while (i < rest.len) : (i += 1) {
+ var flag: []const u8 = "";
+ var inline_value: ?[]const u8 = null;
+ for ([_][]const u8{ "--env", "--header" }) |f| {
+ if (std.mem.eql(u8, rest[i], f)) {
+ flag = f;
+ } else if (std.mem.startsWith(u8, rest[i], f) and rest[i].len > f.len and rest[i][f.len] == '=') {
+ flag = f;
+ inline_value = rest[i][f.len + 1 ..];
+ } else continue;
+ break;
+ }
+ if (flag.len == 0) return null;
+ const kv = inline_value orelse blk: {
+ i += 1;
+ if (i >= rest.len) return null;
+ break :blk rest[i];
+ };
+ const eq = std.mem.indexOfScalar(u8, kv, '=') orelse return null;
+ const pair: Pair = .{ .key = kv[0..eq], .value = kv[eq + 1 ..] };
+ try (if (std.mem.eql(u8, flag, "--env")) &env else &headers).append(a, pair);
+ }
+ return .{ .env = env.items, .headers = headers.items };
+}
+
+fn find(pairs: []const Pair, key: []const u8) ?[]const u8 {
+ for (pairs) |p| if (std.ascii.eqlIgnoreCase(p.key, key)) return p.value;
+ return null;
+}
+
+fn putPairs(a: Allocator, cfg: *std.json.ObjectMap, field: []const u8, pairs: []const Pair) !void {
+ if (pairs.len == 0) return;
+ var obj: std.json.ObjectMap = if (cfg.get(field)) |v| (if (v == .object) v.object else .empty) else .empty;
+ for (pairs) |p| try obj.put(a, p.key, .{ .string = p.value });
+ try cfg.put(a, field, .{ .object = obj });
+}
+
+/// Resolve `query` and fold in what the person gave: the curated list, then a
+/// bare `*mcp*` npm name, then the registry. Prints where the entry came from;
+/// exits with the reason when it cannot be saved as it stands.
+pub fn resolve(io: Io, gpa: Allocator, a: Allocator, environ_map: anytype, query: []const u8, name_override: ?[]const u8, given: Given, out: *Io.Writer) !@import("mcp_add.zig").Named {
+ const add = @import("mcp_add.zig");
+ const catalog_url = environ_map.get("GRAFF_MCP_CATALOG_URL") orelse default_catalog_url;
+ const registry_url = environ_map.get("GRAFF_MCP_REGISTRY_URL") orelse default_registry_url;
+ var found = lookupCatalog(io, gpa, a, catalog_url, query) orelse blk: {
+ if (try add.infer(a, query, name_override)) |pkg| break :blk Found{ .name = pkg.name, .title = query, .cfg = pkg.cfg, .source = "npm" };
+ const result = lookupRegistry(io, gpa, a, registry_url, query) catch |err|
+ std.process.fatal("mcp add: '{s}' is not on codegraff.com/mcp, and the MCP registry could not be reached ({t}). Give its URL or package instead.", .{ query, err });
+ switch (result) {
+ .found => |f| break :blk f,
+ .not_found => std.process.fatal("mcp add: no MCP server named '{s}' on codegraff.com/mcp or in the MCP registry. Give its URL, an npm package (@scope/name), or uvx:<python-package>.", .{query}),
+ .candidates => |names| {
+ var list: Io.Writer.Allocating = .init(a);
+ for (names) |n| try list.writer.print("\n {s}", .{n});
+ std.process.fatal("mcp add: '{s}' is not on codegraff.com/mcp, and no registry publisher owns that name, so graff will not pick one. Registry servers that mention it:{s}\nCheck one at registry.modelcontextprotocol.io, then add it by its URL or package.", .{ query, list.writer.buffered() });
+ },
+ }
+ };
+ if (found.limitation) |why| std.process.fatal("mcp add: {s}: {s}", .{ found.title, why });
+ const hosted = found.cfg.get("url") != null;
+ if (given.env.len > 0 and hosted) std.process.fatal("mcp add: {s} is a hosted server; pass credentials with --header, not --env", .{found.title});
+ if (given.headers.len > 0 and !hosted) std.process.fatal("mcp add: {s} runs locally; pass credentials with --env, not --header", .{found.title});
+
+ var headers: std.ArrayList(Pair) = .empty;
+ for (given.headers) |h| try headers.append(a, h);
+ var missing: Io.Writer.Allocating = .init(a);
+ var retry: Io.Writer.Allocating = .init(a);
+ for (found.needs) |need| {
+ if (need.env) |key| {
+ if (find(given.env, key) != null) continue;
+ if (environ_map.get(key) != null) {
+ try out.print(" using {s} from your environment\n", .{key});
+ continue;
+ }
+ try missing.writer.print("\n {s}: {s}", .{ key, need.hint });
+ try retry.writer.print(" --env {s}=…", .{key});
+ } else if (need.header) |key| {
+ if (find(headers.items, key)) |value| {
+ // A bare token for an `Authorization: Bearer` header gets its scheme.
+ if (need.prefix.len > 0 and !std.ascii.startsWithIgnoreCase(value, need.prefix)) {
+ for (headers.items) |*h| if (std.ascii.eqlIgnoreCase(h.key, key)) {
+ h.value = try std.fmt.allocPrint(a, "{s}{s}", .{ need.prefix, value });
+ };
+ }
+ continue;
+ }
+ try missing.writer.print("\n {s} header: {s}", .{ key, need.hint });
+ try retry.writer.print(" --header \"{s}={s}…\"", .{ key, need.prefix });
+ }
+ }
+ if (missing.writer.buffered().len > 0)
+ std.process.fatal("mcp add: {s} needs{s}\nnothing was saved; run `graff mcp add {s}{s}`", .{ found.title, missing.writer.buffered(), query, retry.writer.buffered() });
+ try putPairs(a, &found.cfg, "env", given.env);
+ try putPairs(a, &found.cfg, "headers", headers.items);
+ if (!std.mem.eql(u8, found.source, "npm")) try out.print(" found {s} via {s}\n", .{ found.title, found.source });
+ return .{ .name = name_override orelse found.name, .cfg = found.cfg };
+}
+
+test "parseGiven accepts only credential pairs" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const g = (try parseGiven(a, &.{ "--env", "K=V", "--header=Authorization=Bearer x" })).?;
+ try std.testing.expectEqualStrings("V", g.env[0].value);
+ try std.testing.expectEqualStrings("Bearer x", g.headers[0].value);
+ try std.testing.expect((try parseGiven(a, &.{ "--", "node", "x.js" })) == null);
+ try std.testing.expect((try parseGiven(a, &.{"--url"})) == null);
+ try std.testing.expect((try parseGiven(a, &.{ "--env", "NOEQUALS" })) == null);
+ try std.testing.expectEqual(@as(usize, 0), (try parseGiven(a, &.{})).?.env.len);
+}
+
+test "bare names are words, not URLs, packages, or paths" {
+ try std.testing.expect(isBareName("linear"));
+ try std.testing.expect(isBareName("brave-search"));
+ try std.testing.expect(!isBareName("@playwright/mcp"));
+ try std.testing.expect(!isBareName("uvx:mcp-server-fetch"));
+ try std.testing.expect(!isBareName("https://mcp.linear.app/mcp"));
+ try std.testing.expect(!isBareName("./server.js"));
+ try std.testing.expect(!isBareName("-x"));
+}
+
+test "fromCatalog matches a slug or an alias and carries needs and limits" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const root = try std.json.parseFromSliceLeaky(Value, a,
+ \\{"version":1,"servers":[
+ \\ {"slug":"linear","name":"Linear","config":{"url":"https://mcp.linear.app/mcp"}},
+ \\ {"slug":"brave-search","name":"Brave Search","aliases":["brave"],"config":{"command":"npx","args":["-y","@brave/brave-search-mcp-server"]},
+ \\ "needs":[{"env":"BRAVE_API_KEY","hint":"an API key"}]},
+ \\ {"slug":"slack","name":"Slack","config":{"url":"https://mcp.slack.com/mcp"},"limitation":"not yet"}]}
+ , .{ .allocate = .alloc_always });
+ const linear = (try fromCatalog(a, root, "Linear")).?;
+ try std.testing.expectEqualStrings("https://mcp.linear.app/mcp", linear.cfg.get("url").?.string);
+ const brave = (try fromCatalog(a, root, "brave")).?;
+ try std.testing.expectEqualStrings("brave-search", brave.name);
+ try std.testing.expectEqualStrings("BRAVE_API_KEY", brave.needs[0].env.?);
+ try std.testing.expectEqualStrings("not yet", (try fromCatalog(a, root, "slack")).?.limitation.?);
+ try std.testing.expect((try fromCatalog(a, root, "jira")) == null);
+}
+
+test "fromRegistry picks only a publisher that owns the name" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ try std.testing.expectEqualStrings("stripe", ownerOf("com.stripe/mcp"));
+ try std.testing.expectEqualStrings("getsentry", ownerOf("io.github.getsentry/sentry-mcp"));
+ const root = try std.json.parseFromSliceLeaky(Value, a,
+ \\{"servers":[
+ \\ {"server":{"name":"io.github.someone/stripe-mcp","packages":[{"registryType":"npm","identifier":"stripe-mcp-x","version":"1.0.0"}]}},
+ \\ {"server":{"name":"com.stripe/mcp","title":"Stripe","remotes":[{"type":"streamable-http","url":"https://mcp.stripe.com"}]}},
+ \\ {"server":{"name":"com.stripe/old","remotes":[{"type":"sse","url":"https://mcp.stripe.com/sse"}]},
+ \\ "_meta":{"io.modelcontextprotocol.registry/official":{"status":"deprecated"}}}]}
+ , .{ .allocate = .alloc_always });
+ const got = try fromRegistry(a, root, "stripe");
+ try std.testing.expectEqualStrings("https://mcp.stripe.com", got.found.cfg.get("url").?.string);
+ try std.testing.expectEqualStrings("stripe", got.found.name);
+
+ const pkg = try std.json.parseFromSliceLeaky(Value, a,
+ \\{"servers":[{"server":{"name":"io.github.acme/acme","packages":[
+ \\ {"registryType":"npm","identifier":"@acme/mcp","version":"2.1.0","transport":{"type":"stdio"},
+ \\ "environmentVariables":[{"name":"ACME_TOKEN","isRequired":true,"description":"token"},{"name":"OPTIONAL"}]}]}}]}
+ , .{ .allocate = .alloc_always });
+ const acme = (try fromRegistry(a, pkg, "acme")).found;
+ try std.testing.expectEqualStrings("npx", acme.cfg.get("command").?.string);
+ try std.testing.expectEqualStrings("@acme/[email protected]", acme.cfg.get("args").?.array.items[1].string);
+ try std.testing.expectEqual(@as(usize, 1), acme.needs.len);
+ try std.testing.expectEqualStrings("ACME_TOKEN", acme.needs[0].env.?);
+
+ const squat = try std.json.parseFromSliceLeaky(Value, a,
+ \\{"servers":[{"server":{"name":"io.github.someone/linear-tools","packages":[{"registryType":"npm","identifier":"linear-tools"}]}}]}
+ , .{ .allocate = .alloc_always });
+ const listed = try fromRegistry(a, squat, "linear");
+ try std.testing.expectEqualStrings("io.github.someone/linear-tools", listed.candidates[0]);
+ try std.testing.expect((try fromRegistry(a, squat, "nothing-like-it")) == .not_found);
+}
diff --git a/src/mcp_cli.zig b/src/mcp_cli.zig
index 800a5773..41326cdf 100644
--- a/src/mcp_cli.zig
+++ b/src/mcp_cli.zig
@@ -205,6 +205,7 @@ fn mcpCliUsage(w: *Io.Writer) !void {
\\ graff mcp list servers in .mcp.json + ~/.codegraff/mcp.json
\\ graff mcp import copy Claude/Cursor MCP + skills into graff folders
\\ graff mcp add <url | @scope/package | uvx:package | '{json}' | -> infer, save, then connect to check it
+ \\ graff mcp add <name> [--env K=V] [--header K=V] look up a server (codegraff.com/mcp, then the MCP registry)
\\ graff mcp add <name> --url <https://...> [--header KEY=VALUE ...]
\\ graff mcp login <name> OAuth login for a remote server
\\ graff mcp add <name> [--env KEY=VALUE ...] -- <command> [args...]
@@ -222,10 +223,15 @@ fn mcpCliUsage(w: *Io.Writer) !void {
/// `add <url|package|json|->` and `add <name> <url|package>`. False when the
/// arguments are an explicit form for the caller to parse.
-fn addInferred(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, add_args: []const []const u8, name_flag: ?[]const u8, verify_after: bool, out: *Io.Writer) !bool {
+fn addInferred(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, environ_map: anytype, add_args: []const []const u8, name_flag: ?[]const u8, verify_after: bool, out: *Io.Writer) !bool {
const add = @import("mcp_add.zig");
+ const catalog = @import("mcp_catalog.zig");
var entries: []const add.Named = &.{};
- if (add_args.len == 2) {
+ const given = if (add_args.len >= 2 and catalog.isBareName(add_args[1])) try catalog.parseGiven(arena, add_args[2..]) else null;
+ if (given) |g| {
+ // `add linear`, `add brave-search --env BRAVE_API_KEY=…`: look the name up.
+ entries = try arena.dupe(add.Named, &.{try catalog.resolve(io, gpa, arena, environ_map, add_args[1], name_flag, g, out)});
+ } else if (add_args.len == 2) {
const token = add_args[1];
if (std.mem.eql(u8, token, "-") or std.mem.startsWith(u8, std.mem.trimStart(u8, token, " \t\r\n"), "{")) {
const text = if (std.mem.eql(u8, token, "-")) blk: {
@@ -381,7 +387,7 @@ pub fn mcpCommand(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, en
}
}
const add_args = kept.items;
- if (try addInferred(io, gpa, arena, home, add_args, name_flag, verify_after, &out.interface)) return;
+ if (try addInferred(io, gpa, arena, home, environ_map, add_args, name_flag, verify_after, &out.interface)) return;
if (add_args.len < 3) {
try mcpCliUsage(&out.interface);
try out.interface.flush();