feat: Add Docker support and multi-host connection pooling

[ta5n]

Add Docker Support and Multi-Host Connection Pooling

Summary

This PR introduces two major features to the SSH MCP Server:

1. Multi-host connection pooling - Manage multiple SSH connections simultaneously
2. Docker containerization - Run SSH MCP Server in isolated containers

Motivation

Multi-Host Support:

• Users needed to manage multiple SSH servers from a single MCP instance
• Connection overhead was high when repeatedly connecting to the same hosts
• No visibility into active SSH connections

Docker Support:

• Requested by users wanting isolated, portable deployments
• Needed for Docker MCP Gateway integration
• Simplifies deployment and dependency management

Changes

Multi-Host Connection Pooling

New Features:

• ✨ Connection pool with persistent connections per host
• ✨ Optional host parameter in exec and sudo-exec tools
• ✨ New list-hosts tool to monitor active connections
• ✨ Automatic connection reuse for better performance
• ✨ Support for hostname:port format (e.g., example.com:2222)

Implementation Details:

// Connection pool using Map
const connectionManagers: Map<string, SSHConnectionManager> = new Map();

// Connection key format: user@host:port
const connectionKey = `${targetUser}@${targetHost}:${targetPort}`;

**Example Usage:**
```bash
// Execute on default host
await callTool('exec', { command: 'ls -la' });

// Execute on different host
await callTool('exec', {
  command: 'df -h',
  host: '192.168.1.101:2222'
});

// List all connections
await callTool('list-hosts', {});
// Output: root@192.168.1.100:22 (connected)
//         root@192.168.1.101:2222 (connected)

Docker Support:

New Files:

• Dockerfile - Multi-stage build with Node.js 20 Alpine
• .dockerignore - Optimized build context
• docker-compose.example.yml - Multiple deployment examples
• docker-compose.test.yml - Test environment with 3 SSH servers
• docker-mcp-gateway-compose.yml - MCP Gateway integration
• .env.example - Environment variable template

Example Usage:

  # Build
  docker build -t ssh-mcp:latest .

  # Run with password auth
  docker run -i ssh-mcp:latest \
    --host=192.168.1.100 \
    --user=admin \
    --password=secret

  # Run with SSH key
  docker run -i \
    -v ~/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
    ssh-mcp:latest \
    --host=example.com \
    --user=root \
    --key=/root/.ssh/id_rsa

Testing

New Test Files:

• test/list-hosts.test.ts - Tests for connection pool monitoring
• test/multi-host.test.ts - Comprehensive multi-host scenarios:
  • Concurrent connections to multiple hosts
  • Parallel command execution
  • Independent connection state
  • Error isolation between hosts
  • Connection lifecycle management
• test/test-multi-host-manual.js - Manual integration testing script

Test Coverage:

• ✅ Connection pool management
• ✅ Concurrent multi-host connections
• ✅ Parallel command execution
• ✅ Connection reuse
• ✅ Error isolation
• ✅ list-hosts tool functionality

Documentation

README.md Updates:

• Added "Docker Usage" section with comprehensive examples
• Added "Multi-Host Usage" section explaining connection pooling
• Updated tool descriptions to document host parameter
• Documented list-hosts tool
• Added Docker MCP Gateway integration guide

New Documentation:

• CLAUDE_CODE_SETUP.md - Detailed Turkish setup guide for Claude Code users

Benefits

Multi-Host Support

• 🚀 Performance - Persistent connections reduce overhead
• 🔄 Flexibility - Manage multiple servers from single instance
• 💪 Reliability - Independent connection management
• 🎯 Convenience - No need for multiple MCP server instances

Docker Support

• 📦 Portability - Run anywhere Docker runs
• 🔒 Isolation - Containerized execution environment
• 🔧 Easy deployment - Simple docker run or docker-compose
• 🌐 MCP Gateway ready - Integrates with Docker MCP Gateway

Backward Compatibility

✅ Fully backward compatible - All existing configurations and usage patterns continue to work unchanged.

Suggestion for Maintainer

Docker Hub Publication:
I suggest publishing this MCP server to Docker Hub for easier distribution. Benefits:

• Users can pull pre-built images without building locally
• Automated builds via GitHub Actions
• Version tagging for stable releases
• Easier discovery and adoption

Suggested repository: tufantunc/ssh-mcp or docker.io/tufantunc/ssh-mcp

Testing Instructions

Multi-Host Testing

  # Start test SSH servers
  docker-compose -f docker-compose.test.yml up -d

  # Run multi-host tests
  npm test test/multi-host.test.ts

  # Manual testing
  node test/test-multi-host-manual.js

Docker Testing

  # Build image
  docker build -t ssh-mcp:latest .

  # Test basic functionality
  docker run -i ssh-mcp:latest \
    --host=YOUR_HOST \
    --user=YOUR_USER \
    --password=YOUR_PASSWORD

Related Issues

Addresses user requests for:

• Multi-server management from single MCP instance
• Docker deployment option
• Connection persistence and performance improvements

Checklist

• Code follows project style guidelines
• Tests added for new functionality
• Documentation updated (README.md)
• Backward compatibility maintained
• No breaking changes

Screenshots/Examples

  Multi-Host Usage:
  User: Check disk space on server1 and server2
  Claude: [Uses exec with host parameter for each server]

  Output:
  server1 (192.168.1.100):
  Filesystem      Size  Used Avail Use% Mounted on
  /dev/sda1        50G   20G   30G  40% /

  server2 (192.168.1.101):
  Filesystem      Size  Used Avail Use% Mounted on
  /dev/sda1       100G   45G   55G  45% /

  Docker Deployment:
  $ docker run -i ssh-mcp:latest --host=example.com --user=root --password=secret
  SSH MCP Server running on stdio

---

Note: The Turkish setup guide (CLAUDE_CODE_SETUP.md) is included for Turkish-speaking users. Consider adding an English version or integrating relevant content into the main README.

[tufantunc]

This is the feature that i planned to made one day, really happy to see this pr. Now i need some time to carefully read those changes. Thanks for contributing 🎉

[ta5n]

You are welcome!

[miolamio]

Great PR, cant wait.