Shell-MCP

Instructions

Implementation Reference

• src/index.ts:45-85 (handler)

  Generic handler for calling shell tools like shell_find. Resolves 'shell_find' to 'shell.find' from allowedCommands, validates arguments, executes the 'find' command via CommandExecutor, and streams the output.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      const command = String(request.params?.name || '');
      const fullCommand = `shell.${command.replace('shell_', '')}`;  // Replace shell_ back to shell.
      
      if (!(fullCommand in allowedCommands)) {
        return {
          content: [{ type: "text", text: `Unknown command: ${command}` }],
          isError: true
        };
      }
      
      const actualCommand = allowedCommands[fullCommand].command;
      const args = Array.isArray(request.params?.arguments?.args)
        ? request.params.arguments.args.map(String)
        : [];
    
      validator.validateCommand(actualCommand, args);
      const stream = await executor.execute(actualCommand, args);
    
      return {
        content: [{
          type: "text",
          text: await new Promise((resolve, reject) => {
            const chunks: Buffer[] = [];
            stream.stdout.on('data', (chunk: Buffer) => chunks.push(chunk));
            stream.stdout.on('end', () => resolve(Buffer.concat(chunks).toString()));
            stream.stdout.on('error', reject);
          })
        }]
      };
    } catch (error) {
      return {
        content: [{ 
          type: "text", 
          text: `Command execution failed: ${error instanceof Error ? error.message : String(error)}` 
        }],
        isError: true
      };
    }
  });

• src/index.ts:27-43 (registration)

  Registers all available tools by mapping allowedCommands to MCP tools, transforming keys like 'shell.find' to 'shell_find'.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    const tools = Object.entries(allowedCommands).map(([name, config]) => ({
      name: name.replace('shell.', 'shell_'),  // Replace shell. with shell_
      description: config.description,
      inputSchema: {
        type: "object",
        properties: {
          args: {
            type: "array",
            items: { type: "string" },
            description: "Command arguments"
          }
        }
      }
    }));
    return { tools };
  });

• src/index.ts:32-40 (schema)

  Input schema for shell_find and other shell tools: object with 'args' array of strings.

    type: "object",
    properties: {
      args: {
        type: "array",
        items: { type: "string" },
        description: "Command arguments"
      }
    }
  }

• src/config/allowlist.ts:95-109 (helper)

  Configuration for the 'shell.find' command, which is mapped to tool 'shell_find'. Defines the executable command, description, allowed arguments, and timeout.

  'shell.find': {
    command: 'find',
    description: 'Search for files in a directory hierarchy',
    allowedArgs: [
      '-name',
      '-type',
      '-size',
      '-mtime',
      '-maxdepth',
      '-mindepth',
      '-ls',
      '*'      // allow paths and patterns
    ],
    timeout: 10000
  },