Shell-MCP

Instructions

Implementation Reference

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

  MCP CallToolRequestSchema handler for shell_lspci: converts tool name to allowlist key, retrieves lspci command config, validates args, executes via executor, streams stdout 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-44 (registration)

  Registers the shell_lspci tool (transforms 'shell.lspci' key to 'shell_lspci' name) with description and input schema in ListToolsRequestSchema handler.

  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/config/allowlist.ts:124-135 (schema)

  Schema/configuration for shell.lspci tool: maps to 'lspci' command, provides description, allowed arguments, and timeout.

  'shell.lspci': {
    command: 'lspci',
    description: 'List PCI devices',
    allowedArgs: [
      '-v',     // verbose
      '-k',     // kernel drivers
      '-mm',    // machine readable
      '-nn',    // show vendor/device codes
      '--help'
    ],
    timeout: 2000
  },

• src/core/executor.ts:31-139 (handler)

  Core execution handler: spawns child_process for lspci command with args, handles timeout/signal, returns stdout stream.

  async execute(
    command: string,
    args: string[] = [],
    options: ExecuteOptions = {}
  ): Promise<{ stdout: Readable }> {
    const commandKey = `${command} ${args.join(' ')}`;
    
    try {
      // Check security
      await this.securityChecker.validateCommand(command, args, options);
  
      // Check cache
      const cached = this.cache.get(commandKey);
      if (cached) {
        this.logger.debug('Using cached command result', { command, args });
        return this.createStreamFromCache(cached);
      }
  
      // Remove 'shell.' prefix for execution
      const baseCommand = command.replace('shell.', '');
  
      // Execute command
      this.logger.debug('Starting command execution', { command, args, options });
      const childProcess = spawn(baseCommand, args, {
        stdio: ['ignore', 'pipe', 'pipe'],
        timeout: options.timeout,
        cwd: options.cwd,
        env: {
          ...process.env,
          ...options.env
        },
        signal: options.signal
      });
  
      this.currentProcess = childProcess;
  
      // Error handling
      childProcess.on('error', (error: Error) => {
        this.logger.error('Command execution error', {
          command,
          args,
          error: error.message
        });
        throw new ToolError(
          'PROCESS_ERROR',
          'Command execution error',
          { command, args, error: error.message }
        );
      });
  
      // Timeout handling
      if (options.timeout) {
        setTimeout(() => {
          if (childProcess.exitCode === null) {
            this.logger.warn('Command execution timeout', {
              command,
              args,
              timeout: options.timeout
            });
            childProcess.kill();
            throw new ToolError(
              'TIMEOUT',
              'Command execution timeout',
              { command, args, timeout: options.timeout }
            );
          }
        }, options.timeout);
      }
  
      if (!childProcess.stdout) {
        throw new ToolError(
          'STREAM_ERROR',
          'Unable to get command output stream',
          { command, args }
        );
      }
  
      // Monitor process status
      childProcess.on('exit', (code, signal) => {
        this.logger.debug('Command execution completed', {
          command,
          args,
          exitCode: code,
          signal
        });
      });
  
      return {
        stdout: childProcess.stdout
      };
  
    } catch (error) {
      this.logger.error('Command execution failed', {
        command,
        args,
        error: error instanceof Error ? error.message : String(error)
      });
      
      throw new ToolError(
        'EXECUTION_ERROR',
        'Command execution failed',
        { 
          command, 
          args, 
          error: error instanceof Error ? error.message : String(error)
        }
      );
    }
  }

• src/core/validator.ts:11-59 (helper)

  Validates command and arguments against allowlist config before execution.

  validateCommand(
    command: string, 
    args: string[] = [], 
    options: CommandOptions = {}
  ): void {
    console.log('Validating command:', {
      command,
      args,
      baseCommand: command.replace('shell.', ''),
      fullCommand: `shell.${command.replace('shell.', '')}`,
      config: allowedCommands[`shell.${command.replace('shell.', '')}`]
    });
  
    const baseCommand = command.replace('shell.', '');
    
    if (!(`shell.${baseCommand}` in allowedCommands)) {
      throw new Error(`Command not allowed: ${command}`);
    }
    
    const config = allowedCommands[`shell.${baseCommand}`];
    
    const allowedArgs = config.allowedArgs || [];
    
    console.log('Checking args:', {
      allowedArgs,
      hasWildcard: allowedArgs.includes('*')
    });
  
    args.forEach(arg => {
      if (arg.startsWith('-')) {
        if (!allowedArgs.includes(arg)) {
          console.log('Invalid option:', arg);
          throw new Error(`Invalid argument: ${arg}`);
        }
      }
      else if (!allowedArgs.includes('*')) {
        console.log('Path not allowed:', arg);
        throw new Error(`Invalid argument: ${arg}`);
      } else {
        // 檢查路徑參數
        this.validatePath(arg);
      }
    });
    
    // 檢查超時設定
    if (options.timeout && options.timeout > securityConfig.defaultTimeout) {
      throw new Error(`Timeout exceeds maximum allowed value`);
    }
  }