feat: unified MCP layer (third primitive)

[TimCrooker]

What

Adds MCP as ai-context-kit's third generated primitive, alongside context and skills. Declare MCP servers once in .ai/mcp.json; ai-context build fans them out to each agent client's native config — with optional skill + context backing.

Brain design record: project 61c0f576 (full design + linked architecture decision).

Why

Today MCP config is per-client, per-machine, hand-edited (e.g. ~/.claude.json) — not repo-owned or agent-portable. This makes a server's config and the knowledge to use it a single declarative unit.

How

• Source: .ai/mcp.json registry (core/src/mcp.ts), validated with a secret-literal guard.
• Adapters: pluggable registry (core/src/mcp-adapters/) — v1 ships claude (.mcp.json) and codex (.codex/config.toml, with a collision guard so it never clobbers a hand-written budget config).
• Content outputs, not symlinks: MCP configs flow through the existing writeOutputs path, so verify/diff/staleness come for free.
• Backing reuses existing systems: links to a co-named (or explicit) .ai/skills/<name>; context: true injects an "Available MCP servers" catalog block into AGENTS.md/CLAUDE.md.
• Scope model: project servers are committed; user servers install per-machine via ai-context mcp install <name> --user.
• Secrets: ${VAR} references only; verify fails on a credential literal in a generated file (AICTX_MCP_SECRET_LEAK).
• CLI: ai-context mcp list | install --user | setup.
• Docs: meta-skill section + references/authoring-mcp.md + README.

Tests

8 commits, strict TDD. Full suite green: core 164, cli 23, templates 22 + typecheck + lint. Includes a dogfood integration test fanning posthog/grafana/rn-debugger across claude+codex.

Follow-ups (not in this PR)

• cursor / vscode / gemini adapters (additive — registry is pluggable).
• Migrate list-forge's .mcp.json (posthog/grafana/rn-debugger) into .ai/mcp.json after a kit release.

🤖 Generated with Claude Code

Note

Add unified MCP layer as a third primitive with CLI commands, adapters, and build integration

• Introduces an MCP registry at .ai/mcp.json for declaring MCP servers with scope, transport, targets, and env; parsed and validated by mcp.ts with strict error codes for invalid configs or suspected secret literals.
• Adds per-client adapters (claude.ts, codex.ts) that render managed config files (.mcp.json, .codex/config.toml) from project-scope registry entries during build.
• Integrates MCP generation into the build, diff, and verify engine phases: build writes client configs, diff reports planned changes, and verify flags secret literals in generated files with [AICTX_MCP_SECRET_LEAK].
• Injects an 'Available MCP servers' catalog block into generated AGENTS.md and CLAUDE.md when MCP is configured.
• Adds mcp list, mcp install <name> --user [--dry-run], and mcp setup <name> CLI subcommands for inspecting and installing user-scope servers into the Claude client.
• Risk: existing .codex/config.toml files without the managed marker are preserved but MCP output redirects to .codex/mcp.toml, which may cause confusion if both files exist.

^{Macroscope summarized edc89d1.}

[macroscopeapp]

Approvability

Verdict: Needs human review

Unable to check for correctness in edc89d1. This PR introduces a substantial new feature (unified MCP layer) with new CLI commands, shell command execution, secrets validation, and new file generation. The scope and nature of changes—particularly the new user-facing commands and security-sensitive secrets handling—warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}