twinclaw 1.0.0

package/dist/services/mcp-client-adapter.js

@@ -0,0 +1,291 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { logThought } from '../utils/logger.js';
+import { saveMcpHealthEvent, saveMcpScopeAuditLog } from './db.js';
+import { randomUUID } from 'node:crypto';
+const FAILURE_THRESHOLD = 5;
+const COOLDOWN_MS = 30_000; // 30 seconds
+const SUCCESS_THRESHOLD = 2; // 2 consecutive successes to close half-open
+// Symbols for testing access
+export const INTERNAL_STATE = Symbol('INTERNAL_STATE');
+export const INTERNAL_METRICS = Symbol('INTERNAL_METRICS');
+export const INTERNAL_CLIENT = Symbol('INTERNAL_CLIENT');
+export const INTERNAL_CONVERT = Symbol('INTERNAL_CONVERT');
+/**
+ * Manages the lifecycle of a single MCP server connection.
+ *
+ * - Launches the server as a subprocess via stdio transport.
+ * - Discovers available tools using `list_tools()`.
+ * - Converts MCP tools into TwinBot's `Skill` contract.
+ * - Registers/unregisters tools in the shared `SkillRegistry`.
+ * - Provides `callTool()` for executing MCP tools.
+ */
+export class McpClientAdapter {
+    #config;
+    #registry;
+    #client = null;
+    #transport = null;
+    #state = 'disconnected';
+    #lastError = null;
+    #toolCount = 0;
+    // Health tracking
+    #circuitState = 'closed';
+    #metrics = {
+        failureCount: 0,
+        latencySpikes: 0,
+        timeoutCount: 0,
+        lastFailureTime: null,
+        consecutiveSuccesses: 0,
+    };
+    /** @internal Exposure for tests only */
+    get [INTERNAL_STATE]() { return this.#circuitState; }
+    set [INTERNAL_STATE](v) { this.#circuitState = v; }
+    /** @internal Exposure for tests only */
+    get [INTERNAL_METRICS]() { return this.#metrics; }
+    /** @internal Exposure for tests only */
+    get [INTERNAL_CLIENT]() { return this.#client; }
+    /** @internal Exposure for tests only */
+    [INTERNAL_CONVERT](name, desc, schema) {
+        return this.#convertToSkill(name, desc, schema);
+    }
+    constructor(config, registry) {
+        this.#config = config;
+        this.#registry = registry;
+    }
+    get id() {
+        return this.#config.id;
+    }
+    get state() {
+        return this.#state;
+    }
+    /** Return a read-only snapshot of this adapter's status. */
+    snapshot() {
+        return {
+            id: this.#config.id,
+            name: this.#config.name,
+            state: this.#state,
+            toolCount: this.#toolCount,
+            lastError: this.#lastError,
+            health: this.#healthSnapshot(),
+        };
+    }
+    #healthSnapshot() {
+        let remainingCooldown = 0;
+        if (this.#circuitState === 'open' && this.#metrics.lastFailureTime) {
+            const lastFail = new Date(this.#metrics.lastFailureTime).getTime();
+            remainingCooldown = Math.max(0, COOLDOWN_MS - (Date.now() - lastFail));
+        }
+        return {
+            state: this.#circuitState,
+            metrics: { ...this.#metrics },
+            remainingCooldownMs: remainingCooldown,
+        };
+    }
+    /** Connect to the MCP server and discover its tools. */
+    async connect() {
+        if (this.#state === 'connected' || this.#state === 'connecting')
+            return;
+        this.#state = 'connecting';
+        this.#lastError = null;
+        try {
+            await logThought(`[McpClientAdapter] Connecting to MCP server '${this.#config.id}' (${this.#config.command} ${this.#config.args.join(' ')})`);
+            this.#transport = new StdioClientTransport({
+                command: this.#config.command,
+                args: this.#config.args,
+                env: this.#config.env,
+            });
+            this.#client = new Client({
+                name: `twinbot-${this.#config.id}`,
+                version: '1.0.0',
+            });
+            await this.#client.connect(this.#transport);
+            // Discover and register tools
+            await this.#discoverTools();
+            this.#state = 'connected';
+            await logThought(`[McpClientAdapter] Connected to '${this.#config.id}' — ${this.#toolCount} tools available.`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.#state = 'error';
+            this.#lastError = message;
+            console.error(`[McpClientAdapter] Failed to connect to '${this.#config.id}':`, message);
+            await logThought(`[McpClientAdapter] Connection to '${this.#config.id}' failed: ${message}`);
+        }
+    }
+    /** Disconnect from the MCP server and unregister its tools. */
+    async disconnect() {
+        // Unregister all tools from this server
+        const removed = this.#registry.unregisterByServer(this.#config.id);
+        this.#toolCount = 0;
+        try {
+            await this.#client?.close();
+        }
+        catch {
+            // Best-effort cleanup
+        }
+        this.#client = null;
+        this.#transport = null;
+        this.#state = 'disconnected';
+        await logThought(`[McpClientAdapter] Disconnected from '${this.#config.id}' — removed ${removed} tools.`);
+    }
+    /** Execute a tool call on the MCP server. */
+    async callTool(toolName, args) {
+        if (!this.#client || this.#state !== 'connected') {
+            throw new Error(`MCP server '${this.#config.id}' is not connected (state: ${this.#state}).`);
+        }
+        await logThought(`[McpClientAdapter] Calling tool '${toolName}' on MCP server '${this.#config.id}'.`);
+        // Check circuit state before execution
+        this.#checkCircuitTransition();
+        if (this.#circuitState === 'open') {
+            throw new Error(`MCP server '${this.#config.id}' is unavailable (Circuit OPEN). Failure count: ${this.#metrics.failureCount}`);
+        }
+        const start = Date.now();
+        try {
+            const result = await this.#client.callTool({ name: toolName, arguments: args });
+            const latency = Date.now() - start;
+            this.#recordSuccess(latency);
+            // MCP tool results come as an array of content blocks
+            const content = result.content;
+            if (Array.isArray(content)) {
+                return content
+                    .map((block) => {
+                    if (typeof block === 'object' && block !== null && 'text' in block) {
+                        return String(block.text);
+                    }
+                    return JSON.stringify(block);
+                })
+                    .join('\n');
+            }
+            const output = typeof content === 'string' ? content : JSON.stringify(content);
+            return output;
+        }
+        catch (err) {
+            this.#recordFailure(err);
+            throw err;
+        }
+    }
+    // ── Private Helpers ────────────────────────────────────────────────────────
+    /** Discover tools from the MCP server and register them in the skill registry. */
+    async #discoverTools() {
+        if (!this.#client)
+            return;
+        const response = await this.#client.listTools();
+        const tools = response.tools;
+        for (const tool of tools) {
+            const skill = this.#convertToSkill(tool.name, tool.description ?? '', tool.inputSchema);
+            this.#registry.register(skill);
+        }
+        this.#toolCount = tools.length;
+    }
+    /** Convert an MCP tool's metadata into TwinBot's Skill interface. */
+    #convertToSkill(name, description, inputSchema) {
+        const serverId = this.#config.id;
+        const adapter = this; // Capture reference for the closure
+        const defaultScope = this.#config.capabilities?.defaultScope ?? 'unclassified';
+        const mcpScope = this.#config.capabilities?.tools?.[name] ?? defaultScope;
+        return {
+            name,
+            description: `[MCP:${serverId}] ${description}`,
+            group: 'group:mcp',
+            parameters: inputSchema ?? undefined,
+            source: 'mcp',
+            serverId,
+            mcpScope,
+            adapter,
+            async execute(input) {
+                try {
+                    const output = await adapter.callTool(name, input);
+                    return { ok: true, output };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return { ok: false, output: `MCP tool error: ${message}` };
+                }
+            },
+        };
+    }
+    /** Audit a scope-blocked action. */
+    auditScopeBlock(sessionId, toolName, scope, reason) {
+        saveMcpScopeAuditLog({
+            id: randomUUID(),
+            sessionId,
+            serverId: this.#config.id,
+            toolName,
+            scope,
+            outcome: 'denied',
+            reason,
+        });
+    }
+    /** Audit a scope-allowed action. */
+    auditScopeAllow(sessionId, toolName, scope) {
+        saveMcpScopeAuditLog({
+            id: randomUUID(),
+            sessionId,
+            serverId: this.#config.id,
+            toolName,
+            scope,
+            outcome: 'allowed',
+        });
+    }
+    #checkCircuitTransition() {
+        if (this.#circuitState === 'open' && this.#metrics.lastFailureTime) {
+            const lastFail = new Date(this.#metrics.lastFailureTime).getTime();
+            if (Date.now() - lastFail > COOLDOWN_MS) {
+                const prevState = this.#circuitState;
+                this.#circuitState = 'half-open';
+                saveMcpHealthEvent({
+                    id: randomUUID(),
+                    serverId: this.#config.id,
+                    prevState,
+                    newState: this.#circuitState,
+                    reason: 'Cooldown expired',
+                    metrics: { ...this.#metrics },
+                });
+                logThought(`[McpClientAdapter] Circuit for '${this.#config.id}' transitioned to HALF-OPEN (cooldown expired).`).catch(() => { });
+            }
+        }
+    }
+    #recordSuccess(latencyMs) {
+        this.#metrics.consecutiveSuccesses++;
+        // Latency spikes (> 10s)
+        if (latencyMs > 10_000) {
+            this.#metrics.latencySpikes++;
+        }
+        if (this.#circuitState === 'half-open' && this.#metrics.consecutiveSuccesses >= SUCCESS_THRESHOLD) {
+            const prevState = this.#circuitState;
+            this.#circuitState = 'closed';
+            this.#metrics.failureCount = 0; // Reset failures on full recovery
+            saveMcpHealthEvent({
+                id: randomUUID(),
+                serverId: this.#config.id,
+                prevState,
+                newState: this.#circuitState,
+                reason: 'Success threshold reached in half-open state',
+                metrics: { ...this.#metrics },
+            });
+            logThought(`[McpClientAdapter] Circuit for '${this.#config.id}' transitioned to CLOSED (full recovery achieved).`).catch(() => { });
+        }
+    }
+    #recordFailure(err) {
+        this.#metrics.failureCount++;
+        this.#metrics.lastFailureTime = new Date().toISOString();
+        this.#metrics.consecutiveSuccesses = 0;
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.toLowerCase().includes('timeout')) {
+            this.#metrics.timeoutCount++;
+        }
+        if (this.#circuitState !== 'open' && this.#metrics.failureCount >= FAILURE_THRESHOLD) {
+            const prevState = this.#circuitState;
+            this.#circuitState = 'open';
+            saveMcpHealthEvent({
+                id: randomUUID(),
+                serverId: this.#config.id,
+                prevState,
+                newState: this.#circuitState,
+                reason: `Failure threshold reached: ${message}`,
+                metrics: { ...this.#metrics },
+            });
+            logThought(`[McpClientAdapter] Circuit for '${this.#config.id}' transitioned to OPEN (failure threshold ${FAILURE_THRESHOLD} reached). Last error: ${message}`).catch(() => { });
+        }
+    }
+}

package/dist/services/mcp-server-manager.js

@@ -0,0 +1,143 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { McpClientAdapter } from './mcp-client-adapter.js';
+import { SkillPackageManager } from './skill-package-manager.js';
+import { logThought } from '../utils/logger.js';
+const DEFAULT_CONFIG_PATH = path.resolve('mcp-servers.json');
+/**
+ * Manages multiple MCP server connections.
+ *
+ * Reads a configuration file listing MCP servers, creates an adapter
+ * for each enabled server, and orchestrates connect/disconnect lifecycle.
+ * Failed connections are isolated — one server's failure doesn't affect others.
+ *
+ * Usage:
+ * ```ts
+ * const manager = new McpServerManager(registry);
+ * await manager.loadConfig();
+ * await manager.connectAll();
+ *
+ * // Later:
+ * await manager.disconnectAll();
+ * ```
+ */
+export class McpServerManager {
+    #registry;
+    #adapters = new Map();
+    #packageManager;
+    #configPath;
+    constructor(registry, configPath, packageManager) {
+        this.#registry = registry;
+        this.#configPath = configPath ?? DEFAULT_CONFIG_PATH;
+        this.#packageManager = packageManager ?? new SkillPackageManager();
+    }
+    /** Load MCP server configuration from the config file. */
+    async loadConfig() {
+        const enabledServers = [];
+        try {
+            const raw = await readFile(this.#configPath, 'utf8');
+            const config = JSON.parse(raw);
+            if (!Array.isArray(config.servers)) {
+                console.warn('[McpServerManager] Config file has no servers array.');
+            }
+            else {
+                enabledServers.push(...config.servers.filter((s) => s.enabled !== false));
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (err.code === 'ENOENT') {
+                console.warn(`[McpServerManager] Config file not found at ${this.#configPath}. No MCP servers will be loaded.`);
+            }
+            else {
+                console.error('[McpServerManager] Failed to load config:', message);
+                await logThought(`[McpServerManager] Config load failed: ${message}`);
+            }
+        }
+        const packagePlan = await this.#packageManager.getActivationPlan();
+        for (const packagedServer of packagePlan.servers) {
+            const duplicate = enabledServers.some((server) => server.id === packagedServer.id);
+            if (duplicate) {
+                console.warn(`[McpServerManager] Packaged server '${packagedServer.id}' conflicts with static config and was skipped.`);
+                continue;
+            }
+            enabledServers.push(packagedServer);
+        }
+        for (const serverConfig of enabledServers) {
+            if (this.#adapters.has(serverConfig.id)) {
+                console.warn(`[McpServerManager] Duplicate server ID '${serverConfig.id}' — skipping.`);
+                continue;
+            }
+            const adapter = new McpClientAdapter(serverConfig, this.#registry);
+            this.#adapters.set(serverConfig.id, adapter);
+        }
+        if (packagePlan.diagnostics.violations.length > 0) {
+            const summary = packagePlan.diagnostics.violations
+                .map((violation) => `${violation.packageName}@${violation.version}:${violation.code}`)
+                .join(', ');
+            console.warn(`[McpServerManager] Skill package activation blocked: ${summary}`);
+        }
+        await logThought(`[McpServerManager] Loaded ${enabledServers.length} server(s) from config/package lock.`);
+        return enabledServers;
+    }
+    async getSkillPackageDiagnostics() {
+        return this.#packageManager.getDiagnostics();
+    }
+    async installSkillPackage(packageName, versionRange) {
+        return this.#packageManager.installPackage(packageName, versionRange);
+    }
+    async upgradeSkillPackage(packageName, versionRange) {
+        return this.#packageManager.upgradePackage(packageName, versionRange);
+    }
+    async uninstallSkillPackage(packageName) {
+        return this.#packageManager.uninstallPackage(packageName);
+    }
+    /** Connect all configured servers that have autoConnect enabled. */
+    async connectAll() {
+        const promises = [];
+        for (const adapter of this.#adapters.values()) {
+            // Connect with error isolation — one failure doesn't block others
+            promises.push(adapter.connect().catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`[McpServerManager] Failed to connect '${adapter.id}':`, message);
+            }));
+        }
+        await Promise.allSettled(promises);
+        const snapshots = this.listServers();
+        const connected = snapshots.filter((s) => s.state === 'connected').length;
+        const total = snapshots.length;
+        await logThought(`[McpServerManager] Connection complete: ${connected}/${total} servers connected.`);
+    }
+    /** Connect a specific server by ID. */
+    async connect(serverId) {
+        const adapter = this.#adapters.get(serverId);
+        if (!adapter) {
+            throw new Error(`[McpServerManager] Server '${serverId}' is not configured.`);
+        }
+        await adapter.connect();
+    }
+    /** Disconnect a specific server by ID. */
+    async disconnect(serverId) {
+        const adapter = this.#adapters.get(serverId);
+        if (!adapter)
+            return;
+        await adapter.disconnect();
+    }
+    /** Disconnect all servers gracefully. */
+    async disconnectAll() {
+        const promises = [];
+        for (const adapter of this.#adapters.values()) {
+            promises.push(adapter.disconnect());
+        }
+        await Promise.allSettled(promises);
+        await logThought('[McpServerManager] All MCP servers disconnected.');
+    }
+    /** Return snapshots of all managed MCP servers. */
+    listServers() {
+        return [...this.#adapters.values()].map((a) => a.snapshot());
+    }
+    /** Get a specific adapter by ID (for direct tool calls). */
+    getAdapter(serverId) {
+        return this.#adapters.get(serverId);
+    }
+}