SSH MCP

Instructions

Implementation Reference

• src/ubuntu-website-tools.ts:78-129 (handler)

  The core handler function that implements the ubuntu_nginx_control tool. It validates the action, constructs and executes the appropriate systemctl or nginx command via SSH, processes the result, and returns formatted output or error.
  async ubuntu_nginx_control(params) { const { connectionId, action, sudo = true } = params; try { const conn = getConnection(connectionMap, connectionId); // Validate action const validActions = ['start', 'stop', 'restart', 'status', 'reload', 'check-config']; if (!validActions.includes(action)) { throw new Error(`Invalid action: ${action}. Valid actions are: ${validActions.join(', ')}`); } let command = ''; const sudoPrefix = sudo ? 'sudo ' : ''; switch (action) { case 'start': case 'stop': case 'restart': case 'status': case 'reload': command = `${sudoPrefix}systemctl ${action} nginx`; break; case 'check-config': command = `${sudoPrefix}nginx -t`; break; } const result = await executeSSHCommand(conn, command); let status = result.code === 0 ? 'success' : 'error'; let message = result.stdout || result.stderr; if (action === 'status') { // Extract status info from systemctl output const isActive = message.includes('Active: active'); status = isActive ? 'active' : 'inactive'; } return { content: [{ type: 'text', text: `Nginx ${action} result: ${status}\n\n${message}` }] }; } catch (error: any) { return { content: [{ type: 'text', text: `Nginx control error: ${error.message}` }], isError: true }; } },
• src/ubuntu-website-tools.ts:517-537 (schema)

  The input schema and description for the ubuntu_nginx_control tool, used for tool listing and validation.
  ubuntu_nginx_control: { description: 'Control Nginx web server on Ubuntu', inputSchema: { type: 'object', properties: { connectionId: { type: 'string', description: 'ID of an active SSH connection' }, action: { type: 'string', description: 'Action to perform (start, stop, restart, status, reload, check-config)' }, sudo: { type: 'boolean', description: 'Whether to run the command with sudo (default: true)' } }, required: ['connectionId', 'action'] } },
• src/index.ts:293-296 (registration)

  Registers the call handler for ubuntu_ tools (including ubuntu_nginx_control) by dispatching to the corresponding function in ubuntuToolHandlers within the MCP CallToolRequestSchema handler.
  // Handle Ubuntu tools directly if (toolName.startsWith('ubuntu_') && ubuntuToolHandlers[toolName]) { return ubuntuToolHandlers[toolName](request.params.arguments); }
• src/ubuntu-website-tools.ts:18-58 (helper)

  Utility function used by the handler to execute SSH commands safely with timeout handling and full output capture.
  async function executeSSHCommand(conn: Client, command: string, timeout = 60000): Promise<{ code: number; signal: string; stdout: string; stderr: string; }> { return new Promise((resolve, reject) => { // Set up timeout const timeoutId = setTimeout(() => { reject(new Error(`Command execution timed out after ${timeout}ms`)); }, timeout); conn.exec(command, {}, (err: Error | undefined, stream: any) => { if (err) { clearTimeout(timeoutId); return reject(new Error(`Failed to execute command: ${err.message}`)); } let stdout = ''; let stderr = ''; stream.on('close', (code: number, signal: string) => { clearTimeout(timeoutId); resolve({ code, signal, stdout: stdout.trim(), stderr: stderr.trim() }); }); stream.on('data', (data: Buffer) => { stdout += data.toString(); }); stream.stderr.on('data', (data: Buffer) => { stderr += data.toString(); }); }); }); }
• src/ubuntu-website-tools.ts:61-66 (helper)

  Helper function to retrieve the SSH connection for the given connectionId, used by the handler.
  function getConnection(connections: Map<string, { conn: Client; config: any }>, connectionId: string) { if (!connections.has(connectionId)) { throw new Error(`No active SSH connection with ID: ${connectionId}`); } return connections.get(connectionId)!.conn; }