@syrin/cli 1.3.0

package/dist/runtime/mcp/client/process.js

@@ -0,0 +1,82 @@
+/**
+ * Process spawning utilities for MCP servers.
+ */
+import * as childProcess from 'child_process';
+import { log } from '../../../utils/logger.js';
+/**
+ * Check if a command contains shell operators that require shell execution.
+ * We only detect patterns that absolutely require a shell, avoiding false positives.
+ * Essential operators: &&, ||, |, ;, $, $(, `
+ */
+export function requiresShellExecution(command) {
+    return (/\s+&&\s+/.test(command) || // Logical AND (e.g., "cmd1 && cmd2")
+        /\s+\|\|\s+/.test(command) || // Logical OR (e.g., "cmd1 || cmd2")
+        /\s+\|\s+/.test(command) || // Pipe (e.g., "cmd1 | cmd2")
+        /\s+;\s+/.test(command) || // Command separator (e.g., "cmd1; cmd2")
+        /\$\{/.test(command) || // Variable expansion ${VAR}
+        /\$\(/.test(command) || // Command substitution $(command)
+        /\$\w+/.test(command) || // Variable reference $VAR
+        /`[^`]*`/.test(command) // Command substitution with backticks
+    );
+}
+/**
+ * Parse a command into executable and arguments.
+ * Handles shell operators by wrapping in shell execution.
+ */
+export function parseCommand(command) {
+    const needsShell = requiresShellExecution(command);
+    if (needsShell) {
+        // Command contains shell operators - run through shell
+        return {
+            executable: process.env.SHELL || '/bin/sh',
+            args: ['-c', command],
+        };
+    }
+    // Simple command - split and execute directly
+    const parts = command.split(/\s+/);
+    return {
+        executable: parts[0],
+        args: parts.slice(1),
+    };
+}
+/**
+ * Set up log capture for a child process.
+ * Captures stdout and stderr, formatting them appropriately.
+ */
+export function setupProcessLogCapture(process) {
+    // Capture stdout logs
+    process.stdout?.on('data', (data) => {
+        const message = data.toString().trim();
+        if (message) {
+            log.plain(`[Server] ${message}`);
+        }
+    });
+    // Capture stderr logs
+    process.stderr?.on('data', (data) => {
+        const message = data.toString().trim();
+        if (message) {
+            // Many tools (like Python/Uvicorn) write INFO logs to stderr, which is normal
+            // Only prefix with [Server Error] if it actually looks like an error
+            const isError = /ERROR|CRITICAL|FATAL|Exception|Traceback|Error:/i.test(message);
+            const prefix = isError ? '[Server Error]' : '[Server]';
+            if (isError) {
+                log.error(`${prefix} ${message}`);
+            }
+            else {
+                log.plain(`${prefix} ${message}`);
+            }
+        }
+    });
+}
+/**
+ * Spawn a process with proper configuration.
+ */
+export function spawnProcess(executable, args, options) {
+    return childProcess.spawn(executable, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: options?.env ?? process.env,
+        cwd: options?.cwd ?? process.cwd(),
+        shell: false,
+    });
+}
+//# sourceMappingURL=process.js.map

package/dist/runtime/mcp/connection.d.ts

@@ -0,0 +1,63 @@
+/**
+ * MCP connection utilities.
+ * Provides utilities for connecting to MCP servers via HTTP and stdio transports.
+ * This module is reusable for both testing and establishing MCP connections.
+ * Uses the official MCP SDK for proper protocol handling.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { MCPConnectionResult, MCPConnectionOptions } from './types.js';
+/**
+ * Get a connected MCP client that stays open for operations.
+ * Use this when you need to perform multiple operations with the same connection.
+ * Remember to call close() on the transport when done.
+ *
+ * @param mcpUrl - The MCP server URL to connect to
+ * @param timeout - Connection timeout in milliseconds (default: 5000)
+ * @returns Connected client and transport instances
+ */
+export declare function getConnectedClient(mcpUrl: string, headers?: Record<string, string>, timeout?: number): Promise<{
+    client: Client;
+    transport: StreamableHTTPClientTransport;
+}>;
+/**
+ * Connect to an MCP server via HTTP transport using the official MCP SDK.
+ * This properly handles the SSE protocol and session requirements.
+ *
+ * @param mcpUrl - The MCP server URL to connect to
+ * @param timeout - Connection timeout in milliseconds (default: 5000)
+ * @returns Connection result with connection details
+ */
+export declare function connectHTTP(mcpUrl: string, headers?: Record<string, string>, timeout?: number): Promise<MCPConnectionResult>;
+/**
+ * Get a connected MCP client via stdio transport that stays open for operations.
+ * Use this when you need to perform multiple operations with the same connection.
+ * Remember to call close() on the transport when done.
+ *
+ * @param command - The command to execute (e.g., "python3 server.py")
+ * @param timeout - Connection timeout in milliseconds (default: 10000)
+ * @returns Connected client and transport instances
+ */
+export declare function getConnectedStdioClient(command: string, env?: Record<string, string>, timeout?: number): Promise<{
+    client: Client;
+    transport: StdioClientTransport;
+}>;
+/**
+ * Connect to an MCP server via stdio transport using the official MCP SDK.
+ * This properly handles the stdio protocol and initialization handshake.
+ *
+ * @param command - The command to execute (e.g., "python3 server.py")
+ * @param timeout - Connection timeout in milliseconds (default: 5000)
+ * @returns Connection result
+ */
+export declare function connectStdio(command: string, env?: Record<string, string>, timeout?: number): Promise<MCPConnectionResult>;
+/**
+ * Connect to an MCP server based on transport type.
+ * This is the main entry point for establishing MCP connections.
+ *
+ * @param options - Connection options including transport type and connection details
+ * @returns Connection result
+ */
+export declare function connectMCP(options: MCPConnectionOptions): Promise<MCPConnectionResult>;
+//# sourceMappingURL=connection.d.ts.map

package/dist/runtime/mcp/connection.js

@@ -0,0 +1,449 @@
+/**
+ * MCP connection utilities.
+ * Provides utilities for connecting to MCP servers via HTTP and stdio transports.
+ * This module is reusable for both testing and establishing MCP connections.
+ * Uses the official MCP SDK for proper protocol handling.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { v4 as uuidv4 } from 'uuid';
+import { ConfigurationError } from '../../utils/errors.js';
+import { getCurrentVersion } from '../../utils/version-checker.js';
+/**
+ * Get a connected MCP client that stays open for operations.
+ * Use this when you need to perform multiple operations with the same connection.
+ * Remember to call close() on the transport when done.
+ *
+ * @param mcpUrl - The MCP server URL to connect to
+ * @param timeout - Connection timeout in milliseconds (default: 5000)
+ * @returns Connected client and transport instances
+ */
+export async function getConnectedClient(mcpUrl, headers, timeout = 10000) {
+    // Parse URL
+    const parsedUrl = new URL(mcpUrl);
+    // Create MCP client
+    const client = new Client({
+        name: 'syrin',
+        version: getCurrentVersion(),
+    }, {
+        capabilities: {},
+    });
+    // Prepare request init with headers if provided
+    const requestInit = headers
+        ? {
+            headers,
+        }
+        : undefined;
+    // Create HTTP transport using StreamableHTTPClientTransport
+    // This properly handles SSE protocol and session requirements
+    const transport = new StreamableHTTPClientTransport(parsedUrl, {
+        requestInit,
+    });
+    // Set up error handler
+    client.onerror = () => {
+        // Error handler - errors are logged but we'll catch them in try-catch
+    };
+    // Try to connect with timeout
+    const connectionPromise = client.connect(transport);
+    // Create a timeout promise
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new Error(`Connection timeout after ${timeout}ms`));
+        }, timeout);
+    });
+    // Race between connection and timeout
+    await Promise.race([connectionPromise, timeoutPromise]);
+    return { client, transport };
+}
+/**
+ * Connect to an MCP server via HTTP transport using the official MCP SDK.
+ * This properly handles the SSE protocol and session requirements.
+ *
+ * @param mcpUrl - The MCP server URL to connect to
+ * @param timeout - Connection timeout in milliseconds (default: 5000)
+ * @returns Connection result with connection details
+ */
+export async function connectHTTP(mcpUrl, headers, timeout = 5000) {
+    let client = null;
+    let transport = null;
+    try {
+        // Parse URL
+        const parsedUrl = new URL(mcpUrl);
+        const details = {
+            mcpUrl,
+        };
+        // Create MCP client
+        client = new Client({
+            name: 'syrin',
+            version: getCurrentVersion(),
+        }, {
+            capabilities: {},
+        });
+        // Prepare request init with headers if provided
+        const requestInit = headers
+            ? {
+                headers,
+            }
+            : undefined;
+        // Create HTTP transport using StreamableHTTPClientTransport
+        // This properly handles SSE protocol and session requirements
+        transport = new StreamableHTTPClientTransport(parsedUrl, {
+            requestInit,
+        });
+        // Set up error handler
+        client.onerror = () => {
+            // Error handler - errors are logged but we'll catch them in try-catch
+        };
+        // Try to connect with timeout
+        const connectionPromise = client.connect(transport);
+        // Create a timeout promise
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Connection timeout after ${timeout}ms`));
+            }, timeout);
+        });
+        // Race between connection and timeout
+        try {
+            await Promise.race([connectionPromise, timeoutPromise]);
+        }
+        catch (error) {
+            // Check if it's a timeout error
+            if (error instanceof Error && error.message.includes('timeout')) {
+                return {
+                    success: false,
+                    transport: 'http',
+                    error: error.message,
+                    details,
+                };
+            }
+            // Re-throw to handle connection errors below
+            throw error;
+        }
+        // Connection successful - get server capabilities and protocol version
+        const serverCapabilities = client.getServerCapabilities();
+        if (serverCapabilities) {
+            // Convert capabilities to a simpler format for display
+            // ServerCapabilities is an object where keys are capability names
+            // and values are either objects with capability details or empty objects
+            const capabilities = {};
+            // Extract capability names (keys of the capabilities object)
+            for (const [key, value] of Object.entries(serverCapabilities)) {
+                capabilities[key] = value;
+            }
+            details.capabilities = capabilities;
+        }
+        // Get protocol version from the client
+        // The protocol version is negotiated during initialization
+        // The SDK uses the latest supported version by default
+        details.protocolVersion = '2024-11-05'; // Protocol version used in initialize request
+        // Get session ID if available
+        if (transport.sessionId) {
+            details.sessionId = transport.sessionId;
+            details.metadata = {
+                sessionId: transport.sessionId,
+            };
+        }
+        // Document the initialize handshake that happened
+        // The SDK automatically sends an initialize request during client.connect()
+        // This request includes client info and capabilities
+        details.initializeRequest = {
+            method: 'POST',
+            url: mcpUrl,
+            headers: {
+                Accept: 'text/event-stream',
+                'Content-Type': 'application/json',
+                ...(transport.sessionId
+                    ? { 'mcp-session-id': transport.sessionId }
+                    : {}),
+            },
+            body: {
+                jsonrpc: '2.0',
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2024-11-05',
+                    capabilities: {},
+                    clientInfo: {
+                        name: 'syrin',
+                        version: getCurrentVersion(),
+                    },
+                },
+            },
+        };
+        // The initialize response contains server capabilities
+        // This is how we obtained the capabilities - from the initialize response
+        details.initializeResponse = {
+            statusCode: 200,
+            body: {
+                jsonrpc: '2.0',
+                result: {
+                    protocolVersion: details.protocolVersion,
+                    capabilities: serverCapabilities || {},
+                    serverInfo: {
+                        name: 'MCP Server',
+                    },
+                },
+            },
+        };
+        // Clean up - disconnect gracefully
+        try {
+            await transport.close();
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+        return {
+            success: true,
+            transport: 'http',
+            details,
+        };
+    }
+    catch (error) {
+        // Clean up on error
+        try {
+            if (transport) {
+                await transport.close();
+            }
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        // Parse error message
+        let errorMessage = 'Unknown error';
+        if (error instanceof Error) {
+            errorMessage = error.message;
+            // Check for common connection errors
+            if (errorMessage.includes('ECONNREFUSED') ||
+                errorMessage.includes('fetch failed') ||
+                errorMessage.includes('NetworkError')) {
+                errorMessage = `Cannot connect to MCP server at ${mcpUrl}. Is the server running?`;
+            }
+            else if (errorMessage.includes('401') ||
+                errorMessage.includes('Unauthorized')) {
+                errorMessage =
+                    'Authentication required. The server rejected the connection.';
+            }
+            else if (errorMessage.includes('404')) {
+                errorMessage = 'MCP endpoint not found. Please check the URL.';
+            }
+        }
+        return {
+            success: false,
+            transport: 'http',
+            error: errorMessage,
+            details: {
+                mcpUrl,
+                discoveryUrl: `${new URL(mcpUrl).protocol}//${new URL(mcpUrl).host}/.well-known/mcp`,
+            },
+        };
+    }
+}
+/**
+ * Get a connected MCP client via stdio transport that stays open for operations.
+ * Use this when you need to perform multiple operations with the same connection.
+ * Remember to call close() on the transport when done.
+ *
+ * @param command - The command to execute (e.g., "python3 server.py")
+ * @param timeout - Connection timeout in milliseconds (default: 10000)
+ * @returns Connected client and transport instances
+ */
+export async function getConnectedStdioClient(command, env, timeout = 10000) {
+    // Split command into executable and arguments
+    const parts = command.trim().split(/\s+/);
+    const executable = parts[0];
+    const args = parts.slice(1);
+    if (!executable) {
+        throw new Error('Command is empty');
+    }
+    // Create MCP client
+    const client = new Client({
+        name: 'syrin',
+        version: getCurrentVersion(),
+    }, {
+        capabilities: {},
+    });
+    // Merge provided env vars with process.env (provided vars take precedence)
+    // Filter out undefined values from process.env
+    const processEnvFiltered = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+            processEnvFiltered[key] = value;
+        }
+    }
+    const mergedEnv = env
+        ? { ...processEnvFiltered, ...env }
+        : processEnvFiltered;
+    // Create stdio transport
+    const transport = new StdioClientTransport({
+        command: executable,
+        args,
+        env: mergedEnv,
+    });
+    // Set up error handler
+    client.onerror = () => {
+        // Error handler - errors are logged but we'll catch them in try-catch
+    };
+    // Try to connect with timeout
+    const connectionPromise = client.connect(transport);
+    // Create a timeout promise
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new Error(`Connection timeout after ${timeout}ms`));
+        }, timeout);
+    });
+    // Race between connection and timeout
+    await Promise.race([connectionPromise, timeoutPromise]);
+    return { client, transport };
+}
+/**
+ * Connect to an MCP server via stdio transport using the official MCP SDK.
+ * This properly handles the stdio protocol and initialization handshake.
+ *
+ * @param command - The command to execute (e.g., "python3 server.py")
+ * @param timeout - Connection timeout in milliseconds (default: 5000)
+ * @returns Connection result
+ */
+export async function connectStdio(command, env, timeout = 5000) {
+    let transport = null;
+    try {
+        // Split command into executable and arguments
+        const parts = command.trim().split(/\s+/);
+        const executable = parts[0];
+        const args = parts.slice(1);
+        if (!executable) {
+            return {
+                success: false,
+                transport: 'stdio',
+                error: 'Command is empty',
+            };
+        }
+        // Create MCP client
+        const client = new Client({
+            name: 'syrin',
+            version: getCurrentVersion(),
+        }, {
+            capabilities: {},
+        });
+        // Merge provided env vars with process.env (provided vars take precedence)
+        // Filter out undefined values from process.env
+        const processEnvFiltered = {};
+        for (const [key, value] of Object.entries(process.env)) {
+            if (value !== undefined) {
+                processEnvFiltered[key] = value;
+            }
+        }
+        const mergedEnv = env
+            ? { ...processEnvFiltered, ...env }
+            : processEnvFiltered;
+        // Create stdio transport
+        transport = new StdioClientTransport({
+            command: executable,
+            args,
+            env: mergedEnv,
+        });
+        // Set up error handler
+        client.onerror = () => {
+            // Error handler - errors are logged but we'll catch them in try-catch
+        };
+        // Try to connect with timeout
+        const connectionPromise = client.connect(transport);
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Connection timeout after ${timeout}ms`));
+            }, timeout);
+        });
+        await Promise.race([connectionPromise, timeoutPromise]);
+        // Get server capabilities and session info
+        const serverCapabilities = client.getServerCapabilities() || {};
+        const protocolVersion = '2024-11-05'; // MCP protocol version
+        const sessionId = uuidv4();
+        const details = {
+            command,
+            protocolVersion,
+            sessionId,
+            capabilities: serverCapabilities,
+            client: client,
+            transport: transport,
+        };
+        // Close the connection after gathering info (for testing)
+        try {
+            await transport.close();
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+        return {
+            success: true,
+            transport: 'stdio',
+            details,
+        };
+    }
+    catch (error) {
+        // Clean up on error
+        try {
+            if (transport) {
+                await transport.close();
+            }
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        // Parse error message
+        let errorMessage = 'Unknown error';
+        if (error instanceof Error) {
+            errorMessage = error.message;
+            // Check for common connection errors
+            if (errorMessage.includes('ENOENT') ||
+                errorMessage.includes('not found')) {
+                errorMessage = `Command "${command.split(/\s+/)[0]}" not found in PATH. Is the command installed?`;
+            }
+            else if (errorMessage.includes('EACCES') ||
+                errorMessage.includes('permission denied')) {
+                errorMessage = 'Permission denied. Check if the command is executable.';
+            }
+            else if (errorMessage.includes('timeout')) {
+                errorMessage = `Connection timeout. The MCP server may not be responding.`;
+            }
+        }
+        return {
+            success: false,
+            transport: 'stdio',
+            error: errorMessage,
+            details: {
+                command,
+            },
+        };
+    }
+}
+/**
+ * Connect to an MCP server based on transport type.
+ * This is the main entry point for establishing MCP connections.
+ *
+ * @param options - Connection options including transport type and connection details
+ * @returns Connection result
+ */
+export async function connectMCP(options) {
+    const { transport, url, command, timeout = 5000 } = options;
+    if (transport === 'http') {
+        if (!url) {
+            throw new ConfigurationError('MCP URL is required for HTTP transport');
+        }
+        // Extract headers from options if available
+        const headers = 'headers' in options && options.headers
+            ? options.headers
+            : undefined;
+        return connectHTTP(url, headers, timeout);
+    }
+    if (transport === 'stdio') {
+        if (!command) {
+            throw new ConfigurationError('Command is required for stdio transport');
+        }
+        // Extract env from options if available
+        const env = 'env' in options && options.env
+            ? options.env
+            : undefined;
+        return connectStdio(command, env, timeout);
+    }
+    throw new ConfigurationError(`Unsupported transport type: ${transport}`);
+}
+//# sourceMappingURL=connection.js.map

package/dist/runtime/mcp/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP runtime utilities.
+ * Exports MCP connection, listing, client manager, and related utilities.
+ */
+export * from './types.js';
+export * from './connection.js';
+export * from './list.js';
+export * from './client/manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/mcp/index.js

@@ -0,0 +1,9 @@
+/**
+ * MCP runtime utilities.
+ * Exports MCP connection, listing, client manager, and related utilities.
+ */
+export * from './types.js';
+export * from './connection.js';
+export * from './list.js';
+export * from './client/manager.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/mcp/list.d.ts

@@ -0,0 +1,50 @@
+/**
+ * MCP listing utilities.
+ * Provides functions to list tools, resources, and prompts from MCP servers.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+/**
+ * List all tools available from the MCP server.
+ */
+export declare function listTools(client: Client): Promise<{
+    tools: Array<{
+        name: string;
+        title?: string;
+        description?: string;
+        inputSchema?: unknown;
+        outputSchema?: unknown;
+    }>;
+}>;
+/**
+ * List all resources available from the MCP server.
+ */
+export declare function listResources(client: Client): Promise<{
+    resources: Array<{
+        uri: string;
+        name?: string;
+        description?: string;
+        mimeType?: string;
+    }>;
+}>;
+/**
+ * List all prompts available from the MCP server.
+ */
+export declare function listPrompts(client: Client): Promise<{
+    prompts: Array<{
+        name: string;
+        title?: string;
+        description?: string;
+        arguments?: Array<{
+            name: string;
+            description?: string;
+            required?: boolean;
+        }>;
+    }>;
+}>;
+/**
+ * Close the MCP transport connection.
+ */
+export declare function closeConnection(transport: StreamableHTTPClientTransport | StdioClientTransport): Promise<void>;
+//# sourceMappingURL=list.d.ts.map