mcp-ssh-tool

Instructions

Implementation Reference

• src/session.ts:73-174 (handler)

  The `openSession` method in `SessionManager` handles the actual SSH connection logic, including authentication, SFTP setup, and storing the active session in a map.

  async openSession(params: ConnectionParams): Promise<SessionResult> {
    logger.debug('Opening SSH session', { host: params.host, username: params.username });
  
    const sessionId = this.generateSessionId();
    const now = Date.now();
    const ttl = params.ttlMs || 900000; // 15 minutes default
  
    try {
      // Clean up old sessions if we're at the limit
      if (this.sessions.size >= this.maxSessions) {
        this.evictOldestSession();
      }
  
      const ssh = new NodeSSH();
      const authConfig = await this.buildAuthConfig(params);
  
      const connectConfig = {
        host: params.host,
        username: params.username,
        port: params.port || 22,
        readyTimeout: params.readyTimeoutMs || 20000,
        hostVerifyMethod: params.strictHostKeyChecking
          ? undefined  // Use default strict checking
          : () => true, // Relaxed host key checking
        knownHosts: params.knownHostsPath,
        ...authConfig
      };
  
      logger.debug('Connecting to SSH server');
      await ssh.connect(connectConfig);
  
      // Initialize SFTP client
      const sftp = new SftpClient();
      await sftp.connect({
        host: params.host,
        username: params.username,
        port: params.port || 22,
        readyTimeout: params.readyTimeoutMs || 20000,
        ...authConfig
      });
  
      const sessionInfo: SessionInfo = {
        sessionId,
        host: params.host,
        username: params.username,
        port: params.port || 22,
        createdAt: now,
        expiresAt: now + ttl,
        lastUsed: now
      };
  
      const session: SSHSession = {
        ssh,
        sftp,
        info: sessionInfo,
        connectionParams: params // Store for reconnect
      };
  
      this.sessions.set(sessionId, session);
  
      logger.info('SSH session opened successfully', {
        sessionId,
        host: params.host,
        username: params.username,
        expiresInMs: ttl
      });
  
      return {
        sessionId,
        host: params.host,
        username: params.username,
        expiresInMs: ttl
      };
  
    } catch (error) {
      logger.error('Failed to open SSH session', { error, host: params.host });
  
      if (error instanceof Error) {
        if (error.message.includes('authentication')) {
          throw createAuthError(
            'SSH authentication failed',
            'Check your username, password, or SSH key configuration'
          );
        } else if (error.message.includes('timeout') || error.message.includes('ETIMEDOUT')) {
          throw createTimeoutError(
            'SSH connection timeout',
            'Check if the host is reachable and the SSH service is running'
          );
        } else if (error.message.includes('ECONNREFUSED')) {
          throw createConnectionError(
            'SSH connection refused',
            'Check if the SSH service is running on the target port'
          );
        }
      }
  
      throw createConnectionError(
        `Failed to establish SSH connection: ${error instanceof Error ? error.message : String(error)}`,
        'Verify the host, port, and network connectivity'
      );
    }
  }

• src/mcp.ts:388-393 (registration)

  Registration of the 'ssh_open_session' tool handler in the MCP server request handler switch block.

  case 'ssh_open_session': {
    const params = ConnectionParamsSchema.parse(args);
    const result = await sessionManager.openSession(params);
    logger.info('SSH session opened', { sessionId: result.sessionId, host: redactSensitiveData(params.host) });
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }