Mac Shell MCP Server

Instructions

Implementation Reference

• src/index.ts:268-305 (handler)

  MCP tool handler for 'execute_command': validates input with Zod, delegates to CommandService.executeCommand, formats stdout/stderr response or error.

  private async handleExecuteCommand(args: unknown) {
    const schema = z.object({
      command: z.string(),
      args: z.array(z.string()).optional(),
    });
  
    const { command, args: commandArgs = [] } = schema.parse(args);
  
    try {
      const result = await this.commandService.executeCommand(command, commandArgs);
  
      return {
        content: [
          {
            type: 'text',
            text: result.stdout,
          },
          {
            type: 'text',
            text: result.stderr ? `Error output: ${result.stderr}` : '',
          },
        ],
      };
    } catch (error) {
      if (error instanceof Error) {
        return {
          content: [
            {
              type: 'text',
              text: `Command execution failed: ${error.message}`,
            },
          ],
          isError: true,
        };
      }
      throw error;
    }
  }

• src/index.ts:93-109 (schema)

  Input schema definition for 'execute_command' tool as provided in ListTools response.

  inputSchema: {
    type: 'object',
    properties: {
      command: {
        type: 'string',
        description: 'The command to execute',
      },
      args: {
        type: 'array',
        items: {
          type: 'string',
        },
        description: 'Command arguments',
      },
    },
    required: ['command'],
  },

• src/index.ts:90-110 (registration)

  Registration of 'execute_command' tool in the ListTools handler, including name, description, and schema.

  {
    name: 'execute_command',
    description: 'Execute a shell command on macOS',
    inputSchema: {
      type: 'object',
      properties: {
        command: {
          type: 'string',
          description: 'The command to execute',
        },
        args: {
          type: 'array',
          items: {
            type: 'string',
          },
          description: 'Command arguments',
        },
      },
      required: ['command'],
    },
  },

• src/services/command-service.ts:308-348 (helper)

  Core helper method implementing command execution logic: whitelist validation, approval queuing for risky commands, direct execution for safe ones using child_process.execFile.

  public async executeCommand(
    command: string,
    args: string[] = [],
    options: {
      timeout?: number;
      requestedBy?: string;
    } = {},
  ): Promise<CommandResult> {
    const securityLevel = this.validateCommand(command, args);
  
    // If command is not whitelisted, reject
    if (securityLevel === null) {
      throw new Error(`Command not whitelisted: ${command}`);
    }
  
    // If command is forbidden, reject
    if (securityLevel === CommandSecurityLevel.FORBIDDEN) {
      throw new Error(`Command is forbidden: ${command}`);
    }
  
    // If command requires approval, add to pending queue
    if (securityLevel === CommandSecurityLevel.REQUIRES_APPROVAL) {
      return this.queueCommandForApproval(command, args, options.requestedBy);
    }
  
    // For safe commands, execute immediately
    try {
      const timeout = options.timeout || this.defaultTimeout;
      const { stdout, stderr } = await execFileAsync(command, args, {
        timeout,
        shell: this.shell,
      });
  
      return { stdout, stderr };
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Command execution failed: ${error.message}`);
      }
      throw error;
    }
  }