ssh_start_interactive_shell

Instructions

Implementation Reference

• src/index.ts:893-955 (handler)

  The core handler function that executes the ssh_start_interactive_shell tool. It parses input parameters, retrieves the SSH connection, requests an interactive shell with PTY support, sets up event emitters for data and close events, and manages the shell session.

  private async handleStartInteractiveShell(args: unknown) {
    const params = StartInteractiveShellSchema.parse(args);
    
    const ssh = connectionPool.get(params.connectionId);
    if (!ssh) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Connection ID '${params.connectionId}' not found`
      );
    }
  
    if (shellSessions.has(params.sessionId)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Session ID '${params.sessionId}' already exists`
      );
    }
  
    try {
      // Create a shell session through SSH
      const shell = await ssh.requestShell({
        cols: params.cols,
        rows: params.rows,
        term: 'xterm-256color'
      });
  
      const emitter = new EventEmitter();
      const session: ShellSession = {
        shell: shell, // SSH ClientChannel
        ssh,
        emitter,
        buffer: '',
        isActive: true
      };
  
      // Set up data handling
      shell.on('data', (data: Buffer) => {
        const text = data.toString();
        session.buffer += text;
        emitter.emit('data', text);
      });
  
      shell.on('close', () => {
        session.isActive = false;
        emitter.emit('close');
      });
  
      shellSessions.set(params.sessionId, session);
  
      return {
        content: [
          {
            type: 'text',
            text: `Interactive shell session '${params.sessionId}' started successfully\nShell: ${params.shell}\nTerminal: ${params.cols}x${params.rows}`,
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to start interactive shell: ${error instanceof Error ? error.message : String(error)}`
      );
    }

• src/index.ts:99-105 (schema)

  Zod schema defining the input parameters and validation for the ssh_start_interactive_shell tool.

  const StartInteractiveShellSchema = z.object({
    connectionId: z.string().describe('SSH connection ID'),
    sessionId: z.string().describe('Unique identifier for this interactive session'),
    shell: z.string().default('/bin/bash').describe('Shell to use (e.g., /bin/bash, /bin/zsh)'),
    cols: z.number().default(80).describe('Terminal columns'),
    rows: z.number().default(24).describe('Terminal rows')
  });

• src/index.ts:320-333 (registration)

  Tool registration in the ListTools response, defining name, description, and input schema.

    name: 'ssh_start_interactive_shell',
    description: 'Start an interactive shell session with PTY support for typing simulation',
    inputSchema: {
      type: 'object',
      properties: {
        connectionId: { type: 'string', description: 'SSH connection ID' },
        sessionId: { type: 'string', description: 'Unique identifier for this interactive session' },
        shell: { type: 'string', default: '/bin/bash', description: 'Shell to use (e.g., /bin/bash, /bin/zsh)' },
        cols: { type: 'number', default: 80, description: 'Terminal columns' },
        rows: { type: 'number', default: 24, description: 'Terminal rows' }
      },
      required: ['connectionId', 'sessionId']
    },
  },

• src/index.ts:497-498 (registration)

  Registration of the tool handler in the CallToolRequest switch statement.

  case 'ssh_start_interactive_shell':
    return await this.handleStartInteractiveShell(args);

• src/index.ts:49-55 (helper)

  Interface defining the structure of an interactive shell session, used by the handler.

  interface ShellSession {
    shell: any; // SSH ClientChannel
    ssh: NodeSSH;
    emitter: EventEmitter;
    buffer: string;
    isActive: boolean;
  }