list_schems_ws

Instructions

Implementation Reference

• src/tools/build_settings.ts:84-151 (handler)

  The core handler function that executes the tool logic: runs `xcodebuild -list -workspace`, parses the schemes section from output, lists them, and provides suggested next tool calls.

  async function _handleListSchemesLogic(params: {
    workspacePath?: string;
    projectPath?: string;
  }): Promise<ToolResponse> {
    log('info', 'Listing schemes');
  
    try {
      // For listing schemes, we can't use executeXcodeBuild directly since it's not a standard action
      // We need to create a custom command with -list flag
      const command = ['xcodebuild', '-list'];
  
      if (params.workspacePath) {
        command.push('-workspace', params.workspacePath);
      } else if (params.projectPath) {
        command.push('-project', params.projectPath);
      } // No else needed, one path is guaranteed by callers
  
      const result = await executeCommand(command, 'List Schemes');
  
      if (!result.success) {
        return createTextResponse(`Failed to list schemes: ${result.error}`, true);
      }
  
      // Extract schemes from the output
      const schemesMatch = result.output.match(/Schemes:([\s\S]*?)(?=\n\n|$)/);
  
      if (!schemesMatch) {
        return createTextResponse('No schemes found in the output', true);
      }
  
      const schemeLines = schemesMatch[1].trim().split('\n');
      const schemes = schemeLines.map((line) => line.trim()).filter((line) => line);
  
      // Prepare next steps with the first scheme if available
      let nextStepsText = '';
      if (schemes.length > 0) {
        const firstScheme = schemes[0];
        const projectOrWorkspace = params.workspacePath ? 'workspace' : 'project';
        const path = params.workspacePath || params.projectPath;
  
        nextStepsText = `Next Steps:
  1. Build the app: ${projectOrWorkspace === 'workspace' ? 'macos_build_workspace' : 'macos_build_project'}({ ${projectOrWorkspace}Path: "${path}", scheme: "${firstScheme}" })
     or for iOS: ${projectOrWorkspace === 'workspace' ? 'ios_simulator_build_by_name_workspace' : 'ios_simulator_build_by_name_project'}({ ${projectOrWorkspace}Path: "${path}", scheme: "${firstScheme}", simulatorName: "iPhone 16" })
  2. Show build settings: ${projectOrWorkspace === 'workspace' ? 'show_build_set_ws' : 'show_build_set_proj'}({ ${projectOrWorkspace}Path: "${path}", scheme: "${firstScheme}" })`;
      }
  
      return {
        content: [
          {
            type: 'text',
            text: `✅ Available schemes:`,
          },
          {
            type: 'text',
            text: schemes.join('\n'),
          },
          {
            type: 'text',
            text: nextStepsText,
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      log('error', `Error listing schemes: ${errorMessage}`);
      return createTextResponse(`Error listing schemes: ${errorMessage}`, true);
    }
  }

• src/tools/build_settings.ts:208-224 (registration)

  Registers the 'list_schems_ws' tool with the MCP server using registerTool, including name, description, input schema, and thin handler that validates and delegates to core logic.

  export function registerListSchemesWorkspaceTool(server: McpServer): void {
    registerTool<BaseWorkspaceParams>(
      server,
      'list_schems_ws',
      "Lists available schemes in the workspace. IMPORTANT: Requires workspacePath. Example: list_schems_ws({ workspacePath: '/path/to/MyProject.xcworkspace' })",
      {
        workspacePath: workspacePathSchema,
      },
      async (params: BaseWorkspaceParams) => {
        // Validate required parameters
        const workspaceValidation = validateRequiredParam('workspacePath', params.workspacePath);
        if (!workspaceValidation.isValid) return workspaceValidation.errorResponse!;
  
        return _handleListSchemesLogic(params);
      },
    );
  }

• src/tools/common.ts:22-22 (schema)

  Zod schema definition for the required 'workspacePath' input parameter used by the tool.

  export const workspacePathSchema = z.string().describe('Path to the .xcworkspace file (Required)');

• src/utils/register-tools.ts:114-116 (registration)

  Top-level registration entry that conditionally registers the tool via registerListSchemesWorkspaceTool based on environment variable.

  register: registerListSchemesWorkspaceTool,
  groups: [ToolGroup.PROJECT_DISCOVERY],
  envVar: 'XCODEBUILDMCP_TOOL_LIST_SCHEMES_WORKSPACE',

• src/tools/common.ts:160-179 (helper)

  Shared utility function used to register all tools with the MCP server, wrapping the custom handler to match MCP SDK signature.

  export function registerTool<T extends object>(
    server: McpServer,
    name: string,
    description: string,
    schema: Record<string, z.ZodType>,
    handler: (params: T) => Promise<ToolResponse>,
  ): void {
    // Create a wrapper handler that matches the signature expected by server.tool
    const wrappedHandler = (
      args: Record<string, unknown>,
      _extra: unknown,
    ): Promise<ToolResponse> => {
      // Assert the type *before* calling the original handler
      // This confines the type assertion to one place
      const typedParams = args as T;
      return handler(typedParams);
    };
  
    server.tool(name, description, schema, wrappedHandler);
  }