Feature: global/user-level MCP config (e.g. ~/.graff/mcp.json) merged with project .mcp.json — home-level configs currently silently ignored

[justrach]

Summary

graff only loads MCP servers from the workspace-local .mcp.json (mcp_config_path = ".mcp.json" in src/main.zig). There is no user-scoped/global MCP config, so:

1. Globally useful remote servers (e.g. DeepWiki https://mcp.deepwiki.com/mcp, context7) must be re-added to every project via graff mcp add / /mcp add.
2. If a user puts server entries in a home-level config such as ~/.mcpconfig.json (the path several other MCP clients on macOS use, e.g. Claude-style configs), graff silently ignores them — no error, no warning, the tools just never appear. This looks like a broken server and is hard to debug from inside a session.

Repro

1. Write ~/.mcpconfig.json:

   { "mcpServers": { "deepwiki": { "url": "https://mcp.deepwiki.com/mcp" } } }

2. cd into a project with no .mcp.json and run graff (tested with graff --yolo, v0.0.227).
3. Ask the agent which MCP tools exist: no mcp__deepwiki__* tools, nothing in the trace except the MCP registry startup phase.

Expected

• A user-level MCP config (e.g. ~/.graff/mcp.json, or additionally reading ~/.mcpconfig.json) that is merged with the project .mcp.json (project entries win on name conflicts).
• The same consent model applies: stdio servers from any config need trust; remote URL-only servers could use a one-time trust prompt (/mcp trust already handles the live-connect flow).
• Ideally, when a home-level config exists but is intentionally unsupported, log one line at startup (ignoring ~/.mcpconfig.json: unsupported path, use .mcp.json) instead of failing silently.

Actual

Only <cwd>/.mcp.json is read. Confirmed in the v0.0.227 installed binary (strings shows only .mcp.json references) and in source: Registry.init takes a single config_path; the home parameter in src/mcp.zig is used only for OAuth token storage. No GRAFF_MCP_CONFIG-style env override exists either.

Workaround (verified)

Per-project: create .mcp.json with the server entry, then /mcp trust in-session (connects live, no restart), or /mcp add deepwiki --url https://mcp.deepwiki.com/mcp which connects + persists in one step.

Environment

• graff 0.0.227 (installed at ~/bin/graff), macOS (darwin), launched as graff --yolo from zsh.

[justrach]

Clarifying priority: the primary ask is the global/user-level MCP config itself — a single home-scoped file (suggest ~/.graff/mcp.json, same mcpServers schema as .mcp.json) that is loaded at startup and merged with the project .mcp.json (project wins on name conflicts), so servers like DeepWiki work out of the box in every project without per-repo setup.

Consent model can mirror the existing one: stdio servers from the global file still need trust (or --yolo), remote URL-only servers get the same one-time prompt, and /mcp trust already provides the live-connect path.

The 'don't silently ignore ~/.mcpconfig.json' logging note is secondary/nice-to-have, not the fix.

[justrach]

Implementation deep dive (for the picking-up agent)

Verified against the source tree (post-0.0.227 checkout). This is close to a patch plan.

Current architecture

• src/main.zig: pub const mcp_config_path = ".mcp.json" (cwd-relative, the only config read). Around line 371–376, startup calls session_start.initRegistryConsent(io, gpa, arena, out, in, flags, mcp_config_path, mcp_home, ...); mcp_home = homeEnv(init.environ_map) orelse "".
• src/mcp.zig Registry.init(gpa, io, config_path, home, environ_map) !?Registry (~line 83): reads the file, parsed.object.get("mcpServers"), iterates entries, skips the pinned name smolify, calls reg.startServer(...) per entry. Missing file → null (empty live registry). This is the single merge point.
• Consent: workspace servers are untrusted (a repo can ship arbitrary stdio commands) — auto-connect only under --yolo or the startup [y/N] prompt; Registry.trustWorkspace(config_path) (~line 229) implements /mcp trust live-connect. mcp_cli.zig countServersNeedingConsent (~line 34) counts what the prompt lists.
• Persistence: mcp_cli.zig persistMcpServer / persistMcpUrl merge-write entries into .mcp.json (used by both graff mcp add and /mcp add).

Proposed change

1. Global path: ~/.graff/mcp.json (home-derived via the existing homeEnv; ~/.graff/ already holds sessions/traces). Optional override env GRAFF_MCP_CONFIG for tests/XDG-ish setups. Same mcpServers schema — zero new parsing code.
2. Merge in Registry.init: change signature to accept global + workspace paths (or a precedence-ordered slice). Parse global first into a StringArrayHashMap(Value), overlay workspace entries on top (workspace wins on conflict), keep the smolify pin applied to both files, then run the existing single startServer loop over the merged map. Missing global file is not an error; invalid global JSON → one stderr warning, continue with workspace only.
3. Trust split (the important security bit): the global file is user-owned config, same trust level as graff mcp add — its servers connect without the workspace consent prompt. Only workspace-file entries count toward countServersNeedingConsent and the [y/N] prompt. Track origin per server during the merge (a small origin: enum { global, workspace } alongside the name, or connect global entries first unconditionally, then gate workspace entries exactly as today).
4. Shadowing note: workspace-wins means a malicious repo could shadow a global server name — but workspace servers still require consent/--yolo, so the attack surface is unchanged from today. Worth one comment in code.
5. CLI/UX: graff mcp add --global <name> --url ... and /mcp add --global ... persisting to ~/.graff/mcp.json (reuse persistMcpServer/persistMcpUrl with a path parameter). graff mcp list should label each server's origin (global / workspace / core).
6. Secondary: if ~/.mcpconfig.json exists with a non-empty mcpServers and no global file was loaded, print one startup line: note: ignoring ~/.mcpconfig.json (unsupported); use ~/.graff/mcp.json. Kills the silent-failure mode that prompted this issue.

Tests to add

• merge precedence: same name in both files → workspace value wins
• global-only server connects with no consent prompt (and without --yolo)
• workspace server still gated by consent; countServersNeedingConsent ignores global entries
• smolify pin rejected from the global file too
• missing/invalid global file: startup unaffected, warning emitted once
• GRAFF_MCP_CONFIG override points at a temp file in tests