install_app

Instructions

Implementation Reference

• src/index.ts:1118-1156 (handler)

  The handler function for the install_app tool. Resolves the UDID (booted device), checks app bundle existence, runs `xcrun simctl install`, and returns success/error.

    async ({ udid, app_path }) => {
      try {
        const actualUdid = await getBootedDeviceId(udid);
        const absolutePath = path.isAbsolute(app_path)
          ? app_path
          : path.resolve(app_path);
  
        // Check if the app bundle exists
        if (!fs.existsSync(absolutePath)) {
          throw new Error(`App bundle not found at: ${absolutePath}`);
        }
  
        // run() will throw if the command fails (non-zero exit code)
        await run("xcrun", ["simctl", "install", actualUdid, absolutePath]);
  
        return {
          isError: false,
          content: [
            {
              type: "text",
              text: `App installed successfully from: ${absolutePath}`,
            },
          ],
        };
      } catch (error) {
        return {
          isError: true,
          content: [
            {
              type: "text",
              text: errorWithTroubleshooting(
                `Error installing app: ${toError(error).message}`
              ),
            },
          ],
        };
      }
    }
  );

• src/index.ts:1103-1117 (schema)

  Schema definition for install_app: takes optional udid (matching UDID_REGEX) and required app_path (max 1024 chars).

  "Installs an app bundle (.app or .ipa) on the iOS Simulator",
  {
    udid: z
      .string()
      .regex(UDID_REGEX)
      .optional()
      .describe("Udid of target, can also be set with the IDB_UDID env var"),
    app_path: z
      .string()
      .max(1024)
      .describe(
        "Path to the app bundle (.app directory or .ipa file) to install"
      ),
  },
  { title: "Install App", readOnlyHint: false, openWorldHint: true },

• src/index.ts:1100-1157 (registration)

  Registration of the install_app tool using server.tool() with a filter check.

  if (!isToolFiltered("install_app")) {
    server.tool(
      "install_app",
      "Installs an app bundle (.app or .ipa) on the iOS Simulator",
      {
        udid: z
          .string()
          .regex(UDID_REGEX)
          .optional()
          .describe("Udid of target, can also be set with the IDB_UDID env var"),
        app_path: z
          .string()
          .max(1024)
          .describe(
            "Path to the app bundle (.app directory or .ipa file) to install"
          ),
      },
      { title: "Install App", readOnlyHint: false, openWorldHint: true },
      async ({ udid, app_path }) => {
        try {
          const actualUdid = await getBootedDeviceId(udid);
          const absolutePath = path.isAbsolute(app_path)
            ? app_path
            : path.resolve(app_path);
  
          // Check if the app bundle exists
          if (!fs.existsSync(absolutePath)) {
            throw new Error(`App bundle not found at: ${absolutePath}`);
          }
  
          // run() will throw if the command fails (non-zero exit code)
          await run("xcrun", ["simctl", "install", actualUdid, absolutePath]);
  
          return {
            isError: false,
            content: [
              {
                type: "text",
                text: `App installed successfully from: ${absolutePath}`,
              },
            ],
          };
        } catch (error) {
          return {
            isError: true,
            content: [
              {
                type: "text",
                text: errorWithTroubleshooting(
                  `Error installing app: ${toError(error).message}`
                ),
              },
            ],
          };
        }
      }
    );
  }

• src/index.ts:195-208 (helper)

  getBootedDeviceId helper - resolves the UDID by either using the provided one or finding the currently booted simulator.

  async function getBootedDeviceId(
    deviceId: string | undefined
  ): Promise<string> {
    // If deviceId not provided, get the currently booted simulator
    let actualDeviceId = deviceId;
    if (!actualDeviceId) {
      const { id } = await getBootedDevice();
      actualDeviceId = id;
    }
    if (!actualDeviceId) {
      throw new Error("No booted simulator found and no deviceId provided");
    }
    return actualDeviceId;
  }

• src/index.ts:166-168 (helper)

  errorWithTroubleshooting helper - appends troubleshooting link to error messages.

  function errorWithTroubleshooting(message: string): string {
    return `${message}\n\nFor help, see the ${troubleshootingLink()}`;
  }