list_builds

Instructions

Implementation Reference

• src/tools/list-builds.ts:23-57 (handler)

  The main handler function for the list_builds tool. Takes a validated schema input, calls the API's listBuilds function, and maps the response to a simplified output format with build number, version, platform, upload date, processing state, expiry, and min OS version.

  export async function handleListBuilds(
    client: AppStoreConnectClient,
    args: z.infer<typeof listBuildsSchema>
  ) {
    const { builds, included } = await listBuilds(client, {
      appId: args.app_id,
      preReleaseVersion: args.version,
      processingState: args.processing_state,
      limit: args.limit,
    });
  
    return builds.map((build) => {
      const versionRef = build.relationships?.preReleaseVersion?.data;
      const versionResource =
        versionRef && !Array.isArray(versionRef)
          ? included.find(
              (r) => r.type === "preReleaseVersions" && r.id === versionRef.id
            )
          : null;
      const versionAttrs = versionResource?.attributes as
        | { version?: string; platform?: string }
        | undefined;
  
      return {
        id: build.id,
        buildNumber: build.attributes.version,
        appVersion: versionAttrs?.version ?? null,
        platform: versionAttrs?.platform ?? null,
        uploadedDate: build.attributes.uploadedDate,
        processingState: build.attributes.processingState,
        expired: build.attributes.expired,
        minOsVersion: build.attributes.minOsVersion,
      };
    });
  }

• src/tools/list-builds.ts:5-21 (schema)

  Zod schema defining the input parameters for list_builds: app_id (required string), version (optional string for pre-release filtering), processing_state (optional enum), and limit (optional number 1-200).

  export const listBuildsSchema = z.object({
    app_id: z.string().describe("App Store Connect app ID"),
    version: z
      .string()
      .optional()
      .describe("Filter by pre-release version string (e.g., '1.2.0')"),
    processing_state: z
      .enum(["PROCESSING", "FAILED", "INVALID", "VALID"])
      .optional()
      .describe("Filter by build processing state"),
    limit: z
      .number()
      .min(1)
      .max(200)
      .optional()
      .describe("Maximum number of builds to return (default: 20)"),
  });

• src/index.ts:52-62 (registration)

  Registration of the 'list_builds' tool on the MCP server with its schema and handler, wiring it into the server's tool registry.

  server.tool(
    "list_builds",
    "List TestFlight builds for an app. Filter by version or processing state. Returns build number, version, upload date, and status.",
    listBuildsSchema.shape,
    async (args) => {
      const result = await handleListBuilds(client, args);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    }
  );

• src/api/builds.ts:12-35 (helper)

  API helper function that constructs App Store Connect API query parameters and calls the /builds endpoint via the client. Handles filtering by app, pre-release version, processing state, and sorting.

  export async function listBuilds(
    client: AppStoreConnectClient,
    options: ListBuildsOptions
  ): Promise<{ builds: Build[]; included: JsonApiResource[] }> {
    const params: Record<string, string> = {
      "filter[app]": options.appId,
      "fields[builds]":
        "version,uploadedDate,expirationDate,expired,minOsVersion,processingState,buildAudienceType",
      include: "preReleaseVersion",
      "fields[preReleaseVersions]": "version,platform",
      limit: String(options.limit ?? 20),
      sort: options.sort ?? "-uploadedDate",
    };
  
    if (options.preReleaseVersion) {
      params["filter[preReleaseVersion.version]"] = options.preReleaseVersion;
    }
    if (options.processingState) {
      params["filter[processingState]"] = options.processingState;
    }
  
    const response = await client.requestAll<Build>("/builds", params);
    return { builds: response.data, included: response.included };
  }

• src/api/builds.ts:4-10 (helper)

  TypeScript interface defining the options passed to the API-level listBuilds function.

  export interface ListBuildsOptions {
    appId: string;
    limit?: number;
    preReleaseVersion?: string;
    processingState?: "PROCESSING" | "FAILED" | "INVALID" | "VALID";
    sort?: string;
  }