MCP 服务器

cli-orchestrator-mcp

Resilient multi-CLI orchestration server for AI agents that routes tasks to Claude, Gemini, or Codex with automatic retry, circuit breaker, and fallback.

README

Resilient multi-CLI orchestration server for AI agents

Why cli-orchestrator-mcp?

Modern AI workflows often need more than one LLM CLI. Claude excels at reasoning, Gemini at research, Codex at code generation. But managing multiple CLIs — handling failures, retries, fallbacks, and routing — is complex and error-prone.

cli-orchestrator-mcp solves this by providing a single Model Context Protocol (MCP) server that:

Orchestrates Claude CLI, Gemini CLI, and Codex CLI through a unified interface
Routes intelligently — picks the best CLI based on the agent's role
Recovers automatically — retry with backoff, circuit breaker isolation, and provider fallback
Runs inline — executes CLIs as local subprocesses, no API keys or cloud calls needed

Any MCP-compatible client (Claude Code, Codex CLI, Gemini CLI, OpenCode, or custom agents) can use it out of the box.

Architecture

The server sits between your MCP client and the installed CLI tools. When a task arrives via cli_execute, it flows through the resilience pipeline — global time budget, circuit breaker check, process execution, retry logic, and fallback — before returning a redacted, safe response.

Quick Start

npx -y cli-orchestrator-mcp

Prerequisites: Node.js >= 18 and at least one CLI installed and authenticated:

CLI	Install	Auth
Claude	`npm i -g @anthropic-ai/claude-code`	`claude` (interactive login)
Gemini	`npm i -g @google/gemini-cli`	`gemini` (Google auth)
Codex	`npm i -g @openai/codex`	`codex` (OpenAI auth)

CLIs handle their own authentication inline — no API keys or environment variables required.

Configuration

Claude Code

claude mcp add cli-orchestrator --transport stdio -- npx -y cli-orchestrator-mcp

Codex CLI (`~/.codex/config.toml`)

[mcp_servers.cli-orchestrator]
command = "npx"
args = ["-y", "cli-orchestrator-mcp"]

Gemini CLI (`settings.json`)

{
  "mcpServers": {
    "cli-orchestrator": {
      "command": "npx",
      "args": ["-y", "cli-orchestrator-mcp"]
    }
  }
}

OpenCode (`opencode.json`)

mcp: {
  servers: {
    "cli-orchestrator": { command: "npx", args: ["-y", "cli-orchestrator-mcp"] }
  }
}

What is MCP and Why Use It?

Model Context Protocol (MCP) is an open standard that lets AI agents discover and use tools through a unified interface. Instead of hardcoding integrations, agents connect to MCP servers that expose capabilities as tools, resources, and prompts.

Why MCP for CLI orchestration?

Without MCP	With cli-orchestrator-mcp
Each agent hardcodes CLI calls	Agents call `cli_execute` — one interface for all CLIs
No retry, no fallback, no circuit breaker	Full resilience pipeline built-in
Agent must know which CLI is installed	Auto-detection — server discovers available CLIs
Agent handles errors and timeouts	Server handles errors, redacts secrets, returns clean output
Switching CLI requires code changes	Change the `cli` parameter — or let `cli_route` pick automatically

The goal: Let AI agents focus on what to do, not how to execute it reliably across multiple CLI tools.

MCP Tools

Tool	Description
`cli_execute`	Execute a task with full resilience (retry + circuit breaker + fallback)
`cli_route`	Recommend the best CLI based on agent role
`cli_stats`	Health dashboard — installation, circuit breaker, execution stats
`cli_list`	List installed CLI providers with paths and strengths

`cli_execute`

The primary tool. Sends a prompt to a CLI provider with the full resilience pipeline.

Parameter	Type	Default	Description
`cli`	`"claude" \| "gemini" \| "codex"`	required	Target CLI provider
`prompt`	string (max 100KB)	required	Prompt to send
`mode`	`"generate" \| "analyze"`	`"generate"`	Execution mode
`timeout_seconds`	number (10–1800)	`300`	Global timeout budget (covers all retries and fallbacks)
`allow_fallback`	boolean	`true`	Allow fallback to other CLIs on failure
`cwd`	string	—	Working directory for CLI execution

Returns: { success, provider, output, duration_ms, fallback_used, attempts, error? }

CLI arguments by provider:

Provider	Generate mode	Analyze mode
Claude	`-p <prompt> --allowedTools "" --max-turns N`	`-p <prompt> --max-turns N`
Gemini	`-e none -p <prompt>`	`-e none -p <prompt>`
Codex	`exec <prompt> --full-auto`	`exec <prompt> --full-auto`

--max-turns for Claude is calculated dynamically based on remaining timeout budget (~1 turn per 30s, min 2, max 25).

`cli_route`

Recommends the best available CLI for a given agent role.

Parameter	Type	Description
`role`	`"manager" \| "coordinator" \| "developer" \| "researcher" \| "reviewer" \| "architect"`	Agent role
`task_description`	string (optional)	Task context for better routing

`cli_stats`

Returns per-provider health: installed status, path, circuit breaker state, execution/failure/timeout counts, and strengths.

`cli_list`

Returns all installed CLI providers with their binary paths and declared strengths.

MCP Resources

URI	Description
`mcp://cli-stats`	Real-time health dashboard (JSON)

MCP Prompts

Prompt	Inputs	Description
`code_review`	`code` (required), `language` (optional)	Code review for bugs, performance, best practices
`architecture_design`	`requirements` (required)	System architecture from requirements

Role-based Routing

Each agent role maps to a primary CLI based on its strengths, with automatic fallback to alternatives:

Role	Primary	Why	Fallback Chain
Manager	Gemini	Research, trends, large-context analysis	Claude → Codex
Coordinator	Claude	Reasoning, planning, architecture decisions	Gemini → Codex
Developer	Codex	Code generation, refactoring, full-auto edits	Claude → Gemini
Researcher	Gemini	Knowledge synthesis, web search	Claude → Codex
Reviewer	Claude	Code analysis, debugging, quality review	Gemini → Codex
Architect	Claude	System design, architecture patterns	Gemini → Codex

Resilience Pipeline

Global Time Budget

The entire chain — retries and fallbacks — shares a single time budget (default: 300s). Each attempt receives remainingSeconds, not the full timeout. This prevents the classic problem where 3 providers × 3 attempts × timeout = 9× the expected wait.

Circuit Breaker

Per-provider state machine with separate thresholds for hard failures and timeouts:

State	Behavior
Closed	Normal — track failures (threshold: 3) and timeouts (threshold: 5)
Open	Reject all calls for 60s cooldown
Half-open	Allow 1 test request — success closes, failure reopens

Timeouts use a higher threshold (5 vs 3) because a slow provider isn't necessarily broken.

Retry Policy

Max retries: 2 (3 total attempts per provider)
Backoff: Exponential (base 1s, max 10s) with ±30% jitter
Retryable: Rate limits (429), server errors (503), ECONNRESET, ETIMEDOUT
Non-retryable: Process timeouts (skip directly to fallback), auth errors, permanent failures

Abort Handling

AbortSignal propagates from MCP client through the entire pipeline:

Cancels running CLI process immediately via execa
Interrupts retry backoff sleep — no wasted wait time
Checked between every attempt and every provider

Progress Notifications

During execution, the server sends MCP progress notifications every 5 seconds with enriched context:

[claude] primary, attempt 1, 15s elapsed, 285s remaining
[gemini] fallback #1, attempt 1, 45s elapsed, 255s remaining

Security

Layer	Protection
Environment	Only essential system vars forwarded (PATH, HOME, TERM, proxy). CLIs authenticate inline.
Secrets	API key patterns (`sk-`, `key-`, `AIza`) automatically redacted from all output and errors
Execution	No shell — commands built as arrays, never string concatenation. No `shell: true`.
Prompts	Large prompts (>30KB) sent via stdin to avoid OS arg-length limits
Process	Each CLI runs in isolated subprocess with configurable timeout and buffer limits (10MB)

Development

git clone https://github.com/lleontor705/cli-orchestrator-mcp.git
cd cli-orchestrator-mcp
npm install
npm run build          # Compile TypeScript
npm run dev            # Run with tsx (no build)
npm test               # Unit tests (CI-safe, no CLIs needed)
npm run test:all       # All tests including stress & integration
npm run lint           # Type-check (tsc --noEmit)
npm run inspect        # Debug with MCP Inspector

Test Suites

Command	Scope	Environment
`npm test`	Unit tests — definitions, detection, circuit breaker, resilience	CI — fast, mocked
`npm run test:local`	Integration + stress tests	Local — requires real CLIs
`npm run test:all`	All of the above	Local

Stress tests cover: timeout enforcement, abort/cancellation, concurrent execution (10+), fallback chain timing, large output (5MB+), circuit breaker rapid-fire, large prompt stdin.

Project Structure

src/
  index.ts                  Entry point (stdio transport)
  server.ts                 MCP server factory
  cli/
    definitions.ts          CLI provider configs & arg builders
    detection.ts            Auto-detection with 5-min cache
    executor.ts             Process execution via execa
    circuit-breaker.ts      Per-provider state machine
    resilience.ts           Retry + fallback orchestration
  tools/
    orchestrator.ts         MCP tools, resources, prompts
  types/
    index.ts                TypeScript types & routing table
  utils/
    env-allowlist.ts        Safe environment filtering
    redact.ts               Secret redaction

Tech Stack

Component	Technology
Runtime	Node.js >= 18 (cross-platform)
Language	TypeScript 5.7 (strict mode)
MCP SDK	@modelcontextprotocol/sdk
Process exec	execa
Circuit breaker	Custom (lightweight, per-provider)
Validation	Zod
Testing	Vitest

License

MIT