Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ MCP server for discovering Xcode Cloud products, inspecting and editing workflow
| Discover workflows | `list_workflows` | "List the workflows for product `def456`." | `Feature Branch`, `description`, `isEnabled: true`, `containerFilePath: Chauffeur.xcodeproj` |
| Inspect workflow configuration | `get_workflow_details` | "Show me the full workflow details for `abc123`, including environment and actions." | `general`, `environment`, `startConditions`, `actions`, `postActions` |
| Monitor running or recent builds | `list_build_runs` | "Show me the running builds for workflow `abc123` so I can monitor them." | `number: 93`, `executionProgress: RUNNING`, `completionStatus: null`, `startedDate: ...` |
| Resolve linked TestFlight build IDs | `get_build_run_testflight_builds` | "Verify this release run and find its iOS and tvOS builds for TestFlight." | verified run provenance and per-platform readiness |
| Start an Xcode Cloud build | `start_build` | "Start one build for workflow `abc123`." | newly created build-run ID, number, and execution state |
| Enable or disable a workflow | `set_workflow_enabled` | "Disable workflow `abc123` while we are testing new settings." | `operation.type: set_workflow_enabled`, `workflow.general.isEnabled: false` |
| Update name, description, or clean mode | `update_workflow_general` | "Rename workflow `abc123` to `Feature Branch v2` and adjust its description." | `changedFields: [name, description]`, updated `workflow.general` |
Expand All @@ -36,7 +37,7 @@ Build lookup is workflow-scoped. Retrieval tools accept a direct `buildRunId`, o

`list_products` and `list_workflows` automatically paginate through all results.

`list_build_runs` supports `status: "all" | "failed" | "succeeded" | "running" | "pending"` and an optional `limit`, which defaults to `20`, so agents can poll active workflows without post-processing every run locally or inflating MCP response size.
`list_build_runs` supports `status: "all" | "failed" | "succeeded" | "running" | "pending"` and an optional exact `sourceCommitSha` filter. The limit (default 20, maximum 500) bounds the runs scanned before filtering. Each result includes the full source commit SHA, canonical source ref and its resource ID when available, the PR flag, and the start reason. For a SHA lookup with no results, check `scan.hasMore` for older runs and `scan.unverifiedSourceCount` for scanned runs whose SHA was unavailable. If several runs match, use the intended exact run ID for the handoff.

## Build Start Behavior

Expand Down Expand Up @@ -92,7 +93,8 @@ codex mcp add xcode-cloud \
- `list_products()`
- `list_workflows(productId)`
- `get_workflow_details(workflowId)`
- `list_build_runs(workflowId, limit?, status?)`
- `list_build_runs(workflowId, limit?, status?, sourceCommitSha?)`
- `get_build_run_testflight_builds(buildRunId, workflowId, appId, platforms, expectedSourceRef?, expectedSourceCommitSha?)`
- `start_build(workflowId, clean?, sourceBranchOrTagId?, pullRequestId?, buildRunId?)`
- `set_workflow_enabled(workflowId, enabled)`
- `update_workflow_general(workflowId, name?, description?, clean?)`
Expand Down Expand Up @@ -247,4 +249,14 @@ Creating an archive, making it eligible for TestFlight, and assigning its proces

Apple's [OpenAPI specification](https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip), version 4.4.1, inspected on 2026-09-07, exposes no post-action field or relationship in `CiWorkflow`, `CiWorkflowCreateRequest`, or `CiWorkflowUpdateRequest`, and no workflow post-action endpoint. Consequently, workflow responses explicitly report `testFlightDistribution.status: "UNSUPPORTED_BY_APPLE_API"` and group assignment as `UNKNOWN`; the legacy empty `postActions` array is not evidence that no post-actions exist. See Apple's [BuildAudienceType](https://developer.apple.com/documentation/appstoreconnectapi/buildaudiencetype) and [TestFlight distribution guide](https://developer.apple.com/documentation/xcode/distributing-your-xcode-cloud-builds-through-testflight).

Waiting for completion, TestFlight processing, beta-group assignment, and broader release orchestration remain outside this server's current scope and would not be native Xcode Cloud post-actions.
### Read-only TestFlight handoff

Call `get_build_run_testflight_builds` with an exact Xcode Cloud run ID, its expected workflow ID, the App Store Connect app resource ID, and one or more distinct Apple platform values (`IOS`, `TV_OS`, `MAC_OS`, `VISION_OS`). Run and workflow IDs may also use their `xcode-cloud://` URI forms. For automated handoff, provide both `expectedSourceRef` (for example, `refs/heads/main`) and `expectedSourceCommitSha` (the full Git SHA). With those inputs the tool verifies the branch and revision and rejects pull-request runs.

The tool verifies the run and workflow, reads the run's linked builds, and verifies each build against its App Store Connect app and prerelease version. When the run returns a build ID without its metadata, the tool reads that exact build ID for the missing evidence. The response includes run provenance and the following statuses.

- `ready` means the run succeeded and each requested platform has exactly one verified, valid, unexpired, externally eligible build. Each platform includes `build.id`, marketing version, build number, processing state, audience, and expiration state.
- `pending` means the run is still active, a requested platform has no linked build yet, or a relevant build is processing. Read again after the upload or processing progresses.
- `blocked` reports per-platform reasons such as a failed or canceled run, app mismatch, internal-only or expired build, missing or unknown evidence, or ambiguous eligible builds. A run, workflow, or requested source mismatch produces an MCP error.

A successful archive can precede upload and processing in App Store Connect. When the overall status is `ready`, pass the exact `build.id` values to [app-store-connect-mcp](https://github.com/thatfactory/app-store-connect-mcp) or another consumer that rechecks eligibility before TestFlight distribution. Beta review and group assignment are separate App Store Connect operations.
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@thatfactory/xcode-cloud-mcp",
"version": "0.7.0",
"version": "0.8.0",
"description": "MCP server for configuring Xcode Cloud workflows, starting builds, and retrieving build logs, issues, and test artifacts.",
"license": "MIT",
"type": "module",
Expand Down
39 changes: 26 additions & 13 deletions src/api/base-client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ export class BaseAPIClient {
url.searchParams.set(key, value);
}

return this.request<TData>(url.toString());
return this.request<TData, TIncluded>(url.toString());
}

/**
Expand All @@ -46,27 +46,40 @@ export class BaseAPIClient {
params?: Record<string, string>,
maxItems?: number,
): Promise<TData[]> {
return (await this.listAllWithIncluded<TData, never>(path, params, maxItems)).data;
}

/** Collect primary and included resources, preserving whether the scan hit its bound. */
protected async listAllWithIncluded<TData, TIncluded>(
path: string,
params?: Record<string, string>,
maxItems?: number,
): Promise<{ data: TData[]; included: TIncluded[]; hasMore: boolean }> {
const allData: TData[] = [];
const included: TIncluded[] = [];

let response = await this.get<TData>(path, params);
if (Array.isArray(response.data)) {
allData.push(...response.data);
} else {
return [response.data];
let response = await this.get<TData[], TIncluded>(path, params);
if (!Array.isArray(response.data)) {
return { data: [response.data], included: response.included ?? [], hasMore: false };
}

while (response.links?.next && (!maxItems || allData.length < maxItems)) {
response = await this.request<TData>(this.resolveNextPageUrl(response.links.next));
while (true) {
included.push(...(response.included ?? []));
if (Array.isArray(response.data)) {
allData.push(...response.data);
}
}

if (maxItems && allData.length > maxItems) {
return allData.slice(0, maxItems);
}
const next = response.links?.next;
if (!next || (maxItems && allData.length >= maxItems)) {
return {
data: maxItems ? allData.slice(0, maxItems) : allData,
included,
hasMore: Boolean(next || (maxItems && allData.length > maxItems)),
};
}

return allData;
response = await this.request<TData[], TIncluded>(this.resolveNextPageUrl(next));
}
}

/**
Expand Down
53 changes: 53 additions & 0 deletions src/api/resources/builds.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,24 @@
import { BaseAPIClient } from '../base-client.js';
import type {
AppStoreBuild,
CiBuildAction,
CiBuildRun,
CiBuildRunCreateRequest,
CiBuildRunStartOptions,
CiWorkflow,
PrereleaseVersion,
ScmGitReference,
} from '../types.js';

type BuildIncludedResource = PrereleaseVersion | { type: 'apps'; id: string };

const testFlightBuildFields = {
include: 'app,preReleaseVersion',
'fields[apps]': 'bundleId',
'fields[builds]': 'version,expired,processingState,buildAudienceType,app,preReleaseVersion',
'fields[preReleaseVersions]': 'platform,version',
};

/**
* Build run endpoints.
*/
Expand Down Expand Up @@ -80,6 +93,46 @@ export class BuildsClient extends BaseAPIClient {
return response.data;
}

/** Read the workflow and source linkage alongside the exact build run. */
async getWithProvenance(buildRunId: string) {
return this.get<CiBuildRun, CiWorkflow | ScmGitReference>(
`/v1/ciBuildRuns/${encodeURIComponent(buildRunId)}`,
{ include: 'workflow,sourceBranchOrTag' },
);
}

async getGitReference(referenceId: string): Promise<ScmGitReference> {
const response = await this.get<ScmGitReference>(
`/v1/scmGitReferences/${encodeURIComponent(referenceId)}`,
);
return response.data;
}

/** Scan a bounded number of runs with their source references. */
async listWithProvenance(workflowId: string, scanLimit: number) {
return this.listAllWithIncluded<CiBuildRun, ScmGitReference>(
`/v1/ciWorkflows/${encodeURIComponent(workflowId)}/buildRuns`,
{ include: 'sourceBranchOrTag', sort: '-number', limit: String(Math.min(scanLimit, 200)) },
scanLimit,
);
}

/** Read only the App Store Connect builds explicitly linked to this run. */
async listLinkedBuilds(buildRunId: string) {
return this.listAllWithIncluded<AppStoreBuild, BuildIncludedResource>(
`/v1/ciBuildRuns/${encodeURIComponent(buildRunId)}/builds`,
{ ...testFlightBuildFields, limit: '200' },
);
}

/** Hydrate an exact linked build when the run endpoint omits build evidence. */
async getLinkedBuildDetails(buildId: string) {
return this.get<AppStoreBuild, BuildIncludedResource>(
`/v1/builds/${encodeURIComponent(buildId)}`,
testFlightBuildFields,
);
}

/**
* List build runs for a workflow, paginating through all results.
* Optionally limit the total number of build runs returned.
Expand Down
46 changes: 39 additions & 7 deletions src/api/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -171,21 +171,19 @@ export interface CiBuildRun {
startedDate?: string;
finishedDate?: string;
executionProgress: 'PENDING' | 'RUNNING' | 'COMPLETE';
completionStatus?: 'SUCCEEDED' | 'FAILED' | 'ERRORED' | 'CANCELED';
completionStatus?: 'SUCCEEDED' | 'FAILED' | 'ERRORED' | 'CANCELED' | 'SKIPPED' | null;
isPullRequestBuild: boolean;
issueCounts?: CiIssueCounts;
startReason?: 'GIT_REF_CHANGE' | 'MANUAL' | 'MANUAL_REBUILD' | 'PULL_REQUEST_OPEN' | 'PULL_REQUEST_UPDATE' | 'SCHEDULE';
sourceCommit?: {
commitSha: string;
message?: string;
};
};
relationships?: {
workflow?: {
data: {
type: 'ciWorkflows';
id: string;
};
};
workflow?: ToOneRelationship<'ciWorkflows'>;
sourceBranchOrTag?: ToOneRelationship<'scmGitReferences'>;
pullRequest?: ToOneRelationship<'scmPullRequests'>;
};
}

Expand All @@ -194,6 +192,40 @@ interface ResourceIdentifier<TType extends string> {
id: string;
}

interface ToOneRelationship<TType extends string> {
data?: ResourceIdentifier<TType> | null;
}

export interface ScmGitReference extends ResourceIdentifier<'scmGitReferences'> {
attributes?: {
canonicalName?: string;
kind?: 'BRANCH' | 'TAG';
};
}

export const buildPlatforms = ['IOS', 'MAC_OS', 'TV_OS', 'VISION_OS'] as const;
export type BuildPlatform = (typeof buildPlatforms)[number];

export interface PrereleaseVersion extends ResourceIdentifier<'preReleaseVersions'> {
attributes?: {
platform?: BuildPlatform;
version?: string;
};
}

export interface AppStoreBuild extends ResourceIdentifier<'builds'> {
attributes?: {
version?: string | null;
expired?: boolean | null;
processingState?: 'PROCESSING' | 'FAILED' | 'INVALID' | 'VALID' | null;
buildAudienceType?: BuildAudienceType | null;
};
relationships?: {
app?: ToOneRelationship<'apps'>;
preReleaseVersion?: ToOneRelationship<'preReleaseVersions'>;
};
}

/**
* Options for creating one Xcode Cloud build run.
*/
Expand Down
2 changes: 1 addition & 1 deletion src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ export function createServer(): McpServer {

const server = new McpServer({
name: 'Xcode Cloud MCP',
version: '0.7.0',
version: '0.8.0',
});

registerDiscoveryTools(server, client);
Expand Down
Loading