MCP SSH Manager

Instructions

Implementation Reference

• src/tool-registry.js:57-72 (registration)

  Registration of 'ssh_tunnel_create' tool in the 'advanced' group of the tool registry, used for conditional tool registration based on user configuration.

  advanced: [
    'ssh_deploy',
    'ssh_execute_sudo',
    'ssh_alias',
    'ssh_command_alias',
    'ssh_hooks',
    'ssh_profile',
    'ssh_connection_status',
    'ssh_tunnel_create',
    'ssh_tunnel_list',
    'ssh_tunnel_close',
    'ssh_key_manage',
    'ssh_execute_group',
    'ssh_group_manage',
    'ssh_history'
  ]

• src/tunnel-manager.js:441-479 (handler)

  Core handler function that creates SSH tunnels of type local, remote, or dynamic (SOCKS). Validates input config, creates SSHTunnel instance, starts forwarding, and returns the tunnel object. This implements the logic for the 'ssh_tunnel_create' tool.

  export async function createTunnel(serverName, ssh, config) {
    const tunnelId = `tunnel_${Date.now()}_${uuidv4().substring(0, 8)}`;
  
    // Validate config
    if (!config.type || !Object.values(TUNNEL_TYPES).includes(config.type)) {
      throw new Error(`Invalid tunnel type: ${config.type}`);
    }
  
    // Set defaults
    config.localHost = config.localHost || '127.0.0.1';
  
    if (config.type !== TUNNEL_TYPES.DYNAMIC) {
      if (!config.remoteHost || !config.remotePort) {
        throw new Error('Remote host and port required for port forwarding');
      }
    }
  
    if (!config.localPort) {
      throw new Error('Local port required');
    }
  
    const tunnel = new SSHTunnel(tunnelId, serverName, ssh, config);
    tunnels.set(tunnelId, tunnel);
  
    try {
      await tunnel.start();
  
      logger.info('SSH tunnel created', {
        id: tunnelId,
        type: config.type,
        server: serverName
      });
  
      return tunnel;
    } catch (error) {
      tunnels.delete(tunnelId);
      throw error;
    }
  }

• src/tunnel-manager.js:14-18 (schema)

  Schema defining supported tunnel types (local, remote, dynamic) used for input validation in tunnel creation.

  export const TUNNEL_TYPES = {
    LOCAL: 'local',        // Local port forwarding (access remote service locally)
    REMOTE: 'remote',      // Remote port forwarding (expose local service remotely)
    DYNAMIC: 'dynamic'     // SOCKS proxy
  };

• src/tunnel-manager.js:29-436 (helper)

  SSHTunnel class providing full tunnel lifecycle management: starting forwarding servers, handling connections, data piping, stats tracking, reconnection, and cleanup. Core supporting utility for tunnel operations.

  class SSHTunnel {
    constructor(id, serverName, ssh, config) {
      this.id = id;
      this.serverName = serverName;
      this.ssh = ssh;
      this.type = config.type;
      this.config = config;
      this.state = TUNNEL_STATES.CONNECTING;
      this.createdAt = new Date();
      this.lastActivity = new Date();
      this.connections = new Set();
      this.server = null;
      this.reconnectAttempts = 0;
      this.maxReconnectAttempts = 5;
      this.stats = {
        bytesTransferred: 0,
        connectionsTotal: 0,
        connectionsActive: 0,
        errors: 0
      };
    }
  
    /**
     * Start the tunnel
     */
    async start() {
      try {
        switch (this.type) {
        case TUNNEL_TYPES.LOCAL:
          await this.startLocalForwarding();
          break;
  
        case TUNNEL_TYPES.REMOTE:
          await this.startRemoteForwarding();
          break;
  
        case TUNNEL_TYPES.DYNAMIC:
          await this.startDynamicForwarding();
          break;
  
        default:
          throw new Error(`Unknown tunnel type: ${this.type}`);
        }
  
        this.state = TUNNEL_STATES.ACTIVE;
        this.lastActivity = new Date();
  
        logger.info(`SSH tunnel ${this.id} started`, {
          type: this.type,
          server: this.serverName,
          local: `${this.config.localHost}:${this.config.localPort}`,
          remote: this.type !== TUNNEL_TYPES.DYNAMIC ?
            `${this.config.remoteHost}:${this.config.remotePort}` : 'SOCKS'
        });
  
      } catch (error) {
        this.state = TUNNEL_STATES.FAILED;
        logger.error(`Failed to start tunnel ${this.id}`, {
          error: error.message
        });
        throw error;
      }
    }
  
    /**
     * Start local port forwarding
     */
    async startLocalForwarding() {
      const { localHost, localPort, remoteHost, remotePort } = this.config;
  
      // Create local server
      this.server = net.createServer(async (localSocket) => {
        this.stats.connectionsTotal++;
        this.stats.connectionsActive++;
        this.connections.add(localSocket);
        this.lastActivity = new Date();
  
        logger.debug(`New connection to tunnel ${this.id}`, {
          from: localSocket.remoteAddress
        });
  
        try {
          // Forward to remote via SSH
          const stream = await this.ssh.forwardOut(
            localSocket.remoteAddress || '127.0.0.1',
            localSocket.remotePort || 0,
            remoteHost,
            remotePort
          );
  
          // Pipe data between local and remote
          localSocket.pipe(stream).pipe(localSocket);
  
          // Track data transfer
          localSocket.on('data', (chunk) => {
            this.stats.bytesTransferred += chunk.length;
            this.lastActivity = new Date();
          });
  
          stream.on('data', (chunk) => {
            this.stats.bytesTransferred += chunk.length;
            this.lastActivity = new Date();
          });
  
          // Handle disconnection
          const cleanup = () => {
            this.stats.connectionsActive--;
            this.connections.delete(localSocket);
            localSocket.destroy();
            stream.destroy();
          };
  
          localSocket.on('close', cleanup);
          localSocket.on('error', cleanup);
          stream.on('close', cleanup);
          stream.on('error', cleanup);
  
        } catch (error) {
          this.stats.errors++;
          logger.error('Tunnel forwarding error', {
            tunnel: this.id,
            error: error.message
          });
          localSocket.destroy();
        }
      });
  
      // Start listening
      await new Promise((resolve, reject) => {
        this.server.listen(localPort, localHost, (err) => {
          if (err) reject(err);
          else resolve();
        });
      });
  
      logger.info('Local forwarding established', {
        local: `${localHost}:${localPort}`,
        remote: `${remoteHost}:${remotePort}`
      });
    }
  
    /**
     * Start remote port forwarding
     */
    async startRemoteForwarding() {
      const { localHost, localPort, remoteHost, remotePort } = this.config;
  
      // Request remote forwarding from SSH server
      await new Promise((resolve, reject) => {
        this.ssh.forwardIn(remoteHost, remotePort, (err) => {
          if (err) reject(err);
          else resolve();
        });
      });
  
      // Handle incoming connections from remote
      this.ssh.on('tcp connection', (info, accept, reject) => {
        if (info.destPort !== remotePort) return;
  
        this.stats.connectionsTotal++;
        this.stats.connectionsActive++;
        this.lastActivity = new Date();
  
        const remoteSocket = accept();
  
        // Connect to local service
        const localSocket = net.connect(localPort, localHost, () => {
          // Pipe data between remote and local
          remoteSocket.pipe(localSocket).pipe(remoteSocket);
  
          // Track data transfer
          remoteSocket.on('data', (chunk) => {
            this.stats.bytesTransferred += chunk.length;
            this.lastActivity = new Date();
          });
  
          localSocket.on('data', (chunk) => {
            this.stats.bytesTransferred += chunk.length;
            this.lastActivity = new Date();
          });
        });
  
        // Handle errors and cleanup
        const cleanup = () => {
          this.stats.connectionsActive--;
          remoteSocket.destroy();
          localSocket.destroy();
        };
  
        localSocket.on('error', (err) => {
          this.stats.errors++;
          logger.error('Remote forwarding error', {
            tunnel: this.id,
            error: err.message
          });
          cleanup();
        });
  
        remoteSocket.on('close', cleanup);
        localSocket.on('close', cleanup);
      });
  
      logger.info('Remote forwarding established', {
        local: `${localHost}:${localPort}`,
        remote: `${remoteHost}:${remotePort}`
      });
    }
  
    /**
     * Start dynamic port forwarding (SOCKS proxy)
     */
    async startDynamicForwarding() {
      const { localHost, localPort } = this.config;
  
      // Create SOCKS server
      this.server = net.createServer(async (localSocket) => {
        this.stats.connectionsTotal++;
        this.stats.connectionsActive++;
        this.connections.add(localSocket);
        this.lastActivity = new Date();
  
        let targetHost = null;
        let targetPort = null;
        let stream = null;
  
        // Simple SOCKS5 implementation (basic)
        localSocket.once('data', async (chunk) => {
          // Parse SOCKS request (simplified)
          if (chunk[0] === 0x05) { // SOCKS5
            // Send auth method response
            localSocket.write(Buffer.from([0x05, 0x00]));
  
            localSocket.once('data', async (chunk2) => {
              // Parse connection request
              if (chunk2[0] === 0x05 && chunk2[1] === 0x01) { // CONNECT
                const addrType = chunk2[3];
                let offset = 4;
  
                if (addrType === 0x01) { // IPv4
                  targetHost = `${chunk2[4]}.${chunk2[5]}.${chunk2[6]}.${chunk2[7]}`;
                  offset = 8;
                } else if (addrType === 0x03) { // Domain
                  const domainLen = chunk2[4];
                  targetHost = chunk2.slice(5, 5 + domainLen).toString();
                  offset = 5 + domainLen;
                }
  
                targetPort = (chunk2[offset] << 8) | chunk2[offset + 1];
  
                try {
                  // Create SSH forwarding stream
                  stream = await this.ssh.forwardOut(
                    '127.0.0.1', 0,
                    targetHost, targetPort
                  );
  
                  // Send success response
                  const response = Buffer.from([
                    0x05, 0x00, 0x00, 0x01,
                    0, 0, 0, 0,  // Bind address (0.0.0.0)
                    0, 0         // Bind port
                  ]);
                  localSocket.write(response);
  
                  // Pipe data
                  localSocket.pipe(stream).pipe(localSocket);
  
                  // Track data
                  localSocket.on('data', (chunk) => {
                    this.stats.bytesTransferred += chunk.length;
                    this.lastActivity = new Date();
                  });
  
                  stream.on('data', (chunk) => {
                    this.stats.bytesTransferred += chunk.length;
                    this.lastActivity = new Date();
                  });
  
                } catch (error) {
                  // Send error response
                  const response = Buffer.from([
                    0x05, 0x01, 0x00, 0x01,
                    0, 0, 0, 0, 0, 0
                  ]);
                  localSocket.write(response);
                  localSocket.destroy();
                  this.stats.errors++;
                }
              }
            });
          } else {
            // Not SOCKS5, close connection
            localSocket.destroy();
          }
        });
  
        // Cleanup on disconnect
        localSocket.on('close', () => {
          this.stats.connectionsActive--;
          this.connections.delete(localSocket);
          if (stream) stream.destroy();
        });
  
        localSocket.on('error', () => {
          this.stats.errors++;
          this.stats.connectionsActive--;
          this.connections.delete(localSocket);
          if (stream) stream.destroy();
        });
      });
  
      // Start listening
      await new Promise((resolve, reject) => {
        this.server.listen(localPort, localHost, (err) => {
          if (err) reject(err);
          else resolve();
        });
      });
  
      logger.info('SOCKS proxy established', {
        local: `${localHost}:${localPort}`
      });
    }
  
    /**
     * Get tunnel information
     */
    getInfo() {
      return {
        id: this.id,
        server: this.serverName,
        type: this.type,
        state: this.state,
        config: {
          localHost: this.config.localHost,
          localPort: this.config.localPort,
          remoteHost: this.config.remoteHost,
          remotePort: this.config.remotePort
        },
        stats: this.stats,
        created: this.createdAt,
        lastActivity: this.lastActivity,
        activeConnections: this.connections.size
      };
    }
  
    /**
     * Close the tunnel
     */
    close() {
      logger.info(`Closing tunnel ${this.id}`);
  
      this.state = TUNNEL_STATES.CLOSED;
  
      // Close all active connections
      for (const conn of this.connections) {
        conn.destroy();
      }
      this.connections.clear();
  
      // Close server
      if (this.server) {
        this.server.close();
        this.server = null;
      }
  
      // Cancel remote forwarding if needed
      if (this.type === TUNNEL_TYPES.REMOTE) {
        this.ssh.unforwardIn(this.config.remoteHost, this.config.remotePort);
      }
  
      tunnels.delete(this.id);
    }
  
    /**
     * Reconnect tunnel
     */
    async reconnect() {
      if (this.reconnectAttempts >= this.maxReconnectAttempts) {
        logger.error(`Max reconnect attempts reached for tunnel ${this.id}`);
        this.state = TUNNEL_STATES.FAILED;
        return false;
      }
  
      this.reconnectAttempts++;
      this.state = TUNNEL_STATES.RECONNECTING;
  
      logger.info(`Reconnecting tunnel ${this.id}`, {
        attempt: this.reconnectAttempts
      });
  
      try {
        await this.start();
        this.reconnectAttempts = 0;
        return true;
      } catch (error) {
        logger.error(`Reconnect failed for tunnel ${this.id}`, {
          error: error.message
        });
  
        // Retry with exponential backoff
        const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);
        setTimeout(() => this.reconnect(), delay);
  
        return false;
      }
    }
  }

• src/tunnel-manager.js:20-26 (helper)

  Enumeration of tunnel states used throughout the tunnel management system.

  // Tunnel states
  export const TUNNEL_STATES = {
    CONNECTING: 'connecting',
    ACTIVE: 'active',
    RECONNECTING: 'reconnecting',
    FAILED: 'failed',
    CLOSED: 'closed'