shell_execute_streaming

Instructions

Implementation Reference

• src/tools/shell.ts:95-172 (handler)

  Core handler function that executes the shell command using spawn for real-time streaming output capture and processing.

  export async function executeStreamingCommand(args: z.infer<typeof executeStreamingCommandSchema>): Promise<ToolResponse> {
    try {
      // For sudo commands, wrap the entire command in a shell to ensure all parts run with sudo
      const command = args.sudo
        ? `sudo bash -c ${JSON.stringify(args.command)}`
        : args.command;
  
      return new Promise((resolve) => {
        const child = spawn(command, {
          cwd: args.cwd,
          env: args.env ? { ...process.env, ...args.env } : process.env,
          shell: args.shell || '/bin/bash',
          stdio: ['ignore', 'pipe', 'pipe']
        });
  
        let stdout = '';
        let stderr = '';
  
        child.stdout?.on('data', (data) => {
          stdout += data.toString();
        });
  
        child.stderr?.on('data', (data) => {
          stderr += data.toString();
        });
  
        child.on('close', (code, signal) => {
          resolve({
            content: [
              {
                type: "text" as const,
                text: JSON.stringify({
                  success: code === 0,
                  command: command,
                  stdout: stdout,
                  stderr: stderr,
                  exitCode: code,
                  signal: signal
                }, null, 2)
              }
            ],
            isError: code !== 0
          });
        });
  
        child.on('error', (error) => {
          resolve({
            content: [
              {
                type: "text" as const,
                text: JSON.stringify({
                  success: false,
                  command: command,
                  stdout: stdout,
                  stderr: stderr + '\n' + error.message,
                  error: error.message
                }, null, 2)
              }
            ],
            isError: true
          });
        });
      });
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              success: false,
              error: error instanceof Error ? error.message : String(error)
            }, null, 2)
          }
        ],
        isError: true
      };
    }
  }

• src/tools/shell.ts:24-30 (schema)

  Zod schema defining input validation for the shell_execute_streaming tool parameters.

  export const executeStreamingCommandSchema = z.object({
    command: z.string().describe('The shell command to execute with streaming output'),
    cwd: z.string().optional().describe('Working directory for the command'),
    env: z.record(z.string()).optional().describe('Environment variables to set for the command'),
    shell: z.string().optional().describe('Shell to use (default: /bin/bash)'),
    sudo: z.boolean().default(false).describe('Execute with sudo privileges')
  });

• src/tools/shell.ts:226-265 (registration)

  Tool definition object in shellTools array, used for listing the tool in MCP protocol.

    {
      name: 'shell_execute_streaming',
      description: `Execute a long-running shell command with streaming output support. Captures output as it's produced.
  
  Use this for:
  - Build processes (npm build, cargo build, etc.)
  - Long-running scripts
  - Services that produce continuous output
  - Commands that take significant time to complete
  
  The command runs in /bin/bash by default. Output is streamed and returned when complete.`,
      inputSchema: {
        type: 'object',
        properties: {
          command: {
            type: 'string',
            description: 'The shell command to execute with streaming output'
          },
          cwd: {
            type: 'string',
            description: 'Working directory for the command'
          },
          env: {
            type: 'object',
            additionalProperties: { type: 'string' },
            description: 'Environment variables to set for the command'
          },
          shell: {
            type: 'string',
            description: 'Shell to use (default: /bin/bash)'
          },
          sudo: {
            type: 'boolean',
            default: false,
            description: 'Execute with sudo privileges'
          }
        },
        required: ['command']
      }
    }

• src/index.ts:351-353 (registration)

  Dispatch logic in the central CallToolRequestHandler that routes calls to the streaming shell handler.

  if (name === 'shell_execute_streaming') {
    const validated = executeStreamingCommandSchema.parse(args);
    return await executeStreamingCommand(validated);

• src/index.ts:285-296 (registration)

  ListToolsRequestHandler that includes shellTools (containing shell_execute_streaming) in the available tools list.

  return {
    tools: [
      ...filesystemTools,
      ...shellTools,
      ...dockerTools,
      ...mongodbTools,
      ...redisTools,
      ...gitTools,
      ...processTools,
      ...networkTools
    ]
  };