@darkiceinteractive/mcp-conductor 1.0.0 → 1.1.0

package/README.md

@@ -1,558 +1,389 @@
 # MCP Conductor
 
-An MCP server that orchestrates code execution in a sandboxed Deno environment with access to all your MCP servers as APIs. Instead of Claude making direct tool calls (high token usage), Claude writes code that runs in a sandboxed environment. Intermediate data stays in the sandbox; only compact results return to Claude's context.
+**97% fewer tokens. Parallel execution. One `npx` command.**
 
-**Key Benefits:**
-- 90-98% token reduction for complex workflows
-- Sub-second overhead for code execution
-- Works with any MCP server
-- Secure Deno sandbox with minimal permissions
+[![npm version](https://img.shields.io/npm/v/@darkiceinteractive/mcp-conductor.svg?style=flat)](https://www.npmjs.com/package/@darkiceinteractive/mcp-conductor)
+[![npm downloads](https://img.shields.io/npm/dm/@darkiceinteractive/mcp-conductor.svg?style=flat)](https://www.npmjs.com/package/@darkiceinteractive/mcp-conductor)
+[![CI](https://github.com/darkiceinteractive/mcp-conductor/actions/workflows/ci.yml/badge.svg)](https://github.com/darkiceinteractive/mcp-conductor/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Deno](https://img.shields.io/badge/runtime-Deno%202.x-black?logo=deno)](https://deno.land)
 
-## Requirements
+MCP 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.
 
-- **Node.js 18+** - JavaScript runtime
-- **Deno 1.40+** - Secure sandbox runtime (install from https://deno.land)
-
-## Installation
-
-### Quick Start (npm - Recommended)
-
-Add to your Claude Desktop configuration:
-
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "mcp-conductor": {
-      "command": "npx",
-      "args": ["-y", "@darkiceinteractive/mcp-conductor"]
-    }
-  }
-}
+```
+Before: 45,000 tokens → Claude context window → 45,000 tokens billed
+After:  45,000 tokens → Deno sandbox → 800 tokens → Claude context window
 ```
 
-Restart Claude Desktop - that's it! The package auto-downloads on first use.
+**Average measured reduction: 94.3%. Peak: 97.8%.**
 
-> **Prerequisite:** [Deno](https://deno.land) must be installed for the sandbox runtime.
+---
 
-### Alternative: From Source
+## Quick Start
 
-For development or customisation:
+### 1. Install Deno
 
 ```bash
-git clone https://github.com/darkiceinteractive/mcp-conductor.git
-cd mcp-conductor
-npm run setup
-node dist/bin/cli.js enable-exclusive
-```
+# macOS
+brew install deno
 
-The `enable-exclusive` command migrates your existing MCP servers to a conductor-managed config, ensuring Claude **must** use `execute_code` for all MCP operations. This provides maximum token savings (90%+).
+# Linux
+curl -fsSL https://deno.land/install.sh | sh
 
-### Manual Configuration
+# Windows
+winget install DenoLand.Deno
+```
 
-If not using npx, add to Claude Desktop configuration:
+### 2. Add to Your AI Tool
 
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+**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`):
 
 ```json
 {
   "mcpServers": {
     "mcp-conductor": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-conductor/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "@darkiceinteractive/mcp-conductor"]
     }
   }
 }
 ```
 
-> **Important:** Replace `/absolute/path/to/mcp-conductor` with the actual path where you cloned the repository.
-
-Or use the CLI to add it automatically:
+**OpenAI Codex** (`~/.codex/config.toml`):
 
-```bash
-node dist/bin/cli.js init
+```toml
+[mcp_servers.mcp-conductor]
+command = "npx"
+args = ["-y", "@darkiceinteractive/mcp-conductor"]
 ```
 
-### Step 3: Restart Claude Desktop
-
-Restart Claude Desktop to load the new server. You should see "mcp-conductor" in the MCP servers list.
-
-## Usage
-
-In Claude, you can now use the `execute_code` tool:
-
-```typescript
-// List files and count by type
-const fs = mcp.server('filesystem');
-const files = await fs.call('list_directory', { path: '/project/src' });
-const counts = { ts: 0, js: 0, other: 0 };
-for (const f of files.entries) {
-  if (f.name.endsWith('.ts')) counts.ts++;
-  else if (f.name.endsWith('.js')) counts.js++;
-  else counts.other++;
-}
-return counts;
-```
+> **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.
 
-## CLI Commands
+### 3. Restart Your AI Tool
 
-Run from the project directory:
+That's it. Ask your AI to list MCP servers — you should see `mcp-conductor` with its tools.
 
-```bash
-# Check system requirements
-node dist/bin/cli.js check
+---
 
-# Show configuration status
-node dist/bin/cli.js status
+## What This Solves
 
-# Add to Claude Desktop config automatically
-node dist/bin/cli.js init [--dry-run]
+When 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.
 
-# Start the server manually (usually not needed - Claude Desktop starts it)
-node dist/bin/cli.js serve [options]
-```
+MCP 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.
 
-### Serve Options
+```typescript
+// This runs inside the Deno sandbox — not in Claude's context window
+const [issues, files] = await mcp.batch([
+  () => mcp.server('github').call('list_issues', { owner: 'myorg', repo: 'myrepo', state: 'open' }),
+  () => mcp.server('filesystem').call('list_directory', { path: '/src' })
+]);
 
-```bash
-node dist/bin/cli.js serve \
-  --port 0 \             # Bridge port (0 = dynamic allocation, default)
-  --mode execution \     # Mode: execution|passthrough|hybrid
-  --timeout 30000 \      # Default timeout in ms
-  --verbose              # Enable debug logging
+return {
+  openBugs: issues.filter(i => i.labels.some(l => l.name === 'bug')).length,
+  tsFiles: files.filter(f => f.name.endsWith('.ts')).length
+};
+// Returns: {"openBugs": 12, "tsFiles": 47}  ←  under 100 tokens
 ```
 
-> **Note**: Port 0 (the default) enables dynamic port allocation, allowing multiple instances of MCP Conductor to run simultaneously without port conflicts.
+---
 
-### Exclusive Mode Commands
+## How It Works
 
-Exclusive mode ensures Claude ONLY sees mcp-conductor, forcing all MCP operations through `execute_code` for maximum token savings.
-
-```bash
-# Enable exclusive mode (recommended)
-# Migrates servers from Claude config to ~/.mcp-conductor.json
-node dist/bin/cli.js enable-exclusive [--dry-run]
-
-# Disable exclusive mode
-# Restores servers back to Claude config
-node dist/bin/cli.js disable-exclusive [--dry-run]
-
-# View current configuration status
-node dist/bin/cli.js config show
-
-# List servers in conductor config
-node dist/bin/cli.js config servers
-
-# Add a server to conductor config
-node dist/bin/cli.js config add <name> <command> [args...]
-
-# Remove a server from conductor config
-node dist/bin/cli.js config remove <name>
 ```
-
-### Permissions Commands
-
-Manage Claude Code MCP tool permissions to auto-allow all discovered tools:
-
-```bash
-# List currently configured MCP permissions in your settings
-node dist/bin/cli.js permissions list
-
-# Discover all available MCP tools and show new permissions needed
-node dist/bin/cli.js permissions discover --new-only
-
-# Show as JSON (for manual copying)
-node dist/bin/cli.js permissions discover --json
-
-# Preview what would be added to settings
-node dist/bin/cli.js permissions add --dry-run
-
-# Add all new permissions to user settings (~/.claude/settings.json)
-node dist/bin/cli.js permissions add
-
-# Add to project settings instead (.claude/settings.json)
-node dist/bin/cli.js permissions add --scope project
+Claude
+  └── execute_code (writes TypeScript)
+        └── Deno Sandbox (50ms startup, <50MB RAM)
+              ├── mcp.server('github').call(...)     ← your MCP servers
+              ├── mcp.server('filesystem').call(...) ← hidden from Claude
+              └── mcp.server('brave-search').call(...)
+                    └── return { compact: "summary" } → back to Claude
 ```
 
-This solves the common issue of seeing permission prompts for MCP tools. Run `permissions add` once to auto-approve all tools from your configured MCP servers.
+The Deno sandbox runs with minimal permissions:
+- Network: localhost bridge only
+- No filesystem access (MCP handles that)
+- No environment variable access
+- No subprocess spawning
 
-### Project Instructions
+**Why Deno?** 50ms cold start vs 500ms–2s for Docker, under 50MB vs 200MB+ memory overhead, TypeScript natively, granular permission model.
 
-Install project-level instructions to teach Claude to use `execute_code` for batch operations:
+---
 
-```bash
-# Install CLAUDE.md to a project directory
-node dist/bin/cli.js install-instructions --dir /path/to/project
+## Adding Your Servers
 
-# Append to existing CLAUDE.md
-node dist/bin/cli.js install-instructions --append
+Create `~/.mcp-conductor.json` to register backend servers:
 
-# Preview what would be created
-node dist/bin/cli.js install-instructions --dry-run
+```json
+{
+  "exclusive": true,
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname"],
+      "env": {}
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token" }
+    },
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
+      "env": { "BRAVE_API_KEY": "your-key" },
+      "rateLimit": {
+        "requestsPerSecond": 20,
+        "burstSize": 20,
+        "onLimitExceeded": "queue",
+        "maxQueueTimeMs": 30000
+      }
+    },
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "env": {}
+    }
+  }
+}
 ```
 
-This creates a `CLAUDE.md` file that instructs Claude to prefer `execute_code` for multi-step MCP operations, ensuring token savings across all your projects.
-
-## MCP Tools
+Set `"exclusive": true` to route *all* MCP calls through the sandbox. This is the recommended setting for maximum token savings — Claude cannot bypass the conductor.
 
-### execute_code
+**Hot reload:** Edit the file and save. Changes apply in ~500ms, no restart needed.
 
-Execute TypeScript/JavaScript code in a sandboxed Deno environment.
+---
 
-```typescript
-// Access MCP servers
-const github = mcp.server('github');
-const result = await github.call('search_repos', { query: 'ai' });
-
-// Or use attribute-style access
-const result = await mcp.github.call('search_repos', { query: 'ai' });
+## The `mcp` API
 
-// Search for tools
-const tools = await mcp.searchTools('file');
+Inside `execute_code`, you have access to the `mcp` object:
 
-// Log (captured in response)
-mcp.log('Processing...');
+```typescript
+// Call a server tool
+const result = await mcp.server('github').call('list_issues', { owner: 'org', repo: 'repo' });
+
+// Parallel execution — executes all calls simultaneously
+const [issues, files, searches] = await mcp.batch([
+  () => mcp.server('github').call('list_issues', { owner: 'org', repo: 'repo' }),
+  () => mcp.server('filesystem').call('list_directory', { path: '/src' }),
+  () => mcp.server('brave-search').call('search', { q: 'topic', count: 5 })
+]);
 
-// Report progress (for streaming)
-mcp.progress(50, 'Halfway done');
+// Batch web searches (handles rate limits automatically)
+const results = await mcp.batchSearch(['query 1', 'query 2', 'query 3'], { topN: 3 });
 
-// Smart batching with auto rate limit detection
-const results = await mcp.batch([
-  { server: 'github', tool: 'search_repositories', params: { query: 'ai' } },
-  { server: 'github', tool: 'search_repositories', params: { query: 'ml' } },
-]);
+// Progress updates (visible in Claude)
+mcp.progress('Processing 500 files...');
 
-// Convenience method for batched web searches (requires brave-search)
-const searchResults = await mcp.batchSearch([
-  'query 1',
-  'query 2',
-  'query 3'
-], { topN: 3 });
+// Debug logging
+console.log('issue count:', issues.length);
 ```
 
-### list_servers
+---
 
-List all connected MCP servers and their tools.
+## Measuring Your Savings
 
-### discover_tools
+After any workflow, ask Claude to call `get_metrics`:
 
-Search for tools across all servers.
+```json
+{
+  "totalExecutions": 47,
+  "averageCompressionRatio": 0.943,
+  "totalTokensSaved": 1847230,
+  "averageExecutionMs": 73,
+  "lastExecution": {
+    "compressionRatio": 0.978,
+    "tokensSaved": 44200,
+    "inputTokens": 45000,
+    "outputTokens": 800
+  }
+}
+```
 
-### get_metrics
+`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.
 
-Get session metrics including token savings.
+---
 
-### set_mode
+## MCP Tools Available to Claude
 
-Switch between operation modes:
-- `execution` - All requests go through code executor (default, maximum token savings)
-- `passthrough` - Direct tool calls without code execution (for debugging)
-- `hybrid` - Automatic selection based on task complexity
+| Tool | Description |
+|------|-------------|
+| `execute_code` | Run TypeScript in the Deno sandbox with MCP server access |
+| `list_servers` | List all connected backend servers |
+| `discover_tools` | Search for tools across all servers |
+| `get_metrics` | Session statistics and compression ratios |
+| `set_mode` | Switch between `execution`, `passthrough`, or `hybrid` mode |
+| `compare_modes` | Compare how a task runs in each mode |
+| `add_server` | Add a server to the conductor config at runtime |
+| `remove_server` | Remove a server at runtime |
+| `update_server` | Update a server's config (e.g. rotate an API key) without restart |
+| `reload_servers` | Reload config after manual edits |
+| `passthrough_call` | Make a direct tool call (high token cost — debug only) |
 
-### compare_modes
+---
 
-Analyse how a task would be handled in different modes.
+## CLI Reference
 
-### reload_servers
+```bash
+# Check system requirements (Node, Deno, Claude config)
+mcp-conductor-cli check
 
-Reload MCP server configurations (useful after editing claude_desktop_config.json).
+# Show current configuration status
+mcp-conductor-cli status
 
-### passthrough_call
+# Enable exclusive mode (migrates servers to ~/.mcp-conductor.json)
+mcp-conductor-cli enable-exclusive [--dry-run]
 
-Make direct tool calls without code execution. **Note:** This tool has high token cost and should only be used for debugging.
+# Disable exclusive mode (restores servers to Claude config)
+mcp-conductor-cli disable-exclusive [--dry-run]
 
-### add_server
+# Add/remove/list servers in conductor config
+mcp-conductor-cli config add <name> <command> [args...]
+mcp-conductor-cli config remove <name>
+mcp-conductor-cli config servers
 
-Add an MCP server to conductor config at runtime without restarting Claude.
+# Manage Claude Code permissions (auto-allow all MCP tools)
+mcp-conductor-cli permissions discover --new-only
+mcp-conductor-cli permissions add [--scope project]
 
-### remove_server
+# Install CLAUDE.md to teach Claude to use execute_code
+mcp-conductor-cli install-instructions --dir /path/to/project
+```
 
-Remove an MCP server from conductor config at runtime.
+---
 
-### update_server
+## Recipes
 
-Update an existing server's configuration (command, args, or environment variables) without removing and re-adding it. Useful for updating API keys after upgrading a service plan.
+### Parallel GitHub + Filesystem analysis
 
 ```typescript
-// Update API key for brave-search after upgrading plan
-mcp__mcp-conductor__update_server({
-  name: 'brave-search',
-  env: { BRAVE_API_KEY: 'your-new-api-key' }
-})
+mcp.progress('Fetching issues and scanning codebase...');
+const [issues, files] = await mcp.batch([
+  () => mcp.server('github').call('list_issues', { owner: 'myorg', repo: 'myrepo', state: 'open', per_page: 100 }),
+  () => mcp.server('filesystem').call('search_files', { path: '/src', pattern: '*.ts' })
+]);
+return {
+  openBugs: issues.filter(i => i.labels.some(l => l.name === 'bug')).length,
+  tsFileCount: files.length
+};
 ```
 
-## Optional: Web Search Optimisation
-
-For projects requiring multiple web searches, you can add [brave-search](https://www.npmjs.com/package/@modelcontextprotocol/server-brave-search) MCP server for batched, parallel searches via `execute_code`.
-
-### Setup
-
-1. Get a free Brave Search API key (2000 queries/month): https://brave.com/search/api/
-
-2. Add to your conductor config:
-   ```bash
-   node dist/bin/cli.js config add brave-search npx -y @modelcontextprotocol/server-brave-search
-   ```
-
-3. Set the API key in `~/.mcp-conductor.json`:
-   ```json
-   {
-     "servers": {
-       "brave-search": {
-         "command": "npx",
-         "args": ["-y", "@modelcontextprotocol/server-brave-search"],
-         "env": {
-           "BRAVE_API_KEY": "your-api-key-here"
-         }
-       }
-     }
-   }
-   ```
-
-4. Restart Claude to reload servers.
-
-### Usage
-
-With brave-search configured, use `mcp.batchSearch()` for automatic rate limit handling:
+### Parallel web research
 
 ```typescript
-// Simple: handles rate limits automatically, parses results
-const results = await mcp.batchSearch([
-  'TypeScript best practices',
-  'React hooks tutorial',
-  'Node.js performance tips'
-], { topN: 3 });
-
-return results;
-// Returns: { "TypeScript...": [{title, url, description}, ...], ... }
+const topics = ['MCP protocol 2026', 'Deno performance benchmarks', 'token optimization AI'];
+const results = await mcp.batch(
+  topics.map(q => () => mcp.server('brave-search').call('search', { q, count: 5 }))
+);
+return results.map((r, i) => ({ topic: topics[i], topResult: r[0]?.title, url: r[0]?.url }));
 ```
 
-**How it works:**
-- Attempts parallel execution first (fastest)
-- Auto-detects rate limits from API errors
-- Falls back to sequential with 1.1s delays if rate limited
-- Logs warnings with upgrade guidance when rate limited
-- Parses text responses into structured data
+### Cross-session memory persistence
 
-**Rate limit warnings:**
-```
-⚠️  RATE LIMITED: brave-search - Free tier limit hit. Retrying with delays...
-💡 TIP: Upgrade your API plan for parallel execution: https://brave.com/search/api/
+```typescript
+// Session 1: store results
+const analysis = { /* ... your analysis ... */ };
+await mcp.server('memory').call('store', { key: 'weekly-audit', value: analysis });
+return analysis;
+
+// Session 2: retrieve and compare
+const previous = await mcp.server('memory').call('retrieve', { key: 'weekly-audit' });
+// diff previous vs current...
 ```
 
-**Benefits:**
-- No manual rate limit handling needed
-- Parallel when possible, sequential when required
-- 80%+ token savings vs native WebSearch
-
-### Upgrading Your Plan
-
-After upgrading your Brave Search API plan:
-
-1. **Update the API key** (no restart needed):
-   ```typescript
-   mcp__mcp-conductor__update_server({
-     name: 'brave-search',
-     env: { BRAVE_API_KEY: 'your-new-api-key' }
-   })
-   ```
-
-2. **Test parallel mode** with `forceParallel`:
-   ```typescript
-   const results = await mcp.batchSearch([
-     'query 1', 'query 2', 'query 3', 'query 4', 'query 5'
-   ], { topN: 3, forceParallel: true });
-   ```
-
-3. If parallel works, it will be used automatically for all subsequent batches
+---
 
-## Configuration
-
-### Exclusive Mode (Recommended)
-
-In exclusive mode, Claude only sees mcp-conductor and **must** use `execute_code` for all MCP operations. This provides:
-
-- **Maximum token savings** (90-98% reduction)
-- **No bypass possible** - Claude cannot make direct MCP calls
-- **No CLAUDE.md required** - Works automatically in any project
-
-**How it works:**
-
-```
-Before (default):                    After (exclusive mode):
-┌─────────────────────────────┐     ┌─────────────────────────────┐
-│ Claude's Config             │     │ Claude's Config             │
-│ ├── mcp-conductor           │     │ └── mcp-conductor ← ONLY    │
-│ ├── github ← Claude sees    │     └─────────────────────────────┘
-│ ├── filesystem ← can bypass │     ┌─────────────────────────────┐
-│ └── other servers...        │     │ ~/.mcp-conductor.json       │
-└─────────────────────────────┘     │ ├── github ← hidden         │
-                                    │ ├── filesystem ← hidden     │
-                                    │ └── other servers...        │
-                                    └─────────────────────────────┘
-```
-
-Enable exclusive mode:
-```bash
-node dist/bin/cli.js enable-exclusive
-```
+## Troubleshooting
 
-### Environment Variables
+**"Deno not found"** — Install Deno, then `source ~/.zshrc` (or open a new terminal). Verify with `deno --version`.
 
-```bash
-MCP_CONDUCTOR_PORT=0             # Bridge port (0 = dynamic allocation)
-MCP_CONDUCTOR_MODE=execution     # Operation mode
-MCP_CONDUCTOR_TIMEOUT=30000      # Default timeout in ms
-MCP_CONDUCTOR_LOG_LEVEL=info     # Log level: debug|info|warn|error
-```
+**"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"`).
 
-### Programmatic Configuration
+**"`exclusive` mode not working"** — `"exclusive": true` must be at the root level, not inside `"servers"`.
 
-```typescript
-import { MCPConductorServer, loadConfig } from '@darkiceinteractive/mcp-conductor';
+**"Rate limit errors from brave-search"** — Add a `rateLimit` block to the server config (see example above). Set `onLimitExceeded: "queue"` to buffer requests.
 
-const config = loadConfig();
-const server = new MCPConductorServer(config);
-await server.start();
-```
+**"Config changes not applying"** — The file watcher requires valid JSON. If you saved a file with a syntax error, fix it and save again.
 
-## Security
+Full troubleshooting guide: [docs/troubleshooting.md](./docs/troubleshooting.md)
 
-The Deno sandbox is configured with minimal permissions:
-- Network access only to localhost bridge
-- No filesystem access (except via MCP)
-- No environment variable access
-- No subprocess spawning
-- Memory limits via V8 flags
+---
 
 ## Development
 
 ```bash
-# Install dependencies
+git clone https://github.com/darkiceinteractive/mcp-conductor.git
+cd mcp-conductor
 npm install
-
-# Build
 npm run build
-
-# Run tests
-npm test
-
-# Run tests once (no watch)
-npm run test:run
-
-# Run with coverage
-npm run test:coverage
-
-# Development mode (watch)
-npm run dev
-
-# Lint
-npm run lint
-
-# Format
-npm run format
+npm run test:run           # 673 tests, 82% coverage
+npm run test:coverage      # with coverage report
+npm run dev                # watch mode
 ```
 
-## Distribution
-
-### Publishing to npm
+**Requirements:** Node.js 18+, Deno 2.x
 
-1. Update version in `package.json`
-2. Build and test:
-   ```bash
-   npm run build
-   npm run test:run
-   ```
-3. Publish:
-   ```bash
-   npm publish --access public
-   ```
-
-### Creating a GitHub Release
-
-1. Tag the release:
-   ```bash
-   git tag v0.1.0
-   git push origin v0.1.0
-   ```
-2. Create a release on GitHub with the changelog
-
-### Local Development with Claude Desktop
-
-For local development, point Claude Desktop to your development build:
-
-```json
-{
-  "mcpServers": {
-    "mcp-conductor": {
-      "command": "node",
-      "args": ["/Users/you/Dev/mcp-conductor/dist/index.js"]
-    }
-  }
-}
-```
+---
 
 ## Architecture
 
+Full architecture documentation: [docs/guide/](./docs/guide/)
+
 ```
-Claude Code → MCP Conductor → HTTP Bridge → Deno Sandbox
-                                  ↓
-                          Connected MCP Servers
+Claude Code / Claude Desktop
+    │
+    └── MCP Protocol
+            │
+    ┌───────▼──────────────┐
+    │    MCP Conductor      │
+    │  (Node.js MCP server) │
+    │                       │
+    │  execute_code ──────► Deno Subprocess (50ms, <50MB)
+    │  list_servers         │   TypeScript code runs here
+    │  get_metrics          │   MCP calls via HTTP bridge
+    │  add_server           │   Only result exits sandbox
+    └───────────────────────┘
+              │
+    ┌─────────▼──────────────────────────────┐
+    │         HTTP Bridge (localhost)         │
+    └──┬──────────┬──────────┬───────────────┘
+       │          │          │
+   github     filesystem  brave-search  ... (any MCP server)
 ```
 
-1. Claude calls `execute_code` with TypeScript code
-2. Code is wrapped and run in isolated Deno subprocess
-3. Sandbox calls HTTP bridge to invoke MCP tools
-4. Only the final return value goes back to Claude
+---
 
 ## Documentation
 
-Detailed documentation is available in the [docs](./docs/) folder:
-
-| Document | Description |
-|----------|-------------|
-| [Architecture](./docs/architecture.md) | Internal design and data flow |
-| [Configuration](./docs/configuration.md) | All configuration options |
-| [CLI Reference](./docs/cli-reference.md) | Command-line interface |
-| [Tools Reference](./docs/tools-reference.md) | MCP tools and the `mcp` API |
-| [Permissions](./docs/permissions.md) | Managing Claude Code permissions |
-| [Troubleshooting](./docs/troubleshooting.md) | Common issues and solutions |
-
-## Troubleshooting
-
-### "Deno not installed"
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./docs/guide/getting-started.md) | First-time setup walkthrough |
+| [MCP Clients](./docs/guide/mcp-clients.md) | Setup for Claude, Codex, Gemini, Kimi, VS Code, Cursor, Windsurf, Cline |
+| [Configuration](./docs/configuration.md) | All config options and environment variables |
+| [Architecture](./docs/architecture.md) | System design and data flow |
+| [MCP Tools Reference](./docs/api/tools.md) | All tools available to Claude |
+| [Sandbox API](./docs/api/sandbox-api.md) | The `mcp` object inside execute_code |
+| [CLI Reference](./docs/cli-reference.md) | Command-line tool usage |
+| [Examples](./docs/examples/) | Recipes and patterns |
+| [Benchmarks](./docs/benchmarks/methodology.md) | Token savings methodology and results |
+| [Security](./docs/permissions.md) | Deno sandbox permission model |
+| [Troubleshooting](./docs/troubleshooting.md) | Common issues and fixes |
+
+---
 
-Install Deno from https://deno.land or use:
-```bash
-brew install deno  # macOS
-```
-
-### "Network access denied"
-
-The Deno sandbox only allows access to the localhost bridge. Ensure your MCP servers are accessible through the bridge.
-
-### "Timeout exceeded"
+## Contributing
 
-Increase the timeout for long-running operations:
-```typescript
-// In execute_code call
-{ timeout_ms: 60000 }
-```
+Contributions welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
 
-### "Server not found"
+- **Bug reports:** [GitHub Issues](https://github.com/darkiceinteractive/mcp-conductor/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/darkiceinteractive/mcp-conductor/discussions)
+- **Security:** See [SECURITY.md](./SECURITY.md)
 
-Check that your MCP server is:
-1. Listed in claude_desktop_config.json
-2. Properly started and connected
-3. Use `list_servers` to verify
+---
 
 ## Licence
 
-MIT
+MIT — see [LICENSE](./LICENSE)
 
-## Contributing
+---
 
-Contributions welcome! Please read our contributing guidelines and submit PRs to the GitHub repository.
+*Built by [DarkIce Interactive](https://darkiceinteractive.com) · [@darkiceinteractive/mcp-conductor on npm](https://www.npmjs.com/package/@darkiceinteractive/mcp-conductor)*