ft-scout 9.0.7 → 9.0.9

package/bin/src/mcp/manager.js

@@ -0,0 +1,648 @@
+/**
+ * Scout MCP Ecosystem - Central Connection Manager
+ * Coordinates lifecycle, connection pools, tool execution, permissions, health, and persistence.
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import { loadMCPServers, saveMCPServers, saveServerSecret, getServerSecret, deleteServerSecret, sanitizeServerConfig, } from './persistence.js';
+import { HttpMcpTransport, StdioMcpTransport } from './transport.js';
+import { MCPClient } from './client.js';
+import { normalizeMCPTool } from './discovery.js';
+import { MCPPermissionManager } from './permissions.js';
+import { MCPToolRouter } from './toolRouter.js';
+import { MCPTelemetry } from './telemetry.js';
+import { MCPHealthMonitor } from './health.js';
+import { MCPRecovery } from './recovery.js';
+import { loadAuthConfig } from '../utils/auth.js';
+export class MCPManager {
+    static instance = null;
+    servers = new Map();
+    clients = new Map();
+    initialized = false;
+    watcherDebounceTimer = null;
+    constructor() {
+        this.loadState();
+        this.setupFileWatcher();
+    }
+    static getInstance() {
+        if (!MCPManager.instance) {
+            MCPManager.instance = new MCPManager();
+        }
+        return MCPManager.instance;
+    }
+    setupFileWatcher() {
+        try {
+            const homeFtDir = path.join(os.homedir(), '.ft');
+            if (!fs.existsSync(homeFtDir)) {
+                fs.mkdirSync(homeFtDir, { recursive: true });
+            }
+            fs.watch(homeFtDir, (eventType, filename) => {
+                if (filename === 'mcp_servers.json' || !filename) {
+                    if (this.watcherDebounceTimer)
+                        clearTimeout(this.watcherDebounceTimer);
+                    this.watcherDebounceTimer = setTimeout(() => {
+                        try {
+                            this.syncWithDisk();
+                        }
+                        catch { }
+                    }, 100);
+                }
+            });
+        }
+        catch {
+            // Non-fatal if filesystem watcher cannot be established
+        }
+    }
+    /**
+     * Synchronize in-memory server configurations with disk storage (~/.ft/mcp_servers.json).
+     * Automatically picks up servers added, modified, or removed via CLI or other processes.
+     */
+    syncWithDisk() {
+        const diskServers = loadMCPServers();
+        const diskServerMap = new Map();
+        for (const s of diskServers) {
+            diskServerMap.set(s.id, s);
+        }
+        // Add or update servers from disk
+        for (const [id, diskServer] of diskServerMap.entries()) {
+            const existing = this.servers.get(id);
+            if (!existing) {
+                // New server added from CLI or external process
+                if (diskServer.status === 'connecting' || diskServer.status === 'reconnecting') {
+                    diskServer.status = 'disconnected';
+                }
+                this.servers.set(id, diskServer);
+            }
+            else {
+                // Server already in memory; update its config & permissions from disk
+                // Preserve in-memory client connection if currently alive in this process
+                const isConnectedLocally = this.clients.has(id);
+                existing.name = diskServer.name;
+                existing.description = diskServer.description;
+                existing.transport = diskServer.transport;
+                existing.endpoint = diskServer.endpoint;
+                existing.command = diskServer.command;
+                existing.args = diskServer.args;
+                existing.env = diskServer.env;
+                existing.authType = diskServer.authType;
+                existing.authHeader = diskServer.authHeader;
+                existing.permissions = diskServer.permissions;
+                existing.hasSecret = diskServer.hasSecret;
+                existing.userId = diskServer.userId || existing.userId;
+                existing.userEmail = diskServer.userEmail || existing.userEmail;
+                existing.updatedAt = diskServer.updatedAt;
+                if (!isConnectedLocally) {
+                    existing.status = diskServer.status;
+                    existing.health = diskServer.health;
+                    existing.tools = diskServer.tools;
+                    existing.capabilities = diskServer.capabilities;
+                    existing.lastConnectedAt = diskServer.lastConnectedAt;
+                    existing.lastActivityAt = diskServer.lastActivityAt;
+                }
+            }
+        }
+        // Remove any servers from memory that were deleted from disk
+        for (const id of Array.from(this.servers.keys())) {
+            if (!diskServerMap.has(id)) {
+                this.clients.get(id)?.disconnect().catch(() => { });
+                this.clients.delete(id);
+                this.servers.delete(id);
+            }
+        }
+    }
+    loadState() {
+        const saved = loadMCPServers();
+        this.servers.clear();
+        for (const s of saved) {
+            // Reset in-memory volatile status on startup if was previously connecting
+            if (s.status === 'connecting' || s.status === 'reconnecting') {
+                s.status = 'disconnected';
+            }
+            this.servers.set(s.id, s);
+        }
+        this.initialized = true;
+    }
+    persistState() {
+        const list = Array.from(this.servers.values());
+        saveMCPServers(list);
+    }
+    /**
+     * Find server by ID or case-insensitive Name
+     */
+    getServer(idOrName) {
+        if (!idOrName)
+            return undefined;
+        // Direct ID lookup
+        let byId = this.servers.get(idOrName);
+        if (byId)
+            return byId;
+        // Sync with disk in case it was just added in CLI
+        this.syncWithDisk();
+        byId = this.servers.get(idOrName);
+        if (byId)
+            return byId;
+        // Name lookup
+        const lower = idOrName.toLowerCase().trim();
+        for (const s of this.servers.values()) {
+            if (s.name.toLowerCase() === lower || s.id.toLowerCase() === lower) {
+                return s;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * List all registered MCP servers (with secrets sanitized), optionally filtered by user account
+     */
+    listServers(filterUserEmail, filterUserId) {
+        this.syncWithDisk();
+        let list = Array.from(this.servers.values());
+        // Account-wise filtering if requested
+        if (filterUserEmail || filterUserId) {
+            const normEmail = filterUserEmail ? filterUserEmail.toLowerCase().trim() : '';
+            list = list.filter((s) => {
+                if (filterUserId && s.userId === filterUserId)
+                    return true;
+                if (normEmail && s.userEmail && s.userEmail.toLowerCase().trim() === normEmail)
+                    return true;
+                // Allow untagged (legacy/global) servers to be visible to avoid losing access
+                if (!s.userId && !s.userEmail)
+                    return true;
+                return false;
+            });
+        }
+        return list.map((s) => sanitizeServerConfig(s));
+    }
+    /**
+     * Register a new MCP server configuration and optionally store credentials
+     */
+    async addServer(config, secret) {
+        const name = config.name.trim();
+        const existing = this.getServer(name);
+        if (existing) {
+            throw new Error(`An MCP server with name "${name}" already exists.`);
+        }
+        const id = config.id || name.toLowerCase().replace(/[^a-z0-9]/g, '-') || `mcp-${Date.now()}`;
+        const now = new Date().toISOString();
+        const currentAuth = loadAuthConfig();
+        const defaultPermissions = {
+            enabled: true,
+            allowedTools: [],
+            disabledTools: [],
+            requireConfirmationForDestructive: true,
+            autoApproveSafe: true,
+            ...config.permissions,
+        };
+        const server = {
+            id,
+            name,
+            description: config.description || '',
+            transport: config.transport,
+            endpoint: config.endpoint,
+            command: config.command,
+            args: config.args || [],
+            env: config.env || {},
+            authType: config.authType || (secret ? 'bearer' : 'none'),
+            authHeader: config.authHeader,
+            userId: config.userId || currentAuth?.user?.id || undefined,
+            userEmail: config.userEmail || currentAuth?.user?.email || undefined,
+            status: 'disconnected',
+            health: {
+                status: 'disconnected',
+            },
+            tools: [],
+            permissions: defaultPermissions,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.servers.set(id, server);
+        if (secret) {
+            saveServerSecret(id, secret);
+            server.hasSecret = true;
+        }
+        this.persistState();
+        return sanitizeServerConfig(server);
+    }
+    /**
+     * Remove an MCP server and its stored secrets
+     */
+    async removeServer(idOrName) {
+        const server = this.getServer(idOrName);
+        if (!server)
+            return false;
+        await this.disconnectServer(server.id).catch(() => { });
+        deleteServerSecret(server.id);
+        this.servers.delete(server.id);
+        this.clients.delete(server.id);
+        this.persistState();
+        return true;
+    }
+    /**
+     * Create an IMCPTransport instance for the given server config
+     */
+    createTransport(server) {
+        if (server.transport === 'http') {
+            if (!server.endpoint) {
+                throw new Error(`HTTP MCP server "${server.name}" requires an endpoint URL.`);
+            }
+            const headers = {};
+            const secret = getServerSecret(server.id);
+            if (secret) {
+                const headerName = server.authHeader || 'Authorization';
+                if (server.authType === 'bearer' || server.authType === 'oauth') {
+                    headers[headerName] = `Bearer ${secret}`;
+                }
+                else if (server.authType === 'api-key') {
+                    headers[headerName] = secret;
+                }
+                else {
+                    headers[headerName] = secret;
+                }
+            }
+            return new HttpMcpTransport(server.endpoint, headers);
+        }
+        else {
+            if (!server.command) {
+                throw new Error(`stdio MCP server "${server.name}" requires a command.`);
+            }
+            return new StdioMcpTransport(server.command, server.args || [], server.env || {});
+        }
+    }
+    /**
+     * Connect to an MCP server, perform initialize handshake, and discover tools
+     */
+    async connectServer(idOrName) {
+        const server = this.getServer(idOrName);
+        if (!server) {
+            throw new Error(`MCP server "${idOrName}" not found.`);
+        }
+        server.status = 'connecting';
+        this.persistState();
+        try {
+            // Disconnect old client if present
+            if (this.clients.has(server.id)) {
+                await this.clients.get(server.id)?.disconnect().catch(() => { });
+                this.clients.delete(server.id);
+            }
+            const transport = this.createTransport(server);
+            const client = new MCPClient(transport);
+            const initResult = await client.connectAndInitialize();
+            server.capabilities = initResult.capabilities;
+            // Discover and normalize tools
+            const rawTools = await client.listTools();
+            const normalizedTools = rawTools.map((rt) => normalizeMCPTool(rt, server.id, server.name));
+            // Restore disabled state if previously set
+            const disabledSet = new Set(server.permissions.disabledTools || []);
+            for (const t of normalizedTools) {
+                if (disabledSet.has(t.name)) {
+                    t.enabled = false;
+                }
+            }
+            server.tools = normalizedTools;
+            server.status = 'connected';
+            server.lastConnectedAt = new Date().toISOString();
+            server.updatedAt = new Date().toISOString();
+            // Ping for initial latency check
+            try {
+                const latency = await client.ping();
+                server.health = {
+                    status: 'connected',
+                    latencyMs: latency,
+                    lastCheckedAt: new Date().toISOString(),
+                };
+            }
+            catch {
+                server.health = {
+                    status: 'connected',
+                    lastCheckedAt: new Date().toISOString(),
+                };
+            }
+            this.clients.set(server.id, client);
+            this.persistState();
+            return sanitizeServerConfig(server);
+        }
+        catch (err) {
+            server.status = 'error';
+            server.health = {
+                status: 'error',
+                error: err?.message || String(err),
+                lastCheckedAt: new Date().toISOString(),
+            };
+            this.persistState();
+            throw err;
+        }
+    }
+    /**
+     * Disconnect an active MCP server
+     */
+    async disconnectServer(idOrName) {
+        const server = this.getServer(idOrName);
+        if (!server) {
+            throw new Error(`MCP server "${idOrName}" not found.`);
+        }
+        const client = this.clients.get(server.id);
+        if (client) {
+            await client.disconnect().catch(() => { });
+            this.clients.delete(server.id);
+        }
+        server.status = 'disconnected';
+        server.health = {
+            status: 'disconnected',
+            lastCheckedAt: new Date().toISOString(),
+        };
+        server.updatedAt = new Date().toISOString();
+        this.persistState();
+        return sanitizeServerConfig(server);
+    }
+    /**
+     * Reconnect to an MCP server
+     */
+    async reconnectServer(idOrName) {
+        const server = this.getServer(idOrName);
+        if (!server) {
+            throw new Error(`MCP server "${idOrName}" not found.`);
+        }
+        await this.disconnectServer(server.id).catch(() => { });
+        return await this.connectServer(server.id);
+    }
+    /**
+     * Check health and latency for a server, or all connected servers
+     */
+    async checkHealth(idOrName) {
+        this.syncWithDisk();
+        const results = {};
+        const targets = idOrName
+            ? [this.getServer(idOrName)].filter(Boolean)
+            : Array.from(this.servers.values());
+        for (const server of targets) {
+            const client = this.clients.get(server.id);
+            const health = await MCPHealthMonitor.checkHealth(server, client);
+            server.health = health;
+            server.status = health.status;
+            results[server.id] = health;
+        }
+        this.persistState();
+        return results;
+    }
+    /**
+     * Retrieve all discovered tools for a server
+     */
+    getToolsForServer(idOrName) {
+        const server = this.getServer(idOrName);
+        return server ? server.tools : [];
+    }
+    /**
+     * Retrieve all discovered tools across all servers
+     */
+    getAllTools(options = {}) {
+        const list = [];
+        for (const server of this.servers.values()) {
+            if (options.onlyEnabled && (server.status !== 'connected' || !server.permissions.enabled)) {
+                continue;
+            }
+            for (const tool of server.tools) {
+                if (options.onlyEnabled && !tool.enabled)
+                    continue;
+                list.push(tool);
+            }
+        }
+        return list;
+    }
+    /**
+     * Enable or disable an individual tool on a server
+     */
+    setToolEnabled(serverId, toolName, enabled) {
+        const server = this.getServer(serverId);
+        if (!server)
+            return false;
+        const tool = server.tools.find((t) => t.name === toolName || t.qualifiedName === toolName);
+        if (!tool)
+            return false;
+        tool.enabled = enabled;
+        const disabledSet = new Set(server.permissions.disabledTools || []);
+        if (enabled) {
+            disabledSet.delete(tool.name);
+        }
+        else {
+            disabledSet.add(tool.name);
+        }
+        server.permissions.disabledTools = Array.from(disabledSet);
+        server.updatedAt = new Date().toISOString();
+        this.persistState();
+        return true;
+    }
+    /**
+     * Update permissions for an MCP server
+     */
+    setServerPermissions(serverId, permissions) {
+        const server = this.getServer(serverId);
+        if (!server)
+            return false;
+        server.permissions = {
+            ...server.permissions,
+            ...permissions,
+        };
+        server.updatedAt = new Date().toISOString();
+        this.persistState();
+        return true;
+    }
+    /**
+     * Toggle a tool enabled/disabled state for a given server
+     */
+    toggleTool(serverId, toolName, enabled) {
+        const server = this.getServer(serverId);
+        if (!server)
+            return undefined;
+        const targetTool = server.tools.find((t) => t.originalName === toolName || t.name === toolName);
+        if (!targetTool)
+            return undefined;
+        targetTool.enabled = enabled !== undefined ? enabled : !targetTool.enabled;
+        const disabledList = new Set(server.permissions.disabledTools || []);
+        if (targetTool.enabled) {
+            disabledList.delete(targetTool.originalName);
+            disabledList.delete(targetTool.name);
+        }
+        else {
+            disabledList.add(targetTool.originalName);
+        }
+        server.permissions.disabledTools = Array.from(disabledList);
+        server.updatedAt = new Date().toISOString();
+        this.persistState();
+        return sanitizeServerConfig(server);
+    }
+    /**
+     * Route user request to relevant MCP tools
+     */
+    routeTools(userGoal) {
+        this.syncWithDisk();
+        return MCPToolRouter.routeTools(userGoal, Array.from(this.servers.values()));
+    }
+    /**
+     * Find tool by either its qualified name (mcp__<serverId>__<toolName>) or its original name
+     */
+    findTool(nameOrQualified) {
+        this.syncWithDisk();
+        for (const server of this.servers.values()) {
+            for (const tool of server.tools) {
+                if (tool.qualifiedName === nameOrQualified || tool.name === nameOrQualified) {
+                    return { tool, server };
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Execute an MCP tool by name, handling permissions, connection, retry, and telemetry
+     */
+    async executeTool(nameOrQualified, args = {}) {
+        const startedAt = new Date().toISOString();
+        const startTime = Date.now();
+        const invocationId = `mcp_inv_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
+        const target = this.findTool(nameOrQualified);
+        if (!target) {
+            const err = `Tool "${nameOrQualified}" is not registered on any connected MCP server.`;
+            const result = {
+                serverId: 'unknown',
+                serverName: 'Unknown',
+                toolName: nameOrQualified,
+                invocationId,
+                startedAt,
+                completedAt: new Date().toISOString(),
+                status: 'error',
+                inputSummary: JSON.stringify(args),
+                outputSummary: err,
+                result: null,
+                error: err,
+                executionDurationMs: Date.now() - startTime,
+            };
+            MCPTelemetry.recordResult(result);
+            return result;
+        }
+        const { tool, server } = target;
+        // 1. Enforce Permissions
+        const perm = MCPPermissionManager.checkToolAccess(server, tool);
+        if (!perm.allowed) {
+            const blockedReason = perm.reason || `Tool "${tool.name}" is restricted by Scout permissions.`;
+            const result = {
+                serverId: server.id,
+                serverName: server.name,
+                toolName: tool.name,
+                invocationId,
+                startedAt,
+                completedAt: new Date().toISOString(),
+                status: 'blocked',
+                inputSummary: JSON.stringify(args),
+                outputSummary: `[MCP PERMISSION BLOCKED]: ${blockedReason}`,
+                result: { success: false, error: 'PermissionBlocked', message: blockedReason },
+                error: blockedReason,
+                executionDurationMs: Date.now() - startTime,
+            };
+            MCPTelemetry.recordResult(result);
+            return result;
+        }
+        // 2. Ensure Client is connected
+        let client = this.clients.get(server.id);
+        if (!client || !client.isConnected()) {
+            try {
+                await this.connectServer(server.id);
+                client = this.clients.get(server.id);
+            }
+            catch (connErr) {
+                const classified = MCPRecovery.classifyError(connErr, server.name, tool.permissionLevel === 'destructive');
+                const result = {
+                    serverId: server.id,
+                    serverName: server.name,
+                    toolName: tool.name,
+                    invocationId,
+                    startedAt,
+                    completedAt: new Date().toISOString(),
+                    status: 'error',
+                    inputSummary: JSON.stringify(args),
+                    outputSummary: classified.userFriendlyMessage,
+                    result: null,
+                    error: classified.originalError,
+                    executionDurationMs: Date.now() - startTime,
+                };
+                MCPTelemetry.recordResult(result);
+                return result;
+            }
+        }
+        if (!client) {
+            throw new Error(`Could not obtain active client for MCP server "${server.name}".`);
+        }
+        // 3. Execute with bounded recovery
+        let execResult = null;
+        let execError = null;
+        const maxRetries = tool.permissionLevel === 'read' ? 1 : 0;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                execResult = await client.callTool(tool.originalName, args);
+                execError = null;
+                break;
+            }
+            catch (callErr) {
+                execError = callErr;
+                const classified = MCPRecovery.classifyError(callErr, server.name, tool.permissionLevel === 'destructive');
+                if (classified.isRecoverable && classified.canRetry && attempt < maxRetries) {
+                    // Try reconnecting once before final retry
+                    await this.reconnectServer(server.id).catch(() => { });
+                    client = this.clients.get(server.id) || client;
+                    continue;
+                }
+                break;
+            }
+        }
+        server.lastActivityAt = new Date().toISOString();
+        this.persistState();
+        const completedAt = new Date().toISOString();
+        const duration = Date.now() - startTime;
+        if (execError) {
+            const classified = MCPRecovery.classifyError(execError, server.name, tool.permissionLevel === 'destructive');
+            const result = {
+                serverId: server.id,
+                serverName: server.name,
+                toolName: tool.name,
+                invocationId,
+                startedAt,
+                completedAt,
+                status: classified.category === 'TIMEOUT' ? 'timeout' : 'error',
+                inputSummary: JSON.stringify(args),
+                outputSummary: classified.userFriendlyMessage,
+                result: null,
+                error: classified.originalError,
+                executionDurationMs: duration,
+            };
+            MCPTelemetry.recordResult(result);
+            return result;
+        }
+        const outSummary = typeof execResult === 'string'
+            ? execResult.slice(0, 300)
+            : (execResult?.text ? String(execResult.text).slice(0, 300) : JSON.stringify(execResult).slice(0, 300));
+        const successRecord = {
+            serverId: server.id,
+            serverName: server.name,
+            toolName: tool.name,
+            invocationId,
+            startedAt,
+            completedAt,
+            status: 'success',
+            inputSummary: JSON.stringify(args),
+            outputSummary: outSummary,
+            result: execResult,
+            executionDurationMs: duration,
+        };
+        MCPTelemetry.recordResult(successRecord);
+        return successRecord;
+    }
+    /**
+     * Get recent observable activity
+     */
+    getActivityLog(limit = 50) {
+        return MCPTelemetry.loadActivity(limit);
+    }
+}
+export function getMCPManager() {
+    return MCPManager.getInstance();
+}
+//# sourceMappingURL=manager.js.map