SSH MCP Server

# Epic 3: MCP Server Integration ## Epic Intent Implement the Model Context Protocol (MCP) server framework integration that exposes SSH functionality as MCP tools, enabling Claude Code to interact with remote servers through standardized MCP interfaces. ## Story 1: MCP Server Foundation As a developer integrating with Claude Code, I want an MCP server that properly implements the MCP specification so that Claude Code can discover and use SSH tools. ### Acceptance Criteria - **Given** the MCP server implementation is started - **When** Claude Code connects to the server - **Then** the server responds to MCP handshake requests correctly - **And** server capabilities are advertised according to MCP specification - **And** the server implements required MCP message types (initialize, tools/list, tools/call) - **And** the server provides proper error handling for malformed requests - **And** the server maintains connection state with Claude Code - **And** server logging captures all MCP interactions for debugging **Technical Requirements:** - Use @modelcontextprotocol/sdk TypeScript library - Implement proper JSON-RPC 2.0 messaging - Support both stdio and TCP transport methods ## Story 2: SSH Connection Tool Implementation As a Claude Code user, I want an MCP tool to establish SSH connections so that I can create named persistent sessions with remote servers. ### Acceptance Criteria - **Given** the MCP server is running and connected to Claude Code - **When** Claude Code calls the ssh_connect tool - **Then** the tool accepts parameters: name (string), host (string), credentials (object) - **And** credentials support SSH key authentication and password authentication - **And** the tool validates all required parameters are provided - **And** a new SSH connection is established using the provided credentials - **And** the connection is stored with the provided name identifier - **And** success response includes connection status and session details - **And** error responses provide specific failure reasons - **And** duplicate connection names are rejected with clear error messages **Parameter Validation:** - name: required, alphanumeric with hyphens/underscores only - host: required, valid hostname or IP address - credentials: required, must include either keyFile path or password ## Story 3: Command Execution Tool Implementation As a Claude Code user, I want an MCP tool to execute bash commands on remote servers so that I can run development operations through SSH sessions. ### Acceptance Criteria - **Given** an active SSH session exists with a specific name - **When** Claude Code calls the ssh_exec tool - **Then** the tool accepts parameters: sessionName (string), command (string), workingDir (optional string) - **And** the command is executed in the specified SSH session - **And** the working directory is changed if workingDir parameter is provided - **And** command output (stdout and stderr) is captured completely - **And** the command exit code is returned in the response - **And** terminal state (working directory, environment) persists after execution - **And** error responses are provided for invalid session names - **And** long-running commands are supported without timeout issues **Performance Requirements:** - Commands must begin execution within 2 seconds - Output must be captured completely regardless of size - Support commands that run for up to 30 minutes ## Story 4: Session Management Tools As a Claude Code user, I want MCP tools to manage SSH sessions so that I can list, monitor, and disconnect sessions as needed. ### Acceptance Criteria - **Given** SSH sessions may be active - **When** Claude Code calls session management tools - **Then** ssh_list_sessions tool returns all active sessions with status information - **And** each session includes: name, host, status, lastActivity, connectionTime - **And** ssh_get_session_url tool returns monitoring URL for a specific session - **And** ssh_disconnect tool closes a specific session by name - **And** ssh_session_status tool provides detailed status for a single session - **And** all tools validate session names exist before operations - **And** tools provide consistent error messages for invalid sessions ## Story 5: Tool Error Handling and Validation As a Claude Code user, I want robust error handling from MCP tools so that I receive clear feedback when operations fail. ### Acceptance Criteria - **Given** MCP tools are called with various inputs - **When** invalid parameters or error conditions occur - **Then** tools return proper MCP error responses with specific error codes - **And** error messages are descriptive and actionable - **And** parameter validation occurs before expensive operations - **And** network connectivity issues are handled gracefully - **And** SSH authentication failures provide clear error messages - **And** session management errors distinguish between different failure types - **And** all errors are logged for debugging purposes **Error Categories:** - INVALID_PARAMS: Parameter validation failures - CONNECTION_ERROR: SSH connection establishment issues - SESSION_NOT_FOUND: Operations on non-existent sessions - AUTHENTICATION_FAILED: SSH credential issues - NETWORK_ERROR: Connectivity problems ## Story 6: MCP Tool Documentation and Schema As a Claude Code integration, I want properly documented MCP tool schemas so that the system can understand tool capabilities and parameters. ### Acceptance Criteria - **Given** Claude Code requests tool information - **When** the MCP server provides tool schemas - **Then** each tool has complete parameter documentation - **And** parameter types, required/optional status, and descriptions are specified - **And** tool descriptions clearly explain functionality and use cases - **And** example usage patterns are included in tool documentation - **And** return value schemas are documented - **And** error conditions and codes are documented - **And** schemas validate successfully against MCP specification ## Story 7: Configuration and Startup Management As a system administrator, I want configurable MCP server settings so that I can customize behavior for different environments. ### Acceptance Criteria - **Given** the MCP server needs to be configured - **When** the server starts up - **Then** configuration is loaded from environment variables and config files - **And** web server port for monitoring is configurable (default: 8080) - **And** SSH connection timeouts are configurable (default: 30 seconds) - **And** maximum concurrent sessions limit is configurable (default: 10) - **And** log level is configurable (debug, info, warn, error) - **And** invalid configuration values prevent server startup with clear error messages - **And** configuration validation occurs at startup **Configuration Parameters:** - WEB_PORT: monitoring interface port - SSH_TIMEOUT: connection timeout in seconds - MAX_SESSIONS: maximum concurrent SSH sessions - LOG_LEVEL: logging verbosity level