mcp-cli-exec MCP Server

Instructions

Implementation Reference

• src/server.ts:106-163 (handler)

  Main handler logic for the cli-exec-raw tool. It validates the input, executes the raw command using the CommandExecutor, measures duration, formats the output as CommandResult, and returns it as JSON-formatted text content. Handles execution errors by returning an error-formatted result.

  case 'cli-exec-raw': {
    if (!isValidExecRawArgs(request.params.arguments)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid execution arguments'
      );
    }
  
    try {
      const startTime = Date.now();
      const result = await this.executor.executeCommand(
        request.params.arguments.command,
        undefined,
        request.params.arguments.timeout
      );
      const duration = Date.now() - startTime;
  
      const formattedResult: CommandResult = {
        command: request.params.arguments.command,
        success: result.exitCode === 0,
        exitCode: result.exitCode,
        stdout: result.stdout,
        stderr: result.stderr,
        duration,
        workingDirectory: process.cwd(),
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(formattedResult, null, 2),
          },
        ],
      };
    } catch (error) {
      const errorResult: CommandResult = {
        command: request.params.arguments.command,
        success: false,
        exitCode: -1,
        stdout: '',
        stderr: '',
        error: error instanceof Error ? error.message : String(error),
        duration: 0,
        workingDirectory: process.cwd(),
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(errorResult, null, 2),
          },
        ],
        isError: true,
      };
    }
  }

• src/server.ts:47-65 (registration)

  Tool registration in the ListTools response, defining the name, description, and input schema for cli-exec-raw.

  {
    name: 'cli-exec-raw',
    description: 'Execute a raw CLI command and return structured output',
    inputSchema: {
      type: 'object',
      properties: {
        command: {
          type: 'string',
          description: 'The CLI command to execute',
        },
        timeout: {
          type: 'number',
          description: 'Optional timeout in milliseconds (default: 5 minutes)',
          minimum: 0,
        },
      },
      required: ['command'],
    },
  },

• src/types.ts:18-21 (schema)

  TypeScript interface defining the input arguments for cli-exec-raw.

  export interface ExecRawArgs {
    command: string;
    timeout?: number;
  }

• src/executor.ts:6-33 (helper)

  Core helper method that performs the actual CLI command execution using execa, with ANSI stripping, timeout handling, and optional cwd. Used by the cli-exec-raw handler.

  async executeCommand(
    command: string,
    cwd?: string,
    timeout?: number
  ): Promise<{ exitCode: number; stdout: string; stderr: string, cwd:string }> {
    try {
    
      const result = await execa(command, [], {
        cwd: cwd,
        shell: true,
        timeout: timeout || DEFAULT_TIMEOUT,
        reject: false,
        all: true,
      });
  
      return {
        exitCode: result.exitCode ?? -1,
        stdout: stripAnsi(result.stdout ?? ''),
        stderr: stripAnsi(result.stderr ?? ''),
        cwd:result.cwd
      };
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Command execution failed: ${error.message}`);
      }
      throw error;
    }
  }

• src/validation.ts:3-7 (helper)

  Validation function for cli-exec-raw input arguments, ensuring command is string and timeout is optional number.

  export const isValidExecRawArgs = (args: any): args is ExecRawArgs =>
    typeof args === 'object' &&
    args !== null &&
    typeof args.command === 'string' &&
    (args.timeout === undefined || typeof args.timeout === 'number');