XC-MCP: XCode CLI wrapper

Instructions

Implementation Reference

• src/tools/cache/list-cached.ts:64-120 (handler)

  The core handler function for the 'list-cached-responses' tool. It processes arguments, retrieves cache stats and recent responses from responseCache, formats a JSON response with summaries, and returns MCP-formatted content.

  export async function listCachedResponsesTool(args: any) {
    const { tool, limit = 10 } = args as ListCachedArgs;
  
    try {
      const stats = responseCache.getStats();
  
      let recentResponses;
      if (tool) {
        recentResponses = responseCache.getRecentByTool(tool, limit);
      } else {
        // Get recent from all tools
        const allTools = Object.keys(stats.byTool);
        recentResponses = allTools
          .flatMap(toolName =>
            responseCache.getRecentByTool(toolName, Math.ceil(limit / allTools.length))
          )
          .sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime())
          .slice(0, limit);
      }
  
      const responseData = {
        cacheStats: stats,
        recentResponses: recentResponses.map(cached => ({
          id: cached.id,
          tool: cached.tool,
          timestamp: cached.timestamp,
          exitCode: cached.exitCode,
          outputSize: cached.fullOutput.length,
          stderrSize: cached.stderr.length,
          summary: cached.metadata.summary || {},
          projectPath: cached.metadata.projectPath,
          scheme: cached.metadata.scheme,
        })),
        usage: {
          totalCached: stats.totalEntries,
          availableTools: Object.keys(stats.byTool),
          note: 'Use xcodebuild-get-details with any ID to retrieve full details',
        },
      };
  
      const responseText = JSON.stringify(responseData, null, 2);
  
      return {
        content: [
          {
            type: 'text' as const,
            text: responseText,
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `list-cached-responses failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/tools/cache/list-cached.ts:4-7 (schema)

  Type definition for the tool's input parameters: optional tool filter and limit.

  interface ListCachedArgs {
    tool?: string;
    limit?: number;
  }

• src/tools/cache/list-cached.ts:122-162 (schema)

  Detailed markdown documentation for the tool, including parameters, returns, examples, and related tools. Serves as de facto schema description.

  export const CACHE_LIST_CACHED_RESPONSES_DOCS = `
  # list-cached-responses
  
  📋 **List cached build and test results with progressive disclosure** - View recent operations.
  
  Retrieve recent cached build/test results with ability to drill down into full logs via progressive disclosure pattern.
  
  ## Advantages
  
  • Access recent build and test results without re-running operations
  • Drill down into full logs using returned cache IDs
  • Filter by specific tool to find relevant operations
  • Understand cache age and expiry information
  
  ## Parameters
  
  ### Optional
  - \`limit\` (number, default: 10): Maximum number of cached responses to return
  - \`tool\` (string): Filter by specific tool (optional)
  
  ## Returns
  
  - List of recent cache entries with IDs
  - Summary information for each cached operation
  - Cache expiry times
  - References for accessing full details
  
  ## Related Tools
  
  - \`xcodebuild-get-details\` - Retrieve full build logs from cache ID
  - \`xcodebuild-test\` - Run tests (generates new cache entries)
  - \`cache-get-stats\` - View cache performance statistics
  - \`cache-clear\` - Clear specific caches
  
  ## Notes
  
  - Returns summaries only to avoid token waste
  - Use returned cache IDs with xcodebuild-get-details for full output
  - Ordered by recency (most recent first)
  - Limited to reduce response token usage
  `;

• src/tools/docs-registry.ts:591-592 (registration)

  Registration of the tool's documentation in the central TOOL_DOCS map used by the rtfm/get-tool-docs tool.

  'list-cached-responses': CACHE_LIST_CACHED_RESPONSES_DOCS,

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

  Reference to the tool in the consolidated cache tool documentation.

  - \`list-cached-responses\`: View cached response IDs