@darkiceinteractive/mcp-conductor 1.0.0

package/dist/utils/rate-limiter.js

@@ -0,0 +1,187 @@
+/**
+ * Token bucket rate limiter for MCP servers
+ */
+import { EventEmitter } from 'node:events';
+import { logger } from './logger.js';
+/**
+ * Token bucket rate limiter with queue and reject modes
+ */
+export class RateLimiter extends EventEmitter {
+    serverName;
+    requestsPerSecond;
+    maxTokens;
+    mode;
+    maxQueueTimeMs;
+    tokens;
+    lastRefill;
+    queue = [];
+    refillInterval = null;
+    // Stats
+    totalRequests = 0;
+    totalWaited = 0;
+    totalRejected = 0;
+    constructor(config, serverName) {
+        super();
+        this.serverName = serverName;
+        this.requestsPerSecond = config.requestsPerSecond;
+        this.maxTokens = config.burstSize ?? config.requestsPerSecond;
+        this.mode = config.onLimitExceeded ?? 'queue';
+        this.maxQueueTimeMs = config.maxQueueTimeMs ?? 30000;
+        // Start with full bucket
+        this.tokens = this.maxTokens;
+        this.lastRefill = Date.now();
+        // Start background token refill
+        this.startRefillTimer();
+        logger.debug(`RateLimiter created for ${serverName}`, {
+            requestsPerSecond: this.requestsPerSecond,
+            maxTokens: this.maxTokens,
+            mode: this.mode,
+        });
+    }
+    /**
+     * Acquire a token before making a request
+     * In queue mode: waits until a token is available
+     * In reject mode: throws immediately if no token available
+     */
+    async acquire() {
+        this.totalRequests++;
+        // Try to get a token immediately
+        if (this.tryAcquire()) {
+            this.emit('acquired', { serverName: this.serverName, waitedMs: 0 });
+            return;
+        }
+        // No token available
+        if (this.mode === 'reject') {
+            this.totalRejected++;
+            const error = new Error(`Rate limit exceeded for ${this.serverName}: ${this.requestsPerSecond} req/s`);
+            this.emit('rejected', { serverName: this.serverName, reason: 'no tokens available' });
+            throw error;
+        }
+        // Queue mode: wait for a token
+        return this.enqueue();
+    }
+    /**
+     * Release a token back (for cancelled requests before they actually execute)
+     */
+    release() {
+        this.tokens = Math.min(this.tokens + 1, this.maxTokens);
+    }
+    /**
+     * Get current rate limiter stats
+     */
+    getStats() {
+        return {
+            serverName: this.serverName,
+            availableTokens: this.tokens,
+            maxTokens: this.maxTokens,
+            requestsPerSecond: this.requestsPerSecond,
+            queueLength: this.queue.length,
+            totalRequests: this.totalRequests,
+            totalWaited: this.totalWaited,
+            totalRejected: this.totalRejected,
+        };
+    }
+    /**
+     * Clean up resources
+     */
+    destroy() {
+        if (this.refillInterval) {
+            clearInterval(this.refillInterval);
+            this.refillInterval = null;
+        }
+        // Reject all queued requests
+        for (const request of this.queue) {
+            clearTimeout(request.timeout);
+            request.reject(new Error(`RateLimiter for ${this.serverName} destroyed`));
+        }
+        this.queue = [];
+        logger.debug(`RateLimiter destroyed for ${this.serverName}`);
+    }
+    /**
+     * Try to acquire a token without waiting
+     */
+    tryAcquire() {
+        this.refillTokens();
+        if (this.tokens >= 1) {
+            this.tokens--;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Enqueue a request to wait for a token
+     */
+    enqueue() {
+        return new Promise((resolve, reject) => {
+            const queuePosition = this.queue.length + 1;
+            const estimatedWaitMs = Math.ceil((queuePosition / this.requestsPerSecond) * 1000);
+            this.emit('waiting', {
+                serverName: this.serverName,
+                queuePosition,
+                estimatedWaitMs,
+            });
+            logger.debug(`Request queued for ${this.serverName}`, {
+                queuePosition,
+                estimatedWaitMs,
+            });
+            const timeout = setTimeout(() => {
+                // Remove from queue
+                const index = this.queue.findIndex((r) => r.timeout === timeout);
+                if (index !== -1) {
+                    this.queue.splice(index, 1);
+                }
+                this.totalRejected++;
+                const error = new Error(`Rate limit queue timeout for ${this.serverName} after ${this.maxQueueTimeMs}ms`);
+                this.emit('rejected', { serverName: this.serverName, reason: 'queue timeout' });
+                reject(error);
+            }, this.maxQueueTimeMs);
+            this.queue.push({
+                resolve,
+                reject,
+                timeout,
+                enqueuedAt: Date.now(),
+            });
+        });
+    }
+    /**
+     * Refill tokens based on elapsed time
+     */
+    refillTokens() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        // Calculate tokens to add based on elapsed time
+        const tokensToAdd = (elapsed / 1000) * this.requestsPerSecond;
+        if (tokensToAdd >= 1) {
+            this.tokens = Math.min(this.tokens + Math.floor(tokensToAdd), this.maxTokens);
+            this.lastRefill = now;
+        }
+    }
+    /**
+     * Start background timer to process queued requests
+     */
+    startRefillTimer() {
+        // Check queue every 50ms
+        this.refillInterval = setInterval(() => {
+            this.processQueue();
+        }, 50);
+    }
+    /**
+     * Process queued requests when tokens become available
+     */
+    processQueue() {
+        this.refillTokens();
+        while (this.queue.length > 0 && this.tokens >= 1) {
+            const request = this.queue.shift();
+            if (request) {
+                clearTimeout(request.timeout);
+                this.tokens--;
+                this.totalWaited++;
+                const waitedMs = Date.now() - request.enqueuedAt;
+                this.emit('acquired', { serverName: this.serverName, waitedMs });
+                logger.debug(`Request dequeued for ${this.serverName}`, { waitedMs });
+                request.resolve();
+            }
+        }
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/utils/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/watcher/config-watcher.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Config File Watcher
+ *
+ * Watches Claude config files for changes and triggers hot-reload
+ * of MCP server connections.
+ */
+import { EventEmitter } from 'node:events';
+export interface WatcherConfig {
+    /** Path to watch (auto-detect if not specified) */
+    configPath?: string;
+    /** Debounce delay in milliseconds */
+    debounceMs?: number;
+    /** Whether to watch for changes */
+    enabled?: boolean;
+}
+export interface WatcherEvents {
+    configChanged: (path: string) => void;
+    watcherError: (error: Error) => void;
+    watcherStarted: (path: string) => void;
+    watcherStopped: () => void;
+}
+export declare class ConfigWatcher extends EventEmitter {
+    private config;
+    private watcher;
+    private debounceTimer;
+    private watchedPath;
+    private isRunning;
+    constructor(config?: WatcherConfig);
+    /**
+     * Start watching the config file
+     */
+    start(): Promise<boolean>;
+    /**
+     * Stop watching the config file
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle file change event with debouncing
+     */
+    private handleChange;
+    /**
+     * Check if watcher is running
+     */
+    isWatching(): boolean;
+    /**
+     * Get the path being watched
+     */
+    getWatchedPath(): string | null;
+    /**
+     * Update the debounce delay
+     */
+    setDebounceMs(ms: number): void;
+    /**
+     * Trigger a manual reload (without file change)
+     */
+    triggerReload(): void;
+}
+/**
+ * Create a config watcher that integrates with an MCP Hub
+ */
+export declare function createHubWatcher(hub: {
+    reload: () => Promise<{
+        added: string[];
+        removed: string[];
+    }>;
+}, config?: WatcherConfig): ConfigWatcher;
+//# sourceMappingURL=config-watcher.d.ts.map

package/dist/watcher/config-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-watcher.d.ts","sourceRoot":"","sources":["../../src/watcher/config-watcher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACrC,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAQD,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,GAAE,aAAkB;IAKtC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAkD/B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI/B;;OAEG;IACH,aAAa,IAAI,IAAI;CAMtB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE;IAAE,MAAM,EAAE,MAAM,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,EACtE,MAAM,GAAE,aAAkB,GACzB,aAAa,CAgBf"}

package/dist/watcher/config-watcher.js

@@ -0,0 +1,150 @@
+/**
+ * Config File Watcher
+ *
+ * Watches Claude config files for changes and triggers hot-reload
+ * of MCP server connections.
+ */
+import { watch } from 'chokidar';
+import { EventEmitter } from 'node:events';
+import { logger } from '../utils/index.js';
+import { findClaudeConfig } from '../config/loader.js';
+const DEFAULT_WATCHER_CONFIG = {
+    configPath: '',
+    debounceMs: 500,
+    enabled: true,
+};
+export class ConfigWatcher extends EventEmitter {
+    config;
+    watcher = null;
+    debounceTimer = null;
+    watchedPath = null;
+    isRunning = false;
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_WATCHER_CONFIG, ...config };
+    }
+    /**
+     * Start watching the config file
+     */
+    async start() {
+        if (!this.config.enabled) {
+            logger.debug('Config watcher disabled');
+            return false;
+        }
+        if (this.isRunning) {
+            logger.warn('Config watcher already running');
+            return true;
+        }
+        // Find the config file to watch
+        const configPath = this.config.configPath || findClaudeConfig();
+        if (!configPath) {
+            logger.warn('No Claude config file found to watch');
+            return false;
+        }
+        this.watchedPath = configPath;
+        try {
+            this.watcher = watch(configPath, {
+                persistent: true,
+                ignoreInitial: true,
+                awaitWriteFinish: {
+                    stabilityThreshold: this.config.debounceMs,
+                    pollInterval: 100,
+                },
+            });
+            this.watcher.on('change', (path) => {
+                this.handleChange(path);
+            });
+            this.watcher.on('error', (error) => {
+                logger.error('Config watcher error', { error: String(error) });
+                this.emit('watcherError', error);
+            });
+            this.isRunning = true;
+            logger.info(`Config watcher started`, { path: configPath });
+            this.emit('watcherStarted', configPath);
+            return true;
+        }
+        catch (error) {
+            logger.error('Failed to start config watcher', { error: String(error) });
+            return false;
+        }
+    }
+    /**
+     * Stop watching the config file
+     */
+    async stop() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+        this.isRunning = false;
+        this.watchedPath = null;
+        logger.info('Config watcher stopped');
+        this.emit('watcherStopped');
+    }
+    /**
+     * Handle file change event with debouncing
+     */
+    handleChange(path) {
+        // Clear any existing debounce timer
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        // Set up debounced callback
+        this.debounceTimer = setTimeout(() => {
+            logger.info('Config file changed, triggering reload', { path });
+            this.emit('configChanged', path);
+            this.debounceTimer = null;
+        }, this.config.debounceMs);
+    }
+    /**
+     * Check if watcher is running
+     */
+    isWatching() {
+        return this.isRunning;
+    }
+    /**
+     * Get the path being watched
+     */
+    getWatchedPath() {
+        return this.watchedPath;
+    }
+    /**
+     * Update the debounce delay
+     */
+    setDebounceMs(ms) {
+        this.config.debounceMs = ms;
+    }
+    /**
+     * Trigger a manual reload (without file change)
+     */
+    triggerReload() {
+        if (this.watchedPath) {
+            logger.info('Manual reload triggered', { path: this.watchedPath });
+            this.emit('configChanged', this.watchedPath);
+        }
+    }
+}
+/**
+ * Create a config watcher that integrates with an MCP Hub
+ */
+export function createHubWatcher(hub, config = {}) {
+    const watcher = new ConfigWatcher(config);
+    watcher.on('configChanged', async () => {
+        try {
+            const result = await hub.reload();
+            logger.info('Hub reloaded after config change', {
+                added: result.added,
+                removed: result.removed,
+            });
+        }
+        catch (error) {
+            logger.error('Failed to reload hub after config change', { error: String(error) });
+        }
+    });
+    return watcher;
+}
+//# sourceMappingURL=config-watcher.js.map

package/dist/watcher/config-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-watcher.js","sourceRoot":"","sources":["../../src/watcher/config-watcher.ts"],"names":[],"mappings":"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"}

package/dist/watcher/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Watcher module exports
+ */
+export { ConfigWatcher, createHubWatcher, type WatcherConfig, type WatcherEvents, } from './config-watcher.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/watcher/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/watcher/index.js

@@ -0,0 +1,5 @@
+/**
+ * Watcher module exports
+ */
+export { ConfigWatcher, createHubWatcher, } from './config-watcher.js';
+//# sourceMappingURL=index.js.map

package/dist/watcher/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/watcher/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,aAAa,EACb,gBAAgB,GAGjB,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@darkiceinteractive/mcp-conductor",
+  "version": "1.0.0",
+  "description": "MCP server that orchestrates code execution in a sandboxed Deno environment with access to all MCP servers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-conductor": "./dist/bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "setup": "./scripts/setup.sh",
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:e2e": "vitest run test/e2e",
+    "test:benchmark": "vitest run test/benchmark",
+    "test:coverage": "vitest run --coverage",
+    "test:all": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "code-execution",
+    "sandbox",
+    "deno"
+  ],
+  "author": "DarkIce Interactive",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/darkiceinteractive/mcp-conductor.git"
+  },
+  "homepage": "https://github.com/darkiceinteractive/mcp-conductor#readme",
+  "bugs": {
+    "url": "https://github.com/darkiceinteractive/mcp-conductor/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.5.3",
+    "commander": "^12.1.0",
+    "conf": "^13.0.1",
+    "gray-matter": "^4.0.3",
+    "ora": "^8.1.1",
+    "uuid": "^10.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/uuid": "^10.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/templates/CLAUDE.md

@@ -0,0 +1,137 @@
+# MCP Conductor - Project Instructions
+
+This project has MCP Conductor configured for token-efficient MCP operations.
+
+## Critical: Use execute_code for MCP Operations
+
+**ALWAYS use `mcp-conductor`'s `execute_code` tool** instead of making direct MCP tool calls when:
+
+1. **Multiple tool calls needed** - Batch operations into a single execute_code call
+2. **Processing data** - Filter, transform, or aggregate results in the sandbox
+3. **Iterating over items** - Files, repos, search results, etc.
+4. **Large datasets** - Process data server-side, return only summaries
+
+### Why This Matters
+
+Direct MCP calls consume tokens for BOTH request AND response in Claude's context. With execute_code:
+- Write code once (small token cost)
+- All intermediate data stays in sandbox (zero token cost)
+- Only final return value enters context (minimal tokens)
+
+**Token savings: 90%+ for multi-step operations**
+
+### Example: Reading Multiple Files
+
+**BAD - Direct calls (high token usage):**
+```
+1. filesystem.list_directory → full response in context
+2. filesystem.read_file → full file in context
+3. filesystem.read_file → full file in context
+4. filesystem.read_file → full file in context
+... (each response consumes tokens)
+```
+
+**GOOD - execute_code (minimal tokens):**
+```typescript
+// Use mcp-conductor's execute_code tool with this code:
+const fs = mcp.server('filesystem');
+const files = await fs.call('list_directory', { path: '/src' });
+const tsFiles = files.entries.filter(f => f.name.endsWith('.ts'));
+const contents = await Promise.all(
+  tsFiles.map(f => fs.call('read_file', { path: '/src/' + f.name }))
+);
+// Only this summary enters Claude's context:
+return {
+  count: tsFiles.length,
+  totalLines: contents.reduce((sum, c) => sum + c.split('\n').length, 0)
+};
+```
+
+### When Direct MCP Calls Are OK
+
+- Single, simple tool call with no processing
+- Debugging or interactive exploration
+- When you need streaming feedback
+
+## Web Search Optimisation (Optional)
+
+If `brave-search` MCP server is configured, use `mcp.batchSearch()` for efficient batched searches:
+
+**Native WebSearch (sequential, high tokens):**
+```
+1. WebSearch("query 1") → full results in context
+2. WebSearch("query 2") → full results in context
+3. WebSearch("query 3") → full results in context
+```
+
+**mcp.batchSearch() (auto rate-limit handling, filtered):**
+```typescript
+// Simple: auto handles rate limits, parses results, returns top 3 per query
+const results = await mcp.batchSearch([
+  'React hooks best practices',
+  'Vue composition API tutorial',
+  'Svelte vs React performance'
+], { topN: 3 });
+
+return results;
+// Returns: { "React hooks...": [{title, url, description}, ...], ... }
+```
+
+**How it works:**
+- Attempts parallel execution first (fastest)
+- Auto-detects rate limits from errors
+- Falls back to sequential with delays if needed
+- Caches rate limit status for session
+- Parses text response into structured data
+
+**For other rate-limited APIs, use mcp.batch():**
+```typescript
+// Generic batch with auto rate limit handling
+const results = await mcp.batch([
+  { server: 'github', tool: 'search_repositories', params: { query: 'ai' } },
+  { server: 'github', tool: 'search_repositories', params: { query: 'ml' } },
+]);
+```
+
+**Rate limit warnings (displayed in logs):**
+```
+⚠️  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:**
+- Automatic rate limit detection and handling
+- No manual delays needed
+- Parallel when possible, sequential when required
+- ~80%+ token savings
+
+**After upgrading API plan, use `forceParallel` to test:**
+```typescript
+const results = await mcp.batchSearch([
+  'query 1', 'query 2', 'query 3', 'query 4', 'query 5'
+], { topN: 3, forceParallel: true });
+```
+
+**Note:** Use native WebSearch for single searches or when brave-search isn't configured.
+
+### Quick Reference
+
+```typescript
+// Get a server client
+const github = mcp.server('github');
+// Or use attribute style
+const github = mcp.github;
+
+// Call a tool
+const repos = await github.call('search_repositories', { query: 'ai' });
+
+// Search for tools across all servers
+const tools = await mcp.searchTools('file');
+
+// Log (captured in response)
+mcp.log('Processing...');
+```
+
+## Available MCP Servers
+
+Run `mcp-conductor - list_servers` to see all connected servers and their tools.