Shell Command MCP Server

Instructions

Implementation Reference

• src/execute-bash-script-sync.ts:52-115 (handler)

  Core handler logic: asynchronously spawns a bash process via child_process.spawn, pipes command to stdin, collects stdout/stderr, handles timeout and process exit/error, returns CommandResult with stdout, stderr, exitCode.

  export async function executeCommand(
    command: string,
    options: CommandOptions = {},
  ): Promise<CommandResult> {
    return new Promise((resolve, reject) => {
      // 環境変数を設定
      const env = {
        ...process.env,
        ...options.env,
      };
  
      // bashプロセスを起動
      const bash = spawn(shellProgram, [], {
        cwd: options.cwd,
        env,
        stdio: ['pipe', 'pipe', 'pipe'],
      });
  
      let stdout = '';
      let stderr = '';
      let timeoutId: NodeJS.Timeout | null = null;
  
      // 標準出力の収集
      bash.stdout.on('data', (data) => {
        stdout += data.toString();
      });
  
      // 標準エラー出力の収集
      bash.stderr.on('data', (data) => {
        stderr += data.toString();
      });
  
      // タイムアウト処理
      if (options.timeout) {
        timeoutId = setTimeout(() => {
          bash.kill();
          reject(new Error(`Command timed out after ${options.timeout}ms`));
        }, options.timeout);
      }
  
      // プロセス終了時の処理
      bash.on('close', (code) => {
        if (timeoutId) clearTimeout(timeoutId);
  
        console.error('bash process exited with code', code);
        resolve({
          stdout,
          stderr,
          exitCode: code !== null ? code : 1,
        });
      });
  
      bash.on('error', (error) => {
        if (timeoutId) clearTimeout(timeoutId);
  
        console.error('Failed to start bash process:', error);
        reject(error);
      });
  
      // コマンドを標準入力に書き込み、EOF を送信
      bash.stdin.write(command + '\n');
      bash.stdin.end();
    });
  }

• src/execute-bash-script-sync.ts:23-38 (schema)

  Input schema using Zod: command (string), options object with cwd (opt string), env (opt record), timeout (opt positive int).

  export const toolOptionsSchema = {
    command: z.string().describe('The bash script to execute'),
    options: z.object({
      cwd: z.string().optional().describe(`The working directory to execute the script.
  use this option argument to avoid cd command in the first line of the script.
  \`~\` and environment variable is not supported. use absolute path instead.
  `),
      env: z.record(z.string(), z.string()).optional()
        .describe(`The environment variables for the script.
  Set environment variables using this option instead of using export command in the script.
  `),
      timeout: z.number().int().positive().optional().describe(`The timeout in milliseconds.
  Set enough long timeout even if you don't need to set timeout to avoid unexpected blocking.
  `),
    }),
  };

• src/execute-bash-script-sync.ts:117-141 (registration)

  Registers the 'execute-bash-script-sync' tool on the MCP server with server.tool(), providing toolName, description, schema, and inline handler that calls executeCommand and returns stdout/stderr/exitCode as text contents.

  // Execute a shell command
  export function setTool(server: McpServer) {
    server.tool(toolName, toolDescription, toolOptionsSchema, async ({ command, options }) => {
      const { stdout, stderr, exitCode } = await executeCommand(command, options);
      return {
        content: [
          {
            type: 'text',
            text: `stdout: ${stdout}`,
            resource: undefined,
          },
          {
            type: 'text',
            text: `stderr: ${stderr}`,
            resource: undefined,
          },
          {
            type: 'text',
            text: `exitCode: ${exitCode}`,
            resource: undefined,
          },
        ],
      };
    });
  }

• src/index.ts:13-14 (registration)

  Calls setTool from execute-bash-script-sync to register the tool on the main MCP server instance.

  setSyncTool(server);
  setAsyncTool(server);

• src/execute-bash-script-sync.ts:7-15 (helper)

  Tool name constant and description string used in registration.

  export const toolName = 'execute-bash-script-sync';
  
  export const toolDescription = `This tool executes shell scripts synchronously in bash.
  Executing each command creates a new bash process.
  Synchronous execution requires to wait the scripts completed.
  Asynchronous execution makes it possible to execute multiple scripts in parallel.
  You can reduce waiting time by planning in advance which shell scripts need to be executed and executing them in parallel.
  Avoid using this execute-bash-script-sync tool unless you really need to, and use the execute-bash-script-async tool whenever possible.
  `;