MCP SSH Server

# Project Journal - SSH MCP Server ## 2025-08-13 - Project Creation ### Initial Setup - Created new MCP server project for SSH operations - Set up TypeScript configuration with ES2022 target and ESNext modules - Configured package.json with necessary dependencies: - `@modelcontextprotocol/sdk` for MCP server implementation - `node-ssh` and `ssh2` for SSH functionality - `zod` for runtime type validation - TypeScript and development dependencies ### Core Implementation - **Main Server File**: `src/index.ts` - Implemented SSHMCPServer class with full MCP protocol support - Added connection pooling for efficient SSH connection management - Implemented comprehensive error handling with proper MCP error codes ### Available Tools Implemented 1. **ssh_connect**: Connect to SSH servers with password or key authentication 2. **ssh_disconnect**: Properly disconnect and cleanup SSH connections 3. **ssh_execute**: Execute commands on remote servers with optional working directory 4. **ssh_copy_file**: Copy files between local/remote and remote/remote with four scenarios: - Local to Local - Local to Remote - Remote to Local - Remote to Remote (using temporary files) 5. **ssh_list_files**: List directory contents on local or remote systems 6. **ssh_file_info**: Get detailed file information including permissions and timestamps ### Key Features - **Connection Management**: Unique connection IDs with pooling - **Type Safety**: Full TypeScript implementation with Zod schema validation - **Error Handling**: Comprehensive error handling with proper MCP error codes - **Security**: Support for both password and private key authentication - **Cleanup**: Automatic connection cleanup on server shutdown - **Temporary Files**: Safe handling of temporary files for remote-to-remote transfers ### File Structure ``` mcp-ssh/ ├── package.json # Project configuration and dependencies ├── tsconfig.json # TypeScript configuration ├── README.md # Comprehensive documentation ├── docs/ │ └── journal.md # This project journal └── src/ └── index.ts # Main MCP server implementation ``` ### Build and Development - Configured build scripts for development (`npm run dev`) and production (`npm run build`) - Added type checking script (`npm run type-check`) - All TypeScript compilation passes without errors - Ready for immediate use with MCP clients ### Claude Desktop Integration (2025-08-13 - Update) - **Enhanced Documentation**: Added comprehensive Claude Desktop integration section to README - **Configuration Examples**: Created platform-specific configuration examples for macOS, Windows, and Linux - **Troubleshooting Guide**: Added detailed troubleshooting section for common integration issues - **File Structure Updates**: - Updated `examples/mcp-config.json` with correct absolute path format - Created `examples/claude-desktop-configs.md` with platform-specific examples - Enhanced README with step-by-step Claude Desktop setup instructions ### Key Improvements - **User Experience**: Clear instructions for finding configuration file locations - **Error Prevention**: Detailed troubleshooting for common setup issues - **Platform Support**: Specific examples for macOS, Windows, and Linux - **Verification Steps**: Clear steps to verify successful integration ### Authentication Documentation Enhancement (2025-08-13 - Update) - **Enhanced Usage Examples**: Added comprehensive authentication methods section - **Security Best Practices**: Documented SSH key vs password authentication recommendations - **Common Scenarios**: Added examples for AWS EC2, Ubuntu servers, and custom ports - **File Permission Guidelines**: Added chmod instructions for SSH key security - **README Updates**: Enhanced ssh_connect tool documentation with both authentication methods ### Key Authentication Features - **Password Authentication**: Simple username/password connection - **SSH Key Authentication**: More secure private key-based authentication - **Passphrase Support**: Optional passphrase protection for private keys - **Flexible Key Paths**: Support for custom private key file locations - **Common Scenarios**: AWS EC2, Ubuntu, custom ports examples ### User-Friendly Authentication Guide (2025-08-13 - Update) - **Created Beginner Guide**: Added `examples/how-to-use-authentication.md` for non-technical users - **Natural Language Examples**: Showed how to use plain English instead of JSON - **Real-World Scenarios**: Provided practical examples for common use cases - **Troubleshooting Section**: Added common issues and solutions - **README Quick Start**: Added prominent link to the user-friendly guide ### Key Improvements for Usability - **Plain English Instructions**: Users don't need to understand JSON format - **Step-by-Step Examples**: Clear progression from setup to actual usage - **Common Scenarios**: Home lab, AWS EC2, VPS examples - **Error Prevention**: Troubleshooting tips for connection issues ### Schema Validation Fix (2025-08-13 - Update) - **Fixed MCP Schema Errors**: Converted Zod schemas to proper JSON Schema format - **Tool Registration**: All 6 tools now properly register with `type: 'object'` in inputSchema - **Validation Compliance**: Fixed "Invalid literal value, expected 'object'" errors - **Build Success**: TypeScript compilation and type checking passes without errors - **Schema Consistency**: Maintained all parameter descriptions and requirements ### Technical Improvements - **JSON Schema Format**: Proper MCP-compliant tool schema definitions - **Type Safety**: Maintained Zod validation for runtime parameter checking - **Error Prevention**: Fixed schema validation that was preventing tool registration - **Compatibility**: Ensures proper integration with Claude Desktop and other MCP clients ## 2025-08-14 - Enhanced Interactive Features ### Enhanced SSH MCP Server - Option 3 Implementation - **Major Enhancement**: Successfully implemented Option 3 - Enhanced MCP Server with full PTY support and interactive session management - **New Interactive Features**: - `ssh_start_interactive_shell`: Creates interactive shell sessions with PTY support - `ssh_send_input`: Sends input with optional typing simulation (50-150ms delays per character) - `ssh_read_output`: Reads buffered output from interactive sessions - `ssh_close_interactive_shell`: Properly closes interactive sessions - **Key Capabilities**: - ✅ Interactive sudo password prompts - ✅ Human-like typing simulation - ✅ Real-time shell interaction - ✅ Session management with proper cleanup - **Successful Test**: Accessed `/root` directory using interactive sudo with password authentication - **Dependencies Added**: `node-pty` for PTY support ### Technical Implementation - **Session Management**: Map-based session pool with EventEmitter for real-time communication - **PTY Integration**: Direct SSH ClientChannel integration (not node-pty as initially planned) - **Typing Simulation**: Random delays between 50-150ms per character for realistic interaction - **Error Handling**: Comprehensive session lifecycle management with proper cleanup ### Credential Management System (2025-08-14 - Update) - **New Credential Tools**: Added comprehensive credential management system - `ssh_save_credential`: Save SSH credentials for reuse with unique IDs - `ssh_list_credentials`: List all saved credentials with connection details - `ssh_delete_credential`: Remove stored credentials - `ssh_connect_with_credential`: Connect using saved credentials - **Security Features**: Credentials stored in memory with last-used timestamps - **User Experience**: Eliminates need to re-enter connection details repeatedly - **Testing**: Successfully tested credential save, list, connect, and delete operations ## 2025-08-14 - Working Directory & Docker Deployment Features ### Enhanced Working Directory Management - **Connection Context System**: Added persistent working directory tracking per SSH connection - **New Working Directory Tools**: - `ssh_set_working_directory`: Set and verify working directory for a connection - `ssh_get_working_directory`: Get current working directory (cached or from remote) - **Context Persistence**: Working directories maintained throughout connection lifecycle - **Directory Validation**: Automatic verification that directories exist before setting ### Docker Deployment Integration - **Specialized Docker Tools**: - `ssh_docker_deploy`: Deploy Docker applications with multiple deployment types - `ssh_docker_status`: Check Docker container and compose status - **Deployment Types Supported**: - `compose`: Docker Compose deployments with custom compose files - `build`: Docker image building with build arguments - `run`: Docker container execution with ports, volumes, and environment variables - **Advanced Features**: - Environment variable injection - Build argument support - Port and volume mapping - Detached mode support - Custom container naming ### Technical Implementation - **ConnectionContext Interface**: Tracks SSH connection, working directory state - **Context Management**: Automatic initialization on connect, cleanup on disconnect - **Schema Validation**: Comprehensive Zod schemas for all new tools - **Error Handling**: Proper validation and error reporting for Docker operations - **Type Safety**: Full TypeScript implementation with zero compilation errors ### Problem Solved - **Working Directory Persistence**: Eliminates repeated folder searches and navigation - **Docker Workflow Optimization**: Streamlined Docker deployments in specific directories - **Context Awareness**: MCP server now maintains state between operations - **User Experience**: Faster Docker deployments with fewer manual steps ### Next Steps - Server is production-ready with comprehensive SSH, interactive, credential, and Docker features - All authentication methods documented with user-friendly examples - Working directory management solves the folder navigation efficiency issue - Docker deployment tools provide specialized workflow optimization - Consider adding additional features like: - SSH tunnel management - Batch file operations - Progress reporting for large file transfers - SSH config file parsing - Docker log streaming - Container health monitoring