Mac Shell MCP Server

Instructions

Implementation Reference

• src/index.ts:326-357 (handler)

  The primary handler for the 'add_to_whitelist' MCP tool. Validates input parameters using Zod, maps the security level string to the CommandSecurityLevel enum, delegates to CommandService.addToWhitelist, and returns a formatted success response.

  private async handleAddToWhitelist(args: unknown) {
    const schema = z.object({
      command: z.string(),
      securityLevel: z.enum(['safe', 'requires_approval', 'forbidden']),
      description: z.string().optional(),
    });
  
    const { command, securityLevel, description } = schema.parse(args);
  
    // Map string security level to enum
    const securityLevelEnum =
      securityLevel === 'safe'
        ? CommandSecurityLevel.SAFE
        : securityLevel === 'requires_approval'
          ? CommandSecurityLevel.REQUIRES_APPROVAL
          : CommandSecurityLevel.FORBIDDEN;
  
    this.commandService.addToWhitelist({
      command,
      securityLevel: securityLevelEnum,
      description,
    });
  
    return {
      content: [
        {
          type: 'text',
          text: `Command '${command}' added to whitelist with security level '${securityLevel}'`,
        },
      ],
    };
  }

• src/index.ts:120-141 (registration)

  The tool registration entry in the ListTools response, defining the tool name, description, and JSON input schema for validation.

    name: 'add_to_whitelist',
    description: 'Add a command to the whitelist',
    inputSchema: {
      type: 'object',
      properties: {
        command: {
          type: 'string',
          description: 'The command to whitelist',
        },
        securityLevel: {
          type: 'string',
          enum: ['safe', 'requires_approval', 'forbidden'],
          description: 'Security level for the command',
        },
        description: {
          type: 'string',
          description: 'Description of the command',
        },
      },
      required: ['command', 'securityLevel'],
    },
  },

• src/services/command-service.ts:23-32 (schema)

  TypeScript interface defining the structure of a whitelist entry, used as input to addToWhitelist.

  export interface CommandWhitelistEntry {
    /** The command path or name */
    command: string;
    /** Security level of the command */
    securityLevel: CommandSecurityLevel;
    /** Allowed arguments (string for exact match, RegExp for pattern match) */
    allowedArgs?: Array<string | RegExp>;
    /** Description of the command for documentation */
    description?: string;
  }

• src/services/command-service.ts:209-211 (helper)

  The core utility method in CommandService that stores the new whitelist entry in the internal Map.

  public addToWhitelist(entry: CommandWhitelistEntry): void {
    this.whitelist.set(entry.command, entry);
  }

• src/services/command-service.ts:11-18 (schema)

  Enum defining possible security levels for whitelisted commands, used throughout the implementation.

  export enum CommandSecurityLevel {
    /** Safe commands that can be executed without approval */
    SAFE = 'safe',
    /** Commands that require approval before execution */
    REQUIRES_APPROVAL = 'requires_approval',
    /** Commands that are explicitly forbidden */
    FORBIDDEN = 'forbidden',
  }