@gguf/coder 0.3.0 → 0.3.1

package/source/mcp/transport-factory.spec.ts

@@ -0,0 +1,406 @@
+import test from 'ava';
+import type {MCPServer, MCPTransportType} from '../types/mcp';
+import {TransportFactory} from './transport-factory';
+
+console.log(`\ntransport-factory.spec.ts`);
+
+// ============================================================================
+// Tests for TransportFactory
+// ============================================================================
+
+test('TransportFactory.createTransport: creates stdio transport', t => {
+	const server: MCPServer = {
+		name: 'test-stdio',
+		transport: 'stdio',
+		command: 'node',
+		args: ['server.js'],
+		env: {NODE_ENV: 'test'},
+	};
+
+	const transport = TransportFactory.createTransport(server);
+
+	t.truthy(transport);
+});
+
+test('TransportFactory.createTransport: creates websocket transport', t => {
+	const server: MCPServer = {
+		name: 'test-websocket',
+		transport: 'websocket',
+		url: 'ws://localhost:3000/mcp',
+	};
+
+	const transport = TransportFactory.createTransport(server);
+
+	t.truthy(transport);
+});
+
+test('TransportFactory.createTransport: creates http transport', t => {
+	const server: MCPServer = {
+		name: 'test-http',
+		transport: 'http',
+		url: 'https://example.com/mcp',
+	};
+
+	const transport = TransportFactory.createTransport(server);
+
+	t.truthy(transport);
+});
+
+test('TransportFactory.createTransport: throws error for unsupported transport', t => {
+	const server = {
+		name: 'test-unsupported',
+		transport: 'unsupported' as MCPTransportType,
+	};
+
+	t.throws(
+		() => {
+			TransportFactory.createTransport(server);
+		},
+		{
+			message: /Unsupported transport type: unsupported/,
+		},
+	);
+});
+
+test('TransportFactory.createTransport: throws error for stdio missing command', t => {
+	const server: MCPServer = {
+		name: 'test-stdio-no-command',
+		transport: 'stdio',
+	};
+
+	t.throws(
+		() => {
+			TransportFactory.createTransport(server);
+		},
+		{
+			message: /missing command for stdio transport/,
+		},
+	);
+});
+
+test('TransportFactory.createTransport: throws error for websocket missing URL', t => {
+	const server: MCPServer = {
+		name: 'test-websocket-no-url',
+		transport: 'websocket',
+	};
+
+	t.throws(
+		() => {
+			TransportFactory.createTransport(server);
+		},
+		{
+			message: /missing URL for websocket transport/,
+		},
+	);
+});
+
+test('TransportFactory.createTransport: throws error for http missing URL', t => {
+	const server: MCPServer = {
+		name: 'test-http-no-url',
+		transport: 'http',
+	};
+
+	t.throws(
+		() => {
+			TransportFactory.createTransport(server);
+		},
+		{
+			message: /missing URL for http transport/,
+		},
+	);
+});
+
+test('TransportFactory.createTransport: throws error for invalid websocket URL', t => {
+	const server: MCPServer = {
+		name: 'test-websocket-invalid-url',
+		transport: 'websocket',
+		url: 'http://example.com/mcp', // Should be ws:// or wss://
+	};
+
+	t.throws(
+		() => {
+			TransportFactory.createTransport(server);
+		},
+		{
+			message: /Invalid WebSocket URL protocol/,
+		},
+	);
+});
+
+test('TransportFactory.createTransport: throws error for invalid http URL', t => {
+	const server: MCPServer = {
+		name: 'test-http-invalid-url',
+		transport: 'http',
+		url: 'ws://example.com/mcp', // Should be http:// or https://
+	};
+
+	t.throws(
+		() => {
+			TransportFactory.createTransport(server);
+		},
+		{
+			message: /Invalid HTTP URL protocol/,
+		},
+	);
+});
+
+// ============================================================================
+// Tests for TransportFactory.validateServerConfig
+// ============================================================================
+
+test('TransportFactory.validateServerConfig: validates stdio config', t => {
+	const server: MCPServer = {
+		name: 'test-stdio',
+		transport: 'stdio',
+		command: 'node',
+		args: ['server.js'],
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	t.true(result.valid);
+	t.is(result.errors.length, 0);
+});
+
+test('TransportFactory.validateServerConfig: validates websocket config', t => {
+	const server: MCPServer = {
+		name: 'test-websocket',
+		transport: 'websocket',
+		url: 'wss://example.com/mcp',
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	t.true(result.valid);
+	t.is(result.errors.length, 0);
+});
+
+test('TransportFactory.validateServerConfig: validates http config', t => {
+	const server: MCPServer = {
+		name: 'test-http',
+		transport: 'http',
+		url: 'https://example.com/mcp',
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	t.true(result.valid);
+	t.is(result.errors.length, 0);
+});
+
+test('TransportFactory.validateServerConfig: detects invalid stdio config', t => {
+	const server: MCPServer = {
+		name: 'test-stdio-invalid',
+		transport: 'stdio',
+		// Missing command
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	t.false(result.valid);
+	t.true(
+		result.errors.some((error: string) =>
+			error.includes('stdio transport requires a command'),
+		),
+	);
+});
+
+test('TransportFactory.validateServerConfig: detects invalid websocket config', t => {
+	const server: MCPServer = {
+		name: 'test-websocket-invalid',
+		transport: 'websocket',
+		url: 'http://example.com/mcp', // Invalid protocol
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	t.false(result.valid);
+	t.true(
+		result.errors.some((error: string) =>
+			error.includes('websocket URL must use ws:// or wss:// protocol'),
+		),
+	);
+});
+
+test('TransportFactory.validateServerConfig: detects invalid http config', t => {
+	const server: MCPServer = {
+		name: 'test-http-invalid',
+		transport: 'http',
+		url: 'ws://example.com/mcp', // Invalid protocol
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	t.false(result.valid);
+	t.true(
+		result.errors.some((error: string) =>
+			error.includes('http URL must use http:// or https:// protocol'),
+		),
+	);
+});
+
+// ============================================================================
+// Tests for TransportFactory.getTransportTips
+// ============================================================================
+
+test('TransportFactory.getTransportTips: returns stdio tips', t => {
+	const tips = TransportFactory.getTransportTips('stdio');
+
+	t.true(tips.length > 0);
+	t.true(tips.some((tip: string) => tip.includes('Stdio transport')));
+});
+
+test('TransportFactory.getTransportTips: returns websocket tips', t => {
+	const tips = TransportFactory.getTransportTips('websocket');
+
+	t.true(tips.length > 0);
+	t.true(tips.some((tip: string) => tip.includes('WebSocket')));
+});
+
+test('TransportFactory.getTransportTips: returns http tips', t => {
+	const tips = TransportFactory.getTransportTips('http');
+
+	t.true(tips.length > 0);
+	t.true(tips.some((tip: string) => tip.includes('HTTP')));
+});
+
+test('TransportFactory.getTransportTips: handles unknown transport', t => {
+	const tips = TransportFactory.getTransportTips('unknown' as MCPTransportType);
+
+	t.is(tips.length, 1);
+	t.is(tips[0], 'Unknown transport type');
+});
+
+// ============================================================================
+// Tests for Header Warning Functionality (New Feature)
+// ============================================================================
+
+test('TransportFactory.createTransport: warns about auth config for websocket transport', t => {
+	// Test that transport is created despite auth config warning
+	// Note: Warnings are now logged via the logging system (logWarning),
+	// not console.warn directly
+	const server: MCPServer = {
+		name: 'test-websocket-with-auth',
+		transport: 'websocket',
+		url: 'ws://localhost:3000/mcp',
+		auth: {
+			type: 'bearer',
+			token: 'token123',
+		},
+	};
+
+	const transport = TransportFactory.createTransport(server);
+
+	// Transport should still be created even with unsupported auth config
+	t.truthy(transport);
+	// Warning is logged via logWarning() to the logging system
+});
+
+test('TransportFactory.createTransport: creates http transport with headers', t => {
+	const server: MCPServer = {
+		name: 'test-http-with-headers',
+		transport: 'http',
+		url: 'https://example.com/mcp',
+		headers: {
+			Authorization: 'Bearer token123',
+		},
+	};
+
+	const transport = TransportFactory.createTransport(server);
+
+	t.truthy(transport);
+});
+
+test('TransportFactory.createTransport: warns about auth config for http transport', t => {
+	// Test that transport is created despite auth config warning
+	// Note: Warnings are now logged via the logging system (logWarning),
+	// not console.warn directly
+	const server: MCPServer = {
+		name: 'test-http-with-auth',
+		transport: 'http',
+		url: 'https://example.com/mcp',
+		auth: {
+			type: 'bearer',
+			token: 'token123',
+		},
+	};
+
+	const transport = TransportFactory.createTransport(server);
+
+	// Transport should still be created even with unsupported auth config
+	t.truthy(transport);
+	// Warning is logged via logWarning() to the logging system
+});
+
+test('TransportFactory.validateServerConfig: validates http config with headers', t => {
+	const server: MCPServer = {
+		name: 'test-http-with-headers-validation',
+		transport: 'http',
+		url: 'https://example.com/mcp',
+		headers: {
+			'Custom-Header': 'value',
+		},
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	t.true(result.valid);
+	t.is(result.errors.length, 0);
+});
+
+// ============================================================================
+// Tests for Command Existence Validation (Issue #148 Fix)
+// ============================================================================
+
+test('TransportFactory.validateServerConfig: detects missing command', t => {
+	const server: MCPServer = {
+		name: 'test-stdio-missing-command',
+		transport: 'stdio',
+		command: 'this-command-definitely-does-not-exist-xyz123',
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	t.false(result.valid);
+	t.true(
+		result.errors.some((error: string) =>
+			error.includes("Command 'this-command-definitely-does-not-exist-xyz123' not found"),
+		),
+	);
+});
+
+test('TransportFactory.validateServerConfig: returns uvx-specific installation hint', t => {
+	const server: MCPServer = {
+		name: 'test-stdio-uvx-hint',
+		transport: 'stdio',
+		command: 'uvx',
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	// Note: uvx may or may not be installed in different test environments
+	// If uvx is installed and valid, the test passes
+	// If uvx is not installed, check for uvx-specific installation instructions
+	if (result.valid) {
+		t.pass('uvx is installed in this environment');
+	} else {
+		t.true(result.errors.length > 0);
+		t.true(result.errors.some((error: string) => error.includes("'uv' Python package manager")));
+		t.true(result.errors.some((error: string) => error.includes('astral.sh/uv/install.sh')));
+	}
+});
+
+test('TransportFactory.validateServerConfig: validates existing command (node)', t => {
+	// node should exist since we're running tests with it
+	const server: MCPServer = {
+		name: 'test-stdio-node-exists',
+		transport: 'stdio',
+		command: 'node',
+		args: ['--version'],
+	};
+
+	const result = TransportFactory.validateServerConfig(server);
+
+	t.true(result.valid);
+	t.is(result.errors.length, 0);
+});

package/source/mcp/transport-factory.ts

@@ -0,0 +1,312 @@
+import {execFileSync} from 'child_process';
+import {accessSync, constants as fsConstants} from 'fs';
+import {logWarning} from '@/utils/message-queue';
+import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';
+import {StreamableHTTPClientTransport} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import {WebSocketClientTransport} from '@modelcontextprotocol/sdk/client/websocket.js';
+import type {MCPServer, MCPTransportType} from '../types/mcp.js';
+
+/**
+ * Installation instructions for common MCP server dependencies
+ */
+const COMMAND_INSTALL_HINTS: Record<string, string> = {
+	uvx: `'uvx' is part of the 'uv' Python package manager.
+
+Install uv:
+  • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
+  • Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+  • pip: pip install uv
+  • Homebrew: brew install uv
+
+After installation, restart your terminal and try again.`,
+	npx: `'npx' is part of Node.js.
+
+Install Node.js from: https://nodejs.org/
+Or use a version manager like nvm, fnm, or volta.`,
+	node: `'node' is not installed.
+
+Install Node.js from: https://nodejs.org/
+Or use a version manager like nvm, fnm, or volta.`,
+	python: `'python' is not installed.
+
+Install Python from: https://python.org/downloads/
+Or use a version manager like pyenv.`,
+	python3: `'python3' is not installed.
+
+Install Python from: https://python.org/downloads/
+Or use a version manager like pyenv.`,
+};
+
+/**
+ * Checks if a command exists in the system PATH or as an executable path.
+ * Uses execFileSync with separate arguments to prevent shell injection.
+ * Handles both PATH lookups and direct path references (./bin/cmd, /usr/bin/cmd).
+ */
+function commandExists(command: string): boolean {
+	// Check if command is a path (contains path separators)
+	if (command.includes('/') || command.includes('\\')) {
+		try {
+			// Check if file exists and is executable
+			accessSync(command, fsConstants.X_OK);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	// PATH lookup using which/where
+	try {
+		const checkCmd = process.platform === 'win32' ? 'where' : 'which';
+		execFileSync(checkCmd, [command], {stdio: 'ignore'});
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Gets installation hint for a missing command
+ */
+function getInstallHint(command: string): string {
+	return (
+		COMMAND_INSTALL_HINTS[command] ||
+		`'${command}' is not installed or not in your PATH.`
+	);
+}
+
+// Union type for all supported client transports
+type ClientTransport =
+	| StdioClientTransport
+	| WebSocketClientTransport
+	| StreamableHTTPClientTransport;
+
+/**
+ * Factory for creating MCP client transports based on server configuration
+ */
+export class TransportFactory {
+	/**
+	 * Creates a transport instance for the given MCP server configuration
+	 */
+	static createTransport(server: MCPServer): ClientTransport {
+		switch (server.transport) {
+			case 'stdio':
+				return this.createStdioTransport(server);
+
+			case 'websocket':
+				return this.createWebSocketTransport(server);
+
+			case 'http':
+				return this.createHTTPTransport(server);
+
+			default: {
+				const _exhaustiveCheck: never = server.transport;
+				throw new Error(
+					`Unsupported transport type: ${_exhaustiveCheck as string}`,
+				);
+			}
+		}
+	}
+
+	/**
+	 * Creates a stdio transport for local MCP servers
+	 */
+	private static createStdioTransport(server: MCPServer): StdioClientTransport {
+		if (!server.command) {
+			throw new Error(
+				`MCP server "${server.name}" missing command for stdio transport`,
+			);
+		}
+
+		return new StdioClientTransport({
+			command: server.command,
+			args: server.args || [],
+			env: server.env
+				? ({...process.env, ...server.env} as Record<string, string>)
+				: undefined,
+		});
+	}
+
+	/**
+	 * Creates a WebSocket transport for remote MCP servers
+	 */
+	private static createWebSocketTransport(
+		server: MCPServer,
+	): WebSocketClientTransport {
+		if (!server.url) {
+			throw new Error(
+				`MCP server "${server.name}" missing URL for websocket transport`,
+			);
+		}
+
+		const url = new URL(server.url);
+
+		// Validate WebSocket URL
+		if (!url.protocol.startsWith('ws')) {
+			throw new Error(
+				`Invalid WebSocket URL protocol: ${url.protocol}. Expected ws:// or wss://`, // nosemgrep
+			);
+		}
+
+		const transport = new WebSocketClientTransport(url);
+
+		// Note: The WebSocketClientTransport doesn't directly support headers in the current SDK
+		// Authentication would need to be handled at the protocol level or via URL parameters
+		if (server.auth) {
+			logWarning('WebSocket transport has unsupported auth config', true, {
+				context: {
+					serverName: server.name,
+					transportType: 'websocket',
+					reason:
+						'Current SDK does not support headers for WebSocket transport',
+				},
+			});
+		}
+
+		return transport;
+	}
+
+	/**
+	 * Creates an HTTP transport for remote MCP servers
+	 */
+	private static createHTTPTransport(
+		server: MCPServer,
+	): StreamableHTTPClientTransport {
+		if (!server.url) {
+			throw new Error(
+				`MCP server "${server.name}" missing URL for http transport`,
+			);
+		}
+
+		const url = new URL(server.url);
+
+		// Validate HTTP URL
+		if (!url.protocol.startsWith('http')) {
+			throw new Error(
+				`Invalid HTTP URL protocol: ${url.protocol}. Expected http:// or https://`,
+			);
+		}
+
+		// Create transport with headers if provided
+		const transportOptions = server.headers
+			? {requestInit: {headers: server.headers}}
+			: undefined;
+		const transport = new StreamableHTTPClientTransport(url, transportOptions);
+
+		if (server.auth) {
+			logWarning('HTTP transport has unsupported auth config', true, {
+				context: {
+					serverName: server.name,
+					transportType: 'http',
+					reason:
+						'Current SDK does not support custom headers for HTTP transport',
+				},
+			});
+		}
+
+		// Check if headers are specified but cannot be used
+		if (server.headers) {
+			const headerKeys = Object.keys(server.headers);
+			if (headerKeys.length > 0) {
+				// Headers are now being used, so don't show the warning anymore
+				// console.warn(...) - Commented out since headers are now supported
+			}
+		}
+
+		return transport;
+	}
+
+	/**
+	 * Validates the server configuration for the given transport type
+	 */
+	static validateServerConfig(server: MCPServer): {
+		valid: boolean;
+		errors: string[];
+	} {
+		const errors: string[] = [];
+
+		switch (server.transport) {
+			case 'stdio':
+				if (!server.command) {
+					errors.push('stdio transport requires a command');
+				} else if (!commandExists(server.command)) {
+					const hint = getInstallHint(server.command);
+					errors.push(`Command '${server.command}' not found.\n\n${hint}`);
+				}
+				break;
+
+			case 'websocket':
+				if (!server.url) {
+					errors.push('websocket transport requires a URL');
+				} else {
+					try {
+						const url = new URL(server.url);
+						if (!url.protocol.startsWith('ws')) {
+							errors.push('websocket URL must use ws:// or wss:// protocol'); // nosemgrep
+						}
+					} catch {
+						errors.push('websocket URL is invalid');
+					}
+				}
+				break;
+
+			case 'http':
+				if (!server.url) {
+					errors.push('http transport requires a URL');
+				} else {
+					try {
+						const url = new URL(server.url);
+						if (!url.protocol.startsWith('http')) {
+							errors.push('http URL must use http:// or https:// protocol');
+						}
+					} catch {
+						errors.push('http URL is invalid');
+					}
+				}
+
+				// Headers are now supported, so we don't need to warn about them being ignored
+				// The actual warning logic has been moved to the createHTTPTransport method
+				break;
+		}
+
+		return {
+			valid: errors.length === 0,
+			errors,
+		};
+	}
+
+	/**
+	 * Gets transport-specific configuration tips for users
+	 */
+	static getTransportTips(transportType: MCPTransportType): string[] {
+		switch (transportType) {
+			case 'stdio':
+				return [
+					'Stdio transport spawns a local process',
+					'Requires a command and optional arguments',
+					'Environment variables can be passed to the process',
+					'Best for local MCP servers and tools',
+				];
+
+			case 'websocket':
+				return [
+					'WebSocket transport connects to remote MCP servers',
+					'Requires a ws:// or wss:// URL', // nosemgrep
+					'Supports real-time bidirectional communication',
+					'Best for interactive remote services',
+					'Note: Custom headers are not currently supported by the SDK and will be ignored',
+				];
+
+			case 'http':
+				return [
+					'HTTP transport connects to remote MCP servers via REST API',
+					'Requires an http:// or https:// URL',
+					'Uses the StreamableHTTP protocol from MCP specification',
+					'Best for stateless remote services and APIs',
+					'Custom headers are now supported for authentication',
+				];
+
+			default:
+				return ['Unknown transport type'];
+		}
+	}
+}