@daniel.stefan/metalink 1.3.1

package/packages/core/dist/server/http.js

@@ -0,0 +1,4253 @@
+/**
+ * HTTP Server - Express-based API for MetaLink
+ */
+import express from 'express';
+import rateLimit from 'express-rate-limit';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+import { randomUUID, createHmac } from 'crypto';
+import { ServerManager } from './manager.js';
+import { version } from "../index.js";
+import { calculateTotalTokens } from './token-calculator.js';
+import { globalMetrics, MetricsPersistence, MetricsAggregator } from '../metrics/index.js';
+import { logger, generateRequestId, getOrCreateRequestId } from '../logging/index.js';
+import { getPromptsList, getPrompt } from './prompts.js';
+import { getResourcesList, getResourceTemplatesList, readResource } from './resources.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// MCP Protocol Version - MUST be set in all HTTP responses per spec 2025-06-18
+const MCP_PROTOCOL_VERSION = '2025-06-18';
+// Custom error class for invalid parameters (JSON-RPC error code -32602)
+class InvalidParamsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidParamsError';
+    }
+}
+// Custom error class for method not found (JSON-RPC error code -32601)
+class MethodNotFoundError extends Error {
+    constructor(method) {
+        super(`Method not found: ${method}`);
+        this.name = 'MethodNotFoundError';
+    }
+}
+// Custom error class for session not initialized (triggers HTTP 404 for MCP spec compliance)
+// Per MCP spec, clients MUST reinitialize when receiving 404 for invalid session
+// Using HTTP 404 allows existing client auto-reinitialize handlers to work
+class SessionNotInitializedError extends Error {
+    constructor(method) {
+        super(`Session must be initialized before calling ${method}. Call initialize first.`);
+        this.name = 'SessionNotInitializedError';
+    }
+}
+export class HttpServer {
+    constructor(configLoader) {
+        this.server = null; // HTTP server instance (keeps event loop alive)
+        this.eventClients = new Set();
+        // Streamable HTTP session management
+        this.sessions = new Map();
+        this.SESSION_TIMEOUT = 24 * 60 * 60 * 1000; // 24 hours (security best practice)
+        this.sessionCleanupInterval = null;
+        // SSE connections for bidirectional communication
+        this.sseConnections = new Map();
+        // SSE event tracking for Last-Event-ID resumption (per MCP spec 2025-06-18)
+        this.sseEventBuffer = new Map(); // sessionId -> events
+        this.sseEventCounter = 0;
+        this.MAX_EVENTS_PER_SESSION = 100; // Keep last 100 events for resumption
+        // SECURITY: Per-server tool execution rate limiting (OWASP DOS Prevention)
+        // Prevents denial-of-service attacks by limiting tool calls per server
+        this.toolExecutionRateLimiter = new Map();
+        this.TOOL_RATE_LIMIT_WINDOW_MS = 60000; // 1 minute window
+        this.TOOL_RATE_LIMIT_MAX_CALLS = 100; // Max 100 calls per server per minute
+        // SECURITY: Discovery endpoint rate limiting (P1 - OWASP DOS Prevention)
+        // Prevents abuse of search_tools and describe_tool endpoints
+        this.discoveryRateLimiter = new Map();
+        this.DISCOVERY_RATE_LIMIT_WINDOW_MS = 60000; // 1 minute window
+        this.DISCOVERY_RATE_LIMIT_MAX_CALLS = 200; // Max 200 discovery calls per session per minute
+        // Daemon uptime tracking
+        this.startTime = Date.now();
+        // ===  Session Persistence (v1.1.24+) ===
+        /**
+         * Session persistence file format
+         */
+        this.SESSION_PERSIST_VERSION = 1;
+        /**
+         * Send notifications/tools/list_changed to all connected SSE clients
+         * Throttled to max 1 notification per second
+         */
+        this.lastToolsListNotification = 0;
+        this.TOOLS_LIST_NOTIFICATION_THROTTLE_MS = 1000;
+        this.app = express();
+        this.configLoader = configLoader;
+        this.config = configLoader.getConfig();
+        // Pass config with schemasCacheTTL to ServerManager
+        this.serverManager = new ServerManager(this.config);
+        // v1.4.0: Register callback for discovery expiration notifications
+        this.serverManager.setToolsListChangedCallback(() => {
+            this.notifyToolsListChanged();
+        });
+        // v1.3.72: Enable proactive schema caching by providing server list
+        this.serverManager.setServerListProvider(() => this.configLoader.getServers());
+        // Phase 2: Set config loader for tool safety classification
+        this.serverManager.setConfigLoader(this.configLoader);
+        // Phase 4 - v1.4.0: Initialize metrics persistence and aggregation
+        const metricsDir = process.env.METALINK_METRICS_DIR || '~/.config/metalink';
+        this.metricsPersistence = new MetricsPersistence(metricsDir);
+        this.metricsAggregator = new MetricsAggregator();
+        // Session persistence path (v1.1.24+)
+        const configDir = (process.env.METALINK_CONFIG_DIR || '~/.config/metalink').replace(/^~/, process.env.HOME || '~');
+        this.sessionPersistPath = path.join(configDir, 'sessions.json');
+        // Load persisted metrics on startup
+        this.loadPersistedMetrics();
+        // Load persisted sessions on startup (v1.1.24+)
+        this.loadSessions();
+        this.setupMiddleware();
+        this.setupRoutes();
+        this.setupSSE();
+        // Start session cleanup for Streamable HTTP
+        this.startSessionCleanup();
+        // Start periodic metrics persistence (Phase 4 - v1.4.0)
+        this.startMetricsPersistence();
+    }
+    /**
+     * Get server manager instance
+     */
+    getServerManager() {
+        return this.serverManager;
+    }
+    /**
+     * Pagination support - Encode cursor data to opaque base64 string
+     */
+    encodeCursor(data) {
+        return Buffer.from(JSON.stringify(data)).toString('base64');
+    }
+    /**
+     * Pagination support - Decode cursor from base64 string
+     */
+    decodeCursor(cursor) {
+        try {
+            const decoded = Buffer.from(cursor, 'base64').toString('utf-8');
+            return JSON.parse(decoded);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Pagination support - Truncate string to character limit
+     */
+    truncateToChars(value, maxChars) {
+        const json = JSON.stringify(value);
+        if (json.length <= maxChars) {
+            return value;
+        }
+        // Truncate and add indicator
+        const truncated = json.substring(0, maxChars - 20) + '... [truncated]';
+        try {
+            return JSON.parse(truncated);
+        }
+        catch {
+            // If truncated JSON is invalid, return string
+            return truncated;
+        }
+    }
+    /**
+     * Pagination support - Apply pagination to tool result
+     *
+     * @param result - Tool execution result (any type)
+     * @param params - Pagination parameters from request
+     * @returns Paginated result with metadata
+     */
+    paginateResult(result, params) {
+        const DEFAULT_MAX_CHARS = 50000; // 50KB default limit per MCP spec
+        const maxChars = params.max_result_chars ?? DEFAULT_MAX_CHARS;
+        // Handle cursor continuation
+        let startOffset = 0;
+        if (params.cursor) {
+            const cursorData = this.decodeCursor(params.cursor);
+            if (cursorData) {
+                startOffset = cursorData.offset;
+            }
+        }
+        // Check if result is an array and apply max_results
+        if (Array.isArray(result) && params.max_results) {
+            const totalAvailable = result.length;
+            const endOffset = startOffset + params.max_results;
+            if (endOffset < totalAvailable) {
+                // More results available - create cursor
+                const nextCursor = this.encodeCursor({
+                    offset: endOffset,
+                    type: 'array'
+                });
+                return {
+                    result: result.slice(startOffset, endOffset),
+                    _pagination: {
+                        nextCursor,
+                        totalAvailable,
+                        truncated: true
+                    }
+                };
+            }
+            else if (startOffset > 0) {
+                // Last page
+                return {
+                    result: result.slice(startOffset),
+                    _pagination: {
+                        totalAvailable,
+                        truncated: false
+                    }
+                };
+            }
+        }
+        // Check character limit
+        const json = JSON.stringify(result);
+        if (json.length > maxChars) {
+            // Generate cursor for continuation
+            const nextCursor = this.encodeCursor({
+                offset: maxChars,
+                type: 'chars'
+            });
+            return {
+                result: this.truncateToChars(result, maxChars),
+                _pagination: {
+                    nextCursor,
+                    totalAvailable: json.length,
+                    truncated: true
+                }
+            };
+        }
+        // No pagination needed
+        return {
+            result,
+            _pagination: {
+                truncated: false
+            }
+        };
+    }
+    /**
+     * Setup Express middleware
+     */
+    setupMiddleware() {
+        // Request ID middleware - generate or extract correlation ID
+        this.app.use((req, _res, next) => {
+            const requestId = getOrCreateRequestId(req.headers['x-request-id']);
+            req.requestId = requestId;
+            next();
+        });
+        // Debug middleware - structured logging for all requests
+        this.app.use((req, _res, next) => {
+            const requestId = req.requestId;
+            logger.debug('Incoming request', {
+                requestId,
+                method: req.method,
+                path: req.path,
+                url: req.url,
+                userAgent: req.headers['user-agent'],
+            });
+            next();
+        });
+        // Metrics middleware (Phase 4 - v1.4.0)
+        this.app.use((req, res, next) => {
+            const startTime = Date.now();
+            const requestId = req.requestId;
+            globalMetrics.recordApiRequest();
+            res.on('finish', () => {
+                const latency = Date.now() - startTime;
+                globalMetrics.recordApiResponse(latency);
+                if (res.statusCode >= 400) {
+                    globalMetrics.recordApiError();
+                }
+                // Log response with correlation ID
+                logger.info('Request completed', {
+                    requestId,
+                    method: req.method,
+                    path: req.path,
+                    status: res.statusCode,
+                    duration_ms: latency,
+                });
+            });
+            next();
+        });
+        // Origin header validation to prevent DNS rebinding attacks
+        this.app.use((req, res, next) => {
+            // Only validate POST requests (where state changes can occur)
+            if (req.method === 'POST') {
+                const origin = req.headers.origin;
+                const requestId = req.requestId;
+                // Allow requests with no Origin header (non-browser clients, Electron apps)
+                if (!origin) {
+                    next();
+                    return;
+                }
+                // Parse origin and validate
+                try {
+                    const originUrl = new URL(origin);
+                    const hostname = originUrl.hostname;
+                    // Allow localhost, 127.0.0.1, and IPv6 loopback
+                    const allowedHosts = ['localhost', '127.0.0.1', '[::1]', '::1'];
+                    if (!allowedHosts.includes(hostname)) {
+                        logger.warn('Rejected request from unauthorized origin', {
+                            requestId,
+                            origin,
+                            hostname,
+                            security: 'dns_rebinding_protection',
+                        });
+                        res.status(403).json({
+                            jsonrpc: '2.0',
+                            error: {
+                                code: -32600,
+                                message: 'Invalid Request: Origin not allowed'
+                            }
+                        });
+                        return;
+                    }
+                }
+                catch (err) {
+                    // Invalid origin URL
+                    logger.warn('Rejected request with malformed origin', {
+                        requestId,
+                        origin,
+                        error: err instanceof Error ? err.message : 'Unknown error',
+                        security: 'dns_rebinding_protection',
+                    });
+                    res.status(403).json({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32600,
+                            message: 'Invalid Request: Malformed origin'
+                        }
+                    });
+                    return;
+                }
+            }
+            next();
+        });
+        // Raw body parser for MCP endpoints (must come before JSON parser)
+        this.app.use('/mcp', express.raw({ type: 'application/json' }));
+        this.app.use('/mcp/rpc', express.raw({ type: 'application/json' }));
+        this.app.use('/rpc', express.raw({ type: 'application/json' }));
+        this.app.use('/rpc/rpc', express.raw({ type: 'application/json' }));
+        // JSON body parser for other endpoints
+        this.app.use(express.json());
+        // Rate limiting
+        const daemonConfig = this.config.daemon;
+        if (daemonConfig && daemonConfig.rateLimit && daemonConfig.rateLimit.enabled) {
+            const limiter = rateLimit({
+                windowMs: daemonConfig.rateLimit.windowMs || 60000,
+                max: daemonConfig.rateLimit.max || 500,
+                keyGenerator: (req) => {
+                    if (daemonConfig.rateLimit && daemonConfig.rateLimit.keyGenerator === 'user') {
+                        return req.userId || req.ip || '';
+                    }
+                    return req.ip || '';
+                },
+            });
+            this.app.use(limiter);
+        }
+        // Authentication middleware (if enabled)
+        if (daemonConfig && daemonConfig.auth && daemonConfig.auth.enabled) {
+            this.app.use(this.authMiddleware.bind(this));
+        }
+        // Request logging
+        this.app.use((req, res, next) => {
+            const start = Date.now();
+            res.on('finish', () => {
+                const duration = Date.now() - start;
+                console.log(`[${req.method}] ${req.path} ${res.statusCode} ${duration}ms`);
+            });
+            next();
+        });
+    }
+    /**
+     * Authentication middleware
+     */
+    authMiddleware(req, res, next) {
+        const authHeader = req.headers.authorization;
+        if (!authHeader) {
+            res.status(401).json({ error: 'Missing Authorization header' });
+            return;
+        }
+        const [scheme] = authHeader.split(' ');
+        if (scheme !== 'Bearer') {
+            res.status(401).json({ error: 'Invalid Authorization scheme' });
+            return;
+        }
+        const token = authHeader.substring(7);
+        const secret = this.config?.daemon?.auth?.secret;
+        if (!secret) {
+            console.warn('[Auth] No auth secret configured, rejecting request');
+            res.status(500).json({ error: 'Auth not configured' });
+            return;
+        }
+        const expectedToken = createHmac('sha256', secret)
+            .update('metalink-auth-token').digest('hex');
+        if (token !== expectedToken) {
+            res.status(401).json({ error: 'Invalid authentication token' });
+            return;
+        }
+        req.authenticated = true;
+        req.userId = 'authenticated-user';
+        next();
+    }
+    /**
+     * Setup API routes
+     */
+    setupRoutes() {
+        const api = express.Router();
+        // Server endpoints
+        api.get('/servers', this.listServers.bind(this));
+        api.get('/servers/available/list', this.listAvailableServers.bind(this));
+        api.post('/servers/:name/start', this.startServer.bind(this));
+        api.post('/servers/:name/stop', this.stopServer.bind(this));
+        api.post('/servers/:name/restart', this.restartServer.bind(this));
+        api.post('/servers/:name/enable', this.enableServer.bind(this));
+        api.post('/servers/:name/disable', this.disableServer.bind(this));
+        api.get('/servers/:name/status', this.getServerStatus.bind(this));
+        api.get('/servers/:name/info', this.getServerInfo.bind(this));
+        api.post('/servers/:name/refresh-tools', this.refreshServerTools.bind(this)); // v1.4.2: Force refresh tools
+        // Tool endpoints
+        api.get('/servers/:name/tools', this.getServerTools.bind(this));
+        api.post('/servers/:name/tools/:toolName/execute', this.executeTool.bind(this));
+        // Configuration endpoints
+        api.get('/config', this.getConfig.bind(this));
+        api.put('/config', this.updateConfig.bind(this));
+        // Registry management endpoints
+        api.post('/registry/servers', this.addServer.bind(this));
+        api.delete('/registry/servers/:name', this.removeServer.bind(this));
+        api.post('/registry/validate', this.validateServer.bind(this));
+        // Health endpoints
+        api.get('/health', this.healthCheck.bind(this));
+        // Version endpoint
+        api.get('/version', this.getVersion.bind(this));
+        // Metrics endpoints (Phase 4 - v1.4.0)
+        api.get('/metrics', this.getMetrics.bind(this));
+        api.get('/metrics/prometheus', this.getPrometheusMetrics.bind(this));
+        api.get('/metrics/api', this.getApiMetrics.bind(this));
+        api.get('/metrics/servers/:name', this.getServerMetrics.bind(this));
+        api.get('/metrics/hourly', this.getHourlyMetrics.bind(this));
+        api.get('/metrics/daily', this.getDailyMetrics.bind(this));
+        api.get('/metrics/weekly', this.getWeeklyMetrics.bind(this));
+        api.get('/metrics/errors', this.getErrorAnalytics.bind(this));
+        api.get('/metrics/errors/:toolName', this.getToolErrorMetrics.bind(this));
+        api.get('/metrics/tools', this.getToolMetrics.bind(this)); // Test 187: Tool-specific granular metrics
+        // Safety endpoints (Phase 1 - v1.2.0)
+        api.get("/safety", this.getSafetyRules.bind(this));
+        api.get("/safety/check/:server/:tool", this.checkToolSafety.bind(this));
+        api.post("/safety/tools/safe", this.addSafeToolOverride.bind(this));
+        api.post("/safety/tools/risky", this.addRiskyToolOverride.bind(this));
+        api.post("/safety/patterns/safe", this.addSafePattern.bind(this));
+        api.post("/safety/patterns/risky", this.addRiskyPattern.bind(this));
+        api.delete("/safety/rules/:rule", this.removeRule.bind(this));
+        api.post("/safety/reset", this.resetSafetyRules.bind(this));
+        api.post("/safety/import", this.importSafetyRules.bind(this));
+        this.app.use('/api/v1', api);
+        // Also register /api/metrics endpoint (without /v1 prefix) for backward compatibility with tests
+        this.app.get('/api/metrics', this.getMetrics.bind(this));
+        // MCP endpoint (JSON-RPC over HTTP) - Primary endpoint per MCP 2025-06-18 spec
+        // GET /mcp for streaming/SSE connections (Claude Code HTTP transport)
+        this.app.get('/mcp', this.handleMcpRequest.bind(this));
+        // POST endpoints for standard JSON-RPC
+        this.app.post('/mcp', this.handleMcpRequest.bind(this));
+        // DELETE /mcp for session cleanup (per MCP spec)
+        this.app.delete('/mcp', this.handleMcpRequest.bind(this));
+        // Legacy SSE endpoints for backward compatibility (2025-03-26 and earlier)
+        this.app.get('/sse', this.handleMcpRequest.bind(this)); // Legacy SSE endpoint
+        this.app.post('/messages', this.handleMcpRequest.bind(this)); // Legacy JSON-RPC endpoint
+        // Alternative MCP endpoint paths for compatibility with various clients
+        // Grok HTTP transport expects /mcp/rpc path
+        this.app.post('/mcp/rpc', this.handleMcpRequest.bind(this));
+        // Root-level /rpc for clients that don't use /mcp prefix (e.g., Grok CLI)
+        this.app.post('/rpc', this.handleMcpRequest.bind(this));
+        // Grok appends /rpc to URL, creating /rpc/rpc when given http://.../rpc
+        this.app.post('/rpc/rpc', this.handleMcpRequest.bind(this));
+        // Prometheus metrics endpoint (standard /metrics path for scraping)
+        this.app.get('/metrics', this.getPrometheusMetrics.bind(this));
+        // Serve dashboard static files (if available)
+        const dashboardPath = path.join(__dirname, '../../../dashboard/dist');
+        const dashboardExists = fs.existsSync(dashboardPath);
+        const indexPath = path.join(dashboardPath, 'index.html');
+        const indexExists = dashboardExists && fs.existsSync(indexPath);
+        console.log('[HTTP] dashboardPath:', dashboardPath);
+        console.log('[HTTP] dashboard exists:', dashboardExists);
+        console.log('[HTTP] index.html exists:', indexExists);
+        // Serve dashboard - explicit root route
+        if (indexExists) {
+            console.log('[HTTP] Registering GET / route for dashboard');
+            this.app.get('/', (_req, res) => {
+                console.log('[HTTP] Serving root path from:', indexPath);
+                res.sendFile(indexPath);
+            });
+            console.log('[HTTP] GET / route registered successfully');
+        }
+        else {
+            console.log('[HTTP] Skipping GET / - index.html not found');
+        }
+        if (dashboardExists) {
+            console.log('[HTTP] Registering static file middleware for:', dashboardPath);
+            // Serve static assets from dashboard
+            this.app.use(express.static(dashboardPath, {
+                etag: false
+            }));
+            console.log('[HTTP] Static middleware registered');
+        }
+        // SPA fallback - serve index.html for client-side routing (only if dashboard exists)
+        if (indexExists) {
+            console.log('[HTTP] Registering fallback route (*)');
+            this.app.get('*', (_req, res) => {
+                console.log('[HTTP] Fallback route hit for:', _req.path);
+                res.sendFile(indexPath);
+            });
+            console.log('[HTTP] Fallback route registered');
+        }
+        else {
+            console.log('[HTTP] Skipping fallback route - dashboard not available');
+        }
+        // SECURITY: Error handler with sanitization to prevent credential leakage
+        // OWASP Reference: A3:2017-Sensitive Data Exposure
+        this.app.use((err, _req, res, _next) => {
+            // Log full error internally for debugging (not exposed to client)
+            console.error('API Error:', err);
+            // SECURITY: Sanitize error message before sending to client
+            const sanitizedMessage = this.sanitizeErrorMessage(err.message);
+            res.status(500).json({
+                error: 'Internal Server Error',
+                message: sanitizedMessage,
+            });
+        });
+    }
+    /**
+     * SECURITY: Sanitize error messages to prevent credential/path leakage.
+     *
+     * This function removes or masks sensitive information from error messages
+     * before they are sent to clients.
+     *
+     * OWASP Reference: A3:2017-Sensitive Data Exposure
+     *
+     * @param message - Original error message
+     * @returns Sanitized message safe for client exposure
+     */
+    sanitizeErrorMessage(message) {
+        if (!message)
+            return 'An error occurred';
+        // Patterns that indicate sensitive data that should be masked
+        const sensitivePatterns = [
+            // API keys and tokens (various formats)
+            /\b(api[_-]?key|apikey|token|bearer|auth)[=:]\s*['"]?[\w-]{20,}['"]?/gi,
+            /\b(sk|pk|rk)[-_][a-zA-Z0-9]{20,}/g, // Stripe-style keys
+            /\bghp_[a-zA-Z0-9]{36,}/g, // GitHub tokens
+            /\bxox[baprs]-[a-zA-Z0-9-]+/g, // Slack tokens
+            // Passwords
+            /password[=:]\s*['"]?[^'"\s]+['"]?/gi,
+            /pwd[=:]\s*['"]?[^'"\s]+['"]?/gi,
+            // Connection strings
+            /mongodb(\+srv)?:\/\/[^@]+@/gi,
+            /postgres(ql)?:\/\/[^@]+@/gi,
+            /mysql:\/\/[^@]+@/gi,
+            /redis:\/\/[^@]+@/gi,
+            // AWS credentials
+            /\bAKIA[A-Z0-9]{16}\b/g,
+            /\b[A-Za-z0-9/+=]{40}\b/g, // AWS secret keys (40 chars base64)
+            // Home directory paths (may reveal usernames)
+            /\/Users\/[a-zA-Z0-9_-]+/g,
+            /\/home\/[a-zA-Z0-9_-]+/g,
+            /C:\\Users\\[a-zA-Z0-9_-]+/gi,
+            // Environment variable dumps
+            /\benv\[['"]?[A-Z_]+['"]?\]\s*=\s*['"]?[^'"\s]+['"]?/gi,
+        ];
+        let sanitized = message;
+        for (const pattern of sensitivePatterns) {
+            sanitized = sanitized.replace(pattern, '[REDACTED]');
+        }
+        // Additional safety: truncate very long messages that might contain dumps
+        if (sanitized.length > 500) {
+            sanitized = sanitized.substring(0, 500) + '... [truncated]';
+        }
+        return sanitized;
+    }
+    /**
+     * Setup Server-Sent Events
+     */
+    setupSSE() {
+        this.app.get('/api/v1/events', (req, res) => {
+            // Check authentication
+            if (this.config.daemon?.auth?.enabled && !req.authenticated) {
+                res.status(401).json({ error: 'Unauthorized' });
+                return;
+            }
+            res.setHeader('Content-Type', 'text/event-stream');
+            res.setHeader('Cache-Control', 'no-cache');
+            res.setHeader('Connection', 'keep-alive');
+            // Send initial connection message
+            res.write('data: {"type":"connected"}\n\n');
+            this.eventClients.add(res);
+            // Clean up on disconnect
+            req.on('close', () => {
+                this.eventClients.delete(res);
+            });
+        });
+        // Broadcast events from server manager
+        this.serverManager.on('server:started', (data) => {
+            this.broadcastEvent({
+                type: 'server:started',
+                data,
+            });
+        });
+        this.serverManager.on('server:stopped', (data) => {
+            this.broadcastEvent({
+                type: 'server:stopped',
+                data,
+            });
+        });
+        this.serverManager.on('server:error', (data) => {
+            this.broadcastEvent({
+                type: 'server:error',
+                data,
+            });
+        });
+        this.serverManager.on('health:check', (data) => {
+            this.broadcastEvent({
+                type: 'health:check',
+                data,
+            });
+        });
+        // Listen for server removal events (from removeServer method)
+        this.serverManager.on('server:removed', (data) => {
+            this.broadcastEvent({
+                type: 'server:removed',
+                data,
+            });
+        });
+    }
+    /**
+     * Broadcast event to all SSE clients
+     */
+    broadcastEvent(event) {
+        const message = `data: ${JSON.stringify(event)}\n\n`;
+        for (const client of this.eventClients) {
+            client.write(message);
+        }
+    }
+    // === Route Handlers ===
+    /**
+     * List all servers
+     */
+    async listServers(_req, res) {
+        try {
+            const servers = this.configLoader.getServers();
+            const serverInfos = servers.map((config) => {
+                const isStdio = config.transport === 'stdio' || config.transport === undefined;
+                const tools = this.serverManager.getServerTools(config.name);
+                const baseInfo = {
+                    name: config.name,
+                    env: config.env || {},
+                    status: (this.serverManager.getServerStatus(config.name)?.status || 'stopped'),
+                    process: this.serverManager.getServerStatus(config.name),
+                    toolCount: tools.length || 0,
+                    tokenEstimate: calculateTotalTokens(tools),
+                };
+                return isStdio
+                    ? {
+                        ...baseInfo,
+                        command: config.command,
+                        args: config.args || [],
+                    }
+                    : {
+                        ...baseInfo,
+                        transport: config.transport,
+                        url: config.url,
+                    };
+            });
+            res.json({ servers: serverInfos });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to list servers',
+            });
+        }
+    }
+    /**
+     * List all available servers (including disabled ones)
+     */
+    async listAvailableServers(_req, res) {
+        try {
+            const allServers = this.configLoader.getAllServers();
+            const exposedServers = this.configLoader.getServers();
+            const exposedNames = new Set(exposedServers.map(s => s.name));
+            const serverInfos = allServers.map((config) => {
+                const isStdio = config.transport === 'stdio' || config.transport === undefined;
+                const tools = this.serverManager.getServerTools(config.name);
+                const baseInfo = {
+                    name: config.name,
+                    type: isStdio ? 'stdio' : 'http',
+                    env: config.env || {},
+                    status: (this.serverManager.getServerStatus(config.name)?.status || 'stopped'),
+                    process: this.serverManager.getServerStatus(config.name),
+                    enabled: exposedNames.has(config.name),
+                    toolCount: tools.length || 0,
+                    tokenEstimate: calculateTotalTokens(tools),
+                };
+                return isStdio
+                    ? {
+                        ...baseInfo,
+                        command: config.command,
+                        args: config.args || [],
+                        fullCommand: `${config.command} ${(config.args || []).join(' ')}`.trim(),
+                    }
+                    : {
+                        ...baseInfo,
+                        transport: config.transport,
+                        url: config.url,
+                    };
+            });
+            res.json({ servers: serverInfos });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to list available servers',
+            });
+        }
+    }
+    /**
+     * Enable a server (add to EXPOSE_SERVERS)
+     */
+    async enableServer(req, res) {
+        try {
+            const { name } = req.params;
+            const config = this.configLoader.getServer(name);
+            if (!config) {
+                res.status(404).json({ error: `Server ${name} not found` });
+                return;
+            }
+            // Get current EXPOSE_SERVERS list
+            const currentExposed = process.env.EXPOSE_SERVERS
+                ? process.env.EXPOSE_SERVERS.split(',').map(s => s.trim())
+                : (this.config.base_servers || []);
+            // Add server if not already exposed
+            if (!currentExposed.includes(name)) {
+                currentExposed.push(name);
+                process.env.EXPOSE_SERVERS = currentExposed.join(',');
+            }
+            res.json({ success: true, message: `Server ${name} enabled` });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : 'Failed to enable server',
+            });
+        }
+    }
+    /**
+     * Disable a server (remove from EXPOSE_SERVERS)
+     */
+    async disableServer(req, res) {
+        try {
+            const { name } = req.params;
+            // Get current EXPOSE_SERVERS list
+            const currentExposed = process.env.EXPOSE_SERVERS
+                ? process.env.EXPOSE_SERVERS.split(',').map(s => s.trim())
+                : (this.config.base_servers || []);
+            // Remove server if exposed
+            const index = currentExposed.indexOf(name);
+            if (index >= 0) {
+                currentExposed.splice(index, 1);
+                process.env.EXPOSE_SERVERS = currentExposed.join(',');
+            }
+            res.json({ success: true, message: `Server ${name} disabled` });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : 'Failed to disable server',
+            });
+        }
+    }
+    /**
+     * Start a server
+     */
+    async startServer(req, res) {
+        try {
+            const { name } = req.params;
+            const config = this.configLoader.getServer(name);
+            if (!config) {
+                res.status(404).json({ error: `Server ${name} not found in configuration` });
+                return;
+            }
+            const process = await this.serverManager.startServer(config);
+            res.json({
+                success: true,
+                process,
+            });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : 'Failed to start server',
+            });
+        }
+    }
+    /**
+     * Stop a server
+     */
+    async stopServer(req, res) {
+        try {
+            const { name } = req.params;
+            await this.serverManager.stopServer(name);
+            res.json({
+                success: true,
+                message: `Server ${name} stopped`,
+            });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : 'Failed to stop server',
+            });
+        }
+    }
+    /**
+     * Restart a server
+     */
+    async restartServer(req, res) {
+        try {
+            const { name } = req.params;
+            const config = this.configLoader.getServer(name);
+            if (!config) {
+                res.status(404).json({ error: `Server ${name} not found in configuration` });
+                return;
+            }
+            const process = await this.serverManager.restartServer(config);
+            res.json({
+                success: true,
+                process,
+            });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : 'Failed to restart server',
+            });
+        }
+    }
+    /**
+     * Force refresh tools for a server
+     * v1.4.2: Clears cache and re-discovers tools from the MCP server
+     */
+    async refreshServerTools(req, res) {
+        try {
+            const { name } = req.params;
+            const config = this.configLoader.getServer(name);
+            if (!config) {
+                res.status(404).json({ error: `Server ${name} not found in configuration` });
+                return;
+            }
+            console.log(`[HTTP] Force refreshing tools for ${name}...`);
+            const tools = await this.serverManager.forceRefreshSchema(name, config);
+            res.json({
+                success: true,
+                serverName: name,
+                toolCount: tools.length,
+                tools: tools.map(t => t.name),
+            });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : 'Failed to refresh server tools',
+            });
+        }
+    }
+    /**
+     * Get server status
+     */
+    async getServerStatus(req, res) {
+        try {
+            const { name } = req.params;
+            // Check if server exists in registry first
+            const serverConfig = this.configLoader.getServer(name);
+            if (!serverConfig) {
+                res.status(404).json({ error: `Server ${name} not found` });
+                return;
+            }
+            // Get runtime status (may be undefined if stopped)
+            const status = this.serverManager.getServerStatus(name);
+            // If no runtime status, server exists but is stopped
+            if (!status) {
+                res.json({
+                    server: name,
+                    status: {
+                        pid: 0,
+                        status: 'stopped',
+                        uptime: 0,
+                        lastHealthCheck: 0,
+                        errorCount: 0
+                    }
+                });
+                return;
+            }
+            res.json({ server: name, status });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get server status',
+            });
+        }
+    }
+    /**
+     * Get full server information including configuration and runtime status
+     * v1.1.29: Include tools list and support ?forceDiscovery=true to rediscover
+     */
+    async getServerInfo(req, res) {
+        try {
+            const { name } = req.params;
+            const forceDiscovery = req.query.forceDiscovery === 'true';
+            // Get server configuration from registry
+            const serverConfig = this.configLoader.getServer(name);
+            if (!serverConfig) {
+                res.status(404).json({ error: `Server ${name} not found` });
+                return;
+            }
+            // If forceDiscovery is requested, start server and refresh tools
+            if (forceDiscovery) {
+                console.log(`[ServerInfo] Force discovery requested for '${name}'`);
+                try {
+                    // v1.1.47: Clear cache before rediscovery to force fresh tool fetch
+                    // This ensures forceDiscovery actually queries the server, not cache
+                    this.serverManager.invalidateServerSchema(name);
+                    console.log(`[ServerInfo] Invalidated cache for '${name}'`);
+                    await this.serverManager.ensureServerStarted(name, serverConfig);
+                    console.log(`[ServerInfo] Rediscovered tools for '${name}'`);
+                }
+                catch (discoveryError) {
+                    console.warn(`[ServerInfo] Force discovery failed for '${name}':`, discoveryError);
+                }
+            }
+            // Get runtime status
+            const runtimeStatus = this.serverManager.getServerStatus(name);
+            // Get tools from cache (memory or disk)
+            const tools = this.serverManager.getServerTools(name);
+            // Get list of exposed servers to determine if this server is enabled
+            const exposedServers = this.configLoader.getServers();
+            const enabled = exposedServers.some((s) => s.name === name);
+            // Build response - different fields for stdio vs HTTP servers
+            const isStdio = serverConfig.transport === 'stdio' || serverConfig.transport === undefined;
+            const baseResponse = {
+                name: serverConfig.name,
+                status: runtimeStatus?.status || 'stopped',
+                enabled,
+                pid: runtimeStatus?.pid,
+                uptime: runtimeStatus?.uptime,
+                lastHealthCheck: runtimeStatus?.lastHealthCheck,
+                errorCount: runtimeStatus?.errorCount,
+                tools: tools.map(t => t.name),
+                toolCount: tools.length,
+            };
+            const response = isStdio
+                ? {
+                    ...baseResponse,
+                    command: serverConfig.command,
+                    args: serverConfig.args || [],
+                    env: serverConfig.env || {},
+                }
+                : {
+                    ...baseResponse,
+                    transport: serverConfig.transport,
+                    url: serverConfig.url,
+                    auth: serverConfig.auth,
+                    env: serverConfig.env || {},
+                };
+            res.json(response);
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get server info',
+            });
+        }
+    }
+    /**
+     * Get server tools (stub - Phase 2)
+     */
+    async getServerTools(req, res) {
+        try {
+            const { name } = req.params;
+            const status = this.serverManager.getServerStatus(name);
+            if (!status || status.status !== 'running') {
+                res.status(400).json({ error: `Server ${name} is not running` });
+                return;
+            }
+            // Get tools from ServerManager cache (populated during server start)
+            const tools = this.serverManager.getServerTools(name);
+            res.json({ server: name, tools });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get server tools',
+            });
+        }
+    }
+    /**
+     * Execute tool (stub - Phase 2)
+     */
+    async executeTool(req, res) {
+        try {
+            const { name, toolName } = req.params;
+            const { arguments: args } = req.body;
+            const status = this.serverManager.getServerStatus(name);
+            if (!status || status.status !== 'running') {
+                res.status(400).json({ error: `Server ${name} is not running` });
+                return;
+            }
+            // Execute tool via ServerManager
+            const result = await this.serverManager.callTool(name, toolName, args);
+            const response = {
+                success: true,
+                result,
+            };
+            res.json(response);
+        }
+        catch (error) {
+            const response = {
+                success: false,
+                error: error instanceof Error ? error.message : 'Failed to execute tool',
+            };
+            res.status(500).json(response);
+        }
+    }
+    /**
+     * Get configuration
+     */
+    async getConfig(_req, res) {
+        try {
+            const config = this.configLoader.getConfig();
+            res.json(config);
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get configuration',
+            });
+        }
+    }
+    /**
+     * Update configuration (stub - Phase 2)
+     */
+    async updateConfig(req, res) {
+        try {
+            // Extract config updates from request body
+            const updates = req.body;
+            if (!updates || typeof updates !== 'object') {
+                res.status(400).json({ error: 'Invalid configuration: expected object' });
+                return;
+            }
+            // Handle specific config sections that can be updated
+            if (updates.toolSafetyRules) {
+                await this.configLoader.setToolSafetyRules(updates.toolSafetyRules);
+            }
+            // Reload configuration to pick up any file-based changes
+            await this.configLoader.reload();
+            res.json({ success: true, message: 'Configuration updated' });
+        }
+        catch (error) {
+            res.status(400).json({
+                error: error instanceof Error ? error.message : 'Failed to update configuration',
+            });
+        }
+    }
+    /**
+     * Health check endpoint
+     */
+    async healthCheck(_req, res) {
+        try {
+            // Calculate daemon uptime
+            const uptimeMs = Date.now() - this.startTime;
+            const uptimeSeconds = Math.floor(uptimeMs / 1000);
+            // Get base servers from config
+            const baseServers = this.config.base_servers || [];
+            // Build health checks for base servers
+            const baseServerChecks = {};
+            let healthyCount = 0;
+            let degradedCount = 0;
+            for (const serverName of baseServers) {
+                try {
+                    const isActive = this.serverManager.isServerActive(serverName);
+                    if (isActive) {
+                        const tools = this.serverManager.getServerTools(serverName);
+                        baseServerChecks[serverName] = {
+                            status: 'healthy',
+                            tools_count: tools.length
+                        };
+                        healthyCount++;
+                    }
+                    else {
+                        baseServerChecks[serverName] = {
+                            status: 'unhealthy',
+                            error: 'Server not running'
+                        };
+                        degradedCount++;
+                    }
+                }
+                catch (error) {
+                    baseServerChecks[serverName] = {
+                        status: 'unhealthy',
+                        error: error instanceof Error ? error.message : 'Unknown error'
+                    };
+                    degradedCount++;
+                }
+            }
+            // Determine overall status
+            let overallStatus;
+            let httpStatusCode;
+            if (degradedCount === 0) {
+                // All base servers are healthy
+                overallStatus = 'healthy';
+                httpStatusCode = 200;
+            }
+            else if (healthyCount > 0) {
+                // Some base servers are down but not all
+                overallStatus = 'degraded';
+                httpStatusCode = 200; // Still operational
+            }
+            else {
+                // All base servers are down or critical failure
+                overallStatus = 'unhealthy';
+                httpStatusCode = 503; // Service Unavailable
+            }
+            const health = {
+                status: overallStatus,
+                version,
+                uptime_seconds: uptimeSeconds,
+                checks: {
+                    daemon: {
+                        status: 'healthy'
+                    },
+                    base_servers: baseServerChecks
+                }
+            };
+            res.status(httpStatusCode).json(health);
+        }
+        catch (error) {
+            // Critical daemon error
+            res.status(503).json({
+                status: 'unhealthy',
+                version,
+                uptime_seconds: Math.floor((Date.now() - this.startTime) / 1000),
+                checks: {
+                    daemon: {
+                        status: 'unhealthy',
+                        error: error instanceof Error ? error.message : 'Health check failed'
+                    }
+                }
+            });
+        }
+    }
+    /**
+     * Get MetaLink version
+     */
+    async getVersion(_req, res) {
+        try {
+            res.json({ version });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get version',
+            });
+        }
+    }
+    // === Metrics Endpoints (Phase 4 - v1.4.0) ===
+    /**
+     * GET /api/v1/metrics - JSON metrics endpoint
+     */
+    async getMetrics(_req, res) {
+        try {
+            res.json({
+                version,
+                timestamp: Date.now(),
+                api: globalMetrics.getApiMetrics(),
+                servers: globalMetrics.getAllServerMetrics(),
+                tools: globalMetrics.getMetrics(),
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get metrics',
+            });
+        }
+    }
+    /**
+     * GET /api/v1/metrics/prometheus - Prometheus export endpoint
+     */
+    async getPrometheusMetrics(_req, res) {
+        try {
+            res.set('Content-Type', 'text/plain');
+            res.send(globalMetrics.exportPrometheus());
+        }
+        catch (error) {
+            res.status(500).send(`# Error exporting metrics: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * GET /api/v1/metrics/api - API-level metrics
+     */
+    async getApiMetrics(_req, res) {
+        try {
+            res.json(globalMetrics.getApiMetrics());
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get API metrics',
+            });
+        }
+    }
+    /**
+     * GET /api/v1/metrics/servers/:name - Server-specific metrics
+     */
+    async getServerMetrics(req, res) {
+        try {
+            const { name } = req.params;
+            const serverMetrics = globalMetrics.getServerMetrics(name);
+            if (!serverMetrics) {
+                res.status(404).json({ error: `Server '${name}' not found or no metrics available` });
+                return;
+            }
+            res.json(serverMetrics);
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get server metrics',
+            });
+        }
+    }
+    /**
+     * GET /api/v1/metrics/hourly - Hourly aggregation
+     */
+    async getHourlyMetrics(req, res) {
+        try {
+            const hours = parseInt(req.query.hours || '24');
+            const allMetrics = globalMetrics.getMetrics();
+            const hourlyData = this.metricsAggregator.aggregateHourly(allMetrics, hours);
+            res.json({
+                period: 'hourly',
+                hours,
+                data: hourlyData,
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get hourly metrics',
+            });
+        }
+    }
+    /**
+     * GET /api/v1/metrics/daily - Daily aggregation
+     */
+    async getDailyMetrics(req, res) {
+        try {
+            const days = parseInt(req.query.days || '7');
+            const allMetrics = globalMetrics.getMetrics();
+            const dailyData = this.metricsAggregator.aggregateDaily(allMetrics, days);
+            res.json({
+                period: 'daily',
+                days,
+                data: dailyData,
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get daily metrics',
+            });
+        }
+    }
+    /**
+     * GET /api/v1/metrics/weekly - Weekly aggregation
+     */
+    async getWeeklyMetrics(req, res) {
+        try {
+            const weeks = parseInt(req.query.weeks || '4');
+            const allMetrics = globalMetrics.getMetrics();
+            const weeklyData = this.metricsAggregator.aggregateWeekly(allMetrics, weeks);
+            res.json({
+                period: 'weekly',
+                weeks,
+                data: weeklyData,
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get weekly metrics',
+            });
+        }
+    }
+    /**
+     * GET /api/v1/metrics/errors - Error analytics across all tools
+     */
+    async getErrorAnalytics(_req, res) {
+        try {
+            const analytics = globalMetrics.getErrorAnalytics();
+            res.json(analytics);
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get error analytics',
+            });
+        }
+    }
+    /**
+     * GET /api/v1/metrics/errors/:toolName - Per-tool error analytics
+     * Query params: ?serverName=<name> (optional)
+     */
+    async getToolErrorMetrics(req, res) {
+        try {
+            const { toolName } = req.params;
+            const serverName = req.query.serverName;
+            const metrics = globalMetrics.getToolErrorMetrics(toolName, serverName);
+            if (!metrics) {
+                res.status(404).json({
+                    error: `No metrics found for tool '${toolName}'${serverName ? ` on server '${serverName}'` : ''}`
+                });
+                return;
+            }
+            res.json(metrics);
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get tool error metrics',
+            });
+        }
+    }
+    /**
+     * GET /api/v1/metrics/tools - Granular tool-specific metrics (Test 187)
+     * Query params:
+     *   ?serverName=<name> - Filter by server
+     *   ?slow=<limit> - Get slowest tools (by p95 latency)
+     *   ?errors=<threshold> - Get tools with high error rates (default: 5%)
+     */
+    async getToolMetrics(req, res) {
+        try {
+            const { serverName } = req.query;
+            const slow = req.query.slow ? parseInt(req.query.slow, 10) : undefined;
+            const errorsThreshold = req.query.errors ? parseFloat(req.query.errors) : undefined;
+            let metrics = globalMetrics.getAllToolMetrics();
+            // Filter by server if requested
+            if (serverName) {
+                metrics = metrics.filter(m => m.serverName === serverName);
+            }
+            // Return slowest tools if requested
+            if (slow !== undefined) {
+                metrics = globalMetrics.getSlowestTools(slow);
+            }
+            // Return high error rate tools if requested
+            if (errorsThreshold !== undefined) {
+                metrics = globalMetrics.getHighErrorRateTools(errorsThreshold);
+            }
+            res.json({
+                tools: metrics,
+                count: metrics.length,
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get tool metrics',
+            });
+        }
+    }
+    /**
+     * Load persisted metrics on startup (Phase 4 - v1.4.0)
+     */
+    async loadPersistedMetrics() {
+        try {
+            const data = await this.metricsPersistence.load();
+            if (data) {
+                globalMetrics.restoreMetrics(data);
+                console.log('[MetricsPersistence] Successfully restored metrics from disk');
+            }
+            else {
+                console.log('[MetricsPersistence] No persisted metrics found, starting fresh');
+            }
+        }
+        catch (error) {
+            console.error('[MetricsPersistence] Failed to load metrics:', error);
+            console.log('[MetricsPersistence] Starting with fresh metrics');
+        }
+    }
+    /**
+     * Start periodic metrics persistence (Phase 4 - v1.4.0)
+     */
+    startMetricsPersistence() {
+        const getMetricsData = () => ({
+            timestamp: Date.now(),
+            metrics: globalMetrics.getMetrics(),
+            serverMetrics: globalMetrics.getAllServerMetrics(),
+            toolMetrics: Array.from(globalMetrics['toolMetrics'].values()), // Access private field for persistence
+            apiMetrics: globalMetrics.getApiMetrics(),
+        });
+        // Save every 60 seconds
+        this.metricsPersistence.startPeriodicWrites(getMetricsData, 60000);
+        console.log('[MetricsPersistence] Started periodic writes (60s interval)');
+    }
+    // ===  Session Management (Streamable HTTP - MCP 2025-03-26) ===
+    /**
+     * Track SSE event for Last-Event-ID resumption
+     */
+    trackSseEvent(sessionId, eventData) {
+        const eventId = ++this.sseEventCounter;
+        let events = this.sseEventBuffer.get(sessionId);
+        if (!events) {
+            events = [];
+            this.sseEventBuffer.set(sessionId, events);
+        }
+        events.push({
+            id: eventId,
+            timestamp: Date.now(),
+            data: eventData
+        });
+        // Keep only last N events to avoid memory bloat
+        if (events.length > this.MAX_EVENTS_PER_SESSION) {
+            events.shift();
+        }
+        return eventId;
+    }
+    /**
+     * Get events for resumption after Last-Event-ID
+     */
+    getEventsForResumption(sessionId, lastEventId) {
+        const events = this.sseEventBuffer.get(sessionId) || [];
+        if (!lastEventId)
+            return events;
+        // Return all events after lastEventId
+        return events.filter(e => e.id > lastEventId);
+    }
+    createSession(clientInfo) {
+        const sessionId = randomUUID();
+        this.sessions.set(sessionId, {
+            id: sessionId,
+            createdAt: Date.now(),
+            lastActivity: Date.now(),
+            clientInfo,
+            initialized: false,
+            lastEventId: 0,
+            protocolVersion: '2025-06-18'
+        });
+        const clientName = clientInfo?.name || 'unknown';
+        const clientVersion = clientInfo?.version || 'unknown';
+        console.log(`[MCP] Session created: ${sessionId} | Client: ${clientName}/${clientVersion}`);
+        // Persist sessions to disk (v1.1.24+)
+        this.persistSessions();
+        return sessionId;
+    }
+    /**
+     * Get and update session activity with validation logging
+     */
+    getSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.lastActivity = Date.now();
+            const elapsed = Date.now() - session.createdAt;
+            console.log(`[MCP] Session accessed: ${sessionId} | Initialized: ${session.initialized} | Age: ${elapsed}ms`);
+        }
+        else {
+            console.log(`[MCP] Session not found: ${sessionId}`);
+        }
+        return session;
+    }
+    /**
+     * Clean up expired sessions
+     */
+    cleanupSessions() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [id, session] of this.sessions) {
+            if (now - session.lastActivity > this.SESSION_TIMEOUT) {
+                this.sessions.delete(id);
+                cleaned++;
+            }
+        }
+        if (cleaned > 0) {
+            console.log(`[MCP] Cleaned up ${cleaned} expired sessions`);
+            // Persist cleaned state to disk (v1.1.24+)
+            this.persistSessions();
+        }
+    }
+    /**
+     * Start session cleanup timer
+     */
+    startSessionCleanup() {
+        if (this.sessionCleanupInterval) {
+            clearInterval(this.sessionCleanupInterval);
+        }
+        // Run cleanup every 5 minutes
+        this.sessionCleanupInterval = setInterval(() => this.cleanupSessions(), 5 * 60 * 1000);
+    }
+    /**
+     * Stop session cleanup timer
+     */
+    stopSessionCleanup() {
+        if (this.sessionCleanupInterval) {
+            clearInterval(this.sessionCleanupInterval);
+            this.sessionCleanupInterval = null;
+        }
+    }
+    /**
+     * Persist sessions to disk with atomic write (temp file + rename)
+     * Called after session creation and cleanup
+     */
+    persistSessions() {
+        try {
+            // Ensure directory exists
+            const dir = path.dirname(this.sessionPersistPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            // Convert Map to object for JSON serialization
+            const sessionsObj = {};
+            for (const [id, session] of this.sessions) {
+                sessionsObj[id] = session;
+            }
+            const data = {
+                version: this.SESSION_PERSIST_VERSION,
+                persistedAt: Date.now(),
+                sessions: sessionsObj
+            };
+            // Atomic write: write to temp file, then rename
+            const tempPath = `${this.sessionPersistPath}.tmp`;
+            fs.writeFileSync(tempPath, JSON.stringify(data, null, 2), 'utf8');
+            fs.renameSync(tempPath, this.sessionPersistPath);
+            console.log(`[SessionPersistence] Saved ${this.sessions.size} sessions to disk`);
+        }
+        catch (error) {
+            console.error('[SessionPersistence] Failed to persist sessions:', error);
+            // Non-fatal: sessions still work in memory
+        }
+    }
+    /**
+     * Load sessions from disk on startup
+     * Filters out expired sessions during load
+     */
+    loadSessions() {
+        try {
+            if (!fs.existsSync(this.sessionPersistPath)) {
+                console.log('[SessionPersistence] No persisted sessions found, starting fresh');
+                return;
+            }
+            const content = fs.readFileSync(this.sessionPersistPath, 'utf8');
+            const data = JSON.parse(content);
+            // Version check for future migrations
+            if (data.version !== this.SESSION_PERSIST_VERSION) {
+                console.log(`[SessionPersistence] Version mismatch (got ${data.version}, expected ${this.SESSION_PERSIST_VERSION}), starting fresh`);
+                return;
+            }
+            const now = Date.now();
+            let loaded = 0;
+            let expired = 0;
+            for (const [id, session] of Object.entries(data.sessions || {})) {
+                const sess = session;
+                // Filter out expired sessions during load
+                if (now - sess.lastActivity > this.SESSION_TIMEOUT) {
+                    expired++;
+                    continue;
+                }
+                this.sessions.set(id, sess);
+                loaded++;
+            }
+            console.log(`[SessionPersistence] Restored ${loaded} sessions from disk (${expired} expired sessions discarded)`);
+            // If we discarded expired sessions, persist the cleaned state
+            if (expired > 0) {
+                this.persistSessions();
+            }
+        }
+        catch (error) {
+            const errCode = error.code;
+            if (errCode === 'ENOENT') {
+                console.log('[SessionPersistence] No persisted sessions found, starting fresh');
+            }
+            else {
+                console.error('[SessionPersistence] Failed to load sessions:', error);
+                console.log('[SessionPersistence] Starting with fresh sessions');
+            }
+        }
+    }
+    /**
+     * Handle Streamable HTTP request (MCP 2025-03-26)
+     * Returns tuple of [response, sessionId] for session tracking
+     */
+    async handleStreamableRequest(request, req) {
+        const { method, params, id } = request;
+        const sessionId = req?.headers['mcp-session-id'];
+        // Validate JSON-RPC 2.0 structure
+        if (!request.jsonrpc || request.jsonrpc !== '2.0') {
+            return [{
+                    jsonrpc: '2.0',
+                    id,
+                    error: { code: -32600, message: 'Invalid Request: jsonrpc field must be "2.0"' }
+                }, sessionId];
+        }
+        try {
+            let result;
+            let session;
+            let responseSessionId;
+            // Handle session-aware methods
+            if (method === 'initialize') {
+                const initParams = params;
+                // Protocol version negotiation per spec 2025-11-25
+                const requestedVersion = initParams.protocolVersion;
+                const supportedVersions = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05']; // List in order of preference
+                let negotiatedVersion = '2025-11-25'; // Default to latest
+                if (requestedVersion) {
+                    if (supportedVersions.includes(requestedVersion)) {
+                        // Client requested supported version
+                        negotiatedVersion = requestedVersion;
+                        console.log(`[MCP] Protocol version negotiated: ${requestedVersion}`);
+                    }
+                    else {
+                        // Client requested unsupported version - offer fallback chain
+                        console.log(`[MCP] Unsupported protocol version requested: ${requestedVersion}. Offering fallback to ${negotiatedVersion}`);
+                        // Return error with supported versions for client to retry with fallback
+                        return [{
+                                jsonrpc: '2.0',
+                                id,
+                                error: {
+                                    code: -32602,
+                                    message: `Unsupported protocol version: ${requestedVersion}`,
+                                    data: {
+                                        requested: requestedVersion,
+                                        supported: supportedVersions,
+                                        recommended: negotiatedVersion
+                                    }
+                                }
+                            }, undefined];
+                    }
+                }
+                // Create or retrieve session
+                let newSessionId;
+                if (sessionId && this.getSession(sessionId)) {
+                    // Session ID provided and exists - reuse it
+                    newSessionId = sessionId;
+                }
+                else if (sessionId) {
+                    // Session ID provided but doesn't exist - create it with that ID
+                    this.sessions.set(sessionId, {
+                        id: sessionId,
+                        createdAt: Date.now(),
+                        lastActivity: Date.now(),
+                        clientInfo: initParams.clientInfo,
+                        initialized: false,
+                        lastEventId: 0,
+                        protocolVersion: '2025-06-18'
+                    });
+                    newSessionId = sessionId;
+                }
+                else {
+                    // No session ID provided - create new one
+                    newSessionId = this.createSession(initParams.clientInfo);
+                }
+                session = this.getSession(newSessionId);
+                session.initialized = true;
+                session.protocolVersion = negotiatedVersion;
+                session.userAgent = req?.headers?.['user-agent'] || 'unknown';
+                session.lastEventId = 0;
+                responseSessionId = newSessionId;
+                // Store client capabilities for per-client feature adaptation
+                if (initParams.capabilities) {
+                    session.clientCapabilities = initParams.capabilities;
+                }
+                // Extract callback URL from request headers for bidirectional communication (MCP callback protocol)
+                if (req) {
+                    const callbackUrl = req.headers['x-callback-url'];
+                    const callbackPort = req.headers['x-callback-port'];
+                    if (callbackUrl || callbackPort) {
+                        const url = callbackUrl || `http://127.0.0.1:${callbackPort}/mcp`;
+                        session.callbackUrl = url;
+                        session.callbackPort = callbackPort ? parseInt(callbackPort, 10) : undefined;
+                        console.log(`[MCP] Callback registered: ${url}`);
+                    }
+                }
+                console.log(`[MCP] Initialize: ${newSessionId} | Protocol: ${negotiatedVersion} | Client: ${initParams.clientInfo?.name}/${initParams.clientInfo?.version}`);
+                result = {
+                    protocolVersion: negotiatedVersion,
+                    capabilities: {
+                        tools: { listChanged: true },
+                        prompts: { listChanged: false },
+                        resources: { listChanged: false }
+                    },
+                    serverInfo: {
+                        name: 'metalink',
+                        version
+                    }
+                };
+                return [{
+                        jsonrpc: '2.0',
+                        id,
+                        result
+                    }, responseSessionId];
+            }
+            else if (method === 'notifications/initialized') {
+                return [null, sessionId]; // No response for notifications
+            }
+            else {
+                // Allow stateless operation without session
+                responseSessionId = sessionId;
+                if (sessionId) {
+                    session = this.getSession(sessionId);
+                    if (!session) {
+                        // FALLBACK: This should not be reached - caller validates session before calling this function.
+                        // If we get here, it means session was invalidated between caller check and this check.
+                        // Per MCP spec, should return HTTP 404, but we can't from this function.
+                        // Caller handles HTTP 404 at line ~2067. This is defensive programming only.
+                        console.error(`[MCP] Session validation fallback triggered for: ${sessionId.substring(0, 8)}...`);
+                        return [{
+                                jsonrpc: '2.0',
+                                id,
+                                error: { code: -32603, message: 'Invalid or expired session' }
+                            }, sessionId];
+                    }
+                }
+                // Handle other MCP methods
+                if (method === 'ping') {
+                    // MCP spec: ping method for keepalive/health checks
+                    result = {};
+                }
+                else if (method === 'roots/list') {
+                    result = { roots: [] };
+                }
+                else if (method === 'prompts/list') {
+                    result = { prompts: getPromptsList() };
+                }
+                else if (method === 'resources/list') {
+                    result = { resources: getResourcesList() };
+                }
+                else if (method === 'resources/templates/list') {
+                    result = { resourceTemplates: getResourceTemplatesList() };
+                }
+                else if (method === 'prompts/get') {
+                    const promptParams = params;
+                    if (!promptParams.name) {
+                        throw new InvalidParamsError('Missing required parameter: name');
+                    }
+                    try {
+                        result = getPrompt(promptParams.name, promptParams.arguments || {});
+                    }
+                    catch (err) {
+                        throw new InvalidParamsError(err instanceof Error ? err.message : 'Unknown prompt error');
+                    }
+                }
+                else if (method === 'resources/read') {
+                    const resourceParams = params;
+                    if (!resourceParams.uri) {
+                        throw new InvalidParamsError('Missing required parameter: uri');
+                    }
+                    try {
+                        result = await readResource(resourceParams.uri, this.serverManager, this.configLoader);
+                    }
+                    catch (err) {
+                        throw new InvalidParamsError(err instanceof Error ? err.message : 'Unknown resource error');
+                    }
+                }
+                else if (method === 'tools/list') {
+                    // Auto-reinitialize session if not initialized (transparent to client)
+                    // This handles stale sessions from server restarts without client needing to retry
+                    if (!session?.initialized) {
+                        const newSessionId = this.createSession({ name: 'auto-reinit', version: '1.0' });
+                        const newSession = this.getSession(newSessionId);
+                        newSession.initialized = true;
+                        newSession.protocolVersion = '2025-06-18';
+                        responseSessionId = newSessionId;
+                        console.log(`[MCP] Auto-reinitialized session for tools/list: ${newSessionId}`);
+                    }
+                    result = await this.mcpListTools();
+                }
+                else if (method === 'tools/call') {
+                    // Auto-reinitialize session if not initialized (transparent to client)
+                    // This handles stale sessions from server restarts without client needing to retry
+                    let effectiveSessionId = sessionId;
+                    if (!session?.initialized) {
+                        const newSessionId = this.createSession({ name: 'auto-reinit', version: '1.0' });
+                        const newSession = this.getSession(newSessionId);
+                        newSession.initialized = true;
+                        newSession.protocolVersion = '2025-06-18';
+                        responseSessionId = newSessionId;
+                        effectiveSessionId = newSessionId;
+                        console.log(`[MCP] Auto-reinitialized session for tools/call: ${newSessionId}`);
+                    }
+                    const callParams = params;
+                    if (!callParams.name) {
+                        throw new InvalidParamsError('Missing required parameter: name');
+                    }
+                    result = await this.mcpCallTool(callParams.name, callParams.arguments, effectiveSessionId);
+                }
+                else {
+                    return [{
+                            jsonrpc: '2.0',
+                            id,
+                            error: { code: -32601, message: `Unknown method: ${method}` }
+                        }, sessionId];
+                }
+            }
+            return [{
+                    jsonrpc: '2.0',
+                    id,
+                    result
+                }, responseSessionId];
+        }
+        catch (error) {
+            // SessionNotInitializedError must bubble up to trigger HTTP 404
+            // This allows client auto-reinitialize handlers to work per MCP spec
+            if (error instanceof SessionNotInitializedError) {
+                throw error;
+            }
+            // Check if this is an invalid parameters error (JSON-RPC -32602)
+            const isInvalidParams = error instanceof InvalidParamsError;
+            return [{
+                    jsonrpc: '2.0',
+                    id,
+                    error: {
+                        code: isInvalidParams ? -32602 : -32603,
+                        message: error instanceof Error ? error.message : 'Internal error'
+                    }
+                }, sessionId];
+        }
+    }
+    /**
+     * Handle MCP JSON-RPC requests over HTTP
+     */
+    async handleMcpRequest(req, res) {
+        const requestStartTime = Date.now();
+        const userAgent = req.headers['user-agent'] || 'unknown';
+        const sessionId = req.headers['mcp-session-id'];
+        const requestId = req.requestId || generateRequestId();
+        // Create child logger with request context
+        const reqLogger = logger.child({
+            requestId,
+            sessionId,
+            method: req.method,
+            userAgent,
+        });
+        // Log incoming MCP request
+        reqLogger.info('MCP request received', {
+            path: req.path,
+            protocol: req.headers['mcp-protocol-version'],
+        });
+        try {
+            // Handle GET requests per MCP spec 2025-06-18 - SSE streaming for server-sent events
+            if (req.method === 'GET') {
+                const sessionId = req.headers['mcp-session-id'];
+                // If no session ID, handle health check with JSON response
+                if (!sessionId) {
+                    const responseTime = Date.now() - requestStartTime;
+                    reqLogger.info('Health check request', {
+                        accept: req.headers.accept,
+                        protocolVersion: req.headers['mcp-protocol-version'],
+                    });
+                    // Health check - always return JSON regardless of Accept header
+                    res.setHeader('Content-Type', 'application/json');
+                    res.setHeader('MCP-Protocol-Version', MCP_PROTOCOL_VERSION);
+                    res.setHeader('X-Request-Id', requestId);
+                    res.status(200).json({ status: 'ready', protocol: MCP_PROTOCOL_VERSION });
+                    reqLogger.info('Health check response sent', {
+                        status: 200,
+                        duration_ms: responseTime,
+                    });
+                    return;
+                }
+                // Session-based requests - set up SSE streaming with Last-Event-ID resumption support
+                res.setHeader('Content-Type', 'text/event-stream');
+                res.setHeader('Cache-Control', 'no-cache');
+                res.setHeader('Connection', 'keep-alive');
+                res.setHeader('X-Accel-Buffering', 'no');
+                res.setHeader('MCP-Protocol-Version', MCP_PROTOCOL_VERSION);
+                const session = this.getSession(sessionId);
+                if (!session?.initialized) {
+                    res.status(404).json({ error: 'Session not found or not initialized' });
+                    return;
+                }
+                res.setHeader('Mcp-Session-Id', sessionId);
+                // Check for Last-Event-ID header (per MCP 2025-06-18 spec for resumption)
+                const lastEventIdHeader = req.headers['last-event-id'];
+                const lastEventId = lastEventIdHeader ? parseInt(String(lastEventIdHeader), 10) : undefined;
+                if (lastEventId !== undefined) {
+                    reqLogger.info('SSE stream resumption requested', {
+                        lastEventId,
+                        transport: 'sse',
+                    });
+                }
+                else {
+                    reqLogger.info('New SSE stream connection', {
+                        transport: 'sse',
+                    });
+                }
+                // Track SSE connection for server-sent messages
+                this.sseConnections.set(sessionId, res);
+                // Send buffered events for resumption (if Last-Event-ID was provided)
+                if (lastEventId !== undefined) {
+                    const bufferedEvents = this.getEventsForResumption(sessionId, lastEventId);
+                    if (bufferedEvents.length > 0) {
+                        reqLogger.debug('Sending buffered events for resumption', {
+                            eventCount: bufferedEvents.length,
+                            transport: 'sse',
+                        });
+                        for (const event of bufferedEvents) {
+                            res.write(`id: ${event.id}\ndata: ${JSON.stringify(event.data)}\n\n`);
+                        }
+                    }
+                }
+                else {
+                    // Send initial endpoint event ONLY on new connection (not on resumption)
+                    // Resuming connections should only receive buffered events, not duplicate endpoint events
+                    const endpointEventId = this.trackSseEvent(sessionId, { type: 'endpoint' });
+                    res.write(`id: ${endpointEventId}\ndata: ${JSON.stringify({ type: 'endpoint' })}\n\n`);
+                    // Update session's last event ID
+                    if (session) {
+                        session.lastEventId = endpointEventId;
+                    }
+                }
+                // Send periodic keepalive comments to prevent connection timeout
+                // SSE comments (lines starting with :) are ignored by clients but keep stream active
+                // This is critical for clients like mcp-remote that rely on async iterators
+                const keepaliveInterval = setInterval(() => {
+                    try {
+                        res.write(':keepalive\n\n');
+                    }
+                    catch (error) {
+                        reqLogger.debug('SSE keepalive write failed', {
+                            error: error instanceof Error ? error.message : 'Unknown error',
+                            transport: 'sse',
+                        });
+                        clearInterval(keepaliveInterval);
+                    }
+                }, 15000); // Send keepalive every 15 seconds
+                // Clean up on disconnect
+                req.on('close', () => {
+                    clearInterval(keepaliveInterval);
+                    this.sseConnections.delete(sessionId);
+                    reqLogger.info('SSE connection closed', {
+                        transport: 'sse',
+                    });
+                });
+                // Keep connection open for server-sent events
+                return;
+            }
+            // Check Accept header for SSE support
+            // Per HTTP spec, Accept header values left-to-right indicate preference
+            // "application/json, text/event-stream" means JSON is preferred (primary), SSE is fallback
+            // Only use SSE if:
+            // 1. Client explicitly requests ONLY SSE ("text/event-stream")
+            // 2. OR client doesn't offer JSON as an option
+            const acceptHeader = req.headers.accept || 'application/json';
+            const hasJSON = acceptHeader.includes('application/json');
+            const hasSSE = acceptHeader.includes('text/event-stream');
+            // Use SSE only if SSE is available AND JSON is NOT preferred
+            const useSSE = hasSSE && !hasJSON;
+            // Debug: Log all headers to understand mcp-remote communication
+            console.log('[MCP] POST request headers:', {
+                'x-callback-url': req.headers['x-callback-url'],
+                'x-callback-port': req.headers['x-callback-port'],
+                'mcp-session-id': req.headers['mcp-session-id'],
+                'user-agent': req.headers['user-agent'],
+                'content-type': req.headers['content-type'],
+                'accept': req.headers['accept']
+            });
+            console.log(`[MCP] SSE mode: ${useSSE} (based on Accept header: "${acceptHeader}")`);
+            // Parse raw body with robust error handling
+            let text = '';
+            try {
+                if (!req.body) {
+                    // Empty body - valid for some requests
+                    text = '';
+                }
+                else if (typeof req.body === 'string') {
+                    text = req.body;
+                }
+                else if (Buffer.isBuffer(req.body)) {
+                    text = req.body.toString('utf-8');
+                }
+                else {
+                    // Unknown body type - try to convert
+                    text = String(req.body);
+                }
+            }
+            catch (parseError) {
+                console.error('[MCP] Body parsing error:', parseError);
+                res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32700,
+                        message: 'Invalid request body'
+                    },
+                    id: null
+                });
+                return;
+            }
+            if (!text || text.trim().length === 0) {
+                res.setHeader('Content-Type', 'application/json');
+                res.send('');
+                return;
+            }
+            // Parse JSON-RPC requests (support both batch arrays and newline-delimited)
+            const responses = [];
+            let lastSessionId;
+            let requests = [];
+            let isBatchRequest = false;
+            // Try to parse as JSON array (batch request) first
+            try {
+                const parsed = JSON.parse(text.trim());
+                if (Array.isArray(parsed)) {
+                    // JSON-RPC 2.0 batch request
+                    console.log(`[MCP Request] Batch request with ${parsed.length} requests`);
+                    requests = parsed;
+                    isBatchRequest = true;
+                }
+                else {
+                    // Single request (most common case)
+                    requests = [parsed];
+                }
+            }
+            catch (parseError) {
+                // Fallback to newline-delimited format
+                const lines = text.split('\n').filter((line) => line.trim());
+                console.log(`[MCP Request] Newline-delimited format with ${lines.length} lines`);
+                for (const line of lines) {
+                    try {
+                        requests.push(JSON.parse(line));
+                    }
+                    catch (lineError) {
+                        responses.push({
+                            jsonrpc: '2.0',
+                            error: { code: -32700, message: 'Parse error' },
+                            id: null
+                        });
+                    }
+                }
+            }
+            // Log request body for debugging
+            if (requests.length > 0) {
+                console.log(`[MCP Request] Processing ${requests.length} request(s)`);
+                requests.forEach((req, idx) => {
+                    const truncatedParams = JSON.stringify(req.params || {}).substring(0, 200);
+                    console.log(`[MCP Request] ${idx + 1}: method="${req.method}" id="${req.id}" params=${truncatedParams}${JSON.stringify(req.params || {}).length > 200 ? '...' : ''}`);
+                });
+            }
+            for (const request of requests) {
+                try {
+                    // Detect protocol version and route appropriately
+                    if (request.method === 'initialize') {
+                        const protocolVersion = request.params?.protocolVersion;
+                        if (protocolVersion === '2024-11-05') {
+                            // Legacy protocol path
+                            const response = await this.handleJsonRpcRequest(request);
+                            if (response)
+                                responses.push(response);
+                        }
+                        else {
+                            // New Streamable HTTP protocol (default to 2025-06-18)
+                            const [response, sId] = await this.handleStreamableRequest(request, req);
+                            if (response) {
+                                responses.push(response);
+                                if (sId)
+                                    lastSessionId = sId;
+                            }
+                        }
+                    }
+                    else {
+                        // For non-initialize requests, detect by session presence in header
+                        const headerSessionId = req.headers['mcp-session-id'];
+                        if (headerSessionId) {
+                            // Session ID provided - check if it exists
+                            if (!this.getSession(headerSessionId)) {
+                                // Session doesn't exist - auto-create and initialize (transparent recovery)
+                                // This handles stale sessions from server restarts without client needing to reinitialize
+                                const newSessionId = this.createSession({ name: 'auto-reinit', version: '1.0' });
+                                const newSession = this.getSession(newSessionId);
+                                newSession.initialized = true;
+                                newSession.protocolVersion = '2025-06-18';
+                                console.log(`[MCP] Auto-reinitialized stale session ${headerSessionId.substring(0, 8)}... → ${newSessionId.substring(0, 8)}...`);
+                                // Update header for downstream processing (hacky but works)
+                                req.headers['mcp-session-id'] = newSessionId;
+                            }
+                            // Has valid session (original or auto-created) → use Streamable HTTP
+                            const [response, sId] = await this.handleStreamableRequest(request, req);
+                            if (response) {
+                                responses.push(response);
+                                if (sId)
+                                    lastSessionId = sId;
+                            }
+                        }
+                        else {
+                            // No session → use legacy protocol
+                            const response = await this.handleJsonRpcRequest(request);
+                            if (response)
+                                responses.push(response);
+                        }
+                    }
+                }
+                catch (parseError) {
+                    responses.push({
+                        jsonrpc: '2.0',
+                        error: { code: -32700, message: 'Parse error' },
+                        id: null
+                    });
+                }
+            }
+            // Send responses
+            if (responses.length === 0) {
+                const responseTime = Date.now() - requestStartTime;
+                console.log(`[MCP Response] ${new Date().toISOString()} | Empty response (202) | Time: ${responseTime}ms | User-Agent: ${userAgent}`);
+                res.status(202).end();
+                return;
+            }
+            // Respect the Accept header: if client requests SSE, send SSE
+            // Callback port is independent - it's for fallback/bidirectional, not transport selection
+            const shouldUseSSE = useSSE;
+            // Check if session has callback URL registered
+            const session = lastSessionId ? this.getSession(lastSessionId) : undefined;
+            const hasCallback = session?.callbackUrl !== undefined;
+            const responseTime = Date.now() - requestStartTime;
+            if (shouldUseSSE) {
+                // Server-Sent Events format
+                console.log(`[MCP] Sending ${responses.length} response(s) in SSE format`);
+                res.setHeader('Content-Type', 'text/event-stream');
+                res.setHeader('Cache-Control', 'no-cache');
+                res.setHeader('Connection', 'keep-alive');
+                res.setHeader('X-Accel-Buffering', 'no');
+                res.setHeader('MCP-Protocol-Version', MCP_PROTOCOL_VERSION);
+                for (const response of responses) {
+                    const dataStr = `data: ${JSON.stringify(response)}\n\n`;
+                    console.log(`[MCP] Writing SSE data: ${dataStr.substring(0, 100)}...`);
+                    res.write(dataStr);
+                }
+                console.log(`[MCP] Ending SSE response`);
+                res.end();
+                // Log SSE response summary
+                console.log(`[MCP Response] ${new Date().toISOString()} | SSE | Responses: ${responses.length} | Time: ${responseTime}ms | User-Agent: ${userAgent}`);
+                responses.forEach((resp, idx) => {
+                    const truncated = JSON.stringify(resp).substring(0, 300);
+                    console.log(`[MCP Response] SSE ${idx + 1}: ${truncated}${JSON.stringify(resp).length > 300 ? '...' : ''}`);
+                });
+            }
+            else {
+                // Standard JSON (array for batch, newline-delimited for multiple single requests)
+                reqLogger.debug('Sending JSON response', {
+                    responseCount: responses.length,
+                    batch: isBatchRequest,
+                    transport: 'json',
+                });
+                res.setHeader('Content-Type', 'application/json');
+                res.setHeader('MCP-Protocol-Version', MCP_PROTOCOL_VERSION);
+                res.setHeader('X-Request-Id', requestId);
+                // Set Mcp-Session-Id header if session exists
+                if (lastSessionId) {
+                    res.setHeader('Mcp-Session-Id', lastSessionId);
+                }
+                let responseText;
+                if (isBatchRequest) {
+                    // JSON-RPC 2.0 batch response: return as JSON array
+                    responseText = JSON.stringify(responses);
+                }
+                else {
+                    // Newline-delimited format (backward compatibility)
+                    responseText = responses.map(r => JSON.stringify(r)).join('\n');
+                }
+                res.write(responseText);
+                res.end();
+                reqLogger.info('MCP response sent', {
+                    responseCount: responses.length,
+                    duration_ms: responseTime,
+                    transport: 'json',
+                    batch: isBatchRequest,
+                });
+            }
+        }
+        catch (error) {
+            const responseTime = Date.now() - requestStartTime;
+            // SessionNotInitializedError returns HTTP 404 per MCP spec
+            // This triggers client auto-reinitialize handlers
+            if (error instanceof SessionNotInitializedError) {
+                reqLogger.info('Session not initialized - returning HTTP 404 for client auto-reinitialize', {
+                    error: error.message,
+                    duration_ms: responseTime,
+                });
+                res.setHeader('MCP-Protocol-Version', MCP_PROTOCOL_VERSION);
+                res.setHeader('X-Request-Id', requestId);
+                res.status(404).json({ error: error.message });
+                return;
+            }
+            reqLogger.error('MCP request failed', {
+                error: error instanceof Error ? error.message : 'Internal error',
+                stack: error instanceof Error ? error.stack : undefined,
+                duration_ms: responseTime,
+            });
+            res.setHeader('MCP-Protocol-Version', MCP_PROTOCOL_VERSION);
+            res.setHeader('X-Request-Id', requestId);
+            res.status(500).json({ error: error instanceof Error ? error.message : 'Internal error' });
+        }
+    }
+    /**
+     * Handle JSON-RPC method routing
+     */
+    async handleJsonRpcRequest(request) {
+        const { method, params, id } = request;
+        // Validate JSON-RPC 2.0 structure
+        if (!request.jsonrpc || request.jsonrpc !== '2.0') {
+            return {
+                jsonrpc: '2.0',
+                id,
+                error: { code: -32600, message: 'Invalid Request: jsonrpc field must be "2.0"' }
+            };
+        }
+        try {
+            let result;
+            // Handle MCP methods
+            if (method === 'notifications/initialized') {
+                return null; // No response for notifications
+            }
+            if (method === 'initialize') {
+                result = {
+                    protocolVersion: '2024-11-05',
+                    capabilities: {
+                        tools: { listChanged: true },
+                        prompts: { listChanged: false },
+                        resources: { listChanged: false },
+                    },
+                    serverInfo: {
+                        name: 'metalink',
+                        version,
+                    },
+                };
+            }
+            else if (method === 'ping') {
+                // MCP spec: ping method for keepalive/health checks
+                result = {};
+            }
+            else if (method === 'roots/list') {
+                result = { roots: [] };
+            }
+            else if (method === 'prompts/list') {
+                result = { prompts: getPromptsList() };
+            }
+            else if (method === 'resources/list') {
+                result = { resources: getResourcesList() };
+            }
+            else if (method === 'resources/templates/list') {
+                result = { resourceTemplates: getResourceTemplatesList() };
+            }
+            else if (method === 'prompts/get') {
+                const promptParams = params;
+                if (!promptParams.name) {
+                    throw new InvalidParamsError('Missing required parameter: name');
+                }
+                try {
+                    result = getPrompt(promptParams.name, promptParams.arguments || {});
+                }
+                catch (err) {
+                    throw new InvalidParamsError(err instanceof Error ? err.message : 'Unknown prompt error');
+                }
+            }
+            else if (method === 'resources/read') {
+                const resourceParams = params;
+                if (!resourceParams.uri) {
+                    throw new InvalidParamsError('Missing required parameter: uri');
+                }
+                try {
+                    result = await readResource(resourceParams.uri, this.serverManager, this.configLoader);
+                }
+                catch (err) {
+                    throw new InvalidParamsError(err instanceof Error ? err.message : 'Unknown resource error');
+                }
+            }
+            else if (method === 'tools/list') {
+                result = await this.mcpListTools();
+            }
+            else if (method === 'tools/call') {
+                const callParams = params;
+                if (!callParams.name) {
+                    throw new InvalidParamsError('Missing required parameter: name');
+                }
+                result = await this.mcpCallTool(callParams.name, callParams.arguments);
+            }
+            else {
+                throw new MethodNotFoundError(method);
+            }
+            return {
+                jsonrpc: '2.0',
+                id,
+                result,
+            };
+        }
+        catch (error) {
+            console.error(`[MCP] Error handling ${method}:`, error);
+            // Check for specific JSON-RPC error types
+            const isMethodNotFound = error instanceof MethodNotFoundError;
+            const isInvalidParams = error instanceof InvalidParamsError;
+            // Determine appropriate error code
+            let errorCode = -32603; // Default: Internal error
+            if (isMethodNotFound) {
+                errorCode = -32601; // Method not found
+            }
+            else if (isInvalidParams) {
+                errorCode = -32602; // Invalid params
+            }
+            return {
+                jsonrpc: '2.0',
+                id,
+                error: {
+                    code: errorCode,
+                    message: error instanceof Error ? error.message : 'Internal error',
+                },
+            };
+        }
+    }
+    /**
+     * Generate execute_tool description
+     * v1.3.x: Simplified - removed "Safe by default" list that caused confusion.
+     * Now relies solely on annotations.safety from search_tools results.
+     */
+    getExecuteToolDescription() {
+        // v1.3.x: Removed dynamic server list - was causing Claude to ignore annotations.safety
+        // The safety classification is now ONLY determined by checking annotations.safety in search_tools results
+        return 'Execute tool (auto-approved for safe tools). BLOCKS risky tools - use execute_tool_confirm for risky tools. IMPORTANT: Check annotations.safety in search_tools results - use execute_tool for "safe" tools, execute_tool_confirm for "risky" tools. Safety annotation is authoritative.';
+    }
+    /**
+     * MCP: tools/list - return available tools
+     *
+     * SPEAKEASY-INSPIRED 4-TOOL APPROACH (v1.3.52):
+     * 1. search_tools - Fuzzy search across all servers
+     * 2. describe_tool - Get full schema for specific tool
+     * 3. execute_tool - Execute safe/read-only tools (BLOCKS risky tools)
+     * 4. execute_tool_confirm - Execute risky/write tools (user confirmed)
+     *
+     * Optional: Base server tools (if dynamicToolExposure=true in config)
+     */
+    async mcpListTools() {
+        const tools = [];
+        // NO HARDCODING: Read base servers from config
+        const baseServerNames = this.configLoader.getBaseServers();
+        const dynamicToolExposure = this.config.dynamicToolExposure ?? false;
+        /**
+         * SPEAKEASY-INSPIRED 4-TOOL APPROACH (v1.3.52)
+         *
+         * Inspired by Speakeasy's token optimization strategy, we expose only 4 essential meta-tools:
+         *
+         * Discovery Tools (2):
+         * 1. search_tools - Fuzzy search across all available tools
+         * 2. describe_tool - Get full schema for a specific tool
+         *
+         * Execution Tools (2):
+         * 3. execute_tool - Execute safe tools (auto-approved based on annotations.safety)
+         *    - BLOCKS risky tools with error
+         *    - Safety annotation overrides read/write heuristics
+         * 4. execute_tool_confirm - Execute risky tools (requires user confirmation)
+         *    - ALLOWS any tool execution (user already confirmed)
+         *    - Logs classification but doesn't block
+         *
+         * Token usage: ~280 tokens (vs 1,300+ with full base server exposure)
+         * See: https://www.speakeasy.com/blog/how-we-reduced-token-usage-by-100x-dynamic-toolsets-v2
+         *
+         * Legacy mode: Set dynamicToolExposure=true to expose all base server tools
+         */
+        tools.push({
+            name: 'search_tools',
+            description: 'Search tools by keyword across all available servers, or list all tools from a specific server. Can also search by server name to find all tools from matching servers. When exactly 1 tool matches, automatically includes full schema (inputSchema, requiredParams, example) to save a describe_tool call. Each result includes annotations.safety ("safe" or "risky") - use execute_tool for safe, execute_tool_confirm for risky.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'Optional keyword to search for in server names, tool names, and descriptions. If query matches a server name, returns all tools from that server.',
+                    },
+                    server_name: {
+                        type: 'string',
+                        description: 'Optional server name to filter results. If provided, only returns tools from this specific server.',
+                    },
+                },
+                required: [],
+            },
+        }, {
+            name: 'describe_tool',
+            description: 'Get detailed schema for a specific tool including validation hints. Returns inputSchema, requiredParams, and optional validation warnings/suggestions when schema is incomplete or incorrect.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    server_name: {
+                        type: 'string',
+                        description: 'Server name (e.g., "memory", "jira-basic-auth")',
+                    },
+                    tool_name: {
+                        type: 'string',
+                        description: 'Tool name (e.g., "create_entities", "search_issues")',
+                    },
+                },
+                required: ['server_name', 'tool_name'],
+            },
+        }, {
+            name: 'execute_tool',
+            description: this.getExecuteToolDescription(),
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    server_name: {
+                        type: 'string',
+                        description: 'Server name (e.g., "jira-basic-auth", "memory")',
+                        example: 'jira-basic-auth'
+                    },
+                    tool_name: {
+                        type: 'string',
+                        description: 'Tool name (e.g., "confluence_search", "create_entities")',
+                        example: 'confluence_search'
+                    },
+                    arguments: {
+                        type: 'object',
+                        description: 'Tool-specific parameters. Call describe_tool(server_name, tool_name) first to discover required parameters, then nest those parameters here.',
+                        example: {
+                            cql: 'type=page ORDER BY created DESC',
+                            limit: 10
+                        },
+                        additionalProperties: true
+                    },
+                    max_results: {
+                        type: 'number',
+                        description: 'Optional: Limit array results to N items (for pagination)',
+                        example: 50
+                    },
+                    max_result_chars: {
+                        type: 'number',
+                        description: 'Optional: Limit total response size to N characters (default: 50000)',
+                        example: 10000
+                    },
+                    cursor: {
+                        type: 'string',
+                        description: 'Optional: Opaque cursor from previous response to continue pagination'
+                    }
+                },
+                required: ['server_name', 'tool_name', 'arguments'],
+                additionalProperties: false
+            }
+        }, {
+            name: 'execute_tool_confirm',
+            description: 'Execute risky tool (requires user confirmation). IMPORTANT: Check annotations.safety in search_tools results - only use this for "risky" tools, use execute_tool for "safe" tools. Safety annotation is authoritative. Required for external services without explicit safe rules.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    server_name: {
+                        type: 'string',
+                        description: 'Server name (e.g., "jira-basic-auth", "memory")',
+                        example: 'memory'
+                    },
+                    tool_name: {
+                        type: 'string',
+                        description: 'Tool name (e.g., "create_issue", "delete_entities")',
+                        example: 'create_entities'
+                    },
+                    arguments: {
+                        type: 'object',
+                        description: 'Tool arguments object. REQUIRED. All tool-specific parameters MUST be nested inside this object, not at the top level.',
+                        example: {
+                            entities: [{ name: 'test', entityType: 'concept', observations: ['example data'] }]
+                        },
+                        additionalProperties: true
+                    },
+                    max_results: {
+                        type: 'number',
+                        description: 'Optional: Limit array results to N items (for pagination)',
+                        example: 50
+                    },
+                    max_result_chars: {
+                        type: 'number',
+                        description: 'Optional: Limit total response size to N characters (default: 50000)',
+                        example: 10000
+                    },
+                    cursor: {
+                        type: 'string',
+                        description: 'Optional: Opaque cursor from previous response to continue pagination'
+                    }
+                },
+                required: ['server_name', 'tool_name', 'arguments'],
+                additionalProperties: false
+            }
+        });
+        // OPTIONAL: Base server tools - controlled by config options (v1.3.57+)
+        // Three modes:
+        // 1. Speakeasy mode (default): base_servers_auto_expose_tools = false → only 4 meta-tools (~280 tokens)
+        // 2. Base server exposure: base_servers_auto_expose_tools = true → expose base server tools (~1,300+ tokens)
+        // 3. Legacy mode: dynamicToolExposure = true → expose all discovered tools
+        const baseServersAutoExposeTools = this.config.base_servers_auto_expose_tools ?? false;
+        if (dynamicToolExposure || baseServersAutoExposeTools) {
+            const activeServers = this.serverManager.getActiveServers();
+            for (const [serverName, serverData] of activeServers) {
+                // Only expose base servers if baseServersAutoExposeTools is true
+                // Or expose all servers if dynamicToolExposure is true (legacy mode)
+                const isBaseServer = baseServerNames.includes(serverName);
+                const shouldExpose = dynamicToolExposure || (isBaseServer && baseServersAutoExposeTools);
+                if (shouldExpose && serverData.toolsReady && serverData.tools) {
+                    for (const tool of serverData.tools) {
+                        tools.push({
+                            name: `${serverName}-${tool.name}`,
+                            description: tool.description || `Tool from ${serverName} server`,
+                            inputSchema: tool.inputSchema || { type: 'object', properties: {} },
+                        });
+                    }
+                }
+            }
+        }
+        // OLD TOOLS (DEPRECATED in v1.3.0 - commented out for reference)
+        // These have been replaced by discovery tools to save tokens
+        // tools.push(
+        //   { name: 'list_available_servers', ... },
+        //   { name: 'enable_server', ... },
+        //   { name: 'disable_server', ... },
+        //   { name: 'list_servers', ... },
+        //   { name: 'list_tools', ... },
+        //   { name: 'execute_tool', ... },
+        //   { name: 'help', ... }
+        // );
+        return { tools };
+    }
+    /**
+     * MCP: tools/call - route tool calls
+     *
+     * SECURITY: Includes per-server rate limiting to prevent DOS attacks.
+     * Rate limit: 100 calls per server per minute (configurable).
+     * Discovery endpoints (search_tools, describe_tool) have separate rate limiting.
+     */
+    async mcpCallTool(name, args, sessionId) {
+        // Track metrics for tool call (Phase 4 - v1.4.0)
+        const startTime = Date.now();
+        globalMetrics.incrementCounter(`tool_calls_${name}`, 'calls');
+        // SECURITY: Extract server name for rate limiting
+        // For meta-tools (execute_tool, search_tools), extract from args
+        // For direct calls (server-tool), extract from name
+        const serverName = this.extractServerNameForRateLimit(name, args);
+        // Record tool call for error rate tracking
+        globalMetrics.recordToolCall(name, serverName || undefined);
+        // Log tool call with structured context
+        logger.info('Tool call initiated', {
+            tool: name,
+            server: serverName || undefined,
+            sessionId,
+        });
+        // SECURITY: Check rate limit before proceeding
+        if (serverName) {
+            this.checkToolRateLimit(serverName);
+        }
+        // SECURITY: Discovery endpoint rate limiting (P1)
+        // search_tools and describe_tool have separate rate limits per session
+        if (name === 'search_tools' || name === 'describe_tool') {
+            const rateLimitKey = sessionId || 'anonymous';
+            this.checkDiscoveryRateLimit(rateLimitKey);
+        }
+        try {
+            const result = await this.executeToolCall(name, args);
+            // Record successful execution metrics
+            const latency = Date.now() - startTime;
+            globalMetrics.setGauge(`tool_latency_${name}`, latency, 'ms');
+            // Record granular tool-specific metrics (Test 187)
+            if (serverName) {
+                globalMetrics.recordToolExecution(serverName, name.replace(`${serverName}-`, ''), latency);
+            }
+            // Log successful tool execution
+            logger.info('Tool call completed', {
+                tool: name,
+                server: serverName || undefined,
+                duration_ms: latency,
+            });
+            return result;
+        }
+        catch (error) {
+            // Record error metrics with detailed tracking
+            globalMetrics.incrementCounter(`tool_errors_${name}`, 'errors');
+            globalMetrics.recordToolError(error, name, serverName || undefined);
+            // Record granular tool-specific error (Test 187)
+            if (serverName) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                globalMetrics.recordToolFailure(serverName, name.replace(`${serverName}-`, ''), errorMessage);
+            }
+            // Log tool execution error
+            const latency = Date.now() - startTime;
+            logger.error('Tool call failed', {
+                tool: name,
+                server: serverName || undefined,
+                error: error instanceof Error ? error.message : String(error),
+                duration_ms: latency,
+            });
+            throw error;
+        }
+    }
+    /**
+     * SECURITY: Extract server name from tool call for rate limiting.
+     *
+     * @param name - Tool name (e.g., "execute_tool", "memory-search_nodes")
+     * @param args - Tool arguments
+     * @returns Server name or null for meta-tools without server context
+     */
+    extractServerNameForRateLimit(name, args) {
+        // Meta-tools with explicit server_name argument
+        if (name === 'execute_tool' || name === 'execute_tool_confirm' ||
+            name === 'describe_tool' || name === 'list_tools') {
+            const callArgs = args;
+            return callArgs?.server_name || null;
+        }
+        // Discovery tools - no server-specific rate limiting
+        if (name === 'search_tools' || name === 'list_available_servers' || name === 'list_servers') {
+            return null;
+        }
+        // Direct tool calls: "server-toolName" format
+        if (name.includes('-')) {
+            const parts = name.split('-');
+            return parts[0];
+        }
+        return null;
+    }
+    /**
+     * SECURITY: Check and enforce per-server rate limiting.
+     *
+     * OWASP Reference: A6:2017-Security Misconfiguration - DOS Prevention
+     *
+     * @param serverName - Name of the server to check rate limit for
+     * @throws Error if rate limit exceeded
+     */
+    checkToolRateLimit(serverName) {
+        const now = Date.now();
+        const limiter = this.toolExecutionRateLimiter.get(serverName);
+        if (!limiter || now > limiter.resetTime) {
+            // First call or window expired - reset counter
+            this.toolExecutionRateLimiter.set(serverName, {
+                count: 1,
+                resetTime: now + this.TOOL_RATE_LIMIT_WINDOW_MS,
+            });
+            return;
+        }
+        // Increment counter
+        limiter.count++;
+        // Check if rate limit exceeded
+        if (limiter.count > this.TOOL_RATE_LIMIT_MAX_CALLS) {
+            const waitTime = Math.ceil((limiter.resetTime - now) / 1000);
+            console.warn(`[SECURITY] Rate limit exceeded for server '${serverName}': ` +
+                `${limiter.count} calls in window, max ${this.TOOL_RATE_LIMIT_MAX_CALLS}`);
+            globalMetrics.incrementCounter(`rate_limit_exceeded_${serverName}`, 'rate_limits');
+            throw new Error(`Rate limit exceeded for server '${serverName}'. ` +
+                `Maximum ${this.TOOL_RATE_LIMIT_MAX_CALLS} tool calls per minute. ` +
+                `Please wait ${waitTime} seconds before retrying.`);
+        }
+        this.toolExecutionRateLimiter.set(serverName, limiter);
+    }
+    /**
+     * SECURITY: Check discovery endpoint rate limit (P1 - OWASP DOS Prevention)
+     * Prevents abuse of search_tools and describe_tool endpoints
+     *
+     * @param sessionId - Session ID to track rate limit for
+     * @throws Error if rate limit exceeded
+     */
+    checkDiscoveryRateLimit(sessionId) {
+        const now = Date.now();
+        const limiter = this.discoveryRateLimiter.get(sessionId);
+        if (!limiter || now > limiter.resetTime) {
+            // First call or window expired - reset counter
+            this.discoveryRateLimiter.set(sessionId, {
+                count: 1,
+                resetTime: now + this.DISCOVERY_RATE_LIMIT_WINDOW_MS,
+            });
+            return;
+        }
+        // Increment counter
+        limiter.count++;
+        // Check if rate limit exceeded
+        if (limiter.count > this.DISCOVERY_RATE_LIMIT_MAX_CALLS) {
+            const waitTime = Math.ceil((limiter.resetTime - now) / 1000);
+            console.warn(`[SECURITY] Discovery rate limit exceeded for session '${sessionId}': ` +
+                `${limiter.count} calls in window, max ${this.DISCOVERY_RATE_LIMIT_MAX_CALLS}`);
+            globalMetrics.incrementCounter('discovery_rate_limit_exceeded', 'rate_limits');
+            throw new Error(`Discovery rate limit exceeded. ` +
+                `Maximum ${this.DISCOVERY_RATE_LIMIT_MAX_CALLS} discovery calls per minute. ` +
+                `Please wait ${waitTime} seconds before retrying.`);
+        }
+        this.discoveryRateLimiter.set(sessionId, limiter);
+    }
+    /**
+     * Execute tool call logic (extracted for metrics tracking)
+     */
+    async executeToolCall(name, args) {
+        const callArgs = args;
+        switch (name) {
+            case 'list_available_servers': {
+                const allServers = this.configLoader.getAllServers();
+                const enabledServers = this.configLoader.getServers();
+                const enabledNames = new Set(enabledServers.map(s => s.name));
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                servers: allServers.map(s => {
+                                    const isStdio = s.transport === 'stdio' || s.transport === undefined;
+                                    return {
+                                        name: s.name,
+                                        ...(isStdio ? { command: s.command } : { url: s.url }),
+                                        enabled: enabledNames.has(s.name),
+                                    };
+                                }),
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            case 'list_servers': {
+                const servers = this.configLoader.getServers();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                servers: servers.map(s => {
+                                    const isStdio = s.transport === 'stdio' || s.transport === undefined;
+                                    return {
+                                        name: s.name,
+                                        ...(isStdio ? { command: s.command } : { url: s.url }),
+                                        status: this.serverManager.getServerStatus(s.name)?.status || 'stopped',
+                                        toolCount: this.serverManager.getServerTools(s.name).length || 0,
+                                    };
+                                }),
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            case 'list_tools': {
+                const serverName = callArgs?.server_name;
+                if (!serverName)
+                    throw new InvalidParamsError('server_name required');
+                // Get tools from server manager
+                const tools = this.serverManager.getServerTools(serverName);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                server: serverName,
+                                tools: tools || [],
+                            }, null, 2)
+                        }
+                    ]
+                };
+            }
+            case 'execute_tool': {
+                const args = callArgs;
+                // DEBUG: Log raw incoming args to diagnose Raycast/Grok issues
+                console.log(`[DEBUG execute_tool] RAW INCOMING ARGS: ${JSON.stringify(args)}`);
+                // Phase 2a: Detect and fix Raycast format issues
+                const fixedArgs = this.serverManager.detectAndFixRaycastFormat(args);
+                const serverName = fixedArgs.server_name;
+                const toolName = fixedArgs.tool_name;
+                if (!serverName || !toolName) {
+                    throw new InvalidParamsError('server_name and tool_name are required. Format: {"server_name": "memory", "tool_name": "search_nodes", "arguments": {...}}');
+                }
+                // v1.1.29: Extract tool arguments for argument-level safety inspection
+                const toolArgs = fixedArgs.arguments || {};
+                // SAFETY CHECK: Verify this tool is classified as 'safe' (with argument inspection)
+                const safetyResult = this.serverManager.classifyToolSafety(serverName, toolName, toolArgs);
+                if (safetyResult.safety === 'risky') {
+                    throw new InvalidParamsError(`Tool ${serverName}:${toolName} is classified as RISKY and requires user confirmation.\n` +
+                        `Use 'execute_tool_confirm' instead for this tool.\n` +
+                        `Classification reason: ${safetyResult.reason}`);
+                }
+                // Phase 2b: Get tool schema for validation
+                const toolSchema = this.serverManager.getToolSchema(serverName, toolName);
+                if (!toolSchema) {
+                    throw new InvalidParamsError(`Tool '${toolName}' not found in server '${serverName}'. Use describe_tool to get the tool schema or search_tools to find available tools.`);
+                }
+                // Phase 2c: Detect missing arguments
+                const missingArgs = this.serverManager.detectMissingArguments(fixedArgs, toolSchema);
+                if (missingArgs) {
+                    const inputSchema = toolSchema.inputSchema;
+                    const requiredParams = inputSchema?.required?.join(', ') || 'unknown';
+                    const errorMsg = `❌ Missing required parameters for ${serverName}:${toolName}\n` +
+                        `\n` +
+                        `Required: ${requiredParams}\n` +
+                        `\n` +
+                        `✅ CORRECT FORMAT:\n` +
+                        `  {"server_name": "${serverName}", "tool_name": "${toolName}", "arguments": {...}}\n` +
+                        `\n` +
+                        `For full schema: describe_tool('${serverName}', '${toolName}')`;
+                    throw new InvalidParamsError(errorMsg);
+                }
+                // Phase 2d: Validate required params exist inside arguments
+                const args2 = fixedArgs.arguments || {};
+                const inputSchema2 = toolSchema.inputSchema;
+                const requiredParams2 = inputSchema2?.required || [];
+                // Check if required params are missing from arguments
+                const missingRequiredParams = requiredParams2.filter(param => !(param in args2));
+                if (missingRequiredParams.length > 0) {
+                    // Generate example values for each required param
+                    const exampleArgs = {};
+                    for (const param of requiredParams2) {
+                        const propSchema = inputSchema2?.properties?.[param];
+                        if (propSchema?.example)
+                            exampleArgs[param] = propSchema.example;
+                        else if (propSchema?.default)
+                            exampleArgs[param] = propSchema.default;
+                        else if (propSchema?.type === 'string')
+                            exampleArgs[param] = `<${param}>`;
+                        else if (propSchema?.type === 'number')
+                            exampleArgs[param] = 10;
+                        else
+                            exampleArgs[param] = `<${param}>`;
+                    }
+                    const errorMsg = `❌ Missing required parameters for ${serverName}:${toolName}\n` +
+                        `\n` +
+                        `You provided: ${JSON.stringify(args2)}\n` +
+                        `Missing: ${missingRequiredParams.join(', ')}\n` +
+                        `\n` +
+                        `✅ CORRECT FORMAT:\n` +
+                        `  {"server_name": "${serverName}", "tool_name": "${toolName}", "arguments": ${JSON.stringify(exampleArgs)}}\n` +
+                        `\n` +
+                        `For full schema: describe_tool('${serverName}', '${toolName}')`;
+                    throw new InvalidParamsError(errorMsg);
+                }
+                console.log(`[MetaLink] execute_tool (SAFE): ${serverName}:${toolName} with args ${JSON.stringify(args2)}`);
+                // Phase 2e: Auto-start server if not running
+                const serverConfig = this.configLoader.getServer(serverName);
+                if (serverConfig) {
+                    await this.serverManager.ensureServerStarted(serverName, serverConfig);
+                }
+                // Phase 3: Call the actual tool via response router
+                try {
+                    const result = await this.serverManager.callTool(serverName, toolName, args2);
+                    // Phase 4: Apply pagination if parameters provided
+                    const paginationParams = {
+                        max_results: fixedArgs.max_results,
+                        max_result_chars: fixedArgs.max_result_chars,
+                        cursor: fixedArgs.cursor
+                    };
+                    // Only paginate if at least one pagination param is provided
+                    if (paginationParams.max_results || paginationParams.max_result_chars || paginationParams.cursor) {
+                        const paginated = this.paginateResult(result, paginationParams);
+                        // Return result with pagination metadata merged in
+                        if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
+                            return {
+                                ...result,
+                                result: paginated.result,
+                                _pagination: paginated._pagination
+                            };
+                        }
+                        else {
+                            // If result is not an object (e.g., primitive or array), wrap it
+                            return {
+                                result: paginated.result,
+                                _pagination: paginated._pagination
+                            };
+                        }
+                    }
+                    return result;
+                }
+                catch (toolError) {
+                    // Enhanced error with inputSchema for debugging
+                    const errorMsg = `Tool execution failed for ${serverName}:${toolName}: ${toolError instanceof Error ? toolError.message : String(toolError)}`;
+                    const inputSchema = toolSchema.inputSchema;
+                    // Check if error is parameter-related
+                    const errorStr = (toolError instanceof Error ? toolError.message : String(toolError)).toLowerCase();
+                    const isParamError = errorStr.includes('null') || errorStr.includes('undefined') ||
+                        errorStr.includes('required') || errorStr.includes('missing');
+                    if (isParamError && inputSchema) {
+                        const requiredParams = inputSchema.required || [];
+                        const availableParams = Object.keys(inputSchema.properties || {});
+                        const optionalParams = availableParams.filter(p => !requiredParams.includes(p));
+                        const requiredList = requiredParams.length > 0 ? requiredParams.join(', ') : 'none';
+                        const optionalList = optionalParams.length > 0 ? optionalParams.join(', ') : 'none';
+                        const hint = `\n\n💡 Hint: This tool expects:\n` +
+                            `  Required: ${requiredList}\n` +
+                            `  Optional: ${optionalList}\n` +
+                            `  Use describe_tool('${serverName}', '${toolName}') for full schema.`;
+                        throw new Error(errorMsg + hint);
+                    }
+                    throw new Error(errorMsg);
+                }
+            }
+            case 'execute_tool_confirm': {
+                const args = callArgs;
+                // Phase 2a: Detect and fix Raycast format issues
+                const fixedArgs = this.serverManager.detectAndFixRaycastFormat(args);
+                const serverName = fixedArgs.server_name;
+                const toolName = fixedArgs.tool_name;
+                if (!serverName || !toolName) {
+                    throw new InvalidParamsError('server_name and tool_name are required. Format: {"server_name": "task-master-ai", "tool_name": "set_task_status", "arguments": {...}}');
+                }
+                // v1.1.29: Extract tool arguments for argument-level safety inspection
+                const toolArgs = fixedArgs.arguments || {};
+                // SAFETY CHECK: Log classification (but allow regardless - user confirmed)
+                const safetyResult = this.serverManager.classifyToolSafety(serverName, toolName, toolArgs);
+                console.log(`[MetaLink] execute_tool_confirm (${safetyResult.safety.toUpperCase()}): ${serverName}:${toolName} - ${safetyResult.reason}`);
+                // Phase 2b: Get tool schema for validation
+                const toolSchema = this.serverManager.getToolSchema(serverName, toolName);
+                if (!toolSchema) {
+                    throw new InvalidParamsError(`Tool '${toolName}' not found in server '${serverName}'. Use describe_tool to get the tool schema or search_tools to find available tools.`);
+                }
+                // Phase 2c: Detect missing arguments
+                const missingArgs = this.serverManager.detectMissingArguments(fixedArgs, toolSchema);
+                if (missingArgs) {
+                    const inputSchema = toolSchema.inputSchema;
+                    const requiredParams = inputSchema?.required?.join(', ') || 'unknown';
+                    const errorMsg = `❌ Missing required parameters for ${serverName}:${toolName}\n` +
+                        `\n` +
+                        `Required: ${requiredParams}\n` +
+                        `\n` +
+                        `✅ CORRECT FORMAT:\n` +
+                        `  {"server_name": "${serverName}", "tool_name": "${toolName}", "arguments": {...}}\n` +
+                        `\n` +
+                        `For full schema: describe_tool('${serverName}', '${toolName}')`;
+                    throw new InvalidParamsError(errorMsg);
+                }
+                // Phase 2d: Lenient mode - if arguments missing, default to empty object
+                const args2 = fixedArgs.arguments || {};
+                console.log(`[MetaLink] execute_tool_confirm: ${serverName}:${toolName} with args ${JSON.stringify(args2)}`);
+                // Phase 2e: Auto-start server if not running
+                const serverConfig = this.configLoader.getServer(serverName);
+                if (serverConfig) {
+                    await this.serverManager.ensureServerStarted(serverName, serverConfig);
+                }
+                // Phase 3: Call the actual tool via response router
+                try {
+                    const result = await this.serverManager.callTool(serverName, toolName, args2);
+                    // Phase 4: Apply pagination if parameters provided
+                    const paginationParams = {
+                        max_results: fixedArgs.max_results,
+                        max_result_chars: fixedArgs.max_result_chars,
+                        cursor: fixedArgs.cursor
+                    };
+                    // Only paginate if at least one pagination param is provided
+                    if (paginationParams.max_results || paginationParams.max_result_chars || paginationParams.cursor) {
+                        const paginated = this.paginateResult(result, paginationParams);
+                        // Return result with pagination metadata merged in
+                        if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
+                            return {
+                                ...result,
+                                result: paginated.result,
+                                _pagination: paginated._pagination
+                            };
+                        }
+                        else {
+                            // If result is not an object (e.g., primitive or array), wrap it
+                            return {
+                                result: paginated.result,
+                                _pagination: paginated._pagination
+                            };
+                        }
+                    }
+                    return result;
+                }
+                catch (toolError) {
+                    // Enhanced error with inputSchema for debugging
+                    const errorMsg = `Tool execution failed for ${serverName}:${toolName}: ${toolError instanceof Error ? toolError.message : String(toolError)}`;
+                    const inputSchema = toolSchema.inputSchema;
+                    // Check if error is parameter-related
+                    const errorStr = (toolError instanceof Error ? toolError.message : String(toolError)).toLowerCase();
+                    const isParamError = errorStr.includes('null') || errorStr.includes('undefined') ||
+                        errorStr.includes('required') || errorStr.includes('missing');
+                    if (isParamError && inputSchema) {
+                        const requiredParams = inputSchema.required || [];
+                        const availableParams = Object.keys(inputSchema.properties || {});
+                        const optionalParams = availableParams.filter(p => !requiredParams.includes(p));
+                        const requiredList = requiredParams.length > 0 ? requiredParams.join(', ') : 'none';
+                        const optionalList = optionalParams.length > 0 ? optionalParams.join(', ') : 'none';
+                        const hint = `\n\n💡 Hint: This tool expects:\n` +
+                            `  Required: ${requiredList}\n` +
+                            `  Optional: ${optionalList}\n` +
+                            `  Use describe_tool('${serverName}', '${toolName}') for full schema.`;
+                        throw new Error(errorMsg + hint);
+                    }
+                    throw new Error(errorMsg);
+                }
+            }
+            // ===== 4-TOOL SPEAKEASY APPROACH (v1.3.52) =====
+            // Discovery tools: search_tools, describe_tool
+            // Execution tools: execute_tool, execute_tool_confirm
+            case 'search_tools': {
+                // FIX v1.3.52: Search ALL servers using CACHED schemas (no auto-start)
+                // UPDATE v1.3.56: Support optional server_name filter and server name matching
+                // - query (optional): Search term for server names, tool names, and descriptions
+                // - server_name (optional): Filter to specific server
+                // - At least one parameter required
+                try {
+                    const query = callArgs?.query || '';
+                    const serverNameFilter = callArgs?.server_name || '';
+                    // Validate: at least one parameter provided
+                    if (!query && !serverNameFilter) {
+                        throw new InvalidParamsError('At least one parameter required: query or server_name');
+                    }
+                    const results = [];
+                    // Get all servers or filter to specific server
+                    const allServers = this.configLoader.getAllServers();
+                    let serversToSearch = serverNameFilter
+                        ? allServers.filter((s) => s.name === serverNameFilter)
+                        : allServers;
+                    // Validate server_name if provided
+                    if (serverNameFilter && serversToSearch.length === 0) {
+                        throw new InvalidParamsError(`Server '${serverNameFilter}' not found in registry`);
+                    }
+                    // Multi-keyword matching: split query into individual words
+                    const keywords = query.toLowerCase().split(/\s+/).filter(k => k.length > 0);
+                    // Step 1: Check if any keyword matches a server name
+                    let serverKeyword;
+                    if (keywords.length > 0 && !serverNameFilter) {
+                        for (const keyword of keywords) {
+                            const matchedServer = allServers.find((s) => s.name.toLowerCase().includes(keyword) || keyword.includes(s.name.toLowerCase()));
+                            if (matchedServer) {
+                                serverKeyword = keyword;
+                                serversToSearch = [matchedServer];
+                                break;
+                            }
+                        }
+                    }
+                    // Step 2: Get remaining keywords (exclude server name keyword)
+                    const searchKeywords = serverKeyword
+                        ? keywords.filter(k => k !== serverKeyword)
+                        : keywords;
+                    for (const serverConfig of serversToSearch) {
+                        const serverName = serverConfig.name.toLowerCase();
+                        const tools = this.serverManager.getServerTools(serverConfig.name);
+                        for (const tool of tools) {
+                            const toolName = tool.name.toLowerCase();
+                            const toolDesc = (tool.description || '').toLowerCase();
+                            // Determine match type
+                            let matchType = 'all';
+                            let shouldInclude = false;
+                            if (keywords.length === 0) {
+                                // No query, just listing all tools from filtered server
+                                matchType = 'all';
+                                shouldInclude = true;
+                            }
+                            else if (serverKeyword && searchKeywords.length === 0) {
+                                // Only server name in query - return ALL tools from this server
+                                matchType = 'server';
+                                shouldInclude = true;
+                            }
+                            else if (searchKeywords.length > 0) {
+                                // Multi-keyword matching: check if ANY keyword matches tool name or description
+                                const nameMatches = searchKeywords.some(keyword => toolName.includes(keyword));
+                                const descMatches = searchKeywords.some(keyword => toolDesc.includes(keyword));
+                                if (nameMatches && descMatches) {
+                                    matchType = 'all';
+                                    shouldInclude = true;
+                                }
+                                else if (nameMatches) {
+                                    matchType = 'name';
+                                    shouldInclude = true;
+                                }
+                                else if (descMatches) {
+                                    matchType = 'description';
+                                    shouldInclude = true;
+                                }
+                                else if (serverKeyword) {
+                                    // Server matched but no tool/description keywords matched
+                                    // Still include if we're filtering by server (be permissive)
+                                    matchType = 'server';
+                                    shouldInclude = true;
+                                }
+                            }
+                            if (shouldInclude) {
+                                // Extract required and optional params from inputSchema
+                                const inputSchema = tool.inputSchema;
+                                const properties = inputSchema?.properties;
+                                const requiredArray = inputSchema?.required;
+                                const allParams = properties ? Object.keys(properties) : [];
+                                const requiredParams = requiredArray || [];
+                                const optionalParams = allParams.filter(p => !requiredParams.includes(p));
+                                // Generate example arguments from inputSchema
+                                const exampleArgs = {};
+                                if (properties) {
+                                    for (const [key, value] of Object.entries(properties)) {
+                                        const prop = value;
+                                        // Use example from schema if available, otherwise generate placeholder
+                                        if (prop.example !== undefined) {
+                                            exampleArgs[key] = prop.example;
+                                        }
+                                        else if (prop.default !== undefined) {
+                                            exampleArgs[key] = prop.default;
+                                        }
+                                        else if (prop.type === 'string') {
+                                            // Generate meaningful examples for common param names
+                                            if (key === 'query')
+                                                exampleArgs[key] = 'search term';
+                                            else if (key === 'cql')
+                                                exampleArgs[key] = 'type=page ORDER BY created DESC';
+                                            else if (key === 'jql')
+                                                exampleArgs[key] = 'project = PROJ ORDER BY created DESC';
+                                            else if (key === 'timezone')
+                                                exampleArgs[key] = 'UTC';
+                                            else if (key === 'url')
+                                                exampleArgs[key] = 'https://example.com';
+                                            else
+                                                exampleArgs[key] = `<${key}>`;
+                                        }
+                                        else if (prop.type === 'number' || prop.type === 'integer') {
+                                            if (key === 'limit' || key === 'max_results' || key === 'maxResults')
+                                                exampleArgs[key] = 10;
+                                            else
+                                                exampleArgs[key] = 1;
+                                        }
+                                        else if (prop.type === 'boolean') {
+                                            exampleArgs[key] = true;
+                                        }
+                                        else if (prop.type === 'array') {
+                                            exampleArgs[key] = [];
+                                        }
+                                        else if (prop.type === 'object') {
+                                            exampleArgs[key] = {};
+                                        }
+                                    }
+                                }
+                                // Store schema metadata for potential auto-describe
+                                // v1.1.31: Include safety annotations in search results
+                                // v1.3.x: Add argument inspection hints for risky tools with safe patterns
+                                let safetyAnnotation;
+                                if (tool.annotations) {
+                                    safetyAnnotation = tool.annotations;
+                                }
+                                else {
+                                    const classification = this.serverManager.classifyToolSafety(serverConfig.name, tool.name);
+                                    safetyAnnotation = {
+                                        safety: classification.safety,
+                                        safetyReason: classification.reason,
+                                        requiresConfirmation: classification.safety === 'risky',
+                                    };
+                                }
+                                // v1.3.x: Check for argument inspection rules
+                                const toolSafetyRules = this.configLoader.getToolSafetyRules();
+                                const argInspectionRules = toolSafetyRules?.argumentInspectionRules || [];
+                                const fullToolName = `${serverConfig.name}:${tool.name}`;
+                                const argInspectionRule = argInspectionRules.find((rule) => rule.tool === fullToolName);
+                                let toolNote = "Use describe_tool to get full schema before execution";
+                                if (argInspectionRule && safetyAnnotation.safety === 'risky') {
+                                    // Add argument inspection hint for risky tools with auto-approval patterns
+                                    safetyAnnotation.argumentInspection = {
+                                        enabled: true,
+                                        field: argInspectionRule.argumentField,
+                                        safePatterns: argInspectionRule.safeCommandPatterns || [],
+                                        note: `Auto-approved when ${argInspectionRule.argumentField} matches safe patterns (e.g., ${(argInspectionRule.safeCommandPatterns || []).slice(0, 3).join(', ')})`
+                                    };
+                                    toolNote = `Risky by default, but AUTO-APPROVED for read-only operations. Check ${argInspectionRule.argumentField} - patterns like ${(argInspectionRule.safeCommandPatterns || []).slice(0, 3).join(', ')} are safe.`;
+                                }
+                                results.push({
+                                    server: serverConfig.name,
+                                    tool: tool.name,
+                                    name: `${serverConfig.name}-${tool.name}`,
+                                    description: tool.description,
+                                    note: toolNote,
+                                    matchType,
+                                    // v1.3.x: Top-level safety fields for easier access
+                                    safety: safetyAnnotation.safety,
+                                    execute_with: safetyAnnotation.safety === 'safe' ? 'execute_tool' : 'execute_tool_confirm',
+                                    annotations: safetyAnnotation,
+                                    _schema: {
+                                        inputSchema,
+                                        requiredParams,
+                                        optionalParams,
+                                        exampleArgs
+                                    }
+                                });
+                            }
+                        }
+                    }
+                    // Auto-describe for single tool results
+                    let autoDescribed = false;
+                    if (results.length === 1 && results[0]._schema) {
+                        const result = results[0];
+                        const schema = result._schema;
+                        if (schema) {
+                            // Add full schema details to the single result
+                            result.inputSchema = schema.inputSchema;
+                            result.requiredParams = schema.requiredParams;
+                            result.optionalParams = schema.optionalParams;
+                            result.example = {
+                                server_name: result.server,
+                                tool_name: result.tool,
+                                arguments: schema.exampleArgs
+                            };
+                            // Anthropic Advanced Tool Use: Include tool use examples if available
+                            // https://www.anthropic.com/engineering/advanced-tool-use
+                            const tool = this.serverManager.getServerTools(result.server).find(t => t.name === result.tool);
+                            if (tool?.inputExamples && Array.isArray(tool.inputExamples) && tool.inputExamples.length > 0) {
+                                result.inputExamples = tool.inputExamples;
+                            }
+                            // Remove the note since we're providing full schema
+                            delete result.note;
+                            delete result._schema;
+                            autoDescribed = true;
+                        }
+                    }
+                    else {
+                        // Include inputSchema in all results for Raycast compatibility
+                        // v1.1.67: Always include inputSchema even when not auto-describing
+                        results.forEach(r => {
+                            if (r._schema) {
+                                r.inputSchema = r._schema.inputSchema;
+                                r.requiredParams = r._schema.requiredParams;
+                                r.optionalParams = r._schema.optionalParams;
+                                delete r._schema;
+                            }
+                        });
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    query: query || undefined,
+                                    server_name: serverNameFilter || undefined,
+                                    count: results.length,
+                                    autoDescribed,
+                                    tools: results.slice(0, 50)
+                                }, null, 2)
+                            }
+                        ]
+                    };
+                }
+                catch (error) {
+                    throw new Error(`Failed to search tools: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            case 'describe_tool': {
+                try {
+                    const serverName = callArgs?.server_name;
+                    const toolName = callArgs?.tool_name;
+                    // RAYCAST DEBUG: Log what client is requesting
+                    console.log(`[describe_tool] REQUEST: server="${serverName}" tool="${toolName}"`);
+                    if (!serverName || !toolName) {
+                        throw new InvalidParamsError('server_name and tool_name are required');
+                    }
+                    // Get server config
+                    const allServers = this.configLoader.getAllServers();
+                    const serverConfig = allServers.find((s) => s.name === serverName);
+                    if (!serverConfig) {
+                        throw new InvalidParamsError(`Server '${serverName}' not found in registry. Use search_tools to find available tools.`);
+                    }
+                    // Discover tools from the server
+                    const toolSchemas = await this.serverManager.discoverToolSchemas(serverName, serverConfig);
+                    const toolSchema = toolSchemas.find(t => t.name === toolName);
+                    if (!toolSchema) {
+                        const availableTools = toolSchemas.map(t => t.name).join(', ');
+                        throw new Error(`Tool '${toolName}' not found in server '${serverName}'.\n` +
+                            `Available tools: ${availableTools}\n` +
+                            `Use search_tools with a keyword to find tools across all servers.`);
+                    }
+                    // v1.4.0: Validate schema and collect hints
+                    const { SchemaValidator } = await import('./schema-validator.js');
+                    const validator = new SchemaValidator();
+                    const validationResult = validator.validateToolSchema(toolSchema);
+                    // Generate example arguments from inputSchema
+                    const inputSchema = toolSchema.inputSchema;
+                    const properties = inputSchema?.properties;
+                    const requiredArray = inputSchema?.required;
+                    const exampleArgs = {};
+                    if (properties) {
+                        for (const [key, value] of Object.entries(properties)) {
+                            const prop = value;
+                            // Use example from schema if available, otherwise generate placeholder
+                            if (prop.example !== undefined) {
+                                exampleArgs[key] = prop.example;
+                            }
+                            else if (prop.default !== undefined) {
+                                exampleArgs[key] = prop.default;
+                            }
+                            else if (prop.type === 'string') {
+                                exampleArgs[key] = prop.description ? `<${key}>` : 'example';
+                            }
+                            else if (prop.type === 'number') {
+                                exampleArgs[key] = 10;
+                            }
+                            else if (prop.type === 'boolean') {
+                                exampleArgs[key] = true;
+                            }
+                            else if (prop.type === 'array') {
+                                exampleArgs[key] = [];
+                            }
+                            else if (prop.type === 'object') {
+                                exampleArgs[key] = {};
+                            }
+                        }
+                    }
+                    // Calculate optional params (all params not in required array)
+                    const allParams = properties ? Object.keys(properties) : [];
+                    const optionalParams = allParams.filter(p => !(requiredArray || []).includes(p));
+                    // Build tool object matching search_tools auto-describe format for Raycast compatibility
+                    const toolObj = {
+                        server: serverName,
+                        tool: toolName,
+                        name: `${serverName}-${toolName}`,
+                        description: toolSchema.description || '',
+                        inputSchema: toolSchema.inputSchema || {},
+                        requiredParams: requiredArray || [],
+                        optionalParams: optionalParams,
+                        example: {
+                            server_name: serverName,
+                            tool_name: toolName,
+                            arguments: exampleArgs
+                        }
+                    };
+                    // Anthropic Advanced Tool Use: Include tool use examples if available
+                    // https://www.anthropic.com/engineering/advanced-tool-use
+                    if (toolSchema.inputExamples && Array.isArray(toolSchema.inputExamples) && toolSchema.inputExamples.length > 0) {
+                        toolObj.inputExamples = toolSchema.inputExamples;
+                    }
+                    // Phase 2: Include safety annotations if available
+                    if (toolSchema.annotations) {
+                        toolObj.annotations = toolSchema.annotations;
+                    }
+                    // Build response in discover_tools format (array with single tool)
+                    const responseObj = {
+                        server: serverName,
+                        tools: [toolObj],
+                        count: 1,
+                        detailLevel: 'full' // Always full for describe_tool
+                    };
+                    // RAYCAST DEBUG: Log what schema is returned
+                    console.log(`[describe_tool] RESPONSE: ${serverName}:${toolName} - requiredParams=${JSON.stringify(requiredArray || [])} - hasInputSchema=${!!toolSchema.inputSchema}`);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(responseObj, null, 2)
+                            }
+                        ]
+                    };
+                }
+                catch (error) {
+                    throw new Error(`Failed to describe tool: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            // ===== END 4-TOOL SPEAKEASY APPROACH =====
+            // ===== OLD MANAGEMENT TOOLS (DEPRECATED v1.3.0) =====
+            // These have been replaced by discovery tools to reduce token usage
+            // Commented out but kept for reference. Can be removed in v2.0.0
+            /*
+            case 'enable_server': {
+              const serverName = callArgs?.server_name;
+              if (!serverName) throw new Error('server_name required');
+      
+              const timestamp = new Date().toISOString();
+              console.log(`[metalink] Enabling server: ${serverName} at ${timestamp}`);
+      
+              try {
+                // Get server config from registry
+                const allServers = this.configLoader.getAllServers();
+                const serverConfig = allServers.find((s: any) => s.name === serverName);
+      
+                if (!serverConfig) {
+                  const availableNames = allServers.map((s: any) => s.name).join(', ');
+                  throw new Error(
+                    `Server '${serverName}' not found in registry. Available: ${availableNames}`
+                  );
+                }
+      
+                // Check if already enabled
+                const activeServers = this.serverManager.getActiveServers();
+                if (activeServers.has(serverName)) {
+                  const serverData = activeServers.get(serverName);
+                  const tools = serverData?.tools || [];
+                  return {
+                    content: [
+                      {
+                        type: 'text',
+                        text: JSON.stringify({
+                          status: 'already_enabled',
+                          server: serverName,
+                          tools_count: tools.length,
+                          tools: tools.map((t: any) => ({
+                            name: t.name,
+                            description: t.description || '',
+                          })),
+                        }, null, 2)
+                      }
+                    ]
+                  };
+                }
+      
+                // Start server process
+                console.log(`[metalink] Using mcpm to run ${serverName}`);
+                await this.serverManager.startServer(serverConfig);
+      
+                // Get process and fetch tools
+                console.log(`[metalink] Retrieving tools from ${serverName}...`);
+                const serverProcess = this.serverManager.getProcess(serverName);
+                if (!serverProcess) {
+                  throw new Error(`Failed to start ${serverName} - no process found`);
+                }
+      
+                // Fetch tools from the process
+                const tools = await this.serverManager.fetchToolsFromProcess(serverProcess);
+                this.serverManager.setServerTools(serverName, tools);
+      
+                console.log(`[metalink] Successfully retrieved ${tools.length} tools from ${serverName}`);
+                console.log(`[metalink] Response router set up for ${serverName}`);
+      
+                return {
+                  content: [
+                    {
+                      type: 'text',
+                      text: JSON.stringify({
+                        status: 'enabled',
+                        server: serverName,
+                        tools_count: tools.length,
+                        tools: tools.map((t: any) => ({
+                          name: t.name,
+                          description: t.description || '',
+                        })),
+                      }, null, 2)
+                    }
+                  ]
+                };
+              } catch (error: any) {
+                console.error(`[metalink] Failed to enable ${serverName}:`, error);
+                throw new Error(`Failed to enable server '${serverName}': ${error.message}`);
+              }
+            }
+      
+            case 'disable_server': {
+              const serverName = callArgs?.server_name;
+              if (!serverName) throw new InvalidParamsError('server_name required');
+              // This would disable the server at runtime
+              return {
+                content: [
+                  {
+                    type: 'text',
+                    text: JSON.stringify({
+                      disabled: true,
+                      server: serverName,
+                    }, null, 2)
+                  }
+                ]
+              };
+            }
+      
+            case 'help': {
+              const topic = (callArgs?.topic as string) || 'all';
+      
+              const help = {
+                overview: 'MetaLink provides three ways to interact with MCP servers and management tools',
+      
+                management_tools: {
+                  description: 'Control server lifecycle and discover tools',
+                  tools: [
+                    {
+                      name: 'list_available_servers',
+                      description: 'List all servers that can be dynamically loaded',
+                      usage: 'No arguments needed',
+                      example: '{"name": "list_available_servers", "arguments": {}}'
+                    },
+                    {
+                      name: 'enable_server',
+                      description: 'Enable a server and load its tools',
+                      usage: 'Provide server_name (e.g., "memory", "docs-server")',
+                      example: '{"name": "enable_server", "arguments": {"server_name": "task-master-ai"}}'
+                    },
+                    {
+                      name: 'disable_server',
+                      description: 'Disable an enabled server',
+                      usage: 'Provide server_name',
+                      example: '{"name": "disable_server", "arguments": {"server_name": "memory"}}'
+                    },
+                    {
+                      name: 'list_servers',
+                      description: 'Show all currently enabled servers with tool counts',
+                      usage: 'No arguments needed',
+                      example: '{"name": "list_servers", "arguments": {}}'
+                    },
+                    {
+                      name: 'list_tools',
+                      description: 'List tools available on a specific server',
+                      usage: 'Provide server_name',
+                      example: '{"name": "list_tools", "arguments": {"server_name": "memory"}}'
+                    }
+                  ]
+                },
+      
+                direct_tool_calls: {
+                  description: 'Call tools using hyphenated format: server-toolName',
+                  format: 'server-toolName (e.g., memory-search_nodes, time-get_current_time, docs-server-list_libraries)',
+                  example: '{"name": "memory-search_nodes", "arguments": {"query": "metalink"}}',
+                  note: 'Preferred method for direct tool access when you know the server and tool names'
+                },
+      
+                execute_tool_method: {
+                  description: 'Generic tool executor with explicit parameters',
+                  format: 'Use execute_tool with server_name, tool_name, and arguments (nested)',
+                  example: '{"name": "execute_tool", "arguments": {"server_name": "memory", "tool_name": "search_nodes", "arguments": {"query": "metalink"}}}',
+                  critical: 'ALWAYS include "arguments" key in the outer structure, even if the tool takes no args: {"arguments": {}}'
+                },
+      
+                execute_tool_confirm: {
+                  description: 'Execute tools with user confirmation workflow',
+                  format: 'Same as execute_tool, but returns confirmation request before execution',
+                  example: '{"name": "execute_tool_confirm", "arguments": {"server_name": "memory", "tool_name": "delete_entities", "arguments": {"entityNames": ["test"]}}}',
+                  use_case: 'For sensitive/destructive operations that require explicit user approval'
+                },
+      
+                workflow: {
+                  step1_discover: 'list_available_servers → see what servers can be loaded',
+                  step2_enable: 'enable_server → load a server and fetch its tools',
+                  step3_explore: 'list_tools → see all tools available on that server',
+                  step4_execute: 'Use direct calls (server-toolName) OR execute_tool to call tools',
+                  step5_search: 'search_tools → find tools by keyword across all servers'
+                }
+              };
+      
+              // Filter by topic
+              if (topic === 'management') {
+                return {
+                  content: [
+                    {
+                      type: 'text',
+                      text: JSON.stringify({ help: { overview: help.overview, management_tools: help.management_tools } }, null, 2)
+                    }
+                  ]
+                };
+              } else if (topic === 'direct') {
+                return {
+                  content: [
+                    {
+                      type: 'text',
+                      text: JSON.stringify({ help: { overview: help.overview, direct_tool_calls: help.direct_tool_calls } }, null, 2)
+                    }
+                  ]
+                };
+              } else if (topic === 'execute_tool') {
+                return {
+                  content: [
+                    {
+                      type: 'text',
+                      text: JSON.stringify({ help: { overview: help.overview, execute_tool_method: help.execute_tool_method, execute_tool_confirm: help.execute_tool_confirm } }, null, 2)
+                    }
+                  ]
+                };
+              } else if (topic === 'workflow') {
+                return {
+                  content: [
+                    {
+                      type: 'text',
+                      text: JSON.stringify({ help: { overview: help.overview, workflow: help.workflow } }, null, 2)
+                    }
+                  ]
+                };
+              }
+      
+              return {
+                content: [
+                  {
+                    type: 'text',
+                    text: JSON.stringify({ help }, null, 2)
+                  }
+                ]
+              };
+            }
+            */
+            // ===== END OLD MANAGEMENT TOOLS =====
+            default: {
+                // Handle base server tools in format "server-toolName"
+                // Support hyphenated server names like "duckduckgo-mcp"
+                if (name.includes('-')) {
+                    const lastHyphenIndex = name.lastIndexOf('-');
+                    if (lastHyphenIndex === -1) {
+                        throw new InvalidParamsError(`Invalid tool name format: ${name}`);
+                    }
+                    const serverName = name.substring(0, lastHyphenIndex);
+                    const toolName = name.substring(lastHyphenIndex + 1);
+                    if (serverName && toolName) {
+                        // v1.4.0: Refresh discovery timer on tool activity
+                        if (this.serverManager.isDiscovered(serverName)) {
+                            this.serverManager.refreshDiscoveryTimer(serverName);
+                        }
+                        // Phase 3: Auto-start servers on first tool call (including base servers as fallback)
+                        console.log(`[MetaLink] Ensuring server is started: ${serverName}`);
+                        try {
+                            // Get server config and ensure it's started
+                            const allServers = this.configLoader.getAllServers();
+                            const serverConfig = allServers.find((s) => s.name === serverName);
+                            if (!serverConfig) {
+                                throw new InvalidParamsError(`Server '${serverName}' not found in registry`);
+                            }
+                            // Always call ensureServerStarted - it's idempotent and handles base servers too
+                            await this.serverManager.ensureServerStarted(serverName, serverConfig);
+                            // Notify connected clients that tools/list has changed
+                            this.notifyToolsListChanged();
+                        }
+                        catch (autoStartError) {
+                            throw new Error(`Failed to auto-start server ${serverName}: ${autoStartError instanceof Error ? autoStartError.message : String(autoStartError)}`);
+                        }
+                        // Phase 2b: Get tool schema for validation
+                        const toolSchema = this.serverManager.getToolSchema(serverName, toolName);
+                        if (!toolSchema) {
+                            throw new InvalidParamsError(`Tool '${toolName}' not found in server '${serverName}'. Use describe_tool to get the tool schema or search_tools to find available tools.`);
+                        }
+                        // Phase 2d: Use args passed from mcpCallTool (from the 'arguments' parameter in the request)
+                        // args is the 'arguments' object from the MCP request, not callArgs
+                        const args2 = args || {};
+                        console.log(`[MetaLink] direct tool call: ${name} with args ${JSON.stringify(args2)}`);
+                        // Phase 3: Special handling for memory-search_nodes - use fallback directly
+                        if (serverName === 'memory' && toolName === 'search_nodes') {
+                            console.log(`[MetaLink] Intercepting memory-search_nodes - using read_graph with client-side filtering`);
+                            try {
+                                const graphResult = await this.serverManager.callTool('memory', 'read_graph', {});
+                                const query = (args2.query || '').toLowerCase();
+                                // Parse the nested response
+                                if (graphResult && typeof graphResult === 'object') {
+                                    const resultObj = graphResult;
+                                    if (resultObj.content && Array.isArray(resultObj.content)) {
+                                        const textContent = resultObj.content[0]?.text;
+                                        if (textContent) {
+                                            const graphData = JSON.parse(textContent);
+                                            // Filter entities by query
+                                            const filteredEntities = graphData.entities?.filter((e) => query === '' ||
+                                                e.name.toLowerCase().includes(query) ||
+                                                e.observations?.some((obs) => obs.toLowerCase().includes(query))) || [];
+                                            return {
+                                                content: [{
+                                                        type: 'text',
+                                                        text: JSON.stringify({
+                                                            entities: filteredEntities,
+                                                            relations: graphData.relations || []
+                                                        }, null, 2)
+                                                    }]
+                                            };
+                                        }
+                                    }
+                                }
+                            }
+                            catch (fallbackError) {
+                                console.error(`[MetaLink] Fallback for memory:search_nodes failed:`, fallbackError);
+                                throw new Error(`Tool execution failed for ${name}: memory:search_nodes fallback failed - ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);
+                            }
+                        }
+                        // Phase 3: Call the actual tool via response router
+                        try {
+                            const result = await this.serverManager.callTool(serverName, toolName, args2);
+                            return result;
+                        }
+                        catch (toolError) {
+                            // Enhanced error with inputSchema for debugging
+                            const errorMsg = `Tool execution failed for ${name}: ${toolError instanceof Error ? toolError.message : String(toolError)}`;
+                            // Check if error is parameter-related
+                            const errorStr = (toolError instanceof Error ? toolError.message : String(toolError)).toLowerCase();
+                            const isParamError = errorStr.includes('null') || errorStr.includes('undefined') ||
+                                errorStr.includes('required') || errorStr.includes('missing');
+                            if (isParamError && toolSchema) {
+                                const inputSchema = toolSchema.inputSchema;
+                                if (inputSchema) {
+                                    const requiredParams = inputSchema.required || [];
+                                    const availableParams = Object.keys(inputSchema.properties || {});
+                                    const optionalParams = availableParams.filter(p => !requiredParams.includes(p));
+                                    const requiredList = requiredParams.length > 0 ? requiredParams.join(', ') : 'none';
+                                    const optionalList = optionalParams.length > 0 ? optionalParams.join(', ') : 'none';
+                                    const hint = `\n\n💡 Hint: This tool expects:\n` +
+                                        `  Required: ${requiredList}\n` +
+                                        `  Optional: ${optionalList}\n` +
+                                        `  Use describe_tool('${serverName}', '${toolName}') for full schema.`;
+                                    throw new Error(errorMsg + hint);
+                                }
+                            }
+                            throw new Error(errorMsg);
+                        }
+                    }
+                }
+                throw new InvalidParamsError(`Unknown tool: ${name}`);
+            }
+        }
+    }
+    /**
+     * Add a new server to the registry
+     */
+    async addServer(req, res) {
+        try {
+            const serverConfig = req.body;
+            // Validate and add server to registry
+            const server = await this.configLoader.saveServerToRegistry(serverConfig, {
+                allowAnyCommand: false,
+                timeout: 5000,
+            });
+            // v1.1.29: Trigger immediate tool discovery
+            let discoveredToolCount = 0;
+            try {
+                console.log(`[AddServer] Starting immediate tool discovery for '${server.name}'`);
+                await this.serverManager.ensureServerStarted(server.name, server);
+                const tools = this.serverManager.getServerTools(server.name);
+                discoveredToolCount = tools.length;
+                console.log(`[AddServer] Discovered ${discoveredToolCount} tools for '${server.name}': ${tools.map(t => t.name).join(', ')}`);
+            }
+            catch (discoveryError) {
+                console.warn(`[AddServer] Tool discovery failed for '${server.name}' (non-fatal):`, discoveryError);
+                // Don't fail the add operation if discovery fails
+            }
+            // Broadcast server:added event
+            this.broadcastEvent({
+                type: 'server:added',
+                data: {
+                    server,
+                    timestamp: Date.now(),
+                },
+            });
+            res.status(201).json({
+                success: true,
+                message: `Server '${server.name}' added to registry`,
+                server,
+                discoveredTools: discoveredToolCount,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Failed to add server';
+            res.status(400).json({
+                error: message,
+            });
+        }
+    }
+    /**
+     * Remove a server from the registry
+     */
+    async removeServer(req, res) {
+        try {
+            const { name } = req.params;
+            // Check if server exists
+            const server = this.configLoader.getServer(name);
+            if (!server) {
+                res.status(404).json({
+                    error: `Server '${name}' not found in registry`,
+                });
+                return;
+            }
+            // Check if server is running and require force if so
+            const status = this.serverManager.getServerStatus(name);
+            if (status?.status === 'running') {
+                // Check for force flag in query params
+                const force = req.query.force === 'true';
+                if (!force) {
+                    res.status(409).json({
+                        error: `Server '${name}' is currently running. Use ?force=true to remove it anyway.`,
+                        running: true,
+                    });
+                    return;
+                }
+                // Clean up running server before removing
+                try {
+                    await this.serverManager.removeServer(name);
+                }
+                catch (error) {
+                    // Continue anyway - cleanup happened
+                }
+            }
+            // Remove from registry
+            await this.configLoader.removeServerFromRegistry(name, { timeout: 5000 });
+            // Broadcast server:removed event
+            this.broadcastEvent({
+                type: 'server:removed',
+                data: {
+                    name,
+                    timestamp: Date.now(),
+                },
+            });
+            res.json({
+                success: true,
+                message: `Server '${name}' removed from registry`,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Failed to remove server';
+            res.status(400).json({
+                error: message,
+            });
+        }
+    }
+    /**
+     * Validate a server configuration without saving
+     */
+    async validateServer(req, res) {
+        try {
+            const { RegistryManager } = await import('../config/registry.js');
+            const registry = new RegistryManager();
+            // Validate configuration
+            const validation = await registry.validateServer(req.body, {
+                allowAnyCommand: false,
+            });
+            if (validation.valid) {
+                res.json({
+                    valid: true,
+                    message: 'Server configuration is valid',
+                });
+            }
+            else {
+                res.status(400).json({
+                    valid: false,
+                    errors: validation.errors || [],
+                });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Validation error';
+            res.status(400).json({
+                error: message,
+            });
+        }
+    }
+    /**
+     * Start the HTTP server
+     * NOTE: This Promise never resolves - it keeps the event loop alive for background mode
+     */
+    async listen(port, host) {
+        return new Promise((_resolve, reject) => {
+            this.server = this.app.listen(port, host, () => {
+                console.log(`[MetaLink] HTTP server listening on http://${host}:${port}`);
+                console.log(`[MetaLink] Dashboard available at http://${host}:${port}`);
+                console.log(`[MetaLink] API available at http://${host}:${port}/api/v1`);
+                console.log(`[MetaLink] Events available at http://${host}:${port}/api/v1/events`);
+                console.log(`[MetaLink] MCP endpoint available at http://${host}:${port}/mcp`);
+                // NOTE: Intentionally NOT resolving - keeps event loop alive for background mode
+            });
+            // Handle server errors
+            this.server.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Send message via SSE to connected client
+     */
+    sendSSEMessage(sessionId, message) {
+        const conn = this.sseConnections.get(sessionId);
+        if (conn && !conn.destroyed) {
+            try {
+                conn.write(`data: ${JSON.stringify(message)}\n\n`);
+            }
+            catch (err) {
+                console.log(`[SSE] Error sending message to session ${sessionId}:`, err instanceof Error ? err.message : err);
+                this.sseConnections.delete(sessionId);
+            }
+        }
+    }
+    notifyToolsListChanged() {
+        const now = Date.now();
+        if (now - this.lastToolsListNotification < this.TOOLS_LIST_NOTIFICATION_THROTTLE_MS) {
+            console.log('[MCP] Throttling tools/list_changed notification');
+            return;
+        }
+        this.lastToolsListNotification = now;
+        const notification = {
+            jsonrpc: '2.0',
+            method: 'notifications/tools/list_changed'
+        };
+        let sentCount = 0;
+        for (const [sessionId, conn] of this.sseConnections) {
+            if (!conn.destroyed) {
+                try {
+                    const eventId = this.trackSseEvent(sessionId, notification);
+                    conn.write(`id: ${eventId}\ndata: ${JSON.stringify(notification)}\n\n`);
+                    sentCount++;
+                }
+                catch (error) {
+                    console.warn(`[MCP] Failed to send notification to session ${sessionId}:`, error);
+                    this.sseConnections.delete(sessionId);
+                }
+            }
+        }
+        if (sentCount > 0) {
+            console.log(`[MCP] Sent notifications/tools/list_changed to ${sentCount} client(s)`);
+        }
+    }
+    /**
+     * Send response via callback URL (MCP callback protocol for bidirectional communication)
+     */
+    async sendViaCallback(session, response) {
+        if (!session.callbackUrl) {
+            return false;
+        }
+        try {
+            console.log(`[CALLBACK] Posting response to ${session.callbackUrl}`);
+            // POST response to callback URL
+            const callbackResponse = await fetch(session.callbackUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Mcp-Session-Id': session.id,
+                    'MCP-Protocol-Version': MCP_PROTOCOL_VERSION
+                },
+                body: JSON.stringify(response),
+                signal: AbortSignal.timeout(10000) // 10 second timeout
+            });
+            if (!callbackResponse.ok) {
+                console.warn(`[CALLBACK] Warning: callback returned ${callbackResponse.status}`);
+            }
+            return true;
+        }
+        catch (error) {
+            console.error(`[CALLBACK] Error sending to ${session.callbackUrl}:`, error instanceof Error ? error.message : error);
+            return false;
+        }
+    }
+    /**
+     * Cleanup
+     */
+    /**
+     * Get all safety rules
+     */
+    async getSafetyRules(req, res) {
+        try {
+            const includePatterns = req.query.include_patterns === 'true';
+            const rules = this.configLoader.getToolSafetyRules();
+            const response = {
+                safeToolOverrides: rules.safeToolOverrides || [],
+                riskyToolOverrides: rules.riskyToolOverrides || [],
+            };
+            if (includePatterns) {
+                response.safePatterns = rules.safePatterns || [];
+                response.riskyPatterns = rules.riskyPatterns || [];
+            }
+            // Always include argumentInspectionRules (v1.1.29+)
+            response.argumentInspectionRules = rules.argumentInspectionRules || [];
+            res.json(response);
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to get safety rules',
+            });
+        }
+    }
+    /**
+     * Check if a specific tool is safe or risky
+     */
+    async checkToolSafety(req, res) {
+        try {
+            const { server, tool } = req.params;
+            if (!server || !tool) {
+                res.status(400).json({
+                    error: 'Missing required parameters: server and tool',
+                });
+                return;
+            }
+            const result = this.serverManager.classifyToolSafety(server, tool);
+            res.json({
+                server,
+                tool,
+                fullName: `${server}:${tool}`,
+                safety: result.safety,
+                reason: result.reason,
+                requiresConfirmation: result.safety === 'risky',
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to check tool safety',
+            });
+        }
+    }
+    /**
+     * Add a safe tool override
+     */
+    async addSafeToolOverride(req, res) {
+        try {
+            const { tool, reason } = req.body;
+            if (!tool || typeof tool !== 'string') {
+                res.status(400).json({
+                    error: 'Missing or invalid required parameter: tool (string)',
+                });
+                return;
+            }
+            // Validate tool format
+            const toolPattern = /^[a-zA-Z0-9_-]+:[a-zA-Z0-9_*-]+$/;
+            if (!toolPattern.test(tool)) {
+                res.status(400).json({
+                    error: 'Invalid tool format. Expected: server:tool or server:*',
+                });
+                return;
+            }
+            await this.configLoader.addSafeToolOverride(tool);
+            res.status(201).json({
+                success: true,
+                message: `Added ${tool} to safe tools`,
+                tool,
+                reason: reason || undefined,
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to add safe tool override',
+            });
+        }
+    }
+    /**
+     * Add a risky tool override
+     */
+    async addRiskyToolOverride(req, res) {
+        try {
+            const { tool, reason } = req.body;
+            if (!tool || typeof tool !== 'string') {
+                res.status(400).json({
+                    error: 'Missing or invalid required parameter: tool (string)',
+                });
+                return;
+            }
+            // Validate tool format
+            const toolPattern = /^[a-zA-Z0-9_-]+:[a-zA-Z0-9_*-]+$/;
+            if (!toolPattern.test(tool)) {
+                res.status(400).json({
+                    error: 'Invalid tool format. Expected: server:tool or server:*',
+                });
+                return;
+            }
+            await this.configLoader.addRiskyToolOverride(tool);
+            res.status(201).json({
+                success: true,
+                message: `Added ${tool} to risky tools`,
+                tool,
+                reason: reason || undefined,
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to add risky tool override',
+            });
+        }
+    }
+    /**
+     * Add a safe pattern
+     */
+    async addSafePattern(req, res) {
+        try {
+            const { pattern, reason } = req.body;
+            if (!pattern || typeof pattern !== 'string') {
+                res.status(400).json({
+                    error: 'Missing or invalid required parameter: pattern (string)',
+                });
+                return;
+            }
+            // Validate regex pattern
+            try {
+                new RegExp(pattern);
+            }
+            catch (e) {
+                res.status(400).json({
+                    error: `Invalid regex pattern: ${pattern}`,
+                });
+                return;
+            }
+            await this.configLoader.addSafePattern(pattern);
+            res.status(201).json({
+                success: true,
+                message: `Added pattern ${pattern} to safe patterns`,
+                pattern,
+                reason: reason || undefined,
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to add safe pattern',
+            });
+        }
+    }
+    /**
+     * Add a risky pattern
+     */
+    async addRiskyPattern(req, res) {
+        try {
+            const { pattern, reason } = req.body;
+            if (!pattern || typeof pattern !== 'string') {
+                res.status(400).json({
+                    error: 'Missing or invalid required parameter: pattern (string)',
+                });
+                return;
+            }
+            // Validate regex pattern
+            try {
+                new RegExp(pattern);
+            }
+            catch (e) {
+                res.status(400).json({
+                    error: `Invalid regex pattern: ${pattern}`,
+                });
+                return;
+            }
+            await this.configLoader.addRiskyPattern(pattern);
+            res.status(201).json({
+                success: true,
+                message: `Added pattern ${pattern} to risky patterns`,
+                pattern,
+                reason: reason || undefined,
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to add risky pattern',
+            });
+        }
+    }
+    /**
+     * Remove a rule (tool override or pattern)
+     */
+    async removeRule(req, res) {
+        try {
+            const { rule } = req.params;
+            if (!rule) {
+                res.status(400).json({
+                    error: 'Missing required parameter: rule',
+                });
+                return;
+            }
+            // URL decode the rule
+            const decodedRule = decodeURIComponent(rule);
+            // Auto-detect rule type
+            const rules = this.configLoader.getToolSafetyRules();
+            let removed = false;
+            let type = '';
+            if (rules.safeToolOverrides?.includes(decodedRule)) {
+                await this.configLoader.removeSafeToolOverride(decodedRule);
+                removed = true;
+                type = 'safe_tool_override';
+            }
+            else if (rules.riskyToolOverrides?.includes(decodedRule)) {
+                await this.configLoader.removeRiskyToolOverride(decodedRule);
+                removed = true;
+                type = 'risky_tool_override';
+            }
+            else if (rules.safePatterns?.includes(decodedRule)) {
+                await this.configLoader.removeSafePattern(decodedRule);
+                removed = true;
+                type = 'safe_pattern';
+            }
+            else if (rules.riskyPatterns?.includes(decodedRule)) {
+                await this.configLoader.removeRiskyPattern(decodedRule);
+                removed = true;
+                type = 'risky_pattern';
+            }
+            if (!removed) {
+                res.status(404).json({
+                    error: `Rule not found: ${decodedRule}`,
+                });
+                return;
+            }
+            res.json({
+                success: true,
+                message: `Removed ${type}: ${decodedRule}`,
+                rule: decodedRule,
+                type,
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to remove rule',
+            });
+        }
+    }
+    /**
+     * Reset safety rules to defaults
+     */
+    async resetSafetyRules(req, res) {
+        try {
+            const { force } = req.body;
+            if (!force) {
+                res.status(400).json({
+                    error: 'Reset requires explicit confirmation. Set force: true',
+                });
+                return;
+            }
+            await this.configLoader.resetToDefaults();
+            res.json({
+                success: true,
+                message: 'Reset all safety rules to defaults',
+            });
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to reset safety rules',
+            });
+        }
+    }
+    /**
+     * Import safety rules from JSON
+     */
+    async importSafetyRules(req, res) {
+        try {
+            const { rules, merge = true } = req.body; // Default to merge mode
+            if (!rules || typeof rules !== 'object') {
+                res.status(400).json({
+                    error: 'Missing or invalid required parameter: rules (object)',
+                });
+                return;
+            }
+            // Get current rules to preserve argumentInspectionRules
+            const currentRules = this.configLoader.getToolSafetyRules();
+            // Extract arrays from the rules object
+            const safeToolOverrides = Array.isArray(rules.safeToolOverrides) ? rules.safeToolOverrides : [];
+            const riskyToolOverrides = Array.isArray(rules.riskyToolOverrides) ? rules.riskyToolOverrides : [];
+            const safePatterns = Array.isArray(rules.safePatterns) ? rules.safePatterns : [];
+            const riskyPatterns = Array.isArray(rules.riskyPatterns) ? rules.riskyPatterns : [];
+            // Preserve argumentInspectionRules unless explicitly provided in import
+            const argumentInspectionRules = Array.isArray(rules.argumentInspectionRules)
+                ? rules.argumentInspectionRules
+                : (currentRules.argumentInspectionRules || []);
+            if (merge) {
+                // Merge mode: Add new rules to existing ones (default)
+                // Merge tool overrides (avoid duplicates)
+                const mergedSafeTools = [...new Set([...(currentRules.safeToolOverrides || []), ...safeToolOverrides])];
+                const mergedRiskyTools = [...new Set([...(currentRules.riskyToolOverrides || []), ...riskyToolOverrides])];
+                const mergedSafePatterns = [...new Set([...(currentRules.safePatterns || []), ...safePatterns])];
+                const mergedRiskyPatterns = [...new Set([...(currentRules.riskyPatterns || []), ...riskyPatterns])];
+                await this.configLoader.setToolSafetyRules({
+                    safeToolOverrides: mergedSafeTools,
+                    riskyToolOverrides: mergedRiskyTools,
+                    safePatterns: mergedSafePatterns,
+                    riskyPatterns: mergedRiskyPatterns,
+                    argumentInspectionRules, // Always preserve
+                });
+                res.json({
+                    success: true,
+                    message: 'Safety rules imported and merged successfully',
+                    imported: {
+                        safeTools: mergedSafeTools.length,
+                        riskyTools: mergedRiskyTools.length,
+                        safePatterns: mergedSafePatterns.length,
+                        riskyPatterns: mergedRiskyPatterns.length,
+                    },
+                });
+            }
+            else {
+                // Replace mode: Replace all rules with imported ones
+                await this.configLoader.setToolSafetyRules({
+                    safeToolOverrides,
+                    riskyToolOverrides,
+                    safePatterns,
+                    riskyPatterns,
+                    argumentInspectionRules, // Still preserve if not provided
+                });
+                res.json({
+                    success: true,
+                    message: 'Safety rules imported successfully (replace mode)',
+                    imported: {
+                        safeTools: safeToolOverrides.length,
+                        riskyTools: riskyToolOverrides.length,
+                        safePatterns: safePatterns.length,
+                        riskyPatterns: riskyPatterns.length,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error instanceof Error ? error.message : 'Failed to import safety rules',
+            });
+        }
+    }
+    async cleanup() {
+        // Save metrics before shutdown (Phase 4 - v1.4.0)
+        try {
+            this.metricsPersistence.stopPeriodicWrites();
+            const finalMetrics = {
+                timestamp: Date.now(),
+                metrics: globalMetrics.getMetrics(),
+                serverMetrics: globalMetrics.getAllServerMetrics(),
+                apiMetrics: globalMetrics.getApiMetrics(),
+            };
+            await this.metricsPersistence.save(finalMetrics);
+            console.log('[MetricsPersistence] Saved final metrics on shutdown');
+        }
+        catch (error) {
+            console.error('[MetricsPersistence] Failed to save metrics on shutdown:', error);
+        }
+        await this.serverManager.cleanup();
+        for (const client of this.eventClients) {
+            client.end();
+        }
+        this.eventClients.clear();
+        // Close all SSE connections
+        for (const [sessionId, conn] of this.sseConnections) {
+            try {
+                conn.end();
+            }
+            catch (err) {
+                console.log(`[SSE] Error closing connection for session ${sessionId}`);
+            }
+        }
+        this.sseConnections.clear();
+    }
+}
+//# sourceMappingURL=http.js.map