App Store Connect MCP Server

Instructions

Implementation Reference

• src/handlers/workflows.ts:63-91 (handler)

  Core handler function that executes the tool logic: fetches list of build runs for a given CI product (workflow) ID from App Store Connect API, applying filters, sorting, fields, and includes.

  async listBuildRuns(args: {
    ciProductId: string;
    limit?: number;
    sort?: CiBuildRunSortOptions;
    filter?: CiBuildRunFilters;
    fields?: {
      ciBuildRuns?: CiBuildRunFieldOptions[];
    };
    include?: CiBuildRunIncludeOptions[];
  }): Promise<CiBuildRunsResponse> {
    const { ciProductId, limit = 100, sort, filter, fields, include } = args;
    
    const params: Record<string, any> = {
      limit: sanitizeLimit(limit)
    };
  
    if (sort) {
      params.sort = sort;
    }
  
    if (include?.length) {
      params.include = include.join(',');
    }
  
    Object.assign(params, buildFilterParams(filter));
    Object.assign(params, buildFieldParams(fields));
  
    return this.client.get<CiBuildRunsResponse>(`/ciProducts/${ciProductId}/buildRuns`, params);
  }

• src/index.ts:905-977 (schema)

  MCP tool schema definition specifying the input parameters, validation, and description for the list_build_runs tool.

    name: "list_build_runs",
    description: "List build runs for a specific workflow/CI product, including git commit information",
    inputSchema: {
      type: "object",
      properties: {
        ciProductId: {
          type: "string",
          description: "The ID of the CI product (workflow) to list build runs for"
        },
        limit: {
          type: "number",
          description: "Maximum number of build runs to return (default: 100, max: 200)",
          minimum: 1,
          maximum: 200
        },
        sort: {
          type: "string",
          description: "Sort order for the results",
          enum: ["number", "-number", "createdDate", "-createdDate", "startedDate", "-startedDate", "finishedDate", "-finishedDate"]
        },
        filter: {
          type: "object",
          properties: {
            number: {
              type: "number",
              description: "Filter by build run number"
            },
            isPullRequestBuild: {
              type: "boolean",
              description: "Filter by whether it's a pull request build"
            },
            executionProgress: {
              type: "string",
              enum: ["PENDING", "RUNNING", "COMPLETE"],
              description: "Filter by execution progress"
            },
            completionStatus: {
              type: "string",
              enum: ["SUCCEEDED", "FAILED", "ERRORED", "CANCELED", "SKIPPED"],
              description: "Filter by completion status"
            },
            startReason: {
              type: "string",
              enum: ["MANUAL", "SCM_CHANGE", "PULL_REQUEST_UPDATE", "SCHEDULED"],
              description: "Filter by start reason"
            }
          }
        },
        include: {
          type: "array",
          items: {
            type: "string",
            enum: ["builds", "workflow", "product", "sourceBranchOrTag", "destinationBranch", "pullRequest"]
          },
          description: "Related resources to include in the response"
        },
        fields: {
          type: "object",
          properties: {
            ciBuildRuns: {
              type: "array",
              items: {
                type: "string",
                enum: ["number", "createdDate", "startedDate", "finishedDate", "sourceCommit", "destinationCommit", "isPullRequestBuild", "issueCounts", "executionProgress", "completionStatus", "startReason", "cancelReason"]
              },
              description: "Fields to include for each build run"
            }
          }
        }
      },
      required: ["ciProductId"]
    }
  },

• src/index.ts:1427-1429 (registration)

  Registration of the tool in the MCP server request handler: dispatches calls to 'list_build_runs' to the workflowHandlers.listBuildRuns method.

  case "list_build_runs":
    const buildRunsData = await this.workflowHandlers.listBuildRuns(args as any);
    return formatResponse(buildRunsData);

• src/types/workflows.ts:156-215 (schema)

  TypeScript type definitions for the build runs response, filters, sort options, field options, and include options used by the handler and reflected in the tool schema.

  export interface CiBuildRunsResponse {
    data: CiBuildRun[];
    included?: Array<{
      id: string;
      type: "builds" | "ciWorkflows" | "ciProducts" | "scmGitReferences" | "scmPullRequests";
      attributes: any;
    }>;
    links?: {
      self: string;
      first?: string;
      next?: string;
    };
    meta?: {
      paging: {
        total: number;
        limit: number;
      };
    };
  }
  
  export interface CiBuildRunFilters {
    number?: number;
    createdDate?: string;
    startedDate?: string;
    finishedDate?: string;
    isPullRequestBuild?: boolean;
    executionProgress?: "PENDING" | "RUNNING" | "COMPLETE";
    completionStatus?: "SUCCEEDED" | "FAILED" | "ERRORED" | "CANCELED" | "SKIPPED";
    startReason?: "MANUAL" | "SCM_CHANGE" | "PULL_REQUEST_UPDATE" | "SCHEDULED";
    cancelReason?: "AUTOMATICALLY_BY_NEWER_BUILD" | "MANUALLY_BY_USER";
  }
  
  export type CiBuildRunSortOptions = 
    | "number" | "-number"
    | "createdDate" | "-createdDate"
    | "startedDate" | "-startedDate"
    | "finishedDate" | "-finishedDate";
  
  export type CiBuildRunFieldOptions = 
    | "number"
    | "createdDate"
    | "startedDate"
    | "finishedDate"
    | "sourceCommit"
    | "destinationCommit"
    | "isPullRequestBuild"
    | "issueCounts"
    | "executionProgress"
    | "completionStatus"
    | "startReason"
    | "cancelReason";
  
  export type CiBuildRunIncludeOptions =
    | "builds"
    | "workflow"
    | "product"
    | "sourceBranchOrTag"
    | "destinationBranch"
    | "pullRequest";

• src/utils/index.ts:1-29 (helper)

  Re-exports utility functions like sanitizeLimit, buildFilterParams, buildFieldParams used in the handler for parameter processing.

  export * from './validation.js';