XC-MCP: XCode CLI wrapper

Instructions

Implementation Reference

• src/tools/simctl/list.ts:70-192 (handler)

  The main handler function `simctlListTool` that implements the core logic for the 'simctl-list' tool, including caching, filtering, progressive disclosure, and device limiting.

  export async function simctlListTool(args: any) {
    const {
      deviceType,
      runtime,
      availability = 'available',
      outputFormat = 'json',
      concise = true,
      max = 5,
    } = args as SimctlListArgs;
  
    try {
      // Use the new caching system
      const cachedList = await simulatorCache.getSimulatorList();
  
      let responseData: Record<string, unknown> | string;
  
      // Use progressive disclosure by default (concise=true)
      if (concise && outputFormat === 'json') {
        // Generate concise summary
        const summary = extractSimulatorSummary(cachedList);
  
        // Store full output in response cache
        const cacheId = responseCache.store({
          tool: 'simctl-list',
          fullOutput: JSON.stringify(cachedList, null, 2),
          stderr: '',
          exitCode: 0,
          command: 'simctl list -j',
          metadata: {
            totalDevices: summary.totalDevices,
            availableDevices: summary.availableDevices,
            hasFilters: !!(deviceType || runtime || availability !== 'available'),
          },
        });
  
        // Return progressive disclosure response
        responseData = createProgressiveSimulatorResponse(summary, cacheId, {
          deviceType,
          runtime,
          availability,
        });
      } else {
        // Legacy mode: return full filtered list with device limiting
        if (outputFormat === 'json') {
          // Apply filters if specified
          const filteredList = filterCachedSimulatorList(cachedList, {
            deviceType,
            runtime,
            availability,
          });
  
          // Limit devices to max count, sorted by lastUsed date
          const allDevices: Array<{ runtime: string; device: SimulatorInfo }> = [];
          for (const [runtimeKey, devices] of Object.entries(filteredList.devices)) {
            devices.forEach(device => {
              allDevices.push({ runtime: runtimeKey, device });
            });
          }
  
          // Sort by lastUsed date descending (most recent first), nulls at end
          allDevices.sort((a, b) => {
            if (!a.device.lastUsed && !b.device.lastUsed) return 0;
            if (!a.device.lastUsed) return 1;
            if (!b.device.lastUsed) return -1;
            return b.device.lastUsed.getTime() - a.device.lastUsed.getTime();
          });
  
          // Take first max devices
          const limitedDevices = allDevices.slice(0, max);
  
          // Reconstruct grouped structure with limited devices
          const limitedDevicesByRuntime: { [runtime: string]: SimulatorInfo[] } = {};
          for (const { runtime: runtimeKey, device } of limitedDevices) {
            if (!limitedDevicesByRuntime[runtimeKey]) {
              limitedDevicesByRuntime[runtimeKey] = [];
            }
            limitedDevicesByRuntime[runtimeKey].push(device);
          }
  
          responseData = {
            devices: limitedDevicesByRuntime,
            runtimes: filteredList.runtimes,
            devicetypes: filteredList.devicetypes,
            lastUpdated: filteredList.lastUpdated.toISOString(),
            metadata: {
              totalDevicesInCache: Object.values(filteredList.devices).flat().length,
              devicesReturned: limitedDevices.length,
              limitApplied: max,
            },
          };
        } else {
          // For text format, we need to convert back to original format
          responseData =
            `Simulator List (cached at ${cachedList.lastUpdated.toISOString()}):\n` +
            JSON.stringify(cachedList, null, 2);
        }
      }
  
      const responseText =
        outputFormat === 'json'
          ? JSON.stringify(responseData, null, 2)
          : typeof responseData === 'string'
            ? responseData
            : JSON.stringify(responseData, null, 2);
  
      return {
        content: [
          {
            type: 'text' as const,
            text: responseText,
          },
        ],
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `simctl-list failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/registry/simctl.ts:49-77 (registration)

  The `registerSimctlListTool` function that registers the 'simctl-list' tool with the MCP server, including the handler wrapper and input schema.

  export function registerSimctlListTool(server: McpServer): void {
    server.registerTool(
      'simctl-list',
      {
        description: getDescription(SIMCTL_LIST_DOCS, SIMCTL_LIST_DOCS_MINI),
        inputSchema: {
          deviceType: z.string().optional(),
          runtime: z.string().optional(),
          availability: z.enum(['available', 'unavailable', 'all']).default('available'),
          outputFormat: z.enum(['json', 'text']).default('json'),
          concise: z.boolean().default(true),
          max: z.number().default(5),
        },
        ...DEFER_LOADING_CONFIG,
      },
      async args => {
        try {
          await validateXcodeInstallation();
          return await simctlListTool(args);
        } 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/simctl/list.ts:14-192 (schema)

  TypeScript interface `SimctlListArgs` defining the input parameters for the tool, matching the Zod schema in registration.

  interface SimctlListArgs {
    deviceType?: string;
    runtime?: string;
    availability?: 'available' | 'unavailable' | 'all';
    outputFormat?: OutputFormat;
    concise?: boolean;
    max?: number;
  }
  
  /**
   * List iOS simulators with intelligent progressive disclosure and caching
   *
   * **What it does:**
   * Retrieves comprehensive simulator information including devices, runtimes, and device types.
   * Returns concise summaries by default with cache IDs for progressive access to full details,
   * preventing token overflow while maintaining complete functionality.
   *
   * **Why you'd use it:**
   * - Prevents token overflow with 10k+ device lists via progressive disclosure
   * - Shows booted devices and recently used simulators first for faster workflows
   * - 1-hour intelligent caching eliminates redundant queries
   * - Provides smart filtering by device type, runtime, and availability
   * - Limits full output to most recently used devices for efficient browsing
   *
   * **Parameters:**
   * - `deviceType` (string, optional): Filter by device type (e.g., "iPhone", "iPad")
   * - `runtime` (string, optional): Filter by iOS runtime version (e.g., "17", "iOS 17.0")
   * - `availability` (string, optional): Filter by availability ("available", "unavailable", "all")
   * - `outputFormat` (string, optional): Output format ("json" or "text")
   * - `concise` (boolean, optional): Return concise summary with cache ID (default: true)
   * - `max` (number, optional): Maximum devices to return in full mode (default: 5, sorted by lastUsed)
   *
   * **Returns:**
   * - Concise mode: Summary with cacheId for detailed retrieval via simctl-get-details
   * - Full mode: Limited device list (default 5 most recently used) with metadata about limiting
   *
   * **Example:**
   * ```typescript
   * // Get concise summary (default - prevents token overflow)
   * await simctlListTool({})
   *
   * // Get full list for iPhone devices (limited to 5 most recent)
   * await simctlListTool({ deviceType: "iPhone", concise: false })
   *
   * // Get full list with custom limit
   * await simctlListTool({ concise: false, max: 10 })
   *
   * // Filter by iOS version
   * await simctlListTool({ runtime: "17.0" })
   * ```
   *
   * **Full documentation:** See simctl/list.md for detailed parameters and progressive disclosure
   *
   * @param args Tool arguments including optional filters, format, and max device limit
   * @returns Tool result with simulator list or summary with cache ID
   */
  export async function simctlListTool(args: any) {
    const {
      deviceType,
      runtime,
      availability = 'available',
      outputFormat = 'json',
      concise = true,
      max = 5,
    } = args as SimctlListArgs;
  
    try {
      // Use the new caching system
      const cachedList = await simulatorCache.getSimulatorList();
  
      let responseData: Record<string, unknown> | string;
  
      // Use progressive disclosure by default (concise=true)
      if (concise && outputFormat === 'json') {
        // Generate concise summary
        const summary = extractSimulatorSummary(cachedList);
  
        // Store full output in response cache
        const cacheId = responseCache.store({
          tool: 'simctl-list',
          fullOutput: JSON.stringify(cachedList, null, 2),
          stderr: '',
          exitCode: 0,
          command: 'simctl list -j',
          metadata: {
            totalDevices: summary.totalDevices,
            availableDevices: summary.availableDevices,
            hasFilters: !!(deviceType || runtime || availability !== 'available'),
          },
        });
  
        // Return progressive disclosure response
        responseData = createProgressiveSimulatorResponse(summary, cacheId, {
          deviceType,
          runtime,
          availability,
        });
      } else {
        // Legacy mode: return full filtered list with device limiting
        if (outputFormat === 'json') {
          // Apply filters if specified
          const filteredList = filterCachedSimulatorList(cachedList, {
            deviceType,
            runtime,
            availability,
          });
  
          // Limit devices to max count, sorted by lastUsed date
          const allDevices: Array<{ runtime: string; device: SimulatorInfo }> = [];
          for (const [runtimeKey, devices] of Object.entries(filteredList.devices)) {
            devices.forEach(device => {
              allDevices.push({ runtime: runtimeKey, device });
            });
          }
  
          // Sort by lastUsed date descending (most recent first), nulls at end
          allDevices.sort((a, b) => {
            if (!a.device.lastUsed && !b.device.lastUsed) return 0;
            if (!a.device.lastUsed) return 1;
            if (!b.device.lastUsed) return -1;
            return b.device.lastUsed.getTime() - a.device.lastUsed.getTime();
          });
  
          // Take first max devices
          const limitedDevices = allDevices.slice(0, max);
  
          // Reconstruct grouped structure with limited devices
          const limitedDevicesByRuntime: { [runtime: string]: SimulatorInfo[] } = {};
          for (const { runtime: runtimeKey, device } of limitedDevices) {
            if (!limitedDevicesByRuntime[runtimeKey]) {
              limitedDevicesByRuntime[runtimeKey] = [];
            }
            limitedDevicesByRuntime[runtimeKey].push(device);
          }
  
          responseData = {
            devices: limitedDevicesByRuntime,
            runtimes: filteredList.runtimes,
            devicetypes: filteredList.devicetypes,
            lastUpdated: filteredList.lastUpdated.toISOString(),
            metadata: {
              totalDevicesInCache: Object.values(filteredList.devices).flat().length,
              devicesReturned: limitedDevices.length,
              limitApplied: max,
            },
          };
        } else {
          // For text format, we need to convert back to original format
          responseData =
            `Simulator List (cached at ${cachedList.lastUpdated.toISOString()}):\n` +
            JSON.stringify(cachedList, null, 2);
        }
      }
  
      const responseText =
        outputFormat === 'json'
          ? JSON.stringify(responseData, null, 2)
          : typeof responseData === 'string'
            ? responseData
            : JSON.stringify(responseData, null, 2);
  
      return {
        content: [
          {
            type: 'text' as const,
            text: responseText,
          },
        ],
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `simctl-list failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/registry/simctl.ts:54-62 (schema)

  Zod inputSchema used for MCP tool validation of arguments.

  inputSchema: {
    deviceType: z.string().optional(),
    runtime: z.string().optional(),
    availability: z.enum(['available', 'unavailable', 'all']).default('available'),
    outputFormat: z.enum(['json', 'text']).default('json'),
    concise: z.boolean().default(true),
    max: z.number().default(5),
  },
  ...DEFER_LOADING_CONFIG,

• src/registry/index.ts:20-33 (registration)

  The `registerAllTools` function that invokes `registerSimctlListTool` as part of the main tool registration process.

  export function registerAllTools(server: McpServer): void {
    // Always register build-related tools
    registerXcodebuildTools(server);
    registerSimctlListTool(server);
    registerCacheTools(server);
    registerSystemTools(server);
  
    // Only register full toolset when NOT in build-only mode
    if (!config.buildOnly) {
      registerSimctlTools(server);
      registerIdbTools(server);
      registerWorkflowTools(server);
    }
  }