mmcp: Instructions file for Codex

Repository Guidelines

Project Overview

mmcp is a CLI tool to manage MCP (Model Context Protocol) server definitions in one centralized config (~/.mmcp.json) and apply them to various agent configs (Claude Code, Claude Desktop, Cursor, Codex CLI, Gemini CLI, GitHub Copilot CLI).

Essential Commands

# Development workflow
bun install                 # Install dependencies
bun run lint                # Run Biome linter (read-only)
bun run fmt                 # Format and fix with Biome (writes changes)
bun run typecheck           # TypeScript type checking
bun run build               # Build CLI to dist/index.js
bun test                    # Run all tests
bun test <file>             # Run specific test file

# Pre-commit check (same as CI)
bun run lint && bun run typecheck && bun run build && bun test

Architecture

Agent Adapter Pattern

The core architecture uses an adapter pattern for supporting multiple agents. Each agent has different config formats (JSON, TOML) and locations:

• src/lib/agents/adapter.ts: Defines AgentAdapter interface with id, applyConfig(), and configPath() methods
• src/lib/agents/registry.ts: Central registry of all agent adapters; use getAgentById() to retrieve adapters
• Individual adapters (claude-code.ts, codex-cli.ts, etc.): Implement agent-specific logic:
  • JSON-based agents (Claude Code, Claude Desktop, Cursor, Gemini CLI, GitHub Copilot CLI) merge MCP servers into existing JSON configs
  • TOML-based agents (Codex CLI) use @shopify/toml-patch to patch TOML content

Adding a new agent:

1. Create adapter class in src/lib/agents/<agent-name>.ts implementing AgentAdapter
2. Implement applyConfig() to merge mmcp's Config into agent's config file
3. Register in src/lib/agents/registry.ts
4. Update README.md supported agents table

Config Management

• src/lib/config.ts: Manages ~/.mmcp.json with Zod schema validation
• Config schema: { mode: "merge"|"replace", agents: string[], mcpServers: Record<string, MCPServer> } (mode defaults to merge)
• MCPServer schema allows url, command, args, and env (all optional/partial)
• Apply mode merge keeps existing agent entries unless overridden by mmcp, while replace rewrites each agent's MCP servers solely from mmcp.