@darkiceinteractive/mcp-conductor 2.0.0-alpha.1 → 3.0.0-beta.2

package/dist/server/mcp-server.js

@@ -10,6 +10,9 @@ import { logger } from '../utils/index.js';
 import { HttpBridge } from '../bridge/index.js';
 import { DenoExecutor } from '../runtime/index.js';
 import { MCPHub } from '../hub/index.js';
+import { ToolRegistry } from '../registry/registry.js';
+import { applyBuiltInRecommendations } from '../registry/built-in-recommendations.js';
+import { registerPassthroughTools } from './passthrough-registrar.js';
 import { ModeHandler } from '../modes/index.js';
 import { MetricsCollector } from '../metrics/index.js';
 import { shutdownStreamManager } from '../streaming/index.js';
@@ -18,6 +21,13 @@ import { shutdownModeHandler } from '../modes/index.js';
 import { shutdownSkillsEngine } from '../skills/index.js';
 import { loadConductorConfig, saveConductorConfig, getDefaultConductorConfigPath } from '../config/index.js';
 import { VERSION } from '../version.js';
+import { getCostPredictor, getHotPathProfiler, getAnomalyDetector, getReplayRecorder, shutdownCostPredictor, shutdownHotPathProfiler, shutdownAnomalyDetector, shutdownReplayRecorder, } from '../observability/index.js';
+import { findClaudeConfigsWithServers, importServers, formatImportResults, } from '../cli/commands/import-servers.js';
+import { exportToClaude } from '../cli/commands/export-servers.js';
+import { testServer } from '../cli/commands/test-server.js';
+import { getRoutingRecommendations } from '../cli/commands/routing.js';
+import { CacheLayer } from '../cache/index.js';
+import { ReliabilityGateway } from '../reliability/index.js';
 /**
  * MCP Executor Server
  */
@@ -32,6 +42,9 @@ export class MCPExecutorServer {
     config;
     useMockServers;
     currentMode;
+    registry;
+    cache;
+    gateway;
     // Mock server data for testing when no real servers configured
     mockServers = new Map();
     constructor(config, options) {
@@ -85,6 +98,15 @@ export class MCPExecutorServer {
             reconnectDelayMs: 5000,
             maxReconnectAttempts: 3,
         });
+        // Initialise the ToolRegistry backed by the hub.
+        // registry.refresh() + registerPassthroughTools() are called in start()
+        // after the hub has connected, so the registry is fully populated before
+        // any passthrough tool handler can be invoked.
+        this.registry = new ToolRegistry({ bridge: this.hub });
+        // Initialise cache layer (three-tier: memory LRU + disk CBOR + delta).
+        this.cache = new CacheLayer({ registry: this.registry });
+        // Initialise reliability gateway (timeout + retry + circuit breaker).
+        this.gateway = new ReliabilityGateway({});
         // Set up mock servers for fallback/testing
         this.setupMockServers();
         // Register tools
@@ -1306,6 +1328,373 @@ Triggers a reload to apply changes immediately.`,
                 structuredContent: output,
             };
         });
+        // Register predict_cost tool
+        this.server.registerTool('predict_cost', {
+            title: 'Predict Cost',
+            description: 'Predict the token cost and latency of executing code based on historical samples for similar call patterns.',
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                code: z.string().describe('The code whose cost you want to estimate.'),
+            },
+            outputSchema: {
+                estimatedInputTokens: z.number(),
+                estimatedOutputTokens: z.number(),
+                estimatedLatencyMs: z.number(),
+                basedOn: z.number(),
+                available: z.boolean(),
+            },
+        }, async ({ code }) => {
+            const predictor = getCostPredictor();
+            const prediction = predictor.predictFromCode(code);
+            const output = prediction
+                ? { ...prediction, available: true }
+                : { estimatedInputTokens: 0, estimatedOutputTokens: 0, estimatedLatencyMs: 0, basedOn: 0, available: false };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        });
+        // Register get_hot_paths tool
+        this.server.registerTool('get_hot_paths', {
+            title: 'Get Hot Paths',
+            description: 'Return the top-K tool call paths by total latency or p99 within a rolling time window.',
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                sinceMs: z.number().optional().describe('Only include calls made in the last N milliseconds.'),
+                topK: z.number().optional().describe('Maximum number of paths to return (default: 10).'),
+                sortBy: z.enum(['totalLatency', 'p99', 'callCount']).optional().describe('Ranking dimension (default: totalLatency).'),
+            },
+            outputSchema: {
+                paths: z.array(z.object({
+                    server: z.string(),
+                    tool: z.string(),
+                    callCount: z.number(),
+                    totalLatencyMs: z.number(),
+                    meanLatencyMs: z.number(),
+                    p99LatencyMs: z.number(),
+                })),
+            },
+        }, async ({ sinceMs, topK, sortBy }) => {
+            const profiler = getHotPathProfiler();
+            const paths = profiler.getHotPaths({
+                sinceMs,
+                topK: topK ?? 10,
+                sortBy: sortBy ?? 'totalLatency',
+            });
+            const output = { paths };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        });
+        // Register record_session tool
+        this.server.registerTool('record_session', {
+            title: 'Record Session',
+            description: 'Start recording all tool calls in the current session to a replay journal.',
+            annotations: {
+                readOnlyHint: false,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                sessionId: z.string().optional().describe('Optional session ID. A UUID is generated if omitted.'),
+            },
+            outputSchema: {
+                sessionId: z.string(),
+                recordingPath: z.string(),
+            },
+        }, async ({ sessionId }) => {
+            const recorder = getReplayRecorder();
+            const result = recorder.startRecording(sessionId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        });
+        // Register stop_recording tool
+        this.server.registerTool('stop_recording', {
+            title: 'Stop Recording',
+            description: 'Stop an active recording session and finalise the replay journal.',
+            annotations: {
+                readOnlyHint: false,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                sessionId: z.string().describe('Session ID returned by record_session.'),
+            },
+            outputSchema: {
+                recordingPath: z.string(),
+                eventCount: z.number(),
+            },
+        }, async ({ sessionId }) => {
+            const recorder = getReplayRecorder();
+            const result = recorder.stopRecording(sessionId);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        });
+        // Register replay_session tool
+        this.server.registerTool('replay_session', {
+            title: 'Replay Session',
+            description: 'Replay a recorded session, optionally applying modifications. Detects divergence when replayed result differs from recorded result.',
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                recordingPath: z.string().describe('Path to the .jsonl recording file.'),
+                modifications: z.array(z.object({
+                    at: z.number().describe('Zero-based sequence index to target.'),
+                    op: z.enum(['replace', 'skip']).describe('Operation: replace the result or skip the event.'),
+                    with: z.unknown().optional().describe('Replacement value for replace operation.'),
+                })).optional().describe('Optional list of modifications to apply during replay.'),
+            },
+            outputSchema: {
+                result: z.unknown(),
+                divergence: z.object({
+                    at: z.number(),
+                    expected: z.unknown(),
+                    actual: z.unknown(),
+                }).optional(),
+            },
+        }, async ({ recordingPath, modifications }) => {
+            const recorder = getReplayRecorder();
+            const { result, divergence } = recorder.replay(recordingPath, modifications ?? []);
+            const output = { result, divergence };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        });
+        // ------------------------------------------------------------------
+        // Lifecycle tools (Workstream X2)
+        // ------------------------------------------------------------------
+        // import_servers_from_claude
+        this.server.registerTool('import_servers_from_claude', {
+            title: 'Import Servers from Claude',
+            description: `Import MCP servers from Claude config files into ~/.mcp-conductor.json.
+
+Reads ~/.claude/settings.json, ~/Library/Application Support/Claude/claude_desktop_config.json and other standard paths.
+Shows a diff of what will be imported. On confirm=true, copies entries into the conductor config and writes .bak backups of each source file.
+Optionally strips the imported servers from their source configs.`,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                confirm: z.boolean().optional().default(false).describe('Set true to actually perform the import. False (default) shows a dry-run diff.'),
+                remove_originals: z.boolean().optional().default(false).describe('After import, remove the imported servers from their source Claude config files.'),
+            },
+            outputSchema: {
+                dry_run: z.boolean(),
+                sources_found: z.number(),
+                total_imported: z.number(),
+                total_skipped: z.number(),
+                summary: z.string(),
+            },
+        }, async ({ confirm: doImport, remove_originals }) => {
+            const sources = findClaudeConfigsWithServers();
+            if (sources.length === 0) {
+                const output = { dry_run: !doImport, sources_found: 0, total_imported: 0, total_skipped: 0, summary: 'No Claude config files with MCP servers found.' };
+                return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }], structuredContent: output };
+            }
+            // Pass removeOriginals only when actually importing (doImport=true).
+            // Even though importServers() guards the strip on !dryRun internally,
+            // being explicit here prevents accidental destruction if the function
+            // contract ever changes (HIGH-4 defense-in-depth).
+            const results = importServers({
+                yes: true,
+                removeOriginals: (remove_originals ?? false) && doImport,
+                dryRun: !doImport,
+            });
+            const totalImported = results.reduce((sum, r) => sum + r.imported.length, 0);
+            const totalSkipped = results.reduce((sum, r) => sum + r.skipped.length, 0);
+            const summary = formatImportResults(results, !doImport);
+            const output = {
+                dry_run: !doImport,
+                sources_found: sources.length,
+                total_imported: totalImported,
+                total_skipped: totalSkipped,
+                summary,
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }], structuredContent: output };
+        });
+        // test_server
+        this.server.registerTool('test_server', {
+            title: 'Test Server',
+            description: `Transiently connect to a named MCP server from conductor config, list its tools and measure latency.
+Does NOT persist the connection or register the server. The server must be present in ~/.mcp-conductor.json.`,
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                name: z.string().describe('Server name in conductor config to test.'),
+                timeout_ms: z.number().optional().default(15000).describe('Connection timeout in milliseconds.'),
+            },
+            outputSchema: {
+                success: z.boolean(),
+                server_name: z.string(),
+                connected: z.boolean(),
+                tool_count: z.number(),
+                tools: z.array(z.object({ name: z.string(), description: z.string() })),
+                latency_ms: z.number(),
+                error: z.string().optional(),
+            },
+        }, async ({ name, timeout_ms }) => {
+            const result = await testServer({ name, timeoutMs: timeout_ms ?? 15000 });
+            const output = {
+                success: result.success,
+                server_name: result.serverName,
+                connected: result.connected,
+                tool_count: result.toolCount,
+                tools: result.tools,
+                latency_ms: result.latencyMs,
+                ...(result.error ? { error: result.error } : {}),
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }], structuredContent: output };
+        });
+        // diagnose_server
+        this.server.registerTool('diagnose_server', {
+            title: 'Diagnose Server',
+            description: `Diagnose a registered MCP server: process health, connection status, recent errors, reconnect attempts, last successful call, and registry state.
+Returns actionable information about why a server may be failing.`,
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                name: z.string().describe('Server name to diagnose (must be in conductor config).'),
+            },
+            outputSchema: {
+                server_name: z.string(),
+                status: z.string(),
+                tool_count: z.number(),
+                connected_at: z.string().optional(),
+                last_error: z.string().optional(),
+                reconnect_attempts: z.number(),
+                is_connected: z.boolean(),
+                registry_state: z.object({
+                    in_config: z.boolean(),
+                    command: z.string().optional(),
+                }),
+                suggestions: z.array(z.string()),
+            },
+        }, async ({ name }) => {
+            const servers = this.hub.listServers();
+            const found = servers.find((s) => s.name === name);
+            const conductorConfig = loadConductorConfig();
+            const inConfig = !!(conductorConfig?.servers[name]);
+            const configEntry = conductorConfig?.servers[name];
+            const suggestions = [];
+            if (!found && !inConfig) {
+                suggestions.push(`Server '${name}' is not in conductor config. Add it with add_server or import_servers_from_claude.`);
+            }
+            else if (!found) {
+                suggestions.push(`Server '${name}' is in config but not connected. Try reload_servers or restart conductor.`);
+            }
+            else if (found.status === 'error') {
+                suggestions.push(`Server has error status: ${found.lastError ?? 'unknown'}. Check the command path and env vars.`);
+                suggestions.push('Run test_server to verify connectivity.');
+            }
+            else if (found.status === 'disconnected') {
+                suggestions.push('Server is disconnected. Conductor will auto-reconnect; or call reload_servers.');
+            }
+            const output = {
+                server_name: name,
+                status: found?.status ?? 'not_registered',
+                tool_count: found?.toolCount ?? 0,
+                connected_at: found?.connectedAt?.toISOString(),
+                last_error: found?.lastError,
+                reconnect_attempts: 0, // hub does not expose per-server attempt count publicly yet
+                is_connected: found?.status === 'connected',
+                registry_state: {
+                    in_config: inConfig,
+                    command: configEntry?.command,
+                },
+                suggestions,
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }], structuredContent: output };
+        });
+        // recommend_routing
+        this.server.registerTool('recommend_routing', {
+            title: 'Recommend Routing',
+            description: `Apply the X1 routing heuristic to one or all configured servers.
+Servers whose names match lightweight-payload patterns (search, calendar, email, etc.) are recommended as "passthrough".
+All others default to "execute_code" (safe default). Use apply=true to write the hints into conductor config.`,
+            annotations: {
+                readOnlyHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                server_name: z.string().optional().describe('Analyse a single server (omit for all servers).'),
+                apply: z.boolean().optional().default(false).describe('Write routing hints to ~/.mcp-conductor.json.'),
+            },
+            outputSchema: {
+                recommendations: z.array(z.object({
+                    server_name: z.string(),
+                    recommendation: z.enum(['passthrough', 'execute_code']),
+                    reason: z.string(),
+                })),
+                applied: z.boolean(),
+                config_path: z.string().optional(),
+            },
+        }, async ({ server_name, apply }) => {
+            const result = getRoutingRecommendations({ serverName: server_name, apply: apply ?? false });
+            const output = {
+                recommendations: result.recommendations,
+                applied: result.applied,
+                config_path: result.configPath,
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }], structuredContent: output };
+        });
+        // export_to_claude
+        this.server.registerTool('export_to_claude', {
+            title: 'Export to Claude',
+            description: `Generate a mcpServers JSON block that points Claude back at mcp-conductor stdio.
+This is the rollback path: paste the output into your Claude Desktop or Claude Code config to restore direct connectivity.
+Formats: "claude-desktop" (full wrapper object), "claude-code" (flat mcpServers), "raw" (inner object only).`,
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                format: z.enum(['claude-desktop', 'claude-code', 'raw']).optional().default('claude-desktop').describe('Output format.'),
+                conductor_path: z.string().optional().describe('Override the conductor binary path (default: npx @darkiceinteractive/mcp-conductor).'),
+            },
+            outputSchema: {
+                json: z.string(),
+                format: z.string(),
+                server_count: z.number(),
+                instructions: z.string(),
+            },
+        }, async ({ format, conductor_path }) => {
+            const result = exportToClaude({ format: format ?? 'claude-desktop', conductorPath: conductor_path });
+            const instructions = format === 'claude-code'
+                ? 'Merge this into ~/.claude/settings.json under the mcpServers key.'
+                : format === 'raw'
+                    ? 'Add these entries under the mcpServers key in your Claude config.'
+                    : 'Merge this into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent.';
+            const output = { json: result.json, format: result.format, server_count: result.serverCount, instructions };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }], structuredContent: output };
+        });
     }
     /**
      * Start the server
@@ -1320,6 +1709,12 @@ Triggers a reload to apply changes immediately.`,
                 connected: stats.connected,
                 total: stats.total,
             });
+            // Populate the registry from the now-connected hub, apply built-in
+            // routing recommendations for known servers, then register all
+            // `routing: "passthrough"` tools as first-class MCP tools.
+            await this.registry.refresh();
+            applyBuiltInRecommendations(this.registry.getAllTools(), (server, name, meta) => this.registry.annotate(server, name, meta));
+            registerPassthroughTools(this.registry, this.server, this.hub);
         }
         // Set up bridge handlers
         const handlers = {
@@ -1353,8 +1748,61 @@ Triggers a reload to apply changes immediately.`,
                     throw new Error(`Unknown tool: ${serverName}.${toolName}`);
                 }
                 else {
-                    // Use real hub for tool calls
-                    return await this.hub.callTool(serverName, toolName, params);
+                    // Check registry for X4 redact annotation on this tool
+                    const toolDef = this.registry.getTool(serverName, toolName);
+                    const matchers = toolDef?.redact?.response ?? [];
+                    // X4 tokenization path: PII-redacted results use per-call nonces so
+                    // caching would store tokenized values that cannot be reverse-mapped
+                    // after a cache eviction. Skip cache for this path.
+                    if (matchers.length > 0) {
+                        const _obsStart = Date.now();
+                        const { result, reverseMap } = await this.hub.callToolTokenized(serverName, toolName, params, matchers);
+                        const _obsLatency = Date.now() - _obsStart;
+                        const _obsResultStr = JSON.stringify(result ?? '');
+                        getHotPathProfiler().record(serverName, toolName, _obsLatency);
+                        getAnomalyDetector().record(serverName, toolName, _obsLatency, _obsResultStr.length);
+                        getCostPredictor().record(serverName, toolName, params, {
+                            outputText: _obsResultStr,
+                            latencyMs: _obsLatency,
+                        });
+                        // Return TokenizedCallResult sentinel — http-server.ts unwraps it
+                        return { __x4_result: result, __x4_reverseMap: reverseMap };
+                    }
+                    // Standard path: cache check → reliability gateway → backend → cache set.
+                    const cacheable = this.cache.wouldCache(serverName, toolName);
+                    if (cacheable) {
+                        const hit = await this.cache.get(serverName, toolName, params);
+                        if (hit) {
+                            if (!hit.needsRevalidation) {
+                                // Fresh cache hit — return immediately
+                                return hit.value;
+                            }
+                            // Stale-while-revalidate: return stale value, kick off background refresh
+                            this.cache.refreshInBackground(serverName, toolName, params, () => this.gateway.call(serverName, toolName, () => this.hub.callTool(serverName, toolName, params))).catch((err) => logger.warn('SWR background refresh failed', {
+                                serverName,
+                                toolName,
+                                err: String(err),
+                            }));
+                            return hit.value;
+                        }
+                    }
+                    // Cache miss (or non-cacheable): call through reliability gateway
+                    const _obsStart = Date.now();
+                    const _obsResult = await this.gateway.call(serverName, toolName, () => this.hub.callTool(serverName, toolName, params));
+                    const _obsLatency = Date.now() - _obsStart;
+                    const _obsResultStr = JSON.stringify(_obsResult ?? '');
+                    // Feed observability singletons
+                    getHotPathProfiler().record(serverName, toolName, _obsLatency);
+                    getAnomalyDetector().record(serverName, toolName, _obsLatency, _obsResultStr.length);
+                    getCostPredictor().record(serverName, toolName, params, {
+                        outputText: _obsResultStr,
+                        latencyMs: _obsLatency,
+                    });
+                    // Populate cache for future calls
+                    if (cacheable) {
+                        await this.cache.set(serverName, toolName, params, _obsResult);
+                    }
+                    return _obsResult;
                 }
             },
             listServers: () => {
@@ -1427,11 +1875,17 @@ Triggers a reload to apply changes immediately.`,
         if (!this.useMockServers) {
             await this.hub.shutdown();
         }
-        // 3. Shutdown global singletons (intervals, listeners, caches)
+        // 3. Destroy cache layer (unsubscribes registry watcher)
+        this.cache.destroy();
+        // 4. Shutdown global singletons (intervals, listeners, caches)
         shutdownStreamManager();
         shutdownMetricsCollector();
         shutdownModeHandler();
         shutdownSkillsEngine();
+        shutdownCostPredictor();
+        shutdownHotPathProfiler();
+        shutdownAnomalyDetector();
+        shutdownReplayRecorder();
         // 4. Stop HTTP bridge last (Deno processes may still be calling it during cleanup)
         await this.bridge.stop();
         logger.info('MCP Executor server stopped');