XcodeBuildMCP

Instructions

Implementation Reference

• src/mcp/tools/project-discovery/discover_projs.ts:157-270 (handler)

  Core execution logic for the discover_projs tool: validates params, scans directories recursively for .xcodeproj and .xcworkspace files, handles errors, and formats response.

  export async function discover_projsLogic(
    params: DiscoverProjsParams,
    fileSystemExecutor: FileSystemExecutor,
  ): Promise<ToolResponse> {
    // Apply defaults
    const scanPath = params.scanPath ?? '.';
    const maxDepth = params.maxDepth ?? DEFAULT_MAX_DEPTH;
    const workspaceRoot = params.workspaceRoot;
  
    const relativeScanPath = scanPath;
  
    // Calculate and validate the absolute scan path
    const requestedScanPath = path.resolve(workspaceRoot, relativeScanPath ?? '.');
    let absoluteScanPath = requestedScanPath;
    const normalizedWorkspaceRoot = path.normalize(workspaceRoot);
    if (!path.normalize(absoluteScanPath).startsWith(normalizedWorkspaceRoot)) {
      log(
        'warn',
        `Requested scan path '${relativeScanPath}' resolved outside workspace root '${workspaceRoot}'. Defaulting scan to workspace root.`,
      );
      absoluteScanPath = normalizedWorkspaceRoot;
    }
  
    const results = { projects: [], workspaces: [] };
  
    log(
      'info',
      `Starting project discovery request: path=${absoluteScanPath}, maxDepth=${maxDepth}, workspace=${workspaceRoot}`,
    );
  
    try {
      // Ensure the scan path exists and is a directory
      const stats = await fileSystemExecutor.stat(absoluteScanPath);
      if (!stats.isDirectory()) {
        const errorMsg = `Scan path is not a directory: ${absoluteScanPath}`;
        log('error', errorMsg);
        // Return ToolResponse error format
        return {
          content: [createTextContent(errorMsg)],
          isError: true,
        };
      }
    } catch (error) {
      let code;
      let message = 'Unknown error accessing scan path';
  
      // Type guards - refined
      if (error instanceof Error) {
        message = error.message;
        // Check for code property specific to Node.js fs errors
        if ('code' in error) {
          code = error.code;
        }
      } else if (typeof error === 'object' && error !== null) {
        if ('message' in error && typeof error.message === 'string') {
          message = error.message;
        }
        if ('code' in error && typeof error.code === 'string') {
          code = error.code;
        }
      } else {
        message = String(error);
      }
  
      const errorMsg = `Failed to access scan path: ${absoluteScanPath}. Error: ${message}`;
      log('error', `${errorMsg} - Code: ${code ?? 'N/A'}`);
      return {
        content: [createTextContent(errorMsg)],
        isError: true,
      };
    }
  
    // Start the recursive scan from the validated absolute path
    await _findProjectsRecursive(
      absoluteScanPath,
      workspaceRoot,
      0,
      maxDepth,
      results,
      fileSystemExecutor,
    );
  
    log(
      'info',
      `Discovery finished. Found ${results.projects.length} projects and ${results.workspaces.length} workspaces.`,
    );
  
    const responseContent = [
      createTextContent(
        `Discovery finished. Found ${results.projects.length} projects and ${results.workspaces.length} workspaces.`,
      ),
    ];
  
    // Sort results for consistent output
    results.projects.sort();
    results.workspaces.sort();
  
    if (results.projects.length > 0) {
      responseContent.push(
        createTextContent(`Projects found:\n - ${results.projects.join('\n - ')}`),
      );
    }
  
    if (results.workspaces.length > 0) {
      responseContent.push(
        createTextContent(`Workspaces found:\n - ${results.workspaces.join('\n - ')}`),
      );
    }
  
    return {
      content: responseContent,
      isError: false,
    };
  }

• src/mcp/tools/project-discovery/discover_projs.ts:136-148 (schema)

  Zod schema defining input parameters for the discover_projs tool: workspaceRoot (required string), scanPath (optional string), maxDepth (optional nonnegative int).

  const discoverProjsSchema = z.object({
    workspaceRoot: z.string().describe('The absolute path of the workspace root to scan within.'),
    scanPath: z
      .string()
      .optional()
      .describe('Optional: Path relative to workspace root to scan. Defaults to workspace root.'),
    maxDepth: z
      .number()
      .int()
      .nonnegative()
      .optional()
      .describe(`Optional: Maximum directory depth to scan. Defaults to ${DEFAULT_MAX_DEPTH}.`),
  });

• src/mcp/tools/project-discovery/discover_projs.ts:272-284 (registration)

  Default export defining the tool for plugin loading: includes name, description, schema, and handler wrapper using createTypedTool that invokes discover_projsLogic.

  export default {
    name: 'discover_projs',
    description:
      'Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.',
    schema: discoverProjsSchema.shape, // MCP SDK compatibility
    handler: createTypedTool(
      discoverProjsSchema,
      (params: DiscoverProjsParams) => {
        return discover_projsLogic(params, getDefaultFileSystemExecutor());
      },
      getDefaultCommandExecutor,
    ),
  };

• src/mcp/tools/project-discovery/discover_projs.ts:30-133 (helper)

  Recursive helper function that scans directories for Xcode projects and workspaces, skipping symlinks, build dirs, and respecting max depth and workspace boundaries.

  async function _findProjectsRecursive(
    currentDirAbs: string,
    workspaceRootAbs: string,
    currentDepth: number,
    maxDepth: number,
    results: { projects: string[]; workspaces: string[] },
    fileSystemExecutor: FileSystemExecutor = getDefaultFileSystemExecutor(),
  ): Promise<void> {
    // Explicit depth check (now simplified as maxDepth is always non-negative)
    if (currentDepth >= maxDepth) {
      log('debug', `Max depth ${maxDepth} reached at ${currentDirAbs}, stopping recursion.`);
      return;
    }
  
    log('debug', `Scanning directory: ${currentDirAbs} at depth ${currentDepth}`);
    const normalizedWorkspaceRoot = path.normalize(workspaceRootAbs);
  
    try {
      // Use the injected fileSystemExecutor
      const entries = await fileSystemExecutor.readdir(currentDirAbs, { withFileTypes: true });
      for (const rawEntry of entries) {
        // Cast the unknown entry to DirentLike interface for type safety
        const entry = rawEntry as DirentLike;
        const absoluteEntryPath = path.join(currentDirAbs, entry.name);
        const relativePath = path.relative(workspaceRootAbs, absoluteEntryPath);
  
        // --- Skip conditions ---
        if (entry.isSymbolicLink()) {
          log('debug', `Skipping symbolic link: ${relativePath}`);
          continue;
        }
  
        // Skip common build/dependency directories by name
        if (entry.isDirectory() && SKIPPED_DIRS.has(entry.name)) {
          log('debug', `Skipping standard directory: ${relativePath}`);
          continue;
        }
  
        // Ensure entry is within the workspace root (security/sanity check)
        if (!path.normalize(absoluteEntryPath).startsWith(normalizedWorkspaceRoot)) {
          log(
            'warn',
            `Skipping entry outside workspace root: ${absoluteEntryPath} (Workspace: ${workspaceRootAbs})`,
          );
          continue;
        }
  
        // --- Process entries ---
        if (entry.isDirectory()) {
          let isXcodeBundle = false;
  
          if (entry.name.endsWith('.xcodeproj')) {
            results.projects.push(absoluteEntryPath); // Use absolute path
            log('debug', `Found project: ${absoluteEntryPath}`);
            isXcodeBundle = true;
          } else if (entry.name.endsWith('.xcworkspace')) {
            results.workspaces.push(absoluteEntryPath); // Use absolute path
            log('debug', `Found workspace: ${absoluteEntryPath}`);
            isXcodeBundle = true;
          }
  
          // Recurse into regular directories, but not into found project/workspace bundles
          if (!isXcodeBundle) {
            await _findProjectsRecursive(
              absoluteEntryPath,
              workspaceRootAbs,
              currentDepth + 1,
              maxDepth,
              results,
              fileSystemExecutor,
            );
          }
        }
      }
    } catch (error) {
      let code;
      let message = 'Unknown error';
  
      if (error instanceof Error) {
        message = error.message;
        if ('code' in error) {
          code = error.code;
        }
      } else if (typeof error === 'object' && error !== null) {
        if ('message' in error && typeof error.message === 'string') {
          message = error.message;
        }
        if ('code' in error && typeof error.code === 'string') {
          code = error.code;
        }
      } else {
        message = String(error);
      }
  
      if (code === 'EPERM' || code === 'EACCES') {
        log('debug', `Permission denied scanning directory: ${currentDirAbs}`);
      } else {
        log(
          'warning',
          `Error scanning directory ${currentDirAbs}: ${message} (Code: ${code ?? 'N/A'})`,
        );
      }
    }
  }

• src/utils/tool-registry.ts:117-146 (registration)

  Dynamic registration function that loads and registers discovery tools including discover_projs from plugin registry.

  export async function registerDiscoveryTools(server: McpServer): Promise<void> {
    const plugins = await loadPlugins();
    let registeredCount = 0;
  
    // Only register discovery tools initially
    const discoveryTools = [];
    for (const plugin of plugins.values()) {
      // Only load discover_tools and discover_projs initially - other tools will be loaded via workflows
      if (plugin.name === 'discover_tools' || plugin.name === 'discover_projs') {
        discoveryTools.push({
          name: plugin.name,
          config: {
            description: plugin.description ?? '',
            inputSchema: plugin.schema,
          },
          // Adapt callback to match SDK's expected signature
          callback: (args: unknown): Promise<ToolResponse> =>
            plugin.handler(args as Record<string, unknown>),
        });
        registeredCount++;
      }
    }
  
    // Register discovery tools using bulk registration with tracking
    if (discoveryTools.length > 0) {
      registerAndTrackTools(server, discoveryTools);
    }
  
    log('info', `✅ Registered ${registeredCount} discovery tools in dynamic mode.`);
  }