list_feedback

Instructions

Implementation Reference

• src/tools/list-feedback.ts:31-97 (handler)

  Main handler function for the list_feedback tool. Fetches screenshot, crash, and text comment feedback from multiple sources, sorts by timestamp, and returns unified FeedbackItem array.

  export async function handleListFeedback(
    client: AppStoreConnectClient,
    args: z.infer<typeof listFeedbackSchema>
  ): Promise<{
    feedback: FeedbackItem[];
    sources: string[];
    note?: string;
  }> {
    const feedbackType = args.type ?? "all";
    const allFeedback: FeedbackItem[] = [];
    const sources: string[] = [];
    let note: string | undefined;
  
    const opts = {
      appId: args.app_id,
      buildId: args.build_id,
      limit: args.limit,
    };
  
    // Screenshot feedback (official API)
    if (feedbackType === "all" || feedbackType === "screenshots") {
      try {
        const { submissions, included } = await listScreenshotFeedback(client, opts);
        const items = toFeedbackItems(submissions, included, "screenshot");
        allFeedback.push(...items);
        sources.push("official-api:screenshots");
      } catch (error) {
        note = `Screenshot feedback fetch failed: ${error instanceof Error ? error.message : String(error)}`;
      }
    }
  
    // Crash feedback (official API)
    if (feedbackType === "all" || feedbackType === "crashes") {
      try {
        const { submissions, included } = await listCrashFeedback(client, opts);
        const items = toFeedbackItems(submissions, included, "crash");
        allFeedback.push(...items);
        sources.push("official-api:crashes");
      } catch (error) {
        const msg = `Crash feedback fetch failed: ${error instanceof Error ? error.message : String(error)}`;
        note = note ? `${note}; ${msg}` : msg;
      }
    }
  
    // Text comments (iris API, requires browser auth)
    if (feedbackType === "all" || feedbackType === "comments") {
      const irisFeedback = await listIrisFeedback(args.app_id, {
        buildId: args.build_id,
        limit: args.limit,
      });
      if (irisFeedback) {
        allFeedback.push(...irisFeedback);
        sources.push("iris-api:comments");
      } else if (feedbackType === "comments") {
        note = note
          ? `${note}; Text comments require ENABLE_BROWSER_AUTH=true`
          : "Text comments require ENABLE_BROWSER_AUTH=true with ASC_USERNAME and ASC_PASSWORD set.";
      }
    }
  
    // Sort all by timestamp descending
    allFeedback.sort(
      (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
    );
  
    return { feedback: allFeedback, sources, note };
  }

• src/tools/list-feedback.ts:11-29 (schema)

  Zod schema for list_feedback input validation: app_id (required), build_id (optional), type (all/screenshots/crashes/comments, optional), limit (1-200, optional).

  export const listFeedbackSchema = z.object({
    app_id: z.string().describe("App Store Connect app ID"),
    build_id: z
      .string()
      .optional()
      .describe("Filter feedback by build ID"),
    type: z
      .enum(["all", "screenshots", "crashes", "comments"])
      .optional()
      .describe(
        "Type of feedback to retrieve. 'comments' requires browser auth. Default: 'all'"
      ),
    limit: z
      .number()
      .min(1)
      .max(200)
      .optional()
      .describe("Maximum number of feedback items per type (default: 50)"),
  });

• src/index.ts:88-98 (registration)

  Registration of the 'list_feedback' tool with the MCP server, linking the schema and handler.

  server.tool(
    "list_feedback",
    "List TestFlight feedback for an app. Retrieves screenshot submissions, crash reports, and (with browser auth) text comments. Filter by build or feedback type.",
    listFeedbackSchema.shape,
    async (args) => {
      const result = await handleListFeedback(client, args);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    }
  );

• src/api/feedback.ts:173-236 (helper)

  toFeedbackItems helper: converts raw API submissions (screenshot/crash) into unified FeedbackItem format.

  export function toFeedbackItems(
    submissions: (BetaFeedbackScreenshotSubmission | BetaFeedbackCrashSubmission)[],
    included: JsonApiResource[],
    type: "screenshot" | "crash"
  ): FeedbackItem[] {
    return submissions.map((sub) => {
      const testerRef = sub.relationships?.betaTester?.data;
      const buildRef = sub.relationships?.build?.data;
  
      const tester =
        testerRef && !Array.isArray(testerRef)
          ? included.find(
              (r) => r.type === "betaTesters" && r.id === testerRef.id
            )
          : null;
      const build =
        buildRef && !Array.isArray(buildRef)
          ? included.find((r) => r.type === "builds" && r.id === buildRef.id)
          : null;
  
      const testerAttrs = tester?.attributes as
        | { firstName?: string; lastName?: string; email?: string }
        | undefined;
      const buildAttrs = build?.attributes as
        | { version?: string }
        | undefined;
  
      const attrs = sub.attributes as unknown as Record<string, unknown>;
      const screenshotAsset = attrs.screenshotAsset as
        | { templateUrl?: string }
        | undefined;
  
      return {
        id: sub.id,
        type,
        timestamp: attrs.timestamp as string,
        comment: (attrs.comment as string) ?? null,
        testerName: testerAttrs
          ? `${testerAttrs.firstName ?? ""} ${testerAttrs.lastName ?? ""}`.trim() || null
          : null,
        testerEmail: (testerAttrs?.email as string) ?? null,
        buildVersion: buildAttrs?.version ?? null,
        deviceModel: attrs.deviceModel as string,
        osVersion: attrs.osVersion as string,
        locale: attrs.locale as string,
        carrier: (attrs.carrier as string) ?? null,
        timezone: attrs.timezone as string,
        architecture: attrs.architecture as string,
        connectionStatus: attrs.connectionStatus as string,
        batteryPercentage: (attrs.batteryPercentage as number) ?? null,
        appUptime: (attrs.appUptime as number) ?? null,
        screenResolution:
          attrs.screenWidth != null
            ? `${attrs.screenWidth}x${attrs.screenHeight}`
            : null,
        diskSpaceFree: (attrs.diskSpaceFree as number) ?? null,
        screenshotUrl: screenshotAsset?.templateUrl ?? null,
        crashLogUrl:
          type === "crash"
            ? `https://api.appstoreconnect.apple.com/v1/betaFeedbackCrashSubmissions/${sub.id}/relationships/crashLog`
            : null,
      };
    });
  }

• src/api/feedback.ts:97-168 (helper)

  listIrisFeedback helper: fetches text comment feedback via Apple's internal iris API (requires browser auth).

  export async function listIrisFeedback(
    appId: string,
    options?: { buildId?: string; limit?: number }
  ): Promise<FeedbackItem[] | null> {
    if (!isBrowserEnabled()) return null;
  
    let url = `https://appstoreconnect.apple.com/iris/v1/betaFeedbacks?filter[build.app]=${appId}&sort=-timestamp&exists[crash]=false&include=tester,build,screenshots,buildBundle&fields[betaTesters]=firstName,lastName&fields[builds]=version&limit=${options?.limit ?? 60}`;
  
    if (options?.buildId) {
      url += `&filter[build]=${options.buildId}`;
    }
  
    const response = await fetchWithBrowserAuth(url);
    if (!response) return null;
  
    try {
      const json = (await response.json()) as {
        data: IrisBetaFeedback[];
        included?: JsonApiResource[];
      };
  
      return json.data.map((item) => {
        const testerRef = item.relationships?.tester?.data;
        const buildRef = item.relationships?.build?.data;
        const included = json.included ?? [];
  
        const tester = testerRef
          ? included.find((r) => r.type === "betaTesters" && r.id === testerRef.id)
          : null;
        const build = buildRef
          ? included.find((r) => r.type === "builds" && r.id === buildRef.id)
          : null;
  
        const testerAttrs = tester?.attributes as
          | { firstName?: string; lastName?: string }
          | undefined;
        const buildAttrs = build?.attributes as
          | { version?: string }
          | undefined;
  
        return {
          id: item.id,
          type: "comment" as const,
          timestamp: item.attributes.timestamp,
          comment: item.attributes.comment,
          testerName: testerAttrs
            ? `${testerAttrs.firstName ?? ""} ${testerAttrs.lastName ?? ""}`.trim() || null
            : null,
          testerEmail: item.attributes.emailAddress,
          buildVersion: buildAttrs?.version ?? null,
          deviceModel: item.attributes.deviceModel,
          osVersion: item.attributes.osVersion,
          locale: item.attributes.locale,
          carrier: item.attributes.carrier,
          timezone: item.attributes.timezone,
          architecture: item.attributes.architecture,
          connectionStatus: item.attributes.connectionStatus,
          batteryPercentage: item.attributes.batteryPercentage,
          appUptime: item.attributes.appUptime,
          screenResolution: item.attributes.screenWidth
            ? `${item.attributes.screenWidth}x${item.attributes.screenHeight}`
            : null,
          diskSpaceFree: item.attributes.diskSpaceFree,
          screenshotUrl: null,
          crashLogUrl: null,
        };
      });
    } catch {
      console.error("Failed to parse iris feedback response");
      return null;
    }
  }