MCP SSH Agent

# MCP SSH Agent Implementation Notes ## Final Implementation (v2.0 - Simplified SSH) The MCP SSH Agent has been successfully implemented with a simplified, more reliable SSH approach that replaced the problematic `node-ssh` library. ### Architecture 1. **Main Server File**: `server-simple.mjs` - Pure JavaScript implementation using ES modules with createRequire - Uses `@modelcontextprotocol/sdk` for MCP protocol compliance - Uses native `ssh` and `scp` commands via `child_process.exec()` 2. **Core Components**: - `SSHConfigParser`: Parses `~/.ssh/config` and `~/.ssh/known_hosts` - `SSHClient`: Handles all SSH operations using local SSH commands - MCP Server: Provides standardized tool interface ### Key Changes in v2.0 **Problem Solved**: The original implementation using `node-ssh` library failed with authentication errors ("All configured authentication methods failed") even though manual SSH connections worked perfectly. **Solution**: Replaced `node-ssh` with direct execution of local `ssh` and `scp` commands using Node.js `child_process.exec()`. This approach: - Leverages existing SSH infrastructure (agent, keys, config) - Avoids JavaScript library authentication complexities - Is more reliable and simpler to maintain - Provides better error messages and debugging ### MCP Protocol Implementation - **Server Creation**: Uses `Server` class from MCP SDK - **Transport**: `StdioServerTransport` for STDIO communication - **Request Handlers**: - `ListToolsRequestSchema`: Returns available SSH tools - `CallToolRequestSchema`: Executes SSH operations ### SSH Tools Provided 1. **listKnownHosts**: Returns all configured SSH hosts 2. **runRemoteCommand**: Executes single commands remotely using `ssh "host" "command"` 3. **getHostInfo**: Returns host configuration details 4. **checkConnectivity**: Tests SSH connectivity with simple echo test 5. **uploadFile**: Transfers files to remote hosts using `scp` 6. **downloadFile**: Downloads files from remote hosts using `scp` 7. **runCommandBatch**: Executes multiple commands sequentially ### Technical Implementation Details 1. **SSH Command Execution**: ```javascript const sshCommand = `ssh "${hostAlias}" "${command.replace(/"/g, '\\"')}"`; const { stdout, stderr } = await execAsync(sshCommand, { timeout: 30000 }); ``` 2. **File Transfers**: ```javascript // Upload: scp "localPath" "hostAlias:remotePath" // Download: scp "hostAlias:remotePath" "localPath" ``` 3. **Error Handling**: Proper timeout handling (30s for commands, 60s for transfers) ### Key Technical Decisions 1. **Module Resolution**: Used `createRequire()` to handle MCP SDK CommonJS exports 2. **Schema Compliance**: Used proper MCP request schemas instead of string identifiers 3. **SSH Approach**: Native SSH commands instead of JavaScript SSH libraries 4. **Error Handling**: Comprehensive error handling with meaningful error messages 5. **File Structure**: Simplified to single main file to avoid build complexity ### Dependencies (Simplified) - `@modelcontextprotocol/sdk`: MCP protocol implementation - `ssh-config`: SSH configuration parsing - Native Node.js modules: `child_process`, `util`, `os`, `fs` **Removed**: `node-ssh`, `ssh2` (unreliable authentication) ### Testing The implementation has been thoroughly tested with: 1. **Basic Functionality Tests**: ```bash # Test tools listing echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node server-simple.mjs # Test SSH command execution echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"runRemoteCommand","arguments":{"hostAlias":"prod","command":"echo \"test\""}}}' | node server-simple.mjs ``` 2. **SSH Connectivity**: Successfully tested against prod host (157.90.89.149:42077) 3. **Authentication**: Works with SSH agent and default key resolution 4. **Error Handling**: Proper error reporting for failed connections ### Performance and Reliability - **Startup Time**: Fast server initialization (~1-2 seconds) - **Command Execution**: Efficient direct SSH command execution - **Memory Usage**: Minimal - no persistent SSH connections - **Reliability**: Leverages proven SSH infrastructure ### Usage ```bash npm start # Starts the MCP server on STDIO ``` The server is ready for integration with MCP-compatible clients and language models. ## Troubleshooting History ### Issue: SSH Authentication Failures with node-ssh **Problem**: The original implementation using `node-ssh` consistently failed with: ``` Connection to prod failed: All configured authentication methods failed ``` **Investigation**: - SSH config parsing worked correctly (prod host found) - Manual SSH connection (`ssh prod echo test`) worked perfectly - Multiple attempts to configure SSH agent, keys, and connection options failed - Issue appeared to be with node-ssh library's authentication handling **Solution**: Complete replacement with native SSH command execution - Removed dependencies: `node-ssh`, `ssh2` - Replaced with: `child_process.exec()` + local `ssh`/`scp` commands - Result: Immediate success, much simpler code, better reliability This demonstrates the value of using proven system tools over complex JavaScript libraries for system operations. ## Security Considerations - Uses existing SSH key infrastructure - No password storage or handling - Relies on properly configured SSH authentication - All operations respect SSH configuration restrictions ## Maintenance Notes - Keep MCP SDK dependency updated for protocol compliance - Monitor SSH library updates for security patches - Test with various SSH configurations periodically