Skip to content

Commit db83c61

Browse files
backslash-fbackslash-f
authored
Merge pull request #1 from thatfactory/codex/minimal-xcode-cloud-mcp
[codex] Add minimal Xcode Cloud MCP server
2 parents 2c4ca13 + 2d3d1ef commit db83c61

31 files changed

Lines changed: 3970 additions & 1 deletion

‎.github/workflows/ci.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
name: CI
3+
4+
on:
5+
push:
6+
branches:
7+
- main
8+
pull_request:
9+
10+
concurrency:
11+
group: ${{ github.workflow }}-${{ github.ref }}
12+
cancel-in-progress: true
13+
14+
jobs:
15+
test:
16+
name: Test
17+
runs-on: [self-hosted, macOS]
18+
steps:
19+
- name: Checkout Repository
20+
uses: actions/checkout@v6
21+
with:
22+
clean: true
23+
24+
- name: Setup Node.js
25+
uses: actions/setup-node@v4
26+
with:
27+
node-version: 22
28+
cache: npm
29+
30+
- name: Install Dependencies
31+
run: npm ci
32+
33+
- name: Run Tests
34+
run: npm test

‎.github/workflows/nightly.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: Nightly Tests
3+
4+
on:
5+
schedule:
6+
- cron: '0 4 * * *'
7+
8+
concurrency:
9+
group: ${{ github.workflow }}-${{ github.ref }}
10+
cancel-in-progress: true
11+
12+
jobs:
13+
nightly_tests:
14+
name: Nightly Tests
15+
runs-on: [self-hosted, macOS]
16+
steps:
17+
- name: Checkout Repository
18+
uses: actions/checkout@v6
19+
with:
20+
clean: true
21+
22+
- name: Setup Node.js
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: 22
26+
cache: npm
27+
28+
- name: Install Dependencies
29+
run: npm ci
30+
31+
- name: Run Tests
32+
run: npm test

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
node_modules
2+
dist
3+
.env
4+
.DS_Store
5+
coverage

‎README.md‎

Lines changed: 111 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,112 @@
1+
<p align="center">
2+
<a href="https://docs.anthropic.com/en/docs/claude-code/mcp"><img alt="Claude" src="https://img.shields.io/badge/Claude-MCP-D97757.svg?logo=claude&logoColor=white"></a>
3+
<a href="https://developers.openai.com/codex/mcp"><img alt="Codex" src="https://img.shields.io/badge/Codex-MCP-1F70C1.svg?logo=icloud&logoColor=white"></a>
4+
<a href="https://en.wikipedia.org/wiki/MIT_License"><img alt="License" src="https://img.shields.io/badge/License-MIT-67ac5b.svg?logo=googledocs&logoColor=white"></a>
5+
<a href="https://github.com/thatfactory/xcode-cloud-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/thatfactory/xcode-cloud-mcp/actions/workflows/ci.yml/badge.svg"></a>
6+
<a href="https://github.com/thatfactory/xcode-cloud-mcp/actions/workflows/nightly.yml"><img alt="Nightly" src="https://github.com/thatfactory/xcode-cloud-mcp/actions/workflows/nightly.yml/badge.svg"></a>
7+
</p>
8+
19
# xcode-cloud-mcp
2-
MCP server for working with Apple's Xcode Cloud. ☁️
10+
11+
Minimal MCP server for discovering Xcode Cloud products and workflows, then retrieving build issues, logs, test summaries, and UI test artifacts through the App Store Connect API.
12+
13+
## Features
14+
15+
- Discover Xcode Cloud products with `list_products`.
16+
- Discover workflows for a product with `list_workflows`.
17+
- List recent workflow runs with `list_build_runs`.
18+
- Retrieve build issue counts with `get_build_issues`.
19+
- Retrieve and summarize text-like build logs with `get_build_logs`.
20+
- Retrieve test summaries with `get_test_results`.
21+
- Retrieve screenshots, videos, result bundles, and test products with `get_test_artifacts`.
22+
23+
Build lookup is workflow-scoped. Retrieval tools accept a direct `buildRunId`, or a `workflowId` plus `buildNumber`, or a `workflowId` plus `buildSelector: "latest" | "latestFailing"`.
24+
25+
## Requirements
26+
27+
- Node.js `20+`
28+
- App Store Connect API credentials with access to Xcode Cloud
29+
30+
## Environment Variables
31+
32+
Primary names:
33+
34+
- `APPSTORE_CONNECT_API_KEY_ID`
35+
- `APPSTORE_CONNECT_API_ISSUER_ID`
36+
- `APPSTORE_CONNECT_API_KEY_CONTENT`
37+
38+
Compatibility aliases:
39+
40+
- `APP_STORE_KEY_ID`
41+
- `APP_STORE_ISSUER_ID`
42+
- `APP_STORE_PRIVATE_KEY`
43+
44+
The private key can be passed as literal multi-line PEM content or as a string with escaped `\n`.
45+
46+
## Claude Setup
47+
48+
```bash
49+
claude mcp add xcode-cloud \
50+
--env APPSTORE_CONNECT_API_KEY_ID="$APPSTORE_CONNECT_API_KEY_ID" \
51+
--env APPSTORE_CONNECT_API_ISSUER_ID="$APPSTORE_CONNECT_API_ISSUER_ID" \
52+
--env APPSTORE_CONNECT_API_KEY_CONTENT="$APPSTORE_CONNECT_API_KEY_CONTENT" \
53+
-- npx -y @thatfactory/xcode-cloud-mcp
54+
```
55+
56+
## Codex Setup
57+
58+
```bash
59+
codex mcp add xcode-cloud \
60+
--env APPSTORE_CONNECT_API_KEY_ID="$APPSTORE_CONNECT_API_KEY_ID" \
61+
--env APPSTORE_CONNECT_API_ISSUER_ID="$APPSTORE_CONNECT_API_ISSUER_ID" \
62+
--env APPSTORE_CONNECT_API_KEY_CONTENT="$APPSTORE_CONNECT_API_KEY_CONTENT" \
63+
-- npx -y @thatfactory/xcode-cloud-mcp
64+
```
65+
66+
## Available Tools
67+
68+
- `list_products(limit?)`
69+
- `list_workflows(productId, limit?)`
70+
- `list_build_runs(workflowId, limit?, status?)`
71+
- `get_build_issues(buildRunId? workflowId? buildNumber? buildSelector?)`
72+
- `get_build_logs(buildRunId? workflowId? buildNumber? buildSelector?, maxCharacters?)`
73+
- `get_test_results(buildRunId? workflowId? buildNumber? buildSelector?)`
74+
- `get_test_artifacts(buildRunId? workflowId? buildNumber? buildSelector?)`
75+
76+
## Example Prompts
77+
78+
```text
79+
Retrieve logs of the latest failing build for workflow abc123.
80+
```
81+
82+
```text
83+
Retrieve logs of build number 42 for workflow abc123.
84+
```
85+
86+
```text
87+
Show me the latest failing UI test artifacts for workflow abc123.
88+
```
89+
90+
```text
91+
List the workflows for product def456 and then summarize the latest build.
92+
```
93+
94+
## Local Development
95+
96+
Install dependencies:
97+
98+
```bash
99+
npm install
100+
```
101+
102+
Run tests:
103+
104+
```bash
105+
npm test
106+
```
107+
108+
Build the package:
109+
110+
```bash
111+
npm run build
112+
```

0 commit comments

Comments
 (0)