XC-MCP: XCode CLI wrapper

Instructions

Implementation Reference

• src/tools/cache/clear.ts:56-109 (handler)

  The core handler function `clearCacheTool` that executes the cache clearing logic for simulator, project, response caches or all. Validates input and returns JSON confirmation with results.

  export async function clearCacheTool(args: any): Promise<ToolResult> {
    try {
      const { cacheType } = args as ClearCacheArgs;
  
      if (!['simulator', 'project', 'response', 'all'].includes(cacheType)) {
        throw new McpError(
          ErrorCode.InvalidParams,
          'cacheType must be one of: simulator, project, response, all'
        );
      }
  
      const results: Record<string, string> = {};
  
      if (cacheType === 'simulator' || cacheType === 'all') {
        simulatorCache.clearCache();
        results.simulator = 'Cleared successfully';
      }
  
      if (cacheType === 'project' || cacheType === 'all') {
        projectCache.clearCache();
        results.project = 'Cleared successfully';
      }
  
      if (cacheType === 'response' || cacheType === 'all') {
        responseCache.clear();
        results.response = 'Cleared successfully';
      }
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(
              {
                message: 'Cache cleared successfully',
                results,
                timestamp: new Date().toISOString(),
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to clear cache: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/tools/cache/clear.ts:7-9 (schema)

  TypeScript interface defining the input parameters for the cache-clear tool.

  interface ClearCacheArgs {
    cacheType: 'simulator' | 'project' | 'response' | 'all';
  }

• src/registry/cache.ts:20-46 (registration)

  Registration of the consolidated `cache` tool with MCP server, which routes `operation: 'clear'` to the clearCacheTool handler. 'cache-clear' is a legacy alias documented but not separately registered.

  server.registerTool(
    'cache',
    {
      description: getDescription(CACHE_DOCS, CACHE_DOCS_MINI),
      inputSchema: {
        operation: z.enum(['get-stats', 'get-config', 'set-config', 'clear']),
        cacheType: z.enum(['simulator', 'project', 'response', 'all']).optional(),
        maxAgeMs: z.number().optional(),
        maxAgeMinutes: z.number().optional(),
        maxAgeHours: z.number().optional(),
      },
      ...DEFER_LOADING_CONFIG,
    },
    async args => {
      try {
        await validateXcodeInstallation();
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        return (await cacheTool(args)) as any;
      } catch (error) {
        if (error instanceof McpError) throw error;
        throw new McpError(
          ErrorCode.InternalError,
          `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
        );
      }
    }
  );

• src/tools/cache/index.ts:60-97 (helper)

  Routing helper in `cacheTool` that dispatches `operation: 'clear'` to `clearCacheTool`, providing backwards compatibility for legacy `cache-clear` tool.

  async function routeOperation(args: CacheToolArgs) {
    const { operation } = args;
  
    switch (operation) {
      case 'get-stats':
        return getCacheStatsTool({});
      case 'get-config':
        if (!args.cacheType) {
          throw new McpError(
            ErrorCode.InvalidRequest,
            'cacheType is required for get-config operation'
          );
        }
        return getCacheConfigTool({ cacheType: args.cacheType });
      case 'set-config':
        if (!args.cacheType) {
          throw new McpError(
            ErrorCode.InvalidRequest,
            'cacheType is required for set-config operation'
          );
        }
        return setCacheConfigTool({
          cacheType: args.cacheType,
          maxAgeMs: args.maxAgeMs,
          maxAgeMinutes: args.maxAgeMinutes,
          maxAgeHours: args.maxAgeHours,
        });
      case 'clear':
        if (!args.cacheType) {
          throw new McpError(ErrorCode.InvalidRequest, 'cacheType is required for clear operation');
        }
        return clearCacheTool({ cacheType: args.cacheType });
      default:
        throw new McpError(
          ErrorCode.InvalidRequest,
          `Unknown operation: ${operation}. Valid operations: get-stats, get-config, set-config, clear`
        );
    }

• src/registry/cache.ts:24-31 (schema)

  Zod input schema validation for the `cache` tool, including validation for `clear` operation.

  inputSchema: {
    operation: z.enum(['get-stats', 'get-config', 'set-config', 'clear']),
    cacheType: z.enum(['simulator', 'project', 'response', 'all']).optional(),
    maxAgeMs: z.number().optional(),
    maxAgeMinutes: z.number().optional(),
    maxAgeHours: z.number().optional(),
  },
  ...DEFER_LOADING_CONFIG,