@compass-ai/nova 1.0.72 → 1.0.74

package/dist/services/mcp-transport.js

@@ -0,0 +1,1316 @@
+/**
+ * MCP Transport Services.
+ *
+ * This module provides transport layer implementations for connecting to MCP servers
+ * using different protocols: HTTP, SSE (Server-Sent Events), and stdio (local processes).
+ */
+import { spawn } from 'child_process';
+import { logger } from '../utils/logger.js';
+import { getMCPOAuthService } from './mcp-oauth-service.js';
+import { DEFAULT_MCP_TIMEOUT, isMCPHttpConfig, isMCPSseConfig, isMCPStdioConfig, normalizeServerConfig, } from '../types/mcp.js';
+/**
+ * Error thrown when MCP server requires authentication (HTTP 401).
+ */
+export class AuthenticationRequiredError extends Error {
+    serverName;
+    serverUrl;
+    constructor(serverName, serverUrl) {
+        super(`Authentication required for MCP server '${serverName}'`);
+        this.name = 'AuthenticationRequiredError';
+        this.serverName = serverName;
+        this.serverUrl = serverUrl;
+    }
+}
+/**
+ * Creates a simple HTTP-based MCP client.
+ */
+class SimpleMCPClient {
+    url;
+    headers;
+    connected = false;
+    capabilities = {};
+    requestTimeout;
+    serverName;
+    constructor(url, headers = {}, timeout = 30000, serverName = 'unknown') {
+        this.url = url;
+        this.serverName = serverName;
+        this.headers = {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json, text/event-stream',
+            ...headers,
+        };
+        this.requestTimeout = timeout;
+    }
+    /**
+     * Parses a JSON-RPC response from either a plain JSON body or an SSE stream.
+     * MCP Streamable HTTP servers may respond with text/event-stream containing
+     * SSE-formatted JSON-RPC messages.
+     */
+    async parseResponse(response) {
+        const contentType = response.headers.get('content-type') || '';
+        if (contentType.includes('text/event-stream')) {
+            const text = await response.text();
+            // Parse SSE: find "data:" lines and extract JSON from the last message event
+            const lines = text.split('\n');
+            let lastData = '';
+            for (const line of lines) {
+                if (line.startsWith('data:')) {
+                    const data = line.slice(5).trim();
+                    if (data) {
+                        lastData = data;
+                    }
+                }
+            }
+            if (!lastData) {
+                throw new Error('No data found in SSE response');
+            }
+            return JSON.parse(lastData);
+        }
+        return (await response.json());
+    }
+    async connect() {
+        // Attempt to connect and get server info
+        try {
+            const abortController = new AbortController();
+            const timeoutId = setTimeout(() => abortController.abort(), this.requestTimeout);
+            const response = await fetch(this.url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 1,
+                    method: 'initialize',
+                    params: {
+                        protocolVersion: '2024-11-05',
+                        capabilities: {},
+                        clientInfo: { name: 'compass-cli', version: '1.0.0' },
+                    },
+                }),
+                signal: abortController.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const result = await this.parseResponse(response);
+                if (result.result?.capabilities) {
+                    this.capabilities = {
+                        tools: !!result.result.capabilities.tools,
+                        resources: !!result.result.capabilities.resources,
+                        prompts: !!result.result.capabilities.prompts,
+                        logging: !!result.result.capabilities.logging,
+                    };
+                }
+                this.connected = true;
+            }
+            else if (response.status === 401) {
+                // Authentication required - log response details for debugging
+                const responseText = await response.text().catch(() => '');
+                const wwwAuth = response.headers.get('WWW-Authenticate') || '';
+                logger.debug(`401 response from ${this.serverName}: body=${responseText.slice(0, 200)}, WWW-Authenticate=${wwwAuth}`);
+                throw new AuthenticationRequiredError(this.serverName, this.url);
+            }
+            else {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            // Rethrow AuthenticationRequiredError as-is for OAuth flow handling
+            if (error instanceof AuthenticationRequiredError) {
+                throw error;
+            }
+            if (error.name === 'AbortError') {
+                throw new Error('Connection timeout');
+            }
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to connect: ${msg}`);
+        }
+    }
+    async close() {
+        this.connected = false;
+    }
+    async listTools() {
+        if (!this.connected) {
+            return { tools: [] };
+        }
+        try {
+            const abortController = new AbortController();
+            const timeoutId = setTimeout(() => abortController.abort(), this.requestTimeout);
+            const response = await fetch(this.url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 2,
+                    method: 'tools/list',
+                    params: {},
+                }),
+                signal: abortController.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const result = await this.parseResponse(response);
+                return { tools: result.result?.tools || [] };
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to list tools:', error);
+        }
+        return { tools: [] };
+    }
+    async listResources() {
+        if (!this.connected) {
+            return { resources: [] };
+        }
+        try {
+            const abortController = new AbortController();
+            const timeoutId = setTimeout(() => abortController.abort(), this.requestTimeout);
+            const response = await fetch(this.url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 3,
+                    method: 'resources/list',
+                    params: {},
+                }),
+                signal: abortController.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const result = await this.parseResponse(response);
+                return { resources: result.result?.resources || [] };
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to list resources:', error);
+        }
+        return { resources: [] };
+    }
+    async listPrompts() {
+        if (!this.connected) {
+            return { prompts: [] };
+        }
+        try {
+            const abortController = new AbortController();
+            const timeoutId = setTimeout(() => abortController.abort(), this.requestTimeout);
+            const response = await fetch(this.url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 4,
+                    method: 'prompts/list',
+                    params: {},
+                }),
+                signal: abortController.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const result = await this.parseResponse(response);
+                return { prompts: result.result?.prompts || [] };
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to list prompts:', error);
+        }
+        return { prompts: [] };
+    }
+    async callTool(params) {
+        if (!this.connected) {
+            return { success: false, error: 'Not connected' };
+        }
+        try {
+            const abortController = new AbortController();
+            const timeoutId = setTimeout(() => abortController.abort(), this.requestTimeout);
+            const response = await fetch(this.url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 5,
+                    method: 'tools/call',
+                    params: {
+                        name: params.name,
+                        arguments: params.arguments,
+                    },
+                }),
+                signal: abortController.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const result = await this.parseResponse(response);
+                if (result.error) {
+                    return { success: false, error: result.error.message };
+                }
+                return {
+                    success: true,
+                    content: result.result?.content || [],
+                    isError: result.result?.isError,
+                };
+            }
+            return { success: false, error: `HTTP ${response.status}` };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { success: false, error: msg };
+        }
+    }
+    async readResource(params) {
+        if (!this.connected) {
+            return { contents: [] };
+        }
+        try {
+            const abortController = new AbortController();
+            const timeoutId = setTimeout(() => abortController.abort(), this.requestTimeout);
+            const response = await fetch(this.url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 6,
+                    method: 'resources/read',
+                    params: { uri: params.uri },
+                }),
+                signal: abortController.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const result = await this.parseResponse(response);
+                return { contents: result.result?.contents || [] };
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to read resource:', error);
+        }
+        return { contents: [] };
+    }
+    async getPrompt(params) {
+        if (!this.connected) {
+            return { messages: [] };
+        }
+        try {
+            const abortController = new AbortController();
+            const timeoutId = setTimeout(() => abortController.abort(), this.requestTimeout);
+            const response = await fetch(this.url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: 7,
+                    method: 'prompts/get',
+                    params,
+                }),
+                signal: abortController.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const result = await this.parseResponse(response);
+                const messages = (result.result?.messages || []).map((msg) => ({
+                    role: msg.role,
+                    content: typeof msg.content === 'string' ? msg.content : msg.content.text || '',
+                }));
+                return { messages };
+            }
+        }
+        catch (error) {
+            logger.warn('Failed to get prompt:', error);
+        }
+        return { messages: [] };
+    }
+    getServerCapabilities() {
+        return this.connected ? this.capabilities : null;
+    }
+}
+/**
+ * Creates an MCP client that communicates via SSE (Server-Sent Events).
+ * Uses GET to establish SSE stream, POST to send messages to server-provided endpoint.
+ *
+ * Per MCP spec: https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse
+ * 1. Client opens GET request to SSE endpoint
+ * 2. Server sends 'endpoint' event with URL for posting messages
+ * 3. Client sends JSON-RPC via POST to that endpoint
+ * 4. Server sends responses back via SSE stream
+ */
+class SseMCPClient {
+    sseUrl;
+    headers;
+    connected = false;
+    capabilities = {};
+    messageEndpoint = null;
+    requestId = 0;
+    pendingRequests = new Map();
+    abortController = null;
+    connectionTimeout;
+    constructor(url, headers = {}, timeout = 30000) {
+        this.sseUrl = url;
+        this.headers = headers;
+        this.connectionTimeout = timeout;
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                this.abortController?.abort();
+                reject(new Error('SSE connection timeout'));
+            }, this.connectionTimeout);
+            this.establishSseConnection()
+                .then(async () => {
+                clearTimeout(timeoutId);
+                // Wait for endpoint to be received (with timeout)
+                const endpointTimeout = setTimeout(() => {
+                    reject(new Error('Timeout waiting for endpoint event from SSE server'));
+                }, 10000);
+                // Poll for endpoint (it should arrive via SSE event)
+                const checkEndpoint = async () => {
+                    if (this.messageEndpoint) {
+                        clearTimeout(endpointTimeout);
+                        // Now send initialize request
+                        try {
+                            const result = await this.sendRequest('initialize', {
+                                protocolVersion: '2024-11-05',
+                                capabilities: {},
+                                clientInfo: { name: 'compass-cli', version: '1.0.0' },
+                            });
+                            if (result.result?.capabilities) {
+                                this.capabilities = {
+                                    tools: !!result.result.capabilities.tools,
+                                    resources: !!result.result.capabilities.resources,
+                                    prompts: !!result.result.capabilities.prompts,
+                                    logging: !!result.result.capabilities.logging,
+                                };
+                            }
+                            // Send initialized notification
+                            await this.sendNotification('notifications/initialized', {});
+                            this.connected = true;
+                            resolve();
+                        }
+                        catch (initError) {
+                            reject(initError);
+                        }
+                    }
+                    else {
+                        setTimeout(checkEndpoint, 100);
+                    }
+                };
+                checkEndpoint();
+            })
+                .catch((err) => {
+                clearTimeout(timeoutId);
+                reject(err);
+            });
+        });
+    }
+    async establishSseConnection() {
+        this.abortController = new AbortController();
+        try {
+            const response = await fetch(this.sseUrl, {
+                method: 'GET',
+                headers: {
+                    'Accept': 'text/event-stream',
+                    'Cache-Control': 'no-cache',
+                    ...this.headers,
+                },
+                signal: this.abortController.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`SSE connection failed: HTTP ${response.status} ${response.statusText}`);
+            }
+            if (!response.body) {
+                throw new Error('SSE response has no body');
+            }
+            // Start reading the SSE stream in the background
+            this.readSseStream(response.body);
+        }
+        catch (error) {
+            if (error.name === 'AbortError') {
+                throw new Error('SSE connection aborted');
+            }
+            throw error;
+        }
+    }
+    async readSseStream(body) {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let currentEvent = '';
+        let currentData = '';
+        try {
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    logger.debug('SSE stream ended');
+                    this.connected = false;
+                    break;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split(/\r?\n/); // Handle both \n and \r\n line endings
+                buffer = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    const trimmedLine = line.trim(); // Trim to handle any extra whitespace
+                    if (trimmedLine.startsWith('event:')) {
+                        currentEvent = trimmedLine.slice(6).trim();
+                    }
+                    else if (trimmedLine.startsWith('data:')) {
+                        currentData += trimmedLine.slice(5).trim();
+                    }
+                    else if (trimmedLine === '') {
+                        // Empty line = end of event
+                        if (currentEvent || currentData) {
+                            this.handleSseEvent(currentEvent, currentData);
+                            currentEvent = '';
+                            currentData = '';
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (error.name !== 'AbortError') {
+                logger.error('SSE stream error:', error);
+            }
+            this.connected = false;
+            // Reject all pending requests
+            for (const [id, pending] of this.pendingRequests) {
+                pending.reject(new Error('SSE connection closed'));
+                this.pendingRequests.delete(id);
+            }
+        }
+    }
+    handleSseEvent(event, data) {
+        logger.debug(`SSE event received: ${event || 'message'}, data: ${data.substring(0, 100)}...`);
+        if (event === 'endpoint') {
+            // Server is telling us where to POST messages
+            // The data might be a relative or absolute URL
+            try {
+                // Check if it's an absolute URL
+                if (data.startsWith('http://') || data.startsWith('https://')) {
+                    this.messageEndpoint = data;
+                }
+                else {
+                    // It's relative, resolve against the SSE URL
+                    const baseUrl = new URL(this.sseUrl);
+                    this.messageEndpoint = new URL(data, baseUrl).toString();
+                }
+                logger.debug(`SSE message endpoint set to: ${this.messageEndpoint}`);
+            }
+            catch (urlError) {
+                logger.error('Failed to parse endpoint URL:', urlError);
+            }
+        }
+        else if (event === 'message' || event === '') {
+            // JSON-RPC response from server
+            if (data) {
+                try {
+                    const response = JSON.parse(data);
+                    this.handleJsonRpcResponse(response);
+                }
+                catch (parseError) {
+                    logger.debug(`Failed to parse SSE message data: ${data}`);
+                }
+            }
+        }
+    }
+    handleJsonRpcResponse(response) {
+        if (response.id !== undefined && response.id !== null) {
+            const pending = this.pendingRequests.get(response.id);
+            if (pending) {
+                this.pendingRequests.delete(response.id);
+                pending.resolve(response);
+            }
+        }
+        // Notifications (no id) are logged but not handled for now
+    }
+    async sendRequest(method, params) {
+        if (!this.messageEndpoint) {
+            throw new Error('Message endpoint not available - SSE connection may not be established');
+        }
+        const id = ++this.requestId;
+        const request = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+        };
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, { resolve, reject });
+            // Set timeout for request
+            const timeoutId = setTimeout(() => {
+                if (this.pendingRequests.has(id)) {
+                    this.pendingRequests.delete(id);
+                    reject(new Error(`Request timeout: ${method}`));
+                }
+            }, this.connectionTimeout);
+            // Send via POST to message endpoint
+            fetch(this.messageEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.headers,
+                },
+                body: JSON.stringify(request),
+            })
+                .then((response) => {
+                if (!response.ok) {
+                    clearTimeout(timeoutId);
+                    this.pendingRequests.delete(id);
+                    reject(new Error(`HTTP ${response.status}: ${response.statusText}`));
+                }
+                // Response will come via SSE stream, not HTTP response body
+                // Some servers may return 202 Accepted or similar
+            })
+                .catch((error) => {
+                clearTimeout(timeoutId);
+                this.pendingRequests.delete(id);
+                reject(error);
+            });
+        });
+    }
+    async sendNotification(method, params) {
+        if (!this.messageEndpoint) {
+            return;
+        }
+        const notification = {
+            jsonrpc: '2.0',
+            method,
+            params,
+        };
+        try {
+            await fetch(this.messageEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.headers,
+                },
+                body: JSON.stringify(notification),
+            });
+        }
+        catch (error) {
+            logger.debug('Failed to send notification:', error);
+        }
+    }
+    async close() {
+        this.connected = false;
+        this.abortController?.abort();
+        this.abortController = null;
+        this.messageEndpoint = null;
+        // Clear pending requests
+        for (const [id, pending] of this.pendingRequests) {
+            pending.reject(new Error('Client closed'));
+            this.pendingRequests.delete(id);
+        }
+    }
+    async listTools() {
+        if (!this.connected) {
+            return { tools: [] };
+        }
+        try {
+            const result = await this.sendRequest('tools/list', {});
+            return { tools: result.result?.tools || [] };
+        }
+        catch (error) {
+            logger.warn('Failed to list tools:', error);
+            return { tools: [] };
+        }
+    }
+    async listResources() {
+        if (!this.connected) {
+            return { resources: [] };
+        }
+        try {
+            const result = await this.sendRequest('resources/list', {});
+            return { resources: result.result?.resources || [] };
+        }
+        catch (error) {
+            logger.warn('Failed to list resources:', error);
+            return { resources: [] };
+        }
+    }
+    async listPrompts() {
+        if (!this.connected) {
+            return { prompts: [] };
+        }
+        try {
+            const result = await this.sendRequest('prompts/list', {});
+            return { prompts: result.result?.prompts || [] };
+        }
+        catch (error) {
+            logger.warn('Failed to list prompts:', error);
+            return { prompts: [] };
+        }
+    }
+    async callTool(params) {
+        if (!this.connected) {
+            return { success: false, error: 'Not connected' };
+        }
+        try {
+            const result = await this.sendRequest('tools/call', {
+                name: params.name,
+                arguments: params.arguments,
+            });
+            if (result.error) {
+                return { success: false, error: result.error.message };
+            }
+            return {
+                success: true,
+                content: result.result?.content || [],
+                isError: result.result?.isError,
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { success: false, error: msg };
+        }
+    }
+    async readResource(params) {
+        if (!this.connected) {
+            return { contents: [] };
+        }
+        try {
+            const result = await this.sendRequest('resources/read', { uri: params.uri });
+            return { contents: result.result?.contents || [] };
+        }
+        catch (error) {
+            logger.warn('Failed to read resource:', error);
+            return { contents: [] };
+        }
+    }
+    async getPrompt(params) {
+        if (!this.connected) {
+            return { messages: [] };
+        }
+        try {
+            const result = await this.sendRequest('prompts/get', params);
+            const messages = (result.result?.messages || []).map((msg) => ({
+                role: msg.role,
+                content: typeof msg.content === 'string' ? msg.content : msg.content.text || '',
+            }));
+            return { messages };
+        }
+        catch (error) {
+            logger.warn('Failed to get prompt:', error);
+            return { messages: [] };
+        }
+    }
+    getServerCapabilities() {
+        return this.connected ? this.capabilities : null;
+    }
+}
+/**
+ * Creates an MCP client that communicates via stdio (stdin/stdout).
+ * Spawns a child process and uses JSON-RPC 2.0 over newline-delimited JSON.
+ */
+class StdioMCPClient {
+    command;
+    args;
+    cwd;
+    env;
+    requestTimeout;
+    process = null;
+    connected = false;
+    capabilities = {};
+    requestId = 0;
+    pendingRequests = new Map();
+    buffer = '';
+    /** Captures the last critical error from stderr for better error reporting */
+    lastStderrError = null;
+    constructor(command, args = [], cwd, env, requestTimeout = 30000) {
+        this.command = command;
+        this.args = args;
+        this.cwd = cwd;
+        this.env = env;
+        this.requestTimeout = requestTimeout;
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            // Track whether we've already settled the promise
+            let settled = false;
+            const safeReject = (error) => {
+                if (!settled) {
+                    settled = true;
+                    reject(error);
+                }
+            };
+            const safeResolve = () => {
+                if (!settled) {
+                    settled = true;
+                    resolve();
+                }
+            };
+            try {
+                // Merge environment variables
+                const processEnv = {
+                    ...process.env,
+                    ...this.env,
+                };
+                logger.debug(`Spawning stdio MCP server: ${this.command} ${this.args.join(' ')}`);
+                this.process = spawn(this.command, this.args, {
+                    cwd: this.cwd || process.cwd(),
+                    env: processEnv,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                    shell: true,
+                });
+                if (!this.process.stdout || !this.process.stdin) {
+                    safeReject(new Error('Failed to create stdio streams'));
+                    return;
+                }
+                // Handle stdout (responses from server)
+                this.process.stdout.on('data', (data) => {
+                    this.handleStdoutData(data);
+                });
+                // Handle stderr (logging from server)
+                this.process.stderr?.on('data', (data) => {
+                    const message = data.toString().trim();
+                    if (message) {
+                        // All MCP server stderr goes to debug level
+                        logger.debug(`[MCP Server stderr]: ${message}`);
+                        // Capture critical errors for better error reporting
+                        if (message.includes('EADDRINUSE')) {
+                            // Extract port number from error message if present
+                            const portMatch = message.match(/port[:\s]*(\d+)|:(\d+)/i);
+                            const port = portMatch?.[1] || portMatch?.[2] || 'unknown';
+                            this.lastStderrError = `Port ${port} is already in use. A previous MCP server process may still be running. ` +
+                                `Try killing the process using this port or wait for it to terminate.`;
+                        }
+                        else if (message.includes('ECONNREFUSED')) {
+                            this.lastStderrError = 'Connection refused. The target server may not be running.';
+                        }
+                        else if (message.includes('ETIMEDOUT') || message.includes('timeout')) {
+                            this.lastStderrError = 'Connection timed out while trying to reach the server.';
+                        }
+                        else if (message.includes('ENOTFOUND')) {
+                            this.lastStderrError = 'Server hostname not found. Please check the URL.';
+                        }
+                        else if (message.includes('Error:') && !this.lastStderrError) {
+                            // Capture generic errors if no specific error captured yet
+                            const errorMatch = message.match(/Error:\s*(.+?)(?:\n|$)/);
+                            if (errorMatch) {
+                                this.lastStderrError = errorMatch[1].trim();
+                            }
+                        }
+                    }
+                });
+                // Handle process exit
+                this.process.on('exit', (code, signal) => {
+                    logger.debug(`MCP server process exited with code ${code}, signal ${signal}`);
+                    this.connected = false;
+                    this.process = null;
+                    // Build error message - prefer captured stderr error over generic exit code
+                    let errorMessage;
+                    if (this.lastStderrError) {
+                        errorMessage = this.lastStderrError;
+                        // Log the detailed error at error level for visibility
+                        logger.error(`MCP server failed: ${errorMessage}`);
+                    }
+                    else if (code !== 0) {
+                        errorMessage = `Process exited with code ${code}`;
+                    }
+                    else if (signal) {
+                        errorMessage = `Process terminated by signal ${signal}`;
+                    }
+                    else {
+                        errorMessage = 'Process exited unexpectedly';
+                    }
+                    // Reject all pending requests with the detailed error
+                    for (const [id, pending] of this.pendingRequests) {
+                        pending.reject(new Error(errorMessage));
+                        this.pendingRequests.delete(id);
+                    }
+                    // Also reject the connect promise if it hasn't been resolved yet
+                    // This handles the case where the process exits before initialization completes
+                    safeReject(new Error(errorMessage));
+                });
+                this.process.on('error', (error) => {
+                    logger.error('MCP server process error:', error);
+                    this.connected = false;
+                    safeReject(error);
+                });
+                // Give the process a moment to start, then send initialize
+                setTimeout(async () => {
+                    // Check if process is still running before trying to initialize
+                    if (!this.process || settled) {
+                        return; // Process already exited or promise already settled
+                    }
+                    try {
+                        const result = await this.sendRequest('initialize', {
+                            protocolVersion: '2024-11-05',
+                            capabilities: {},
+                            clientInfo: { name: 'compass-cli', version: '1.0.0' },
+                        });
+                        if (result.result?.capabilities) {
+                            this.capabilities = {
+                                tools: !!result.result.capabilities.tools,
+                                resources: !!result.result.capabilities.resources,
+                                prompts: !!result.result.capabilities.prompts,
+                                logging: !!result.result.capabilities.logging,
+                            };
+                        }
+                        // Send initialized notification
+                        this.sendNotification('notifications/initialized', {});
+                        this.connected = true;
+                        logger.debug(`Stdio MCP server connected: ${this.command}`);
+                        safeResolve();
+                    }
+                    catch (initError) {
+                        safeReject(initError instanceof Error ? initError : new Error(String(initError)));
+                    }
+                }, 100);
+            }
+            catch (error) {
+                safeReject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    handleStdoutData(data) {
+        this.buffer += data.toString();
+        // Process complete lines (newline-delimited JSON)
+        let newlineIndex;
+        while ((newlineIndex = this.buffer.indexOf('\n')) !== -1) {
+            const line = this.buffer.substring(0, newlineIndex).trim();
+            this.buffer = this.buffer.substring(newlineIndex + 1);
+            if (line) {
+                try {
+                    const response = JSON.parse(line);
+                    this.handleResponse(response);
+                }
+                catch (parseError) {
+                    logger.debug(`Failed to parse MCP response: ${line}`);
+                }
+            }
+        }
+    }
+    handleResponse(response) {
+        if (response.id !== undefined && response.id !== null) {
+            const pending = this.pendingRequests.get(response.id);
+            if (pending) {
+                this.pendingRequests.delete(response.id);
+                pending.resolve(response);
+            }
+        }
+        // Notifications (no id) are logged but not handled
+    }
+    sendRequest(method, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.process?.stdin) {
+                reject(new Error('Process not running'));
+                return;
+            }
+            const id = ++this.requestId;
+            const request = {
+                jsonrpc: '2.0',
+                id,
+                method,
+                params,
+            };
+            this.pendingRequests.set(id, { resolve, reject });
+            const requestStr = JSON.stringify(request) + '\n';
+            this.process.stdin.write(requestStr, (error) => {
+                if (error) {
+                    this.pendingRequests.delete(id);
+                    reject(error);
+                }
+            });
+            // Timeout after configured duration (default 30 seconds, extended for npx)
+            setTimeout(() => {
+                if (this.pendingRequests.has(id)) {
+                    this.pendingRequests.delete(id);
+                    reject(new Error(`Request timeout: ${method}`));
+                }
+            }, this.requestTimeout);
+        });
+    }
+    sendNotification(method, params) {
+        if (!this.process?.stdin) {
+            return;
+        }
+        const notification = {
+            jsonrpc: '2.0',
+            method,
+            params,
+        };
+        const notificationStr = JSON.stringify(notification) + '\n';
+        this.process.stdin.write(notificationStr);
+    }
+    async close() {
+        this.connected = false;
+        if (this.process) {
+            // Send shutdown request
+            try {
+                this.sendNotification('notifications/cancelled', { reason: 'Client closing' });
+            }
+            catch {
+                // Ignore errors during shutdown
+            }
+            // Kill the process
+            this.process.kill('SIGTERM');
+            // Force kill after 2 seconds if still running
+            setTimeout(() => {
+                if (this.process && !this.process.killed) {
+                    this.process.kill('SIGKILL');
+                }
+            }, 2000);
+            this.process = null;
+        }
+        // Clear pending requests
+        for (const [id, pending] of this.pendingRequests) {
+            pending.reject(new Error('Client closed'));
+            this.pendingRequests.delete(id);
+        }
+    }
+    async listTools() {
+        if (!this.connected) {
+            return { tools: [] };
+        }
+        try {
+            const result = await this.sendRequest('tools/list', {});
+            return { tools: result.result?.tools || [] };
+        }
+        catch (error) {
+            logger.warn('Failed to list tools:', error);
+            return { tools: [] };
+        }
+    }
+    async listResources() {
+        if (!this.connected) {
+            return { resources: [] };
+        }
+        try {
+            const result = await this.sendRequest('resources/list', {});
+            return { resources: result.result?.resources || [] };
+        }
+        catch (error) {
+            logger.warn('Failed to list resources:', error);
+            return { resources: [] };
+        }
+    }
+    async listPrompts() {
+        if (!this.connected) {
+            return { prompts: [] };
+        }
+        try {
+            const result = await this.sendRequest('prompts/list', {});
+            return { prompts: result.result?.prompts || [] };
+        }
+        catch (error) {
+            logger.warn('Failed to list prompts:', error);
+            return { prompts: [] };
+        }
+    }
+    async callTool(params) {
+        if (!this.connected) {
+            return { success: false, error: 'Not connected' };
+        }
+        try {
+            const result = await this.sendRequest('tools/call', {
+                name: params.name,
+                arguments: params.arguments,
+            });
+            if (result.error) {
+                return { success: false, error: result.error.message };
+            }
+            return {
+                success: true,
+                content: result.result?.content || [],
+                isError: result.result?.isError,
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { success: false, error: msg };
+        }
+    }
+    async readResource(params) {
+        if (!this.connected) {
+            return { contents: [] };
+        }
+        try {
+            const result = await this.sendRequest('resources/read', { uri: params.uri });
+            return { contents: result.result?.contents || [] };
+        }
+        catch (error) {
+            logger.warn('Failed to read resource:', error);
+            return { contents: [] };
+        }
+    }
+    async getPrompt(params) {
+        if (!this.connected) {
+            return { messages: [] };
+        }
+        try {
+            const result = await this.sendRequest('prompts/get', params);
+            const messages = (result.result?.messages || []).map((msg) => ({
+                role: msg.role,
+                content: typeof msg.content === 'string' ? msg.content : msg.content.text || '',
+            }));
+            return { messages };
+        }
+        catch (error) {
+            logger.warn('Failed to get prompt:', error);
+            return { messages: [] };
+        }
+    }
+    getServerCapabilities() {
+        return this.connected ? this.capabilities : null;
+    }
+    isConnected() {
+        return this.connected && this.process !== null;
+    }
+}
+/**
+ * Creates and connects to an MCP server using the appropriate transport.
+ */
+export async function createTransportConnection(config, timeout) {
+    // Priority: function parameter > config.timeout > environment variable > default
+    const configTimeout = config.timeout;
+    const connectionTimeout = timeout || configTimeout || parseInt(process.env.MCP_TIMEOUT || '') || DEFAULT_MCP_TIMEOUT;
+    // Normalize config to infer missing type field
+    const normalizedConfig = normalizeServerConfig(config);
+    // Log if type was inferred
+    if (!config.type && normalizedConfig.type) {
+        logger.debug(`Inferred transport type '${normalizedConfig.type}' for server '${normalizedConfig.name}' (missing 'type' field in config)`);
+    }
+    if (isMCPHttpConfig(normalizedConfig)) {
+        return createHttpConnection(normalizedConfig, connectionTimeout);
+    }
+    if (isMCPSseConfig(normalizedConfig)) {
+        return createSseConnection(normalizedConfig, connectionTimeout);
+    }
+    if (isMCPStdioConfig(normalizedConfig)) {
+        return createStdioConnection(normalizedConfig, connectionTimeout);
+    }
+    const serverName = normalizedConfig?.name || 'unknown';
+    throw new Error(`Unknown transport type for server: ${serverName}. ` +
+        `Config must have 'type' field set to 'http', 'sse', or 'stdio', ` +
+        `or have 'url' (for sse) or 'command' (for stdio) fields to infer the type.`);
+}
+/**
+ * Creates an HTTP transport connection.
+ */
+async function createHttpConnection(config, timeout) {
+    logger.debug(`Creating HTTP connection to ${config.name} at ${config.url}`);
+    // Check for existing OAuth tokens and inject Authorization header
+    const oauthService = await getMCPOAuthService();
+    const authHeader = oauthService.getAuthHeader(config.name);
+    const headers = {
+        ...config.headers,
+        ...(authHeader ? { 'Authorization': authHeader } : {}),
+    };
+    logger.debug(`HTTP connection headers for ${config.name}: Authorization=${authHeader ? 'Bearer ***' + authHeader.slice(-8) : 'none'}`);
+    const client = new SimpleMCPClient(config.url, headers, timeout, config.name);
+    let status = 'connecting';
+    let error;
+    try {
+        await client.connect();
+        status = 'connected';
+        logger.info(`Connected to HTTP MCP server: ${config.name}`);
+        return {
+            client,
+            close: async () => {
+                await client.close();
+            },
+            status,
+        };
+    }
+    catch (err) {
+        // Rethrow AuthenticationRequiredError for server manager to handle OAuth flow
+        if (err instanceof AuthenticationRequiredError) {
+            throw err;
+        }
+        error = err instanceof Error ? err.message : String(err);
+        status = 'error';
+        logger.error(`Failed to connect to HTTP MCP server ${config.name}:`, err);
+        return {
+            client,
+            close: async () => {
+                try {
+                    await client.close();
+                }
+                catch {
+                    // Ignore close errors
+                }
+            },
+            status,
+            error,
+        };
+    }
+}
+/**
+ * Creates an SSE transport connection.
+ * Uses proper SSE protocol: GET for event stream, POST for sending messages.
+ */
+async function createSseConnection(config, timeout) {
+    logger.debug(`Creating SSE connection to ${config.name} at ${config.url}`);
+    const client = new SseMCPClient(config.url, config.headers, timeout);
+    let status = 'connecting';
+    let error;
+    try {
+        await client.connect();
+        status = 'connected';
+        logger.info(`Connected to SSE MCP server: ${config.name}`);
+        return {
+            client,
+            close: async () => {
+                await client.close();
+            },
+            status,
+        };
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+        status = 'error';
+        logger.error(`Failed to connect to SSE MCP server ${config.name}:`, err);
+        return {
+            client,
+            close: async () => {
+                try {
+                    await client.close();
+                }
+                catch {
+                    // Ignore close errors
+                }
+            },
+            status,
+            error,
+        };
+    }
+}
+/**
+ * Creates a stdio transport connection.
+ * Spawns a child process and communicates via JSON-RPC over stdin/stdout.
+ */
+async function createStdioConnection(config, timeout) {
+    logger.debug(`Creating stdio connection to ${config.name} with command: ${config.command}`);
+    // Use longer timeout for npx commands (they may need to download packages)
+    const effectiveTimeout = config.command === 'npx' ? Math.max(timeout, 60000) : timeout;
+    if (config.command === 'npx' && effectiveTimeout > timeout) {
+        logger.debug(`Using extended timeout (60s) for npx command - first run may download packages`);
+    }
+    const client = new StdioMCPClient(config.command, config.args || [], config.cwd, config.env, effectiveTimeout);
+    let status = 'connecting';
+    let error;
+    try {
+        await Promise.race([
+            client.connect(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Connection timeout')), effectiveTimeout)),
+        ]);
+        status = 'connected';
+        logger.debug(`Connected to stdio MCP server: ${config.name}`);
+        return {
+            client,
+            close: async () => {
+                await client.close();
+            },
+            status,
+        };
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+        status = 'error';
+        logger.error(`Failed to connect to stdio MCP server ${config.name}:`, err);
+        return {
+            client,
+            close: async () => {
+                try {
+                    await client.close();
+                }
+                catch {
+                    // Ignore close errors
+                }
+            },
+            status,
+            error,
+        };
+    }
+}
+/**
+ * Fetches available tools from an MCP server.
+ */
+export async function fetchServerTools(client) {
+    try {
+        const result = await client.listTools();
+        return result.tools || [];
+    }
+    catch (error) {
+        logger.error('Failed to fetch MCP tools:', error);
+        return [];
+    }
+}
+/**
+ * Fetches available resources from an MCP server.
+ */
+export async function fetchServerResources(client) {
+    try {
+        const result = await client.listResources();
+        return result.resources || [];
+    }
+    catch (error) {
+        logger.error('Failed to fetch MCP resources:', error);
+        return [];
+    }
+}
+/**
+ * Fetches available prompts from an MCP server.
+ */
+export async function fetchServerPrompts(client) {
+    try {
+        const result = await client.listPrompts();
+        return result.prompts || [];
+    }
+    catch (error) {
+        logger.error('Failed to fetch MCP prompts:', error);
+        return [];
+    }
+}
+/**
+ * Fetches server capabilities.
+ */
+export async function fetchServerCapabilities(client) {
+    try {
+        const capabilities = client.getServerCapabilities();
+        return capabilities || {};
+    }
+    catch (error) {
+        logger.error('Failed to fetch MCP server capabilities:', error);
+        return {};
+    }
+}
+/**
+ * Calls a tool on an MCP server.
+ */
+export async function callMCPTool(client, toolName, args) {
+    try {
+        return await client.callTool({ name: toolName, arguments: args });
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to call MCP tool ${toolName}:`, error);
+        return { success: false, error: errorMessage };
+    }
+}
+/**
+ * Reads a resource from an MCP server.
+ */
+export async function readMCPResource(client, uri) {
+    try {
+        const result = await client.readResource({ uri });
+        return { content: result.contents || [] };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to read MCP resource ${uri}:`, error);
+        return { content: [], error: errorMessage };
+    }
+}
+/**
+ * Gets a prompt from an MCP server.
+ */
+export async function getMCPPrompt(client, name, args) {
+    try {
+        const result = await client.getPrompt({ name, arguments: args });
+        return { messages: result.messages || [] };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to get MCP prompt ${name}:`, error);
+        return { messages: [], error: errorMessage };
+    }
+}
+//# sourceMappingURL=mcp-transport.js.map