{"id":49597683,"url":"https://github.com/darkiceinteractive/mcp-conductor","last_synced_at":"2026-05-06T07:05:10.172Z","repository":{"id":353443283,"uuid":"1173312730","full_name":"darkiceinteractive/mcp-conductor","owner":"darkiceinteractive","description":"97% fewer tokens. Parallel MCP execution through a sandboxed Deno runtime.","archived":false,"fork":false,"pushed_at":"2026-04-23T22:14:51.000Z","size":414,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T00:22:10.872Z","etag":null,"topics":["ai-tools","claude","deno","mcp","mcp-server","token-optimization","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@darkiceinteractive/mcp-conductor","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/darkiceinteractive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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},"funding":{"github":["mattcrombie-darkice"]}},"created_at":"2026-03-05T08:23:51.000Z","updated_at":"2026-04-22T08:54:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/darkiceinteractive/mcp-conductor","commit_stats":null,"previous_names":["darkiceinteractive/mcp-conductor"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/darkiceinteractive/mcp-conductor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkiceinteractive%2Fmcp-conductor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkiceinteractive%2Fmcp-conductor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkiceinteractive%2Fmcp-conductor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkiceinteractive%2Fmcp-conductor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darkiceinteractive","download_url":"https://codeload.github.com/darkiceinteractive/mcp-conductor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkiceinteractive%2Fmcp-conductor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32594031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-tools","claude","deno","mcp","mcp-server","token-optimization","typescript"],"created_at":"2026-05-04T06:00:58.070Z","updated_at":"2026-05-04T06:01:03.337Z","avatar_url":"https://github.com/darkiceinteractive.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mattcrombie-darkice"],"categories":[],"sub_categories":[],"readme":"# MCP Conductor\n\n**97% fewer tokens. Parallel execution. One `npx` command.**\n\n[![npm version](https://img.shields.io/npm/v/@darkiceinteractive/mcp-conductor.svg?style=flat)](https://www.npmjs.com/package/@darkiceinteractive/mcp-conductor)\n[![npm downloads](https://img.shields.io/npm/dm/@darkiceinteractive/mcp-conductor.svg?style=flat)](https://www.npmjs.com/package/@darkiceinteractive/mcp-conductor)\n[![CI](https://github.com/darkiceinteractive/mcp-conductor/actions/workflows/ci.yml/badge.svg)](https://github.com/darkiceinteractive/mcp-conductor/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Deno](https://img.shields.io/badge/runtime-Deno%202.x-black?logo=deno)](https://deno.land)\n\nMCP Conductor is a single MCP server that orchestrates all your other MCP servers through a sandboxed Deno runtime. Instead of Claude making direct tool calls (and dumping every intermediate result into your context window), Claude writes TypeScript code that runs in an isolated sandbox. Only the final result comes back.\n\n```\nBefore: 45,000 tokens → Claude context window → 45,000 tokens billed\nAfter:  45,000 tokens → Deno sandbox → 800 tokens → Claude context window\n```\n\n**Average measured reduction: 94.3%. Peak: 97.8%.**\n\n---\n\n## Quick Start\n\n### 1. Install Deno\n\n```bash\n# macOS\nbrew install deno\n\n# Linux\ncurl -fsSL https://deno.land/install.sh | sh\n\n# Windows\nwinget install DenoLand.Deno\n```\n\n### 2. Add to Your AI Tool\n\n**Claude Code** (`~/.claude/settings.json`), **Claude Desktop**, **Gemini CLI** (`~/.gemini/settings.json`), **Kimi CLI** (`~/.kimi/mcp.json`), **Cursor** (`.cursor/mcp.json`), **Windsurf** (`~/.codeium/windsurf/mcp_config.json`), **Cline**, or **VS Code** (`.vscode/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-conductor\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@darkiceinteractive/mcp-conductor\"]\n    }\n  }\n}\n```\n\n**OpenAI Codex** (`~/.codex/config.toml`):\n\n```toml\n[mcp_servers.mcp-conductor]\ncommand = \"npx\"\nargs = [\"-y\", \"@darkiceinteractive/mcp-conductor\"]\n```\n\n\u003e **Note:** VS Code uses `\"servers\"` instead of `\"mcpServers\"` and requires `\"type\": \"stdio\"`. See the [full multi-platform guide](./docs/guide/mcp-clients.md) for exact config per platform.\n\n### 3. Restart Your AI Tool\n\nThat's it. Ask your AI to list MCP servers — you should see `mcp-conductor` with its tools.\n\n---\n\n## What This Solves\n\nWhen Claude calls MCP tools directly, every response lands in the context window — raw JSON, file metadata, pagination objects, fields you never asked for. A single GitHub `list_issues` call can return 40,000+ tokens. If you're making 10 calls per task, that's 400,000 tokens before Claude has written a single line of code.\n\nMCP Conductor flips the model: Claude writes TypeScript code that *processes* the tool responses inside a Deno sandbox. The sandbox can call any connected MCP server, filter and aggregate the results, and return only the compact summary. Your context window stays small. Your costs stay low.\n\n```typescript\n// This runs inside the Deno sandbox — not in Claude's context window\nconst [issues, files] = await mcp.batch([\n  () =\u003e mcp.server('github').call('list_issues', { owner: 'myorg', repo: 'myrepo', state: 'open' }),\n  () =\u003e mcp.server('filesystem').call('list_directory', { path: '/src' })\n]);\n\nreturn {\n  openBugs: issues.filter(i =\u003e i.labels.some(l =\u003e l.name === 'bug')).length,\n  tsFiles: files.filter(f =\u003e f.name.endsWith('.ts')).length\n};\n// Returns: {\"openBugs\": 12, \"tsFiles\": 47}  ←  under 100 tokens\n```\n\n---\n\n## How It Works\n\n```\nClaude\n  └── execute_code (writes TypeScript)\n        └── Deno Sandbox (50ms startup, \u003c50MB RAM)\n              ├── mcp.server('github').call(...)     ← your MCP servers\n              ├── mcp.server('filesystem').call(...) ← hidden from Claude\n              └── mcp.server('brave-search').call(...)\n                    └── return { compact: \"summary\" } → back to Claude\n```\n\nThe Deno sandbox runs with minimal permissions:\n- Network: localhost bridge only\n- No filesystem access (MCP handles that)\n- No environment variable access\n- No subprocess spawning\n\n**Why Deno?** 50ms cold start vs 500ms–2s for Docker, under 50MB vs 200MB+ memory overhead, TypeScript natively, granular permission model.\n\n---\n\n## Adding Your Servers\n\nCreate `~/.mcp-conductor.json` to register backend servers:\n\n```json\n{\n  \"exclusive\": true,\n  \"servers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/Users/yourname\"],\n      \"env\": {}\n    },\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n      \"env\": { \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"your-token\" }\n    },\n    \"brave-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@brave/brave-search-mcp-server\", \"--transport\", \"stdio\"],\n      \"env\": { \"BRAVE_API_KEY\": \"your-key\" },\n      \"rateLimit\": {\n        \"requestsPerSecond\": 20,\n        \"burstSize\": 20,\n        \"onLimitExceeded\": \"queue\",\n        \"maxQueueTimeMs\": 30000\n      }\n    },\n    \"memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-memory\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\nSet `\"exclusive\": true` to route *all* MCP calls through the sandbox. This is the recommended setting for maximum token savings — Claude cannot bypass the conductor.\n\n**Hot reload:** Edit the file and save. Changes apply in ~500ms, no restart needed.\n\n---\n\n## The `mcp` API\n\nInside `execute_code`, you have access to the `mcp` object:\n\n```typescript\n// Call a server tool\nconst result = await mcp.server('github').call('list_issues', { owner: 'org', repo: 'repo' });\n\n// Parallel execution — executes all calls simultaneously\nconst [issues, files, searches] = await mcp.batch([\n  () =\u003e mcp.server('github').call('list_issues', { owner: 'org', repo: 'repo' }),\n  () =\u003e mcp.server('filesystem').call('list_directory', { path: '/src' }),\n  () =\u003e mcp.server('brave-search').call('search', { q: 'topic', count: 5 })\n]);\n\n// Batch web searches (handles rate limits automatically)\nconst results = await mcp.batchSearch(['query 1', 'query 2', 'query 3'], { topN: 3 });\n\n// Progress updates (visible in Claude)\nmcp.progress('Processing 500 files...');\n\n// Debug logging\nconsole.log('issue count:', issues.length);\n```\n\n---\n\n## Measuring Your Savings\n\nAfter any workflow, ask Claude to call `get_metrics`:\n\n```json\n{\n  \"totalExecutions\": 47,\n  \"averageCompressionRatio\": 0.943,\n  \"totalTokensSaved\": 1847230,\n  \"averageExecutionMs\": 73,\n  \"lastExecution\": {\n    \"compressionRatio\": 0.978,\n    \"tokensSaved\": 44200,\n    \"inputTokens\": 45000,\n    \"outputTokens\": 800\n  }\n}\n```\n\n`compressionRatio: 0.978` means 97.8% of tokens were processed inside the sandbox rather than billed to your context window. `totalTokensSaved: 1,847,230` is the cumulative count across all 47 executions.\n\n---\n\n## MCP Tools Available to Claude\n\n| Tool | Description |\n|------|-------------|\n| `execute_code` | Run TypeScript in the Deno sandbox with MCP server access |\n| `list_servers` | List all connected backend servers |\n| `discover_tools` | Search for tools across all servers |\n| `get_metrics` | Session statistics and compression ratios |\n| `set_mode` | Switch between `execution`, `passthrough`, or `hybrid` mode |\n| `compare_modes` | Compare how a task runs in each mode |\n| `add_server` | Add a server to the conductor config at runtime |\n| `remove_server` | Remove a server at runtime |\n| `update_server` | Update a server's config (e.g. rotate an API key) without restart |\n| `reload_servers` | Reload config after manual edits |\n| `passthrough_call` | Make a direct tool call (high token cost — debug only) |\n\n---\n\n## CLI Reference\n\n```bash\n# Check system requirements (Node, Deno, Claude config)\nmcp-conductor-cli check\n\n# Show current configuration status\nmcp-conductor-cli status\n\n# Enable exclusive mode (migrates servers to ~/.mcp-conductor.json)\nmcp-conductor-cli enable-exclusive [--dry-run]\n\n# Disable exclusive mode (restores servers to Claude config)\nmcp-conductor-cli disable-exclusive [--dry-run]\n\n# Add/remove/list servers in conductor config\nmcp-conductor-cli config add \u003cname\u003e \u003ccommand\u003e [args...]\nmcp-conductor-cli config remove \u003cname\u003e\nmcp-conductor-cli config servers\n\n# Manage Claude Code permissions (auto-allow all MCP tools)\nmcp-conductor-cli permissions discover --new-only\nmcp-conductor-cli permissions add [--scope project]\n\n# Install CLAUDE.md to teach Claude to use execute_code\nmcp-conductor-cli install-instructions --dir /path/to/project\n```\n\n---\n\n## Recipes\n\n### Parallel GitHub + Filesystem analysis\n\n```typescript\nmcp.progress('Fetching issues and scanning codebase...');\nconst [issues, files] = await mcp.batch([\n  () =\u003e mcp.server('github').call('list_issues', { owner: 'myorg', repo: 'myrepo', state: 'open', per_page: 100 }),\n  () =\u003e mcp.server('filesystem').call('search_files', { path: '/src', pattern: '*.ts' })\n]);\nreturn {\n  openBugs: issues.filter(i =\u003e i.labels.some(l =\u003e l.name === 'bug')).length,\n  tsFileCount: files.length\n};\n```\n\n### Parallel web research\n\n```typescript\nconst topics = ['MCP protocol 2026', 'Deno performance benchmarks', 'token optimization AI'];\nconst results = await mcp.batch(\n  topics.map(q =\u003e () =\u003e mcp.server('brave-search').call('search', { q, count: 5 }))\n);\nreturn results.map((r, i) =\u003e ({ topic: topics[i], topResult: r[0]?.title, url: r[0]?.url }));\n```\n\n### Cross-session memory persistence\n\n```typescript\n// Session 1: store results\nconst analysis = { /* ... your analysis ... */ };\nawait mcp.server('memory').call('store', { key: 'weekly-audit', value: analysis });\nreturn analysis;\n\n// Session 2: retrieve and compare\nconst previous = await mcp.server('memory').call('retrieve', { key: 'weekly-audit' });\n// diff previous vs current...\n```\n\n---\n\n## Troubleshooting\n\n**\"Deno not found\"** — Install Deno, then `source ~/.zshrc` (or open a new terminal). Verify with `deno --version`.\n\n**\"Server not connecting\"** — Validate your JSON: `cat ~/.mcp-conductor.json | python3 -m json.tool`. Check that env vars are set (not still saying `\"your-token\"`).\n\n**\"`exclusive` mode not working\"** — `\"exclusive\": true` must be at the root level, not inside `\"servers\"`.\n\n**\"Rate limit errors from brave-search\"** — Add a `rateLimit` block to the server config (see example above). Set `onLimitExceeded: \"queue\"` to buffer requests.\n\n**\"Config changes not applying\"** — The file watcher requires valid JSON. If you saved a file with a syntax error, fix it and save again.\n\nFull troubleshooting guide: [docs/troubleshooting.md](./docs/troubleshooting.md)\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/darkiceinteractive/mcp-conductor.git\ncd mcp-conductor\nnpm install\nnpm run build\nnpm run test:run           # 673 tests, 82% coverage\nnpm run test:coverage      # with coverage report\nnpm run dev                # watch mode\n```\n\n**Requirements:** Node.js 18+, Deno 2.x\n\n---\n\n## Architecture\n\nFull architecture documentation: [docs/guide/](./docs/guide/)\n\n```\nClaude Code / Claude Desktop\n    │\n    └── MCP Protocol\n            │\n    ┌───────▼──────────────┐\n    │    MCP Conductor      │\n    │  (Node.js MCP server) │\n    │                       │\n    │  execute_code ──────► Deno Subprocess (50ms, \u003c50MB)\n    │  list_servers         │   TypeScript code runs here\n    │  get_metrics          │   MCP calls via HTTP bridge\n    │  add_server           │   Only result exits sandbox\n    └───────────────────────┘\n              │\n    ┌─────────▼──────────────────────────────┐\n    │         HTTP Bridge (localhost)         │\n    └──┬──────────┬──────────┬───────────────┘\n       │          │          │\n   github     filesystem  brave-search  ... (any MCP server)\n```\n\n---\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Getting Started](./docs/guide/getting-started.md) | First-time setup walkthrough |\n| [MCP Clients](./docs/guide/mcp-clients.md) | Setup for Claude, Codex, Gemini, Kimi, VS Code, Cursor, Windsurf, Cline |\n| [Configuration](./docs/configuration.md) | All config options and environment variables |\n| [Architecture](./docs/architecture.md) | System design and data flow |\n| [MCP Tools Reference](./docs/api/tools.md) | All tools available to Claude |\n| [Sandbox API](./docs/api/sandbox-api.md) | The `mcp` object inside execute_code |\n| [CLI Reference](./docs/cli-reference.md) | Command-line tool usage |\n| [Examples](./docs/examples/) | Recipes and patterns |\n| [Benchmarks](./docs/benchmarks/methodology.md) | Token savings methodology and results |\n| [Security](./docs/permissions.md) | Deno sandbox permission model |\n| [Troubleshooting](./docs/troubleshooting.md) | Common issues and fixes |\n\n---\n\n## Contributing\n\nContributions welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n- **Bug reports:** [GitHub Issues](https://github.com/darkiceinteractive/mcp-conductor/issues)\n- **Discussions:** [GitHub Discussions](https://github.com/darkiceinteractive/mcp-conductor/discussions)\n- **Security:** See [SECURITY.md](./SECURITY.md)\n\n---\n\n## Licence\n\nMIT — see [LICENSE](./LICENSE)\n\n---\n\n*Built by [DarkIce Interactive](https://darkiceinteractive.com) · [@darkiceinteractive/mcp-conductor on npm](https://www.npmjs.com/package/@darkiceinteractive/mcp-conductor)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkiceinteractive%2Fmcp-conductor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarkiceinteractive%2Fmcp-conductor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkiceinteractive%2Fmcp-conductor/lists"}