ssh_start_interactive_shell
Start an interactive terminal session with PTY support over SSH. Use a specific shell, set terminal dimensions, and simulate typing for remote server management.
Instructions
Start an interactive shell session with PTY support for typing simulation
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cols | No | Terminal columns | |
| connectionId | Yes | SSH connection ID | |
| rows | No | Terminal rows | |
| sessionId | Yes | Unique identifier for this interactive session | |
| shell | No | Shell to use (e.g., /bin/bash, /bin/zsh) | /bin/bash |
Input Schema (JSON Schema)
{
"properties": {
"cols": {
"default": 80,
"description": "Terminal columns",
"type": "number"
},
"connectionId": {
"description": "SSH connection ID",
"type": "string"
},
"rows": {
"default": 24,
"description": "Terminal rows",
"type": "number"
},
"sessionId": {
"description": "Unique identifier for this interactive session",
"type": "string"
},
"shell": {
"default": "/bin/bash",
"description": "Shell to use (e.g., /bin/bash, /bin/zsh)",
"type": "string"
}
},
"required": [
"connectionId",
"sessionId"
],
"type": "object"
}
Implementation Reference
- src/index.ts:893-955 (handler)The handler function that implements the ssh_start_interactive_shell tool. It validates input using StartInteractiveShellSchema, checks for existing SSH connection and session, requests an interactive shell with PTY via node-ssh, sets up event handlers for data and close events, stores the session, and returns success message.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-104 (schema)Zod schema defining the input parameters 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-332 (registration)Tool registration entry in the ListTools response, specifying name, description, and input schema matching the Zod 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-497 (handler)Dispatch case in the CallToolRequest handler that routes to the specific implementation method.case 'ssh_start_interactive_shell':
- src/index.ts:57-57 (helper)Global Map storing active shell sessions, used by the interactive shell tools.const shellSessions = new Map<string, ShellSession>();