{"id":47723030,"url":"https://github.com/lleontor705/cli-orchestrator-mcp","last_synced_at":"2026-04-04T21:01:03.475Z","repository":{"id":347950856,"uuid":"1195025734","full_name":"lleontor705/cli-orchestrator-mcp","owner":"lleontor705","description":"MCP Server for resilient multi-CLI orchestration — route AI tasks to Claude, Gemini, or Codex with retry, circuit breaker, and fallback","archived":false,"fork":false,"pushed_at":"2026-04-02T07:49:55.000Z","size":232,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-03T05:39:33.967Z","etag":null,"topics":["ai-agents","circuit-breaker","claude-code","codex","gemini-cli","mcp","model-context-protocol"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lleontor705.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T05:38:13.000Z","updated_at":"2026-04-02T07:49:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"0ca22343-d314-4795-955c-d336e2babbb4","html_url":"https://github.com/lleontor705/cli-orchestrator-mcp","commit_stats":null,"previous_names":["lleontor705/cli-orchestrator-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/lleontor705/cli-orchestrator-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fcli-orchestrator-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fcli-orchestrator-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fcli-orchestrator-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fcli-orchestrator-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lleontor705","download_url":"https://codeload.github.com/lleontor705/cli-orchestrator-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fcli-orchestrator-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31374051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","circuit-breaker","claude-code","codex","gemini-cli","mcp","model-context-protocol"],"created_at":"2026-04-02T19:52:24.199Z","updated_at":"2026-04-03T20:01:15.416Z","avatar_url":"https://github.com/lleontor705.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" alt=\"cli-orchestrator-mcp\" width=\"600\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eResilient multi-CLI orchestration server for AI agents\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/cli-orchestrator-mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/cli-orchestrator-mcp?color=6366f1\u0026label=npm\u0026style=flat-square\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/lleontor705/cli-orchestrator-mcp/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/lleontor705/cli-orchestrator-mcp/ci.yml?style=flat-square\u0026label=CI\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/node/v/cli-orchestrator-mcp?style=flat-square\u0026color=10b981\" alt=\"node\" /\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/cli-orchestrator-mcp?style=flat-square\u0026color=f59e0b\" alt=\"license\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why cli-orchestrator-mcp?\n\nModern 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.\n\n**cli-orchestrator-mcp** solves this by providing a single [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that:\n\n- **Orchestrates** Claude CLI, Gemini CLI, and Codex CLI through a unified interface\n- **Routes intelligently** — picks the best CLI based on the agent's role\n- **Recovers automatically** — retry with backoff, circuit breaker isolation, and provider fallback\n- **Runs inline** — executes CLIs as local subprocesses, no API keys or cloud calls needed\n\nAny MCP-compatible client (Claude Code, Codex CLI, Gemini CLI, OpenCode, or custom agents) can use it out of the box.\n\n---\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/architecture.svg\" alt=\"Architecture Overview\" width=\"850\" /\u003e\n\u003c/p\u003e\n\nThe 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.\n\n---\n\n## Quick Start\n\n```bash\nnpx -y cli-orchestrator-mcp\n```\n\n**Prerequisites:** Node.js \u003e= 18 and at least one CLI installed and authenticated:\n\n| CLI | Install | Auth |\n|-----|---------|------|\n| Claude | `npm i -g @anthropic-ai/claude-code` | `claude` (interactive login) |\n| Gemini | `npm i -g @google/gemini-cli` | `gemini` (Google auth) |\n| Codex | `npm i -g @openai/codex` | `codex` (OpenAI auth) |\n\n\u003e CLIs handle their own authentication inline — **no API keys or environment variables required**.\n\n---\n\n## Configuration\n\n### Claude Code\n\n```bash\nclaude mcp add cli-orchestrator --transport stdio -- npx -y cli-orchestrator-mcp\n```\n\n### Codex CLI (`~/.codex/config.toml`)\n\n```toml\n[mcp_servers.cli-orchestrator]\ncommand = \"npx\"\nargs = [\"-y\", \"cli-orchestrator-mcp\"]\n```\n\n### Gemini CLI (`settings.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"cli-orchestrator\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cli-orchestrator-mcp\"]\n    }\n  }\n}\n```\n\n### OpenCode (`opencode.json`)\n\n```json5\nmcp: {\n  servers: {\n    \"cli-orchestrator\": { command: \"npx\", args: [\"-y\", \"cli-orchestrator-mcp\"] }\n  }\n}\n```\n\n---\n\n## What is MCP and Why Use It?\n\n[**Model Context Protocol (MCP)**](https://modelcontextprotocol.io) 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**.\n\n**Why MCP for CLI orchestration?**\n\n| Without MCP | With cli-orchestrator-mcp |\n|-------------|---------------------------|\n| Each agent hardcodes CLI calls | Agents call `cli_execute` — one interface for all CLIs |\n| No retry, no fallback, no circuit breaker | Full resilience pipeline built-in |\n| Agent must know which CLI is installed | Auto-detection — server discovers available CLIs |\n| Agent handles errors and timeouts | Server handles errors, redacts secrets, returns clean output |\n| Switching CLI requires code changes | Change the `cli` parameter — or let `cli_route` pick automatically |\n\n**The goal:** Let AI agents focus on *what* to do, not *how* to execute it reliably across multiple CLI tools.\n\n---\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| [`cli_execute`](#cli_execute) | Execute a task with full resilience (retry + circuit breaker + fallback) |\n| [`cli_route`](#cli_route) | Recommend the best CLI based on agent role |\n| [`cli_stats`](#cli_stats) | Health dashboard — installation, circuit breaker, execution stats |\n| [`cli_list`](#cli_list) | List installed CLI providers with paths and strengths |\n\n### `cli_execute`\n\nThe primary tool. Sends a prompt to a CLI provider with the full resilience pipeline.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `cli` | `\"claude\" \\| \"gemini\" \\| \"codex\"` | *required* | Target CLI provider |\n| `prompt` | string (max 100KB) | *required* | Prompt to send |\n| `mode` | `\"generate\" \\| \"analyze\"` | `\"generate\"` | Execution mode |\n| `timeout_seconds` | number (10–1800) | `300` | Global timeout budget (covers all retries and fallbacks) |\n| `allow_fallback` | boolean | `true` | Allow fallback to other CLIs on failure |\n| `cwd` | string | — | Working directory for CLI execution |\n\n**Returns:** `{ success, provider, output, duration_ms, fallback_used, attempts, error? }`\n\n**CLI arguments by provider:**\n\n| Provider | Generate mode | Analyze mode |\n|----------|--------------|--------------|\n| Claude | `-p \u003cprompt\u003e --allowedTools \"\" --max-turns N` | `-p \u003cprompt\u003e --max-turns N` |\n| Gemini | `-e none -p \u003cprompt\u003e` | `-e none -p \u003cprompt\u003e` |\n| Codex | `exec \u003cprompt\u003e --full-auto` | `exec \u003cprompt\u003e --full-auto` |\n\n\u003e `--max-turns` for Claude is calculated dynamically based on remaining timeout budget (~1 turn per 30s, min 2, max 25).\n\n### `cli_route`\n\nRecommends the best available CLI for a given agent role.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `role` | `\"manager\" \\| \"coordinator\" \\| \"developer\" \\| \"researcher\" \\| \"reviewer\" \\| \"architect\"` | Agent role |\n| `task_description` | string (optional) | Task context for better routing |\n\n### `cli_stats`\n\nReturns per-provider health: installed status, path, circuit breaker state, execution/failure/timeout counts, and strengths.\n\n### `cli_list`\n\nReturns all installed CLI providers with their binary paths and declared strengths.\n\n### MCP Resources\n\n| URI | Description |\n|-----|-------------|\n| `mcp://cli-stats` | Real-time health dashboard (JSON) |\n\n### MCP Prompts\n\n| Prompt | Inputs | Description |\n|--------|--------|-------------|\n| `code_review` | `code` (required), `language` (optional) | Code review for bugs, performance, best practices |\n| `architecture_design` | `requirements` (required) | System architecture from requirements |\n\n---\n\n## Role-based Routing\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/role-routing.svg\" alt=\"Role-based CLI Routing\" width=\"750\" /\u003e\n\u003c/p\u003e\n\nEach agent role maps to a **primary CLI** based on its strengths, with automatic fallback to alternatives:\n\n| Role | Primary | Why | Fallback Chain |\n|------|---------|-----|----------------|\n| **Manager** | Gemini | Research, trends, large-context analysis | Claude \u0026rarr; Codex |\n| **Coordinator** | Claude | Reasoning, planning, architecture decisions | Gemini \u0026rarr; Codex |\n| **Developer** | Codex | Code generation, refactoring, full-auto edits | Claude \u0026rarr; Gemini |\n| **Researcher** | Gemini | Knowledge synthesis, web search | Claude \u0026rarr; Codex |\n| **Reviewer** | Claude | Code analysis, debugging, quality review | Gemini \u0026rarr; Codex |\n| **Architect** | Claude | System design, architecture patterns | Gemini \u0026rarr; Codex |\n\n---\n\n## Resilience Pipeline\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/resilience-pipeline.svg\" alt=\"Resilience Pipeline\" width=\"850\" /\u003e\n\u003c/p\u003e\n\n### Global Time Budget\n\nThe 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 \u0026times; 3 attempts \u0026times; timeout = 9\u0026times; the expected wait.\n\n### Circuit Breaker\n\nPer-provider state machine with **separate thresholds** for hard failures and timeouts:\n\n| State | Behavior |\n|-------|----------|\n| **Closed** | Normal — track failures (threshold: 3) and timeouts (threshold: 5) |\n| **Open** | Reject all calls for 60s cooldown |\n| **Half-open** | Allow 1 test request — success closes, failure reopens |\n\n\u003e Timeouts use a higher threshold (5 vs 3) because a slow provider isn't necessarily broken.\n\n### Retry Policy\n\n- **Max retries:** 2 (3 total attempts per provider)\n- **Backoff:** Exponential (base 1s, max 10s) with \u0026plusmn;30% jitter\n- **Retryable:** Rate limits (429), server errors (503), ECONNRESET, ETIMEDOUT\n- **Non-retryable:** Process timeouts (skip directly to fallback), auth errors, permanent failures\n\n### Abort Handling\n\n`AbortSignal` propagates from MCP client through the entire pipeline:\n- Cancels running CLI process immediately via execa\n- Interrupts retry backoff sleep — no wasted wait time\n- Checked between every attempt and every provider\n\n### Progress Notifications\n\nDuring execution, the server sends MCP progress notifications every 5 seconds with enriched context:\n\n```\n[claude] primary, attempt 1, 15s elapsed, 285s remaining\n[gemini] fallback #1, attempt 1, 45s elapsed, 255s remaining\n```\n\n---\n\n## Security\n\n| Layer | Protection |\n|-------|------------|\n| **Environment** | Only essential system vars forwarded (PATH, HOME, TERM, proxy). CLIs authenticate inline. |\n| **Secrets** | API key patterns (`sk-`, `key-`, `AIza`) automatically redacted from all output and errors |\n| **Execution** | No shell — commands built as arrays, never string concatenation. No `shell: true`. |\n| **Prompts** | Large prompts (\u0026gt;30KB) sent via stdin to avoid OS arg-length limits |\n| **Process** | Each CLI runs in isolated subprocess with configurable timeout and buffer limits (10MB) |\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/lleontor705/cli-orchestrator-mcp.git\ncd cli-orchestrator-mcp\nnpm install\nnpm run build          # Compile TypeScript\nnpm run dev            # Run with tsx (no build)\nnpm test               # Unit tests (CI-safe, no CLIs needed)\nnpm run test:all       # All tests including stress \u0026 integration\nnpm run lint           # Type-check (tsc --noEmit)\nnpm run inspect        # Debug with MCP Inspector\n```\n\n### Test Suites\n\n| Command | Scope | Environment |\n|---------|-------|-------------|\n| `npm test` | Unit tests — definitions, detection, circuit breaker, resilience | CI \u0026mdash; fast, mocked |\n| `npm run test:local` | Integration + stress tests | Local \u0026mdash; requires real CLIs |\n| `npm run test:all` | All of the above | Local |\n\n**Stress tests cover:** timeout enforcement, abort/cancellation, concurrent execution (10+), fallback chain timing, large output (5MB+), circuit breaker rapid-fire, large prompt stdin.\n\n### Project Structure\n\n```\nsrc/\n  index.ts                  Entry point (stdio transport)\n  server.ts                 MCP server factory\n  cli/\n    definitions.ts          CLI provider configs \u0026 arg builders\n    detection.ts            Auto-detection with 5-min cache\n    executor.ts             Process execution via execa\n    circuit-breaker.ts      Per-provider state machine\n    resilience.ts           Retry + fallback orchestration\n  tools/\n    orchestrator.ts         MCP tools, resources, prompts\n  types/\n    index.ts                TypeScript types \u0026 routing table\n  utils/\n    env-allowlist.ts        Safe environment filtering\n    redact.ts               Secret redaction\n```\n\n---\n\n## Tech Stack\n\n| Component | Technology |\n|-----------|------------|\n| Runtime | Node.js \u003e= 18 (cross-platform) |\n| Language | TypeScript 5.7 (strict mode) |\n| MCP SDK | @modelcontextprotocol/sdk |\n| Process exec | execa |\n| Circuit breaker | Custom (lightweight, per-provider) |\n| Validation | Zod |\n| Testing | Vitest |\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flleontor705%2Fcli-orchestrator-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flleontor705%2Fcli-orchestrator-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flleontor705%2Fcli-orchestrator-mcp/lists"}