XC-MCP: XCode CLI wrapper

Instructions

Implementation Reference

• src/tools/cache/get-stats.ts:58-85 (handler)

  Core handler function that aggregates and returns statistics from all caching systems (simulator, project, response) as formatted JSON.

  export async function getCacheStatsTool(_args: any): Promise<ToolResult> {
    try {
      const simulatorStats = simulatorCache.getCacheStats();
      const projectStats = projectCache.getCacheStats();
      const responseStats = responseCache.getStats();
  
      const stats = {
        simulator: simulatorStats,
        project: projectStats,
        response: responseStats,
        timestamp: new Date().toISOString(),
      };
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(stats, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to get cache stats: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

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

  Registers the 'cache' MCP tool which routes 'get-stats' operation to the cache-get-stats implementation. Provides backwards compatibility for the legacy tool name.

  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/registry/cache.ts:24-31 (schema)

  Zod schema defining input parameters for cache operations, including 'get-stats' which requires no additional arguments.

  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,

• src/tools/cache/index.ts:64-66 (helper)

  Operation router in consolidated cacheTool that invokes the specific getCacheStatsTool handler for 'get-stats'.

  case 'get-stats':
    return getCacheStatsTool({});
  case 'get-config':

• src/tools/cache/get-stats.ts:87-128 (helper)

  Embedded documentation for the cache-get-stats tool, including usage examples and parameter details.

  export const CACHE_GET_STATS_DOCS = `
  # cache-get-stats
  
  📊 **Get comprehensive statistics across all XC-MCP cache systems** - Monitor cache performance and effectiveness.
  
  Retrieves detailed statistics from the simulator cache, project cache, and response cache systems. Shows hit rates, entry counts, storage usage, and performance metrics across all caching layers. Essential for monitoring cache effectiveness and identifying optimization opportunities.
  
  ## Advantages
  
  • Monitor cache performance across all simulator, project, and response caches
  • Understand cache hit rates to optimize build and test workflows
  • Track memory usage and identify tuning opportunities
  • Debug performance issues by analyzing cache patterns
  
  ## Parameters
  
  ### Required
  - (None - retrieves statistics from all cache systems automatically)
  
  ### Optional
  - (None)
  
  ## Returns
  
  - Tool execution results with structured cache statistics
  - Statistics for each cache system (simulator, project, response)
  - Hit rates, entry counts, and performance metrics
  - Timestamp of statistics collection
  
  ## Related Tools
  
  - cache-set-config: Configure cache retention times
  - cache-get-config: Get current cache configuration
  - cache-clear: Clear cached data
  
  ## Notes
  
  - Tool is auto-registered with MCP server
  - Statistics are calculated in real-time
  - Use regularly to monitor cache effectiveness
  - Export statistics for performance analysis across time
  `;