ssh_start_interactive_shell
Start an interactive shell session on a remote server via SSH to execute commands and manage systems with PTY support for terminal simulation.
Instructions
Start an interactive shell session with PTY support for typing simulation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| connectionId | Yes | SSH connection ID | |
| sessionId | Yes | Unique identifier for this interactive session | |
| shell | No | Shell to use (e.g., /bin/bash, /bin/zsh) | /bin/bash |
| cols | No | Terminal columns | |
| rows | No | Terminal rows |
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; }