@darkiceinteractive/mcp-conductor 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DarkIce Interactive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,558 @@
+# 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.
+
+**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
+
+## Requirements
+
+- **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"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop - that's it! The package auto-downloads on first use.
+
+> **Prerequisite:** [Deno](https://deno.land) must be installed for the sandbox runtime.
+
+### Alternative: From Source
+
+For development or customisation:
+
+```bash
+git clone https://github.com/darkiceinteractive/mcp-conductor.git
+cd mcp-conductor
+npm run setup
+node dist/bin/cli.js enable-exclusive
+```
+
+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%+).
+
+### Manual Configuration
+
+If not using npx, add to Claude Desktop configuration:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "mcp-conductor": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-conductor/dist/index.js"]
+    }
+  }
+}
+```
+
+> **Important:** Replace `/absolute/path/to/mcp-conductor` with the actual path where you cloned the repository.
+
+Or use the CLI to add it automatically:
+
+```bash
+node dist/bin/cli.js init
+```
+
+### 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;
+```
+
+## CLI Commands
+
+Run from the project directory:
+
+```bash
+# Check system requirements
+node dist/bin/cli.js check
+
+# Show configuration status
+node dist/bin/cli.js status
+
+# Add to Claude Desktop config automatically
+node dist/bin/cli.js init [--dry-run]
+
+# Start the server manually (usually not needed - Claude Desktop starts it)
+node dist/bin/cli.js serve [options]
+```
+
+### Serve Options
+
+```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
+```
+
+> **Note**: Port 0 (the default) enables dynamic port allocation, allowing multiple instances of MCP Conductor to run simultaneously without port conflicts.
+
+### Exclusive Mode Commands
+
+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
+```
+
+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.
+
+### Project Instructions
+
+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
+
+# Append to existing CLAUDE.md
+node dist/bin/cli.js install-instructions --append
+
+# Preview what would be created
+node dist/bin/cli.js install-instructions --dry-run
+```
+
+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
+
+### execute_code
+
+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' });
+
+// Search for tools
+const tools = await mcp.searchTools('file');
+
+// Log (captured in response)
+mcp.log('Processing...');
+
+// Report progress (for streaming)
+mcp.progress(50, 'Halfway done');
+
+// 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' } },
+]);
+
+// Convenience method for batched web searches (requires brave-search)
+const searchResults = await mcp.batchSearch([
+  'query 1',
+  'query 2',
+  'query 3'
+], { topN: 3 });
+```
+
+### list_servers
+
+List all connected MCP servers and their tools.
+
+### discover_tools
+
+Search for tools across all servers.
+
+### get_metrics
+
+Get session metrics including token savings.
+
+### set_mode
+
+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
+
+### compare_modes
+
+Analyse how a task would be handled in different modes.
+
+### reload_servers
+
+Reload MCP server configurations (useful after editing claude_desktop_config.json).
+
+### passthrough_call
+
+Make direct tool calls without code execution. **Note:** This tool has high token cost and should only be used for debugging.
+
+### add_server
+
+Add an MCP server to conductor config at runtime without restarting Claude.
+
+### remove_server
+
+Remove an MCP server from conductor config at runtime.
+
+### update_server
+
+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.
+
+```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' }
+})
+```
+
+## 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:
+
+```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}, ...], ... }
+```
+
+**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
+
+**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/
+```
+
+**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
+```
+
+### Environment Variables
+
+```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
+```
+
+### Programmatic Configuration
+
+```typescript
+import { MCPConductorServer, loadConfig } from '@darkiceinteractive/mcp-conductor';
+
+const config = loadConfig();
+const server = new MCPConductorServer(config);
+await server.start();
+```
+
+## Security
+
+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
+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
+```
+
+## Distribution
+
+### Publishing to npm
+
+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
+
+```
+Claude Code → MCP Conductor → HTTP Bridge → Deno Sandbox
+                                  ↓
+                          Connected MCP Servers
+```
+
+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"
+
+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"
+
+Increase the timeout for long-running operations:
+```typescript
+// In execute_code call
+{ timeout_ms: 60000 }
+```
+
+### "Server not found"
+
+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
+
+## Contributing
+
+Contributions welcome! Please read our contributing guidelines and submit PRs to the GitHub repository.

package/dist/bin/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * MCP Conductor CLI
+ *
+ * Command-line interface for managing MCP Conductor.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/bin/cli.ts"],"names":[],"mappings":";AACA;;;;GAIG"}