Skip to content

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

Python

mcp: off-lists and a JSON listing for clients

justrach2adf97c781fc
diff --git a/assets/skills/mcp-config.md b/assets/skills/mcp-config.md
index 3e271d94..00cf69c9 100644
--- a/assets/skills/mcp-config.md
+++ b/assets/skills/mcp-config.md
@@ -39,6 +39,10 @@ global one with the same name. Their tools reach the model as
still loads. If tools vanished after an edit, check the file parses first.
- `~/.mcpconfig.json` is not read - that path belongs to other MCP clients.
Startup says so once if it exists.
+- Names under `"disabledMcpServers"` (same object shape, in either file) stay
+ out of the session, including servers graff would otherwise import from
+ another tool's config. Moving an entry back into `mcpServers` turns it on.
+ The global list never removes a server the project file defines.
- A local server starts on first use once graff has seen its tools (they are
cached): the session lists its tools but spawns the process only when a tool
is called. `"startup": "eager"` on an entry starts it with every session;
@@ -52,6 +56,7 @@ global one with the same name. Their tools reach the model as
```sh
graff mcp # list configured servers (global ones tagged)
+graff mcp list --json # the merged set as JSON, with each server's source
graff mcp add <name> -- <command> [args...] # local server
graff mcp add <name> --env KEY=VALUE -- <command> # with env
graff mcp add <name> --url https://host/mcp # remote server
diff --git a/src/mcp.zig b/src/mcp.zig
index 22040d58..87937304 100644
--- a/src/mcp.zig
+++ b/src/mcp.zig
@@ -474,4 +474,5 @@ test {
_ = @import("mcp_cache.zig");
_ = @import("mcp_boot.zig");
_ = @import("mcp_elicitation.zig");
+ _ = @import("mcp_list_json.zig");
}
diff --git a/src/mcp_cli.zig b/src/mcp_cli.zig
index 5336509c..c6225f7c 100644
--- a/src/mcp_cli.zig
+++ b/src/mcp_cli.zig
@@ -208,6 +208,7 @@ fn mcpCliUsage(w: *Io.Writer) !void {
\\ graff mcp install [--directory PATH] [--port N] install HTTP service and client entries
\\ graff mcp serve [--http] [--port N] [--model NAME] [--yolo] expose run_task over stdio or HTTP
\\ graff mcp list servers in .mcp.json + ~/.codegraff/mcp.json
+ \\ graff mcp list --json the same as JSON, with each server's source (no secret values)
\\ graff mcp import copy setup and import this project's Claude history
\\ graff mcp import-session <id> import only one Claude conversation into graff
\\ graff mcp add <url | @scope/package | uvx:package | '{json}' | -> infer, save, then connect to check it
@@ -327,6 +328,11 @@ pub fn mcpCommand(io: Io, gpa: Allocator, arena: Allocator, home: []const u8, en
if (args.len == 0 or std.mem.eql(u8, args[0], "list")) {
const merged = mcp_config.load(io, arena, Io.Dir.cwd(), mcp_config_path, global_path, home, mcp_config.isEnvOverride(environ_map));
+ if (args.len > 1 and std.mem.eql(u8, args[1], "--json")) {
+ try @import("mcp_list_json.zig").write(arena, merged, mcp_config_path, global_path, &out.interface);
+ try out.interface.flush();
+ return;
+ }
try mcp_config.reportInvalid(merged, &out.interface, mcp_config_path, global_path, "", "");
if (merged.servers.count() == 0) {
try out.interface.writeAll("no MCP servers configured. Add one with `graff mcp add <name> -- <command> [args...]`,\nor list servers for every project in ~/" ++ mcp_config.global_rel_path ++ ".\n");
diff --git a/src/mcp_config.zig b/src/mcp_config.zig
index 2f3f9ff5..7902f39f 100644
--- a/src/mcp_config.zig
+++ b/src/mcp_config.zig
@@ -19,6 +19,11 @@
//! same untrusted-server consent gate at startup and the same in-session
//! `/mcp trust`. Writes (`graff mcp add`, `/mcp add`) stay project-local unless
//! `graff mcp add … --everywhere` is asked for — this module only ever reads.
+//!
+//! Either file may also hold `disabledMcpServers`: names graff leaves out of
+//! the merge, imported ones included. A client (Harness's MCP settings) parks
+//! a switched-off server there with its config, or lists an imported name as
+//! `{}`. The global off-list never removes a server the project defines.
const std = @import("std");
const Io = std.Io;
@@ -51,13 +56,37 @@ pub const Merged = struct {
/// still loads: one bad file must not disable MCP everywhere.
invalid_project: bool = false,
invalid_global: bool = false,
+ /// The global file's own `mcpServers`, to tell its entries from imported ones.
+ global: std.json.ObjectMap = .empty,
+ /// Each file's `disabledMcpServers`: names graff leaves out, even when
+ /// another tool's config supplies them. An entry may keep its full config
+ /// (a client switched a server off) or be `{}` (an imported name).
+ global_off: std.json.ObjectMap = .empty,
+ project_off: std.json.ObjectMap = .empty,
+ /// What the off-lists took out of `servers`, with the config each had.
+ disabled: std.json.ObjectMap = .empty,
/// Whether `name` is defined by the global file only.
pub fn isGlobalOnly(self: Merged, name: []const u8) bool {
return self.project.get(name) == null;
}
+
+ pub const Source = enum { project, global, imported };
+
+ /// Which config a server comes from: a graff file (its `mcpServers`, or
+ /// its off-list holding the full entry), else another tool's config.
+ pub fn source(self: Merged, name: []const u8) Source {
+ if (self.project.get(name) != null or hasConfig(self.project_off.get(name))) return .project;
+ if (self.global.get(name) != null or hasConfig(self.global_off.get(name))) return .global;
+ return .imported;
+ }
};
+fn hasConfig(entry: ?Value) bool {
+ const e = entry orelse return false;
+ return e == .object and e.object.count() > 0;
+}
+
/// Resolve the user-level config path: `GRAFF_MCP_CONFIG` when set (an absolute
/// path, mainly for tests and sandboxes), else `{home}/.codegraff/mcp.json`.
/// Null means simply "no global config" — never an error.
@@ -75,38 +104,55 @@ pub fn isEnvOverride(environ_map: anytype) bool {
return false;
}
-/// Read `path` and return its `mcpServers` object. Best-effort throughout:
-/// only "no such file" reads as absent, everything else reads as invalid (and
-/// empty) so a caller can say which file it could not use.
-fn readServers(io: Io, arena: Allocator, dir: Io.Dir, path: []const u8, found: *bool, invalid: *bool) std.json.ObjectMap {
+/// One config file's two tables.
+const Tables = struct {
+ servers: std.json.ObjectMap = .empty,
+ off: std.json.ObjectMap = .empty,
+};
+
+/// Read `path` and return its `mcpServers` and `disabledMcpServers` objects.
+/// Best-effort throughout: only "no such file" reads as absent, everything
+/// else reads as invalid (and empty) so a caller can say which file it could
+/// not use.
+fn readServers(io: Io, arena: Allocator, dir: Io.Dir, path: []const u8, found: *bool, invalid: *bool) Tables {
const text = dir.readFileAlloc(io, path, arena, .limited(1 << 20)) catch |err| switch (err) {
- error.FileNotFound => return .empty,
+ error.FileNotFound => return .{},
// A directory, a permission denial or a file over the 1 MiB limit is a
// config the user meant graff to read. Silently treating it as "no
// config" is how a whole MCP setup disappears without a word.
else => {
found.* = true;
invalid.* = true;
- return .empty;
+ return .{};
},
};
found.* = true;
const parsed = std.json.parseFromSliceLeaky(Value, arena, text, .{ .allocate = .alloc_always }) catch {
invalid.* = true;
- return .empty;
+ return .{};
};
if (parsed != .object) {
invalid.* = true;
- return .empty;
+ return .{};
}
- const servers = parsed.object.get("mcpServers") orelse return .empty;
- if (servers != .object) {
- invalid.* = true;
- return .empty;
+ var tables: Tables = .{};
+ if (parsed.object.get("mcpServers")) |servers| {
+ if (servers != .object) {
+ invalid.* = true;
+ return .{};
+ }
+ tables.servers = servers.object;
}
- return servers.object;
+ // A malformed off-list is ignored rather than invalidating the servers.
+ if (parsed.object.get(off_key)) |off| if (off == .object) {
+ tables.off = off.object;
+ };
+ return tables;
}
+/// The off-list key, shared with clients that switch servers off.
+pub const off_key = "disabledMcpServers";
+
/// Merge the user-level and workspace configs into one `mcpServers` set. `dir`
/// is the workspace root (`Io.Dir.cwd()` in production, a tmp dir in tests) and
/// `global_path` may be absolute — an absolute path ignores the directory
@@ -121,17 +167,22 @@ fn readServers(io: Io, arena: Allocator, dir: Io.Dir, path: []const u8, found: *
/// file is unchanged. A missing or invalid override is not an off-switch.
pub fn load(io: Io, arena: Allocator, dir: Io.Dir, project_path: []const u8, global_path: ?[]const u8, home: []const u8, global_is_override: bool) Merged {
var merged: Merged = .{};
- const global = if (global_path) |p|
+ const global_tables: Tables = if (global_path) |p|
readServers(io, arena, dir, p, &merged.found, &merged.invalid_global)
else
- std.json.ObjectMap.empty;
+ .{};
+ const global = global_tables.servers;
+ merged.global = global;
+ merged.global_off = global_tables.off;
// #549: existing + valid + empty override → MCP stays off. `found` is
// already true (the file existed), so Registry.init does not treat this
// as "no config" and then pick up a project file on a later read.
if (global_is_override and merged.found and !merged.invalid_global and global.count() == 0)
return merged;
- merged.project = readServers(io, arena, dir, project_path, &merged.found, &merged.invalid_project);
+ const project_tables = readServers(io, arena, dir, project_path, &merged.found, &merged.invalid_project);
+ merged.project = project_tables.servers;
+ merged.project_off = project_tables.off;
// Global first, project second: the later `put` for a name overwrites, so
// the workspace keeps the final say over its own tooling.
@@ -142,9 +193,24 @@ pub fn load(io: Io, arena: Allocator, dir: Io.Dir, project_path: []const u8, glo
// Plugin / Claude / Cursor / Grok configs fill names still missing. They
// never beat a graff file. `home` empty keeps tests off the real $HOME.
plugins.mergeMcp(io, arena, home, dir, &merged.servers, &merged.found);
+ // Off-lists last, so they reach imported names too. A project defining a
+ // server itself keeps it even if the global file switched that name off.
+ var global_off_it = merged.global_off.iterator();
+ while (global_off_it.next()) |entry| {
+ if (merged.project.get(entry.key_ptr.*) == null) switchOff(arena, &merged, entry.key_ptr.*, entry.value_ptr.*);
+ }
+ var project_off_it = merged.project_off.iterator();
+ while (project_off_it.next()) |entry| switchOff(arena, &merged, entry.key_ptr.*, entry.value_ptr.*);
return merged;
}
+/// Take `name` out of the merged set, keeping the config it had (or the
+/// off-list's own entry when nothing supplied one) for listings.
+fn switchOff(arena: Allocator, merged: *Merged, name: []const u8, off_entry: Value) void {
+ const config = if (merged.servers.fetchOrderedRemove(name)) |kv| kv.value else off_entry;
+ if (merged.disabled.get(name) == null) merged.disabled.put(arena, name, config) catch {};
+}
+
/// Name every config file that existed but could not be used. A file graff
/// cannot parse must never read back as "nothing configured" — that is exactly
/// the case where the user needs to be told which file to look at, and with two
@@ -325,6 +391,46 @@ test "a populated GRAFF_MCP_CONFIG override still merges the project file (#549)
try testing.expect(!merged.isGlobalOnly("local"));
}
+test "off-lists take servers out of the merge, imported names included" {
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ var tmp = testing.tmpDir(.{});
+ defer tmp.cleanup();
+ try tmp.dir.writeFile(testing.io, .{ .sub_path = "global.json", .data =
+ \\{"mcpServers":{"docs":{"url":"https://g/mcp"},"kept":{"command":"/bin/kept"}},
+ \\ "disabledMcpServers":{"parked":{"command":"/bin/parked"},"kept":{},"local":{}}}
+ });
+ try tmp.dir.writeFile(testing.io, .{ .sub_path = ".mcp.json", .data =
+ \\{"mcpServers":{"local":{"command":"./srv"}},"disabledMcpServers":{"docs":{}}}
+ });
+
+ const merged = loadTmp(arena_state.allocator(), tmp.dir);
+ // The project's off-list beats a global entry; the global off-list does
+ // not beat a server the project defines.
+ try testing.expect(merged.servers.get("docs") == null);
+ try testing.expect(merged.servers.get("local") != null);
+ try testing.expect(merged.servers.get("kept") == null);
+ try testing.expect(merged.servers.get("parked") == null);
+ try testing.expectEqualStrings("https://g/mcp", merged.disabled.get("docs").?.object.get("url").?.string);
+ try testing.expectEqualStrings("/bin/parked", merged.disabled.get("parked").?.object.get("command").?.string);
+ try testing.expect(merged.disabled.get("local") == null);
+ try testing.expectEqual(Merged.Source.global, merged.source("docs"));
+ try testing.expectEqual(Merged.Source.global, merged.source("parked"));
+ try testing.expectEqual(Merged.Source.project, merged.source("local"));
+ try testing.expectEqual(Merged.Source.imported, merged.source("from-elsewhere"));
+}
+
+test "a malformed off-list leaves the servers alone" {
+ var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+ defer arena_state.deinit();
+ var tmp = testing.tmpDir(.{});
+ defer tmp.cleanup();
+ try tmp.dir.writeFile(testing.io, .{ .sub_path = ".mcp.json", .data = "{\"mcpServers\":{\"local\":{\"command\":\"./srv\"}},\"disabledMcpServers\":[\"local\"]}" });
+ const merged = loadTmp(arena_state.allocator(), tmp.dir);
+ try testing.expect(!merged.invalid_project);
+ try testing.expect(merged.servers.get("local") != null);
+}
+
test "a missing or invalid GRAFF_MCP_CONFIG override is not an off-switch (#549)" {
var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
defer arena_state.deinit();
diff --git a/src/mcp_list_json.zig b/src/mcp_list_json.zig
new file mode 100644
index 00000000..ec1d5f1d
--- /dev/null
+++ b/src/mcp_list_json.zig
@@ -0,0 +1,102 @@
+//! `graff mcp list --json`: the merged MCP set as data, for clients (Harness's
+//! MCP settings) that show and edit what graff will connect. Each server says
+//! where it comes from (`project`, `global`, or `imported` from another tool's
+//! config) and whether an off-list switched it off. Env and header VALUES are
+//! never printed, only their names: they are often tokens.
+
+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");
+
+const Server = struct {
+ name: []const u8,
+ source: mcp_config.Merged.Source,
+ enabled: bool,
+ command: ?[]const u8 = null,
+ args: []const []const u8 = &.{},
+ url: ?[]const u8 = null,
+ envKeys: []const []const u8 = &.{},
+ headerKeys: []const []const u8 = &.{},
+};
+
+fn keysOf(arena: Allocator, cfg: std.json.ObjectMap, field: []const u8) []const []const u8 {
+ const obj = cfg.get(field) orelse return &.{};
+ if (obj != .object) return &.{};
+ return arena.dupe([]const u8, obj.object.keys()) catch &.{};
+}
+
+fn server(arena: Allocator, merged: mcp_config.Merged, name: []const u8, cfg: Value, enabled: bool) Server {
+ var out: Server = .{ .name = name, .source = merged.source(name), .enabled = enabled };
+ if (cfg != .object) return out;
+ const o = cfg.object;
+ if (o.get("command")) |c| if (c == .string) {
+ out.command = c.string;
+ };
+ if (o.get("url")) |u| if (u == .string) {
+ out.url = u.string;
+ };
+ if (o.get("args")) |a| if (a == .array) {
+ var args: std.ArrayList([]const u8) = .empty;
+ for (a.array.items) |item| if (item == .string) args.append(arena, item.string) catch {};
+ out.args = args.items;
+ };
+ out.envKeys = keysOf(arena, o, "env");
+ out.headerKeys = keysOf(arena, o, "headers");
+ return out;
+}
+
+pub fn write(arena: Allocator, merged: mcp_config.Merged, project_path: []const u8, global_path: ?[]const u8, w: *Io.Writer) !void {
+ var servers: std.ArrayList(Server) = .empty;
+ var it = merged.servers.iterator();
+ while (it.next()) |e| try servers.append(arena, server(arena, merged, e.key_ptr.*, e.value_ptr.*, true));
+ var off = merged.disabled.iterator();
+ while (off.next()) |e| try servers.append(arena, server(arena, merged, e.key_ptr.*, e.value_ptr.*, false));
+ var s: std.json.Stringify = .{ .writer = w };
+ try s.write(.{
+ .globalPath = global_path,
+ .projectPath = project_path,
+ .invalidGlobal = merged.invalid_global,
+ .invalidProject = merged.invalid_project,
+ .servers = servers.items,
+ });
+ try w.writeByte('\n');
+}
+
+test "the JSON listing tags sources, carries off-listed servers, and never prints values" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ var tmp = std.testing.tmpDir(.{});
+ defer tmp.cleanup();
+ try tmp.dir.writeFile(std.testing.io, .{ .sub_path = "global.json", .data =
+ \\{"mcpServers":{"docs":{"url":"https://g/mcp","headers":{"Authorization":"Bearer secret"}}},
+ \\ "disabledMcpServers":{"parked":{"command":"/bin/parked","args":["-v"],"env":{"TOKEN":"hidden"}}}}
+ });
+ try tmp.dir.writeFile(std.testing.io, .{ .sub_path = ".mcp.json", .data =
+ \\{"mcpServers":{"local":{"command":"./srv","args":["--root","."]}}}
+ });
+ const merged = mcp_config.load(std.testing.io, arena, tmp.dir, ".mcp.json", "global.json", "", false);
+ var aw: Io.Writer.Allocating = .init(arena);
+ try write(arena, merged, ".mcp.json", "global.json", &aw.writer);
+ const text = aw.writer.buffered();
+ try std.testing.expect(std.mem.indexOf(u8, text, "secret") == null);
+ try std.testing.expect(std.mem.indexOf(u8, text, "hidden") == null);
+
+ const parsed = try std.json.parseFromSliceLeaky(Value, arena, text, .{});
+ const list = parsed.object.get("servers").?.array.items;
+ try std.testing.expectEqual(@as(usize, 3), list.len);
+ const find = struct {
+ fn by(items: []const Value, name: []const u8) std.json.ObjectMap {
+ for (items) |item| if (std.mem.eql(u8, item.object.get("name").?.string, name)) return item.object;
+ unreachable;
+ }
+ }.by;
+ try std.testing.expectEqualStrings("global", find(list, "docs").get("source").?.string);
+ try std.testing.expectEqualStrings("Authorization", find(list, "docs").get("headerKeys").?.array.items[0].string);
+ try std.testing.expectEqualStrings("project", find(list, "local").get("source").?.string);
+ try std.testing.expectEqualStrings(".", find(list, "local").get("args").?.array.items[1].string);
+ try std.testing.expect(!find(list, "parked").get("enabled").?.bool);
+ try std.testing.expectEqualStrings("TOKEN", find(list, "parked").get("envKeys").?.array.items[0].string);
+}