Remote Command MCP Server

Instructions

Implementation Reference

• src/index.ts:171-235 (handler)

  Handler for CallToolRequestSchema that specifically handles 'execute_remote_command': validates args, sanitizes/normalizes command, executes it, and returns stdout/stderr or error.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name !== 'execute_remote_command') {
      throw new McpError(
        ErrorCode.MethodNotFound,
        `Unknown tool: ${request.params.name}`
      );
    }
  
    if (!isValidExecArgs(request.params.arguments)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid command execution arguments'
      );
    }
  
    try {
      // Sanitize and normalize the command
      const sanitizedCmd = sanitizeCommand(request.params.arguments.command);
      const normalizedCmd = normalizeCommand(sanitizedCmd);
  
      const { stdout, stderr } = await this.executeCommand(
        normalizedCmd,
        request.params.arguments.cwd
      );
  
      // Combine stdout and stderr in the response
      const output = [];
      
      if (stdout.trim()) {
        output.push(stdout.trim());
      }
      
      if (stderr.trim()) {
        output.push('STDERR:', stderr.trim());
      }
  
      return {
        content: [
          {
            type: 'text',
            text: output.join('\n') || 'Command completed successfully (no output)',
          },
        ],
      };
    } catch (error: any) {
      // Enhanced error handling with more details
      const errorMessage = [
        'Command execution error:',
        `Command: ${request.params.arguments.command}`,
        `Error: ${error?.message || 'Unknown error'}`
      ];
  
      console.error('Command failed:', error);  // Debug log
  
      return {
        content: [
          {
            type: 'text',
            text: errorMessage.join('\n'),
          },
        ],
        isError: true,
      };
    }
  });

• src/index.ts:153-166 (schema)

  Input schema definition for the execute_remote_command tool, specifying command (required) and optional cwd.

  inputSchema: {
    type: 'object',
    properties: {
      command: {
        type: 'string',
        description: 'Command to execute',
      },
      cwd: {
        type: 'string',
        description: 'Working directory for command execution',
      },
    },
    required: ['command'],
  },

• src/index.ts:148-169 (registration)

  Registration of the execute_remote_command tool in the ListTools response.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'execute_remote_command',
        description: 'Execute a command on the host machine',
        inputSchema: {
          type: 'object',
          properties: {
            command: {
              type: 'string',
              description: 'Command to execute',
            },
            cwd: {
              type: 'string',
              description: 'Working directory for command execution',
            },
          },
          required: ['command'],
        },
      },
    ],
  }));

• src/index.ts:84-144 (helper)

  Core helper method that executes the sanitized command using exec or spawn, handles pipes, timeouts, stdout/stderr capture, cross-platform.

  private executeCommand(command: string, cwd?: string): Promise<{ stdout: string; stderr: string }> {
    return new Promise((resolve, reject) => {
      let timeout: NodeJS.Timeout | null = null;
  
      // Set timeout
      timeout = setTimeout(() => {
        reject(new Error(`Command timed out after ${COMMAND_TIMEOUT/1000} seconds`));
      }, COMMAND_TIMEOUT);
  
      // Use exec for commands with pipes, spawn for simple commands
      if (command.includes('|')) {
        execPromise(command, {
          cwd,
          shell: isWindows ? 'cmd.exe' : '/bin/sh',
          timeout: COMMAND_TIMEOUT,
          windowsHide: true
        }).then(({ stdout, stderr }) => {
          if (timeout) clearTimeout(timeout);
          resolve({ stdout, stderr });
        }).catch((error) => {
          if (timeout) clearTimeout(timeout);
          reject(error);
        });
      } else {
        const shell = isWindows ? 'cmd.exe' : '/bin/sh';
        const args = isWindows ? ['/c', command] : ['-c', command];
        
        console.error(`Executing command: ${command} (${shell} ${args.join(' ')})`);  // Debug log
  
        const child = spawn(shell, args, {
          cwd,
          shell: true,
          windowsHide: true
        });
  
        let stdout = '';
        let stderr = '';
  
        child.stdout.on('data', (data) => {
          stdout += data.toString();
        });
  
        child.stderr.on('data', (data) => {
          stderr += data.toString();
        });
  
        child.on('error', (error) => {
          if (timeout) clearTimeout(timeout);
          reject(error);
        });
  
        child.on('close', (code) => {
          if (timeout) clearTimeout(timeout);
          if (code === 0 || stdout.length > 0) { // Consider command successful if there's output even with non-zero exit code
            resolve({ stdout, stderr });
          } else {
            reject(new Error(`Command failed with exit code ${code}${stderr ? ': ' + stderr : ''}`));
          }
        });
      }
    });

• src/index.ts:30-42 (helper)

  Helper to sanitize the command by removing null bytes, semicolons (unix), and || operators to prevent injection.

  const sanitizeCommand = (command: string): string => {
    // Remove any null bytes that could be used for command injection
    command = command.replace(/\0/g, '');
    
    // Only remove malicious command chaining while preserving pipes
    if (isWindows) {
      command = command.replace(/\|\|/g, '');  // Remove OR operator but keep pipes
    } else {
      command = command.replace(/;/g, '').replace(/\|\|/g, '');  // Remove semicolon and OR operator
    }
    
    return command;
  };