内容
# codemagic-mcp
[](https://github.com/lexandro/codemagic-mcp/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/lexandro/codemagic-mcp)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
一个遵循模型上下文协议（MCP）的服务器，允许 AI 代理驱动 Codemagic 的 CI/CD 流程 —— 启动构建、轮询状态、从构建日志中诊断故障 —— 构建在两个严格的约束之上：**代币经济** 和 **秘密隐私**。
> **隐私一句话。** Codemagic API令牌仅从 `CODEMAGIC_API_TOKEN` 环境变量中读取 —— 绝不作为工具参数读取，绝不写入磁盘，绝不输出或错误回显。您的 Codemagic 环境变量的**值**绝不会被暴露；仅限于组和变量的**名称**。**服务器返回的每个字符串都会经过一次编辑**，以去除 PEM 块、长 base64 块、JWT、`key=value` 机密、URL 中的凭证和签名下载 URL。**除非您明确设置 `CODEMAGIC_MCP_ALLOW_BUILDS=true`，否则无法触发构建**。无遥测、无缓存、无文件系统写入。请参阅 [SECURITY.md](SECURITY.md) 以获取威胁模型和诚实的限制。
## 为什么存在
移动发布工程是一个缓慢的反馈循环：触发构建、等待、读取长日志、修复、重复。AI 代理可以驱动该循环 —— 但前提是它可以启动构建、轮询状态和读取故障，而不会因数兆字节的日志而耗尽其上下文窗口，也不会将您的签名密钥输送到聊天记录中。
实际的 Codemagic iOS 构建日志达到数兆字节。该服务器将其转换为约 730 个令牌，并在第一行显示可操作的错误：
```
步骤：构建 ipa（失败，8m29s）
选择：失败步骤
模式：错误聚焦
行数：41/625
匹配项：6
第一个错误：错误（Xcode）：未找到 'com.example.myapp' 的配置文件：Xcode 找不到任何匹配 'com.example.myapp' 的 iOS 应用商店配置文件。自动签名已禁用，无法生成配置文件。要启用自动签名，请传递 -allowProvisioningUpdates 给 xcodebuild。
--
…
```
每个工具的测量数字：[docs/TOKEN-BUDGET.md](docs/TOKEN-BUDGET.md)。
## 安装
**让 AI 为您安装：** 将您的代理指向 [docs/AI-INSTALL.md](docs/AI-INSTALL.md) —— 这是一个确定性的、分步骤的食谱，专为代理编写，包含每个步骤的预期输出。
**手动安装**，使用 Go 工具链：
```bash
go install github.com/lexandro/codemagic-mcp@latest
```
如果您也在开发此服务器，请将其安装在 `go install` 输出目录以外的其他位置 —— 请参阅 [在开发过程中安装](#installing-alongside-development)。
或者，从 [发布页面](https://github.com/lexandro/codemagic-mcp/releases) 为您的平台下载二进制文件。它是一个具有零运行时依赖的静态可执行文件。请使用同一发布中的 `checksums.txt` 验证它 —— 您即将为此二进制文件提供 API 令牌。
## 配置
1. 获取 API 令牌：Codemagic → **账户设置 → API 令牌**。
2. 在启动 MCP 客户端的环境中导出它：
```bash
export CODEMAGIC_API_TOKEN="your-token-here" # macOS / Linux
setx CODEMAGIC_API_TOKEN "your-token-here" # Windows, then reopen the terminal
```
3. 注册服务器：
```bash
codemagic-mcp register project # writes ./.mcp.json
codemagic-mcp register user # writes ~/.claude.json
```
要启用构建触发，请在注册之前设置门控：
```bash
CODEMAGIC_MCP_ALLOW_BUILDS=true codemagic-mcp register project
```
4. 重启您的 MCP 客户端并调用 `status` 以确认。
### 手动配置
`register` 编写如下所示的条目。注意，令牌是一个**引用**，而不是值 —— 您的 MCP 客户端在启动时扩展它，因此此文件可以安全提交：
```json
{
"mcpServers": {
"codemagic": {
"command": "/usr/local/bin/codemagic-mcp",
"args": [],
"env": {
"CODEMAGIC_API_TOKEN": "${CODEMAGIC_API_TOKEN}"
}
}
}
}
```
在 `env` 块中添加 `"CODEMAGIC_MCP_ALLOW_BUILDS": "true"` 以启用 `start_build` 和 `cancel_build`。
### 环境变量
| 变量 | 必需 | 效果 |
|---|---|---|
| `CODEMAGIC_API_TOKEN` | 是 | API 令牌。服务器在没有它的情况下拒绝启动。 |
| `CODEMAGIC_MCP_ALLOW_BUILDS` | 否 | 设置为 `true` 以启用 `start_build` 和 `cancel_build`。其他值使服务器只读。 |
### 标志
| 标志 | 默认值 | 效果 |
|---|---|---|
| `--timeout` | `30s` | 单个 Codemagic API 请求的超时时间。 |
故意**没有更改 API 主机的标志**。指向另一个主机会将您的令牌发送到那里。
## 工具
| 工具 | 目的 | 典型成本 |
|---|---|---|
| `status` | 令牌有效性、两个 API 主机的可达性、是否启用构建 | ~40 令牌 |
| `list_apps` | 令牌可见的应用 | ~17 令牌/应用 |
| `get_app` | 工作流、分支、环境变量组**名称** | ~55 令牌 |
| `list_builds` | 最近的构建，按应用、工作流、分支、标签、状态过滤 | ~24 令牌/构建 |
| `get_build` | 构建状态的轮询工具 | ~52 令牌 |
| `get_build_log` | 诊断故障；默认错误聚焦，绝不会是整个日志 | ~730–3,000 令牌 |
| `list_artifacts` | 构建产物。绝不会获取内容，也绝不会返回签名下载 URL | ~5 令牌/产物 |
| `start_build` | 触发构建。需要 `CODEMAGIC_MCP_ALLOW_BUILDS=true` | ~15 令牌 |
| `cancel_build` | 停止构建。相同的门控 | ~10 令牌 |
每个列表工具都采用 `limit`（默认为 10，最大 100）并将截断报告为 `truncated: 10/42`。每个工具都采用 `verbosity`（默认为 `summary`，按需 `detail`）。
### 输出示例
```
$ status
status: ok
account: 60a0b1c2d3e4f56789abcdef
codemagic.io: ok
api.codemagic.io: ok
CODEMAGIC_API_TOKEN is set (36 characters)
redaction: always on
builds: disabled (set CODEMAGIC_MCP_ALLOW_BUILDS=true and restart to enable start_build and cancel_build)
$ get_app appId=60a0b1c2d3e4f56789abcdef
id: 60a0b1c2d3e4f56789abcdef
name: myapp-ios
repository: https://github.com/example/myapp
provider: github
defaultBranch: main
branches: main, develop
workflows: ios-workflow=iOS Release
variableGroups: appstore, firebase
$ get_build buildId=6890abcdef1234567890abcd
id: 6890abcdef1234567890abcd
status: failed
workflow: ios-workflow=iOS Release
branch: main
build: #42
started: 2026-07-26T10:12:03Z
duration: 8m41s
failedStep: Build ipa
commit: a1b2c3d fix: bump build number
$ list_artifacts buildId=6890abcdef1234567890abcd
Runner.ipa 43MB ipa
```
只有没有什么可说的字段才不会产生一行。这种省略是服务器中节省令牌的最大一项。
### 错误
错误被分类，以便代理知道是重试、等待还是停止：
```
Error [fatal]: invalid or expired API token
Action: Generate a new token in Codemagic > Account settings > API token, set CODEMAGIC_API_TOKEN to it, then restart the MCP server
Details: HTTP 401 from api.codemagic.io
```
`transient` 表示重试有帮助，服务器已经重试。`degraded` 表示回退 —— 通常是速率限制，并伴有秒数等待。`fatal` 表示人类必须更改某些内容。服务器在连接失败时绝不会退出：Codemagic 恢复后，下一次调用即可正常工作。
## 已知的 Codemagic 怪癖
在第一次构建之前值得了解：
- **具有 `codemagic.yaml` 的应用报告错误的工作流或根本没有报告。** Codemagic 不存储 yaml 配置，因此 `get_app` 返回 Web UI 所示的内容 —— 通常是一个陈旧的“默认工作流”，从未被任何构建使用过 —— 或者根本没有。对于这些应用，您传递给 `start_build` 的 `workflowId` 是 `codemagic.yaml` 中的**工作流键**（例如 `ios-workflow`），而不是 `get_app` 中的 ID。这是第一个运行失败的最常见原因。可靠地找到真正的键的方法是 `list_builds`，它显示了每个构建实际运行的工作流。
- **两个主机上的两个 API。** Codemagic 在 `api.codemagic.io` 上运行一个旧版 API，在 `codemagic.io/api/v3` 上运行一个当前 API，此服务器需要这两个 API —— 只有 v1 可以读取构建日志或启动构建，只有 v3 具有类型化的构建详细信息和变量组。出口仅限于这两个主机。
- **一些端点未记录。** `GET /builds`、`GET /builds/:id/step/:stepId`（读取日志的唯一方法）和 v1 响应的格式未在已发布的文档中记录。响应被防御性地解码：缺少字段变为省略的输出行，绝不会崩溃。
- **Codemagic 返回 404 表示令牌无法看到的内容**，而不是 403。服务器表示“未找到，或使用此令牌无法访问”，而不是猜测是哪一个。
- **工件下载 URL 的路径中已签名**，不在查询字符串中，因此无需删除任何内容，该链接对任何拥有它的人都有效。`list_artifacts` 因此返回名称、大小和类型，但不返回 URL。请从 Codemagic UI 下载。
- **构建日志作为 HTML 出现。** Codemagic 将彩色行包装在 `<span>` 元素中，并转义内容。在发生任何其他操作之前，将标记剥离并实体解码。
## 依赖
一个运行时依赖，刻意为之：
| 依赖 | 为什么 |
|---|---|
| `github.com/modelcontextprotocol/go-sdk` | 官方 MCP 协议实现。 |
| Go 标准库 | HTTP、JSON、正则表达式、TLS。没有 HTTP 客户端库，没有日志记录框架。 |
## 开发
```bash
go build -o codemagic-mcp . # build
go vet ./... # vet
go test ./... # everything, no live token needed
go test ./test -run Test_TokenBudget -v # regenerate the token budget table
```
### 在开发过程中安装
**绝不注册您正在重建的二进制文件。** 运行中的 MCP 服务器持有对其自己的可执行文件的打开句柄，因此在 Windows 上， 下一次 `go install` 失败，出现“访问被拒绝”的错误，就像编辑器加载了服务器一样 —— 通常是您正在使用的编辑器来修复它。
将两者分开：开发构建保留在存储库中，MCP 客户端指向您有意更新的已安装副本。
```bash
scripts/install.bat # Windows -> %LOCALAPPDATA%\Programs\codemagic-mcp\
scripts/install.sh # macOS/Linux -> ~/.local/bin (override with CODEMAGIC_MCP_PREFIX)
```
两者都先构建，然后通过重命名旧二进制文件安装，而不是覆盖它，因此在客户端仍在运行先前版本时更新**有效**。客户端继续使用重命名的文件，直到它重新启动，然后选取新的文件。
然后注册该路径：
```bash
"$LOCALAPPDATA/Programs/codemagic-mcp/codemagic-mcp.exe" register project
```
如果您只使用此服务器并且从不修改它，则无需执行此操作 —— `go install` 或发布二进制文件即可。
测试从不触及网络：它们针对伪造的 Codemagic 和真实的 MCP 会话运行，因此缩减中间件和协议层得到锻炼，就像代理一样。
请参阅 [CLAUDE.md](CLAUDE.md) 以获取架构和编码原则。
## 许可证
MIT —— 请参阅 [LICENSE](LICENSE)。
