内容
# asc-feedback-mcp
一款MCP（模型上下文协议）服务器，公开 **App Store Connect TestFlight 测试版反馈** —— 截图提交、崩溃提交、崩溃日志和截图下载 —— 作为MCP客户端的工具。它通过短期的ES256 JWT（从您的 `.p8` API密钥中生成）与App Store Connect API进行身份验证，这样助手可以拉取和分类测试版测试人员的反馈，而您无需将原始凭证粘贴到对话中。服务器在Docker中运行，并在 `http://127.0.0.1:8081/mcp` 处提供可流式HTTP MCP。
## 功能
- 4种工具可用于列出和检查TestFlight测试版反馈以及下载反馈截图。
- 可流式HTTP MCP传输，在 `http://127.0.0.1:8081/mcp` 处提供。
- 通过 `docker compose` 进行基于Docker的部署 —— 无需本地Python环境。
- 仅绑定到 `127.0.0.1`；该服务是无身份验证的，绝不能在本地机器之外公开。
## 架构
```mermaid
classDiagram
class 配置 {
+str 密钥ID
+str 发行者ID
+str 私钥
}
class Asc客户端 {
-str _令牌
-float _令牌过期
-_承载令牌() str
+列出截图反馈(asc应用ID, 限制) dict
+列出崩溃反馈(asc应用ID, 限制) dict
+获取崩溃日志(提交ID) dict
}
class 服务器 {
+列出截图反馈(asc应用ID, 限制) dict
+列出崩溃反馈(asc应用ID, 限制) dict
+获取崩溃日志(提交ID) dict
+下载截图(url) Image
}
服务器 --> Asc客户端 : 调用
Asc客户端 --> 配置 : 读取凭证
```
```mermaid
sequenceDiagram
participant 客户端 as MCP客户端
participant 服务器 as FastMCP服务器
participant Asc客户端 as Asc客户端
participant ASC as App Store Connect API
客户端->>服务器: 调用工具（例如 list_crash_feedback）
服务器->>服务器: 验证参数
服务器->>Asc客户端: 转发请求
Asc客户端->>Asc客户端: 重用缓存的ES256 JWT（仅在接近过期时生成）
Asc客户端->>ASC: 带有Bearer JWT的GET请求
ASC-->>Asc客户端: JSON响应
Asc客户端-->>服务器: 解析结果
服务器-->>客户端: 工具结果
```
## 用法
服务器在 **可流式HTTP** 上通过MCP在以下地址提供服务：
```
http://127.0.0.1:8081/mcp
```
### 工具
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `list_screenshot_feedback` | `asc_app_id: str`, `limit: int = 50` | 列出应用最近的TestFlight截图反馈提交。返回原始App Store Connect API JSON。`asc_app_id` 是应用的数字Apple ID。 |
| `list_crash_feedback` | `asc_app_id: str`, `limit: int = 50` | 列出应用最近的TestFlight崩溃反馈提交。返回原始App Store Connect API JSON。`asc_app_id` 是应用的数字Apple ID。 |
| `get_crash_log` | `submission_id: str` | 获取一次崩溃反馈提交的崩溃日志。返回原始App Store Connect API JSON（`.data.attributes.logText` 包含日志）。 |
| `download_screenshot` | `url: str` | 下载TestFlight反馈截图并以图像内容返回。主机验证是尽力而为的：需要https和Apple拥有的主机名。 |
`asc_app_id` 必须仅包含数字，`limit` 必须在1到200之间（含）。`submission_id` 只能包含字母、数字和破折号。
### 示例MCP客户端配置
```json
{
"mcpServers": {
"asc-feedback": {
"type": "streamable-http",
"url": "http://127.0.0.1:8081/mcp"
}
}
}
```
或使用Claude Code：
```bash
claude mcp add --transport http asc-feedback http://127.0.0.1:8081/mcp
```
主机端口（`8081`）可以在 `docker-compose.yaml` 中配置，但绑定地址必须始终保持 `127.0.0.1:` 前缀 —— 绝不能更改为 `0.0.0.0` 或其他公开暴露。
## 入门指南
### 先决条件
- Docker Desktop 或带有Docker Compose的Docker Engine。
- 一个App Store Connect API密钥。
### 获取App Store Connect API密钥
在App Store Connect中，前往 **用户和访问权限 → 集成 → App Store Connect API** （团队密钥）并在那里生成一个密钥。这为您提供了 **发行者ID** （在该页顶部显示），**密钥ID** （在密钥表中），以及一个可下载的 `.p8` 私钥文件（例如 `AuthKey_ABC123DEFG.p8` ）—— 保存此文件，因为Apple只允许您下载一次。
| 值 | 来源 |
|-------|----------------------|
| `ASC_KEY_ID` | 用户和访问权限 → 集成 → App Store Connect API，密钥表 |
| `ASC_ISSUER_ID` | 用户和访问权限 → 集成 → App Store Connect API，页面顶部显示 |
| `ASC_PRIVATE_KEY_B64` | 创建上述密钥时下载的 `.p8` 文件的Base64 |
| `asc_app_id` （工具参数） | 应用 → *（您的应用）* → 应用信息 → 常规信息 → Apple ID |
### 步骤
1. 克隆此存储库。
2. 复制环境模板：
```bash
cp .env.example .env
```
3. 编辑 `.env` 并填写：
- `ASC_KEY_ID` — 来自集成的API密钥ID。
- `ASC_ISSUER_ID` — 来自集成的发行者ID。
- `ASC_PRIVATE_KEY_B64` — 您的 `.p8` 文件的Base64编码内容，通过以下命令生成：
```bash
base64 -i AuthKey_XXXX.p8 | tr -d '\n'
```
4. 构建并启动服务器：
```bash
docker compose up -d --build
```
5. 通过对端点初始化MCP会话来验证它是否正在运行：
```bash
curl -i http://127.0.0.1:8081/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"verify","version":"1.0"}}}'
```
或者，使用上面的示例配置将服务器添加到MCP客户端，并确认所有4种工具（`list_screenshot_feedback`、`list_crash_feedback`、`get_crash_log`、`download_screenshot`）都出现。
## 安全
此服务**不实施身份验证**。它仅绑定到 `127.0.0.1`，绝不能在 `0.0.0.0` 或任何公共/非环回接口上公开 —— 任何可以访问该端口的人都可以使用您的App Store Connect凭证拉取您的测试反馈。
