mcp-server-commands

Instructions

Implementation Reference

• src/run-command.ts:25-75 (handler)

  The core handler function `runCommand` that parses args, executes the shell command using `execute` (which uses child_process.exec or execFileWithInput), handles workdir and stdin, catches errors, and returns formatted CallToolResult.
  export type RunCommandArgs = Record<string, unknown> | undefined; export async function runCommand(args: RunCommandArgs): Promise<CallToolResult> { const command = args?.command as string; if (!command) { const message = "Command is required, current value: " + command; return { isError: true, content: [{ type: "text", text: message }], }; } const options: ObjectEncodingOptions & ExecOptions = { encoding: "utf8" }; if (args?.workdir) { options.cwd = String(args.workdir); } const stdin = args?.stdin as string; try { const result = await execute(command, stdin, options); return { content: messagesFor(result), }; } catch (error) { // PRN do I want to differentiate non-command related error (i.e. if messagesFor blows up // or presumably if smth else goes wrong with the node code in exec that isn't command related // if so, write a test first // console.log("ERROR_runCommand", error); // ExecException (error + stdout/stderr) merged // - IIUC this happens on uncaught failures // - but if you catch an exec() promise failure (or use exec's callback) => you get separated values: error, stdout, stderr // - which is why I mirror this response type in my reject(error) calls // // 'error' example: // code: 127, // killed: false, // signal: null, // cmd: 'nonexistentcommand', // stdout: '', // stderr: '/bin/sh: nonexistentcommand: command not found\n' const response = { isError: true, content: messagesFor(error as ExecResult), }; always_log("WARN: run_command failed", response); return response; } }
• src/tools.ts:17-44 (schema)

  The input schema definition for the run_command tool, including properties for command (required), workdir, and stdin.
  name: "run_command", description: "Run a command on this " + os.platform() + " machine", inputSchema: { type: "object", properties: { command: { type: "string", description: "Command with args", }, workdir: { // previous run_command calls can probe the filesystem and find paths to change to type: "string", description: "Optional, current working directory", }, stdin: { type: "string", description: "Optional, text to pipe into the command's STDIN. For example, pass a python script to python3. Or, pass text for a new file to the cat command to create it!", }, // args to consider: // - env - obscure cases where command takes a param only via an env var? // - timeout - lets just hard code this for now }, required: ["command"], }, },
• src/tools.ts:11-62 (registration)

  The `reisterTools` function that registers the run_command tool on the MCP server by handling ListToolsRequestSchema (listing the tool with schema) and CallToolRequestSchema (dispatching calls to runCommand based on name).
  export function reisterTools(server: Server) { server.setRequestHandler(ListToolsRequestSchema, async () => { verbose_log("INFO: ListTools"); return { tools: [ { name: "run_command", description: "Run a command on this " + os.platform() + " machine", inputSchema: { type: "object", properties: { command: { type: "string", description: "Command with args", }, workdir: { // previous run_command calls can probe the filesystem and find paths to change to type: "string", description: "Optional, current working directory", }, stdin: { type: "string", description: "Optional, text to pipe into the command's STDIN. For example, pass a python script to python3. Or, pass text for a new file to the cat command to create it!", }, // args to consider: // - env - obscure cases where command takes a param only via an env var? // - timeout - lets just hard code this for now }, required: ["command"], }, }, ], }; }); server.setRequestHandler( CallToolRequestSchema, async (request): Promise<CallToolResult> => { verbose_log("INFO: ToolRequest", request); switch (request.params.name) { case "run_command": { return await runCommand(request.params.arguments); } default: throw new Error("Unknown tool"); } } ); }