内容
# 应用商店连接 MCP
[](https://www.npmjs.com/package/@emre-koc/appstore-connect-mcp)
[](LICENSE)
一个安全、仅限本地的模型上下文协议服务器，用于苹果应用商店连接 API。
- **传输：** 仅限标准输入/输出 - 没有 HTTP 监听器、OAuth、Auth0、遥测或托管中继。
- **凭证：** 从本地模式-`600` `.p8` 文件生成的短寿命 ES256 JWT。
- **网络：** 身份验证的 API 调用固定为 `https://api.appstoreconnect.apple.com`。
- **范围：** 可选的应用资源 ID 允许列表，在启用突变时需要。
- **突变：** 默认禁用，需要确切的操作特定确认短语。
- **API 基础：** 苹果应用商店连接 OpenAPI 规范 **4.4.1**，于 2026-07-26 从苹果官方文档下载。
> 本项目独立且不隶属于或得到苹果公司的支持。
## 快速开始
```bash
# 全局安装
npm install -g @emre-koc/appstore-connect-mcp
# 或在不安装的情况下运行
npx @emre-koc/appstore-connect-mcp --env-file=~/.config/appstore-connect-mcp/env
```
列出您的应用（安全的只读调用 - 无突变）：
```bash
npx @emre-koc/appstore-connect-mcp --env-file=~/.config/appstore-connect-mcp/env \
--tool=list_apps
```
## 要求
- Node.js 22 或更高版本
- 具有仅限您打算使用的工具所需的角色的应用商店连接 API 密钥
- 从应用商店连接下载的原始 `.p8` 私钥
## 安全第一
此服务器可以访问未发布的应用程序数据，并在明确启用时更改应用商店连接资源。在使用它之前：
- 创建一个专用、权限最小的应用商店连接 API 密钥；
- 将 `.p8` 密钥保存在存储库之外，并设置为模式 `600`；
- 配置 `ASC_ALLOWED_APP_IDS`，即使在只读使用时也是如此；
- 除非执行计划更改，否则请保持 `ASC_ENABLE_MUTATIONS=false`；
- 查看 [威胁模型](docs/THREAT-MODEL.md) 和 [安全策略](SECURITY.md)。
构建或运行测试套件不需要应用商店连接凭证。
## 从源代码安装
```bash
git clone https://github.com/emre-koc/appstore-connect-mcp.git
cd appstore-connect-mcp
npm ci --ignore-scripts
npm run check
npm test
npm run build
```
依赖项和传递安全覆盖已在 `package-lock.json` 中固定。
## 凭证
**不要** 将凭证放入此存储库中。创建一个私有配置目录：
```bash
mkdir -p ~/.config/appstore-connect-mcp
cp /secure/location/AuthKey_EXAMPLE.p8 ~/.config/appstore-connect-mcp/AuthKey_EXAMPLE.p8
chmod 600 ~/.config/appstore-connect-mcp/AuthKey_EXAMPLE.p8
cp .env.example ~/.config/appstore-connect-mcp/env
chmod 600 ~/.config/appstore-connect-mcp/env
```
在本地编辑 `~/.config/appstore-connect-mcp/env` 文件。永远不要将其内容粘贴到问题、提交、聊天或日志中。
所需变量：
```dotenv
ASC_KEY_ID=YOUR_KEY_ID
ASC_ISSUER_ID=YOUR_ISSUER_ID
ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_YOUR_KEY_ID.p8
```
推荐的只读应用范围：
```dotenv
ASC_ALLOWED_APP_IDS=123456789
ASC_ENABLE_MUTATIONS=false
```
`ASC_ALLOWED_APP_IDS` 使用应用商店连接 **资源 ID**，而非包 ID 或公共数字应用商店 ID。在禁用突变的情况下，使用 `list_apps` 一次以发现正确的 ID。
## Hermes 配置
使用 Node 的内置 `--env-file` 支持，以便凭证保持在 Hermes YAML 之外。使用 `command -v node` 和 `pwd` 在本地解析两个路径；MCP 客户端配置需要绝对路径，并且不扩展 `~`：
```yaml
mcp_servers:
appstore_connect:
command: "/absolute/path/to/node"
args:
- "--env-file=/absolute/path/to/appstore-connect-mcp-env"
- "/absolute/path/to/appstore-connect-mcp/dist/index.js"
connect_timeout: 30
timeout: 120
sampling:
enabled: false
```
在添加配置后重启 Hermes。工具以 `mcp_appstore_connect_` 前缀显示。
## 配置参考
| 变量 | 必需 | 目的 |
|---|---:|---|
| `ASC_KEY_ID` | 是 | 应用商店连接 API 密钥 ID |
| `ASC_ISSUER_ID` | 是 | 应用商店连接 API 发行者 ID |
| `ASC_PRIVATE_KEY_PATH` | 是 | 模式-`600` `.p8` 密钥文件的绝对路径 |
| `ASC_ALLOWED_APP_IDS` | 推荐 | 以逗号分隔的应用商店连接应用资源 ID；突变时必填 |
| `ASC_ENABLE_MUTATIONS` | 否 | 默认禁用；仅字符串 `true` 启用写入 |
| `ASC_VENDOR_NUMBER` | 否 | 为未来销售/财务报告工具保留 |
## 突变安全性
突变需要全部三个安全措施：
1. 私人本地环境文件中 `ASC_ENABLE_MUTATIONS=true`。
2. 非空的 `ASC_ALLOWED_APP_IDS` 允许列表。
3. 工具调用中的确切确认短语：
```text
EXECUTE <operation_name> FOR <app_resource_id>
```
示例：
```text
EXECUTE create_in_app_purchase_v2 FOR 123456789
```
在正常检查时保持突变禁用。仅在计划更改时启用它们，重启 MCP 进程，执行更改，然后再次禁用它们。
## 工具
### 只读
- `asc_status`
- `list_apps`, `get_app`
- `list_builds`, `get_build`
- `list_app_store_versions`, `get_app_store_version`
- `list_version_localizations`
- `list_in_app_purchases_v2`, `get_in_app_purchase_v2`
- `list_in_app_purchase_versions`
- `list_in_app_purchase_version_localizations`
- `list_in_app_purchase_price_points`
- `get_in_app_purchase_price_schedule`
- `get_in_app_purchase_availability`
- `list_territories`
- `list_beta_groups`
- `list_review_submissions`
### 突变
- `create_app_store_version`, `update_app_store_version`
- `attach_build_to_version`
- `create_version_localization`, `update_version_localization`
- `create_in_app_purchase_v2`, `update_in_app_purchase_v2`
- `create_in_app_purchase_version`
- `create_in_app_purchase_localization_v2`
- `create_in_app_purchase_availability`
- `create_in_app_purchase_price_schedule`
- `create_in_app_purchase_review_item`
- `create_beta_group`, `create_beta_tester`
- `add_beta_testers_to_group`, `add_builds_to_beta_group`
- `create_review_submission`, `submit_review_submission`
## 当前 IAP 工作流程
苹果的 4.4.1 API 将 IAP 资源、可编辑版本/本地化、可用性、定价和统一审查提交分开：
1. `list_apps` — 获取并允许应用资源 ID。
2. `create_in_app_purchase_v2` — 创建产品（`NON_CONSUMABLE`、`CONSUMABLE` 或 `NON_RENEWING_SUBSCRIPTION`）。
3. `create_in_app_purchase_version` — 创建可编辑的 IAP 版本。
4. `create_in_app_purchase_localization_v2` — 将名称/描述附加到该版本。
5. `list_in_app_purchase_price_points` — 为地区选择苹果的价格点资源 ID。
6. `create_in_app_purchase_price_schedule` — 设置基本地区和手动价格。
7. `create_in_app_purchase_availability` — 选择地区。
8. 在应用商店连接中添加所需的审查媒体，直到本地资产上传工具发布。
9. `create_review_submission` — 创建应用的统一审查提交。
10. `create_in_app_purchase_review_item` — 将验证的 IAP 版本添加到该提交中。
11. 仅在审查应用商店连接中的每个提交项目后，提交 `submit_review_submission`。
服务器使用 V2 IAP 创建/更新和 V2 本地化创建。本地化列表通过 `/v1/inAppPurchaseVersions/{id}/localizations` 进行版本范围限定，审查使用统一的 `reviewSubmissionItems`；不公开的父范围本地化和独立 IAP 提交工作流程未公开。价格计划和可用性仍在苹果当前的 V1 创建端点上，因为 OpenAPI 4.4.1 定义了这一点。
## 开发
```bash
npm test
npm run test:coverage
npm run check
npm run build
npm audit --omit=dev
npm pack --dry-run
```
查看：
- [API 覆盖](docs/API-COVERAGE.md)
- [威胁模型](docs/THREAT-MODEL.md)
- [安全策略](SECURITY.md)
- [贡献](CONTRIBUTING.md)
## 官方来源
- [应用商店连接 API](https://developer.apple.com/documentation/appstoreconnectapi)
- [官方 OpenAPI 规范](https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip)
- [为 API 请求生成令牌](https://developer.apple.com/documentation/appstoreconnectapi/generating-tokens-for-api-requests)
- [API 发布说明](https://developer.apple.com/documentation/appstoreconnectapi/app-store-connect-api-release-notes)
- [识别速率限制](https://developer.apple.com/documentation/appstoreconnectapi/identifying-rate-limits)
## 许可证
MIT。查看 [LICENSE](LICENSE)。
