App Store Connect MCP Server

Instructions

Implementation Reference

• src/handlers/workflows.ts:93-121 (handler)

  The main handler function that fetches CI build actions from the App Store Connect API for a given build run ID.

  async listBuildActions(args: {
    buildRunId: string;
    limit?: number;
    sort?: CiBuildActionSortOptions;
    filter?: CiBuildActionFilters;
    fields?: {
      ciBuildActions?: CiBuildActionFieldOptions[];
    };
    include?: CiBuildActionIncludeOptions[];
  }): Promise<CiBuildActionsResponse> {
    const { buildRunId, 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<CiBuildActionsResponse>(`/ciBuildRuns/${buildRunId}/actions`, params);
  }

• src/index.ts:1431-1435 (registration)

  Tool registration in the MCP server handler switch statement, mapping the tool call to the workflow handler.

  // CI Build Actions Management
  case "list_ci_build_actions":
    const buildActionsData = await this.workflowHandlers.listBuildActions(args as any);
    return formatResponse(buildActionsData);

• src/index.ts:981-1045 (schema)

  MCP tool schema definition including input parameters, descriptions, types, and constraints for list_ci_build_actions.

    name: "list_ci_build_actions",
    description: "List build actions (analyze, build, test, archive) for a specific build run",
    inputSchema: {
      type: "object",
      properties: {
        buildRunId: {
          type: "string",
          description: "The ID of the build run to list actions for"
        },
        limit: {
          type: "number",
          description: "Maximum number of build actions to return (default: 100, max: 200)",
          minimum: 1,
          maximum: 200
        },
        sort: {
          type: "string",
          description: "Sort order for the results",
          enum: ["name", "-name", "actionType", "-actionType", "startedDate", "-startedDate", "finishedDate", "-finishedDate"]
        },
        filter: {
          type: "object",
          properties: {
            actionType: {
              type: "string",
              enum: ["ANALYZE", "BUILD", "TEST", "ARCHIVE"],
              description: "Filter by action type"
            },
            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"
            }
          }
        },
        include: {
          type: "array",
          items: {
            type: "string",
            enum: ["buildRun", "issues", "testResults"]
          },
          description: "Related resources to include in the response"
        },
        fields: {
          type: "object",
          properties: {
            ciBuildActions: {
              type: "array",
              items: {
                type: "string",
                enum: ["name", "actionType", "startedDate", "finishedDate", "issueCounts", "executionProgress", "completionStatus"]
              },
              description: "Fields to include for each build action"
            }
          }
        }
      },
      required: ["buildRunId"]
    }
  },

• src/types/workflows.ts:216-300 (schema)

  Type definitions for CI build actions, responses, filters, sort options, field options, and includes used by the tool.

  // CI Build Action Types
  export interface CiBuildAction {
    id: string;
    type: "ciBuildActions";
    attributes: {
      name: string;
      actionType: "ANALYZE" | "BUILD" | "TEST" | "ARCHIVE";
      startedDate?: string;
      finishedDate?: string;
      issueCounts?: {
        analyzerWarnings?: number;
        errors?: number;
        testFailures?: number;
        warnings?: number;
      };
      executionProgress?: "PENDING" | "RUNNING" | "COMPLETE";
      completionStatus?: "SUCCEEDED" | "FAILED" | "ERRORED" | "CANCELED" | "SKIPPED";
    };
    relationships?: {
      buildRun?: {
        data?: {
          id: string;
          type: "ciBuildRuns";
        };
      };
      issues?: {
        data?: Array<{
          id: string;
          type: "ciIssues";
        }>;
      };
      testResults?: {
        data?: Array<{
          id: string;
          type: "ciTestResults";
        }>;
      };
    };
  }
  
  export interface CiBuildActionsResponse {
    data: CiBuildAction[];
    included?: Array<{
      id: string;
      type: "ciBuildRuns" | "ciIssues" | "ciTestResults";
      attributes: any;
    }>;
    links?: {
      self: string;
      first?: string;
      next?: string;
    };
    meta?: {
      paging: {
        total: number;
        limit: number;
      };
    };
  }
  
  export interface CiBuildActionFilters {
    actionType?: "ANALYZE" | "BUILD" | "TEST" | "ARCHIVE";
    executionProgress?: "PENDING" | "RUNNING" | "COMPLETE";
    completionStatus?: "SUCCEEDED" | "FAILED" | "ERRORED" | "CANCELED" | "SKIPPED";
  }
  
  export type CiBuildActionSortOptions = 
    | "name" | "-name"
    | "actionType" | "-actionType"
    | "startedDate" | "-startedDate"
    | "finishedDate" | "-finishedDate";
  
  export type CiBuildActionFieldOptions = 
    | "name"
    | "actionType"
    | "startedDate"
    | "finishedDate"
    | "issueCounts"
    | "executionProgress"
    | "completionStatus";
  
  export type CiBuildActionIncludeOptions =
    | "buildRun"
    | "issues"
    | "testResults";

• src/utils/validation.ts:36-60 (helper)

  Utility functions used in handlers: sanitizeLimit for limit param, buildFilterParams and buildFieldParams for constructing API query parameters.

  export function buildFilterParams(filter: Record<string, any> = {}): Record<string, string> {
    const params: Record<string, string> = {};
    
    Object.entries(filter).forEach(([key, value]) => {
      if (value !== undefined && value !== null) {
        if (Array.isArray(value)) {
          params[`filter[${key}]`] = value.join(',');
        } else {
          params[`filter[${key}]`] = String(value);
        }
      }
    });
    
    return params;
  }
  
  export function buildFieldParams(fields: Record<string, string[]> = {}): Record<string, string> {
    const params: Record<string, string> = {};
    
    Object.entries(fields).forEach(([key, value]) => {
      if (Array.isArray(value) && value.length > 0) {
        params[`fields[${key}]`] = value.join(',');
      }
    });