sl-test

Instructions

Implementation Reference

• src/tools/app_path.ts:49-180 (handler)

  Core handler function that executes the tool logic: constructs and runs xcodebuild -showBuildSettings with platform-specific destination, extracts BUILT_PRODUCTS_DIR and FULL_PRODUCT_NAME to compute app path.

  async function _handleGetAppPathLogic(params: {
    workspacePath?: string;
    projectPath?: string;
    scheme: string;
    configuration: string;
    platform: XcodePlatform;
    simulatorName?: string;
    simulatorId?: string;
    useLatestOS: boolean;
    arch?: string;
  }): Promise<ToolResponse> {
    log('info', `Getting app path for scheme ${params.scheme} on platform ${params.platform}`);
  
    try {
      // Create the command array for xcodebuild with -showBuildSettings option
      const command = ['xcodebuild', '-showBuildSettings'];
  
      // Add the workspace or project
      if (params.workspacePath) {
        command.push('-workspace', params.workspacePath);
      } else if (params.projectPath) {
        command.push('-project', params.projectPath);
      }
  
      // Add the scheme and configuration
      command.push('-scheme', params.scheme);
      command.push('-configuration', params.configuration);
  
      // Handle destination based on platform
      const isSimulatorPlatform = [
        XcodePlatform.iOSSimulator,
        XcodePlatform.watchOSSimulator,
        XcodePlatform.tvOSSimulator,
        XcodePlatform.visionOSSimulator,
      ].includes(params.platform);
  
      let destinationString = '';
  
      if (isSimulatorPlatform) {
        if (params.simulatorId) {
          destinationString = `platform=${params.platform},id=${params.simulatorId}`;
        } else if (params.simulatorName) {
          destinationString = `platform=${params.platform},name=${params.simulatorName}${params.useLatestOS ? ',OS=latest' : ''}`;
        } else {
          return createTextResponse(
            `For ${params.platform} platform, either simulatorId or simulatorName must be provided`,
            true,
          );
        }
      } else if (params.platform === XcodePlatform.macOS) {
        destinationString = constructDestinationString(
          params.platform,
          undefined,
          undefined,
          false,
          params.arch,
        );
      } else if (params.platform === XcodePlatform.iOS) {
        destinationString = 'generic/platform=iOS';
      } else if (params.platform === XcodePlatform.watchOS) {
        destinationString = 'generic/platform=watchOS';
      } else if (params.platform === XcodePlatform.tvOS) {
        destinationString = 'generic/platform=tvOS';
      } else if (params.platform === XcodePlatform.visionOS) {
        destinationString = 'generic/platform=visionOS';
      } else {
        return createTextResponse(`Unsupported platform: ${params.platform}`, true);
      }
  
      command.push('-destination', destinationString);
  
      // Execute the command directly
      const result = await executeCommand(command, 'Get App Path');
  
      if (!result.success) {
        return createTextResponse(`Failed to get app path: ${result.error}`, true);
      }
  
      if (!result.output) {
        return createTextResponse('Failed to extract build settings output from the result.', true);
      }
  
      const buildSettingsOutput = result.output;
      const builtProductsDirMatch = buildSettingsOutput.match(/BUILT_PRODUCTS_DIR = (.+)$/m);
      const fullProductNameMatch = buildSettingsOutput.match(/FULL_PRODUCT_NAME = (.+)$/m);
  
      if (!builtProductsDirMatch || !fullProductNameMatch) {
        return createTextResponse(
          'Failed to extract app path from build settings. Make sure the app has been built first.',
          true,
        );
      }
  
      const builtProductsDir = builtProductsDirMatch[1].trim();
      const fullProductName = fullProductNameMatch[1].trim();
      const appPath = `${builtProductsDir}/${fullProductName}`;
  
      let nextStepsText = '';
      if (params.platform === XcodePlatform.macOS) {
        nextStepsText = `Next Steps:
  1. Get bundle ID: get_macos_bundle_id({ appPath: "${appPath}" })
  2. Launch the app: launch_macos_app({ appPath: "${appPath}" })`;
      } else if (params.platform === XcodePlatform.iOSSimulator) {
        nextStepsText = `Next Steps:
  1. Get bundle ID: get_ios_bundle_id({ appPath: "${appPath}" })
  2. Boot simulator: boot_simulator({ simulatorUuid: "SIMULATOR_UUID" })
  3. Install app: install_app_in_simulator({ simulatorUuid: "SIMULATOR_UUID", appPath: "${appPath}" })
  4. Launch app: launch_app_in_simulator({ simulatorUuid: "SIMULATOR_UUID", bundleId: "BUNDLE_ID" })`;
      } else if (params.platform === XcodePlatform.iOS) {
        nextStepsText = `Next Steps:
  1. Get bundle ID: get_ios_bundle_id({ appPath: "${appPath}" })
  2. Use Xcode to install the app on your connected iOS device`;
      }
  
      return {
        content: [
          {
            type: 'text',
            text: `✅ App path retrieved successfully: ${appPath}`,
          },
          {
            type: 'text',
            text: nextStepsText,
          },
        ],
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      log('error', `Error retrieving app path: ${errorMessage}`);
      return createTextResponse(`Error retrieving app path: ${errorMessage}`, true);
    }
  }

• src/tools/app_path.ts:354-388 (registration)

  Function that registers the 'get_sim_app_path_name_proj' tool on the MCP server, defining its input schema, description, and handler.

  export function registerGetSimulatorAppPathByNameProjectTool(server: McpServer): void {
    type Params = BaseProjectParams & BaseAppPathSimulatorNameParams;
    registerTool<Params>(
      server,
      'get_sim_app_path_name_proj',
      "Gets the app bundle path for a simulator by name using a project file. IMPORTANT: Requires projectPath, scheme, platform, and simulatorName. Example: get_sim_app_path_name_proj({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme', platform: 'iOS Simulator', simulatorName: 'iPhone 16' })",
      {
        projectPath: projectPathSchema,
        scheme: schemeSchema,
        platform: platformSimulatorSchema,
        simulatorName: simulatorNameSchema,
        configuration: configurationSchema,
        useLatestOS: useLatestOSSchema,
      },
      async (params: Params) => {
        const projectValidation = validateRequiredParam('projectPath', params.projectPath);
        if (!projectValidation.isValid) return projectValidation.errorResponse!;
  
        const schemeValidation = validateRequiredParam('scheme', params.scheme);
        if (!schemeValidation.isValid) return schemeValidation.errorResponse!;
  
        const platformValidation = validateRequiredParam('platform', params.platform);
        if (!platformValidation.isValid) return platformValidation.errorResponse!;
  
        const simulatorNameValidation = validateRequiredParam('simulatorName', params.simulatorName);
        if (!simulatorNameValidation.isValid) return simulatorNameValidation.errorResponse!;
  
        return _handleGetAppPathLogic({
          ...params,
          configuration: params.configuration ?? 'Debug',
          useLatestOS: params.useLatestOS ?? true,
        });
      },
    );
  }

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

  Zod schemas for input parameters used by the get_sim_app_path_name_proj tool: projectPath, scheme, platform, simulatorName, configuration, useLatestOS.

  export const workspacePathSchema = z.string().describe('Path to the .xcworkspace file (Required)');
  export const projectPathSchema = z.string().describe('Path to the .xcodeproj file (Required)');
  export const schemeSchema = z.string().describe('The scheme to use (Required)');
  export const configurationSchema = z
    .string()
    .optional()
    .describe('Build configuration (Debug, Release, etc.)');
  export const derivedDataPathSchema = z
    .string()
    .optional()
    .describe('Path where build products and other derived data will go');
  export const extraArgsSchema = z
    .array(z.string())
    .optional()
    .describe('Additional xcodebuild arguments');
  export const simulatorNameSchema = z
    .string()
    .describe("Name of the simulator to use (e.g., 'iPhone 16') (Required)");
  export const simulatorIdSchema = z
    .string()
    .describe('UUID of the simulator to use (obtained from listSimulators) (Required)');
  export const useLatestOSSchema = z
    .boolean()
    .optional()
    .describe('Whether to use the latest OS version for the named simulator');
  export const appPathSchema = z
    .string()
    .describe('Path to the .app bundle (full path to the .app directory)');
  export const bundleIdSchema = z
    .string()
    .describe("Bundle identifier of the app (e.g., 'com.example.MyApp')");
  export const launchArgsSchema = z
    .array(z.string())
    .optional()
    .describe('Additional arguments to pass to the app');
  export const preferXcodebuildSchema = z
    .boolean()
    .optional()
    .describe(
      'If true, prefers xcodebuild over the experimental incremental build system, useful for when incremental build system fails.',
    );
  
  export const platformDeviceSchema = z
    .enum([
      XcodePlatform.macOS,
      XcodePlatform.iOS,
      XcodePlatform.watchOS,
      XcodePlatform.tvOS,
      XcodePlatform.visionOS,
    ])
    .describe('The target device platform (Required)');
  
  export const platformSimulatorSchema = z
    .enum([
      XcodePlatform.iOSSimulator,
      XcodePlatform.watchOSSimulator,
      XcodePlatform.tvOSSimulator,
      XcodePlatform.visionOSSimulator,
    ])
    .describe('The target simulator platform (Required)');

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

  Utility function used to register all MCP tools, wrapping the handler to match MCP server.tool 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);
  }

• src/utils/register-tools.ts:294-302 (registration)

  Entry in the central toolRegistrations array that triggers registration of get_sim_app_path_name_proj when registerTools(server) is called, conditional on environment variable.

  {
    register: registerGetSimulatorAppPathByNameProjectTool,
    groups: [
      ToolGroup.IOS_SIMULATOR_WORKFLOW,
      ToolGroup.APP_DEPLOYMENT,
      ToolGroup.PROJECT_DISCOVERY,
    ],
    envVar: 'XCODEBUILDMCP_TOOL_GET_SIMULATOR_APP_PATH_BY_NAME_PROJECT',
  },