Appcircle MCP Server

官方

Appcircle 官方 MCP 服务器

GitHub

你可以用 Appcircle MCP 做什么？

  • 列出和搜索构建配置文件 — 通过 get_build_profiles 分页检索构建配置文件，并按名称筛选。
  • 检查构建配置和工作流 — 使用 get_build_profile_details、get_build_configuration_details 和 get_workflow_detail 获取特定构建配置文件、其配置及工作流的详细信息。
  • 审查签名身份 — 通过 get_certificates、get_keystores、get_provisioning_profiles 和 get_bundle_identifiers 列出证书、密钥库、预置描述文件和捆绑包标识符。
  • 检查测试和企业分发状态 — 使用 get_distribution_profiles 和 get_distribution_profile_details 获取分发配置文件及其应用版本，或通过 get_store_profiles 检查企业商店配置文件。
  • 生成 CI/CD 健康度和构建历史报告 — 使用 get_build_insights_report 获取聚合趋势和根本原因分析，或使用 get_build_history_report 获取原始构建记录。

文档

Appcircle MCP 服务器

面向 Appcircle 的 MCP 服务器：将构建、签名身份、测试分发、企业应用商店、发布到商店以及报告工具暴露给任何支持 MCP 的客户端（Claude Desktop、Cursor、VS Code 等）。Appcircle MCP 服务器充当 AI 工具与 Appcircle 之间的桥梁；因此，AI 代理、助手和聊天机器人可以通过结构化、受管控且任务级别的工具安全地访问和交互 Appcircle 资源。

使用场景

  • CI/CD 与工作流智能：监控流水线运行，跟踪发布状态，并深入了解您的移动端 CI/CD 工作流。
  • 配置与环境洞察：查询构建配置和签名设置，以了解项目的配置方式以及问题可能源自何处。
  • 报告与运维洞察：生成 CI 稳定性、重复出现的问题、流水线性能以及整体 CI/CD 健康状况的摘要。

运行模式

您可以通过四种方式使用 MCP 服务器：

模式摘要
1. 远程主机连接到 https://mcp.appcircle.io. 无需本地安装；您的客户端会在每次请求时发送您的 Appcircle 令牌（例如 Authorization: Bearer <token>）。
2. 本地 (stdio)从源代码运行服务器：克隆仓库，可选择使用 venv，然后运行 appcircle-mcp（默认传输方式是 stdio）。需要 Python 和 pip。在环境中设置 APPCIRCLE_ACCESS_TOKEN。您的 MCP 客户端会将服务器作为子进程运行。
3. 本地 (streamable-http)通过 HTTP 在本地运行服务器：使用 --transport streamable-http 以及可选的 --host / --port（例如 appcircle-mcp --transport streamable-http --host 127.0.0.1 --port 8000）。客户端连接到该 URL 并在请求中发送其令牌。
4. 本地 (Docker)在您的机器上运行官方 Docker 镜像。需要 Docker。使用镜像的默认端口或通过 --port 覆盖；具体用法请参阅镜像文档。

详细的客户端配置（Cursor、Claude 等）位于专门的安装指南中；本节仅为高级摘要。

安装

客户端特定设置指南：

配置（环境变量）

变量是否必需描述
APPCIRCLE_ACCESS_TOKEN是（仅限 stdio）Appcircle API 访问令牌。使用 stdio 传输时必需。对于 streamable-http，每个客户端发送自己的令牌。请参阅获取令牌了解如何获取。
APPCIRCLE_API_URL否API 基础 URL（默认：https://api.appcircle.io，自托管用户可能不同）。
APPCIRCLE_MCP_ALLOWED_HOST否（仅限 streamable-http）MCP 服务器的公共主机名（例如 mcp.appcircle.io）。在反向代理后部署时设置此项，以便服务器接受来自客户端的 Host 标头。本地主机可省略。
APPCIRCLE_MCP_PORT否（仅限 streamable-http）HTTP 服务器的绑定端口（默认：8000）。如果提供，会被 --port 覆盖。在需要特定端口的本地部署或 Docker 环境中很有用。
LOG_LEVEL否日志级别，例如 DEBUG、INFO（默认：INFO）。
APPCIRCLE_EXCLUDED_TOOLSETS否要排除的工具集，以逗号分隔（例如 build_module,report）。请参阅下面的工具集。

在您的 shell 或 MCP 客户端配置中设置这些变量。

工具集

可用工具集

以下工具集可用：

工具集描述
build_module构建配置文件、配置、工作流、提交和流水线操作
signing_identities签名身份和包标识符
testing_distribution测试分发配置文件及分发详情
publish_to_stores发布配置文件及商店发布操作
enterprise_app_store企业应用商店配置文件及商店详情
report报告：构建历史、分发、签名、发布状态及相关报告

您可以排除一个或多个工具集，使其工具不被注册。排除项可以通过 CLI 参数或 APPCIRCLE_EXCLUDED_TOOLSETS 环境变量设置；两者会合并（取并集）。

  • CLI: --exclude toolset1 toolset2 或 --exclude-toolsets toolset1,toolset2
  • 环境变量: APPCIRCLE_EXCLUDED_TOOLSETS=build_module,report

带有排除项的 MCP 配置示例（Cursor / Claude Desktop）：

{
  "mcpServers": {
    "appcircle": {
      "command": "appcircle-mcp",
      "args": ["--exclude", "report"]
    }
  }
}

工具

工具通过 MCP tools/list 暴露。下面的参考列出了按工具集划分的所有工具；有关响应结构和示例，请参阅 docs/tool_contract.md。

构建

  • get_build_profiles - 获取当前组织的构建配置文件（分页）。可选择按配置文件名称过滤。

    • 访问级别： 读取
    • page：页码（从 1 开始）。默认值：1。（数字，可选）
    • size：每页大小（1-100）。默认值：25。超过 100 的值将被限制为 100。（数字，可选）
    • search：用于按名称过滤配置文件的可选搜索词（不区分大小写的部分匹配）。（字符串，可选）

  • get_build_profile_details - 通过 ID 获取单个构建配置文件，可选择包含其构建配置。

    • 访问级别： 读取
    • profile_id：构建配置文件 ID（例如 UUID）。（字符串，必需）
    • configurations：如果为 true，还会获取配置文件的构建配置。默认值：false。（布尔值，可选）

  • get_build_configuration_details - 通过配置文件 ID 和配置 ID 获取单个构建配置。

    • 访问级别： 读取
    • profile_id：构建配置文件 ID（例如 UUID）。（字符串，必需）
    • configuration_id：构建配置 ID（例如 UUID）。（字符串，必需）

  • get_build_profile_workflows - 通过配置文件 ID 获取构建配置文件的工作流。

    • 访问级别： 读取
    • profile_id：构建配置文件 ID（例如 UUID）。（字符串，必需）

  • get_workflow_detail - 通过构建配置文件 ID 和工作流 ID 获取单个工作流。

    • 访问级别： 读取
    • profile_id：构建配置文件 ID（例如 UUID）。（字符串，必需）
    • workflow_id：工作流 ID（例如 UUID）。（字符串，必需）

  • get_commits_by_branch - 获取构建分支的提交（分页）。

    • 访问级别： 读取
    • branch_id：分支 ID（例如 UUID）。（字符串，必需）
    • page：页码（从 1 开始）。如果与 size 一起提供，则启用分页。默认值：1。（数字，可选）
    • size：每页大小。如果与 page 一起提供，则启用分页。默认值：25，最大 100。（数字，可选）

  • get_commit_details - 通过提交 ID（UUID）或提交哈希（git SHA）获取单个提交。提供 commit_id 或 commit_hash 之一，不能同时提供两者。

    • 访问级别： 读取
    • commit_id：提交 ID（UUID）。（字符串，可选）
    • commit_hash：提交哈希（git SHA）。（字符串，可选）
签名身份

  • get_bundle_identifiers - 获取组织的所有包标识符（iOS/macOS 应用包 ID）。

    • 访问级别： 读取
    • 无参数。

  • get_certificates - 获取组织的所有签名证书。敏感字段（p12Password、p12Binary、metaData、thumbprint）会被省略。

    • 访问级别： 读取
    • 无参数。

  • get_keystores - 获取组织的所有密钥库（例如 Android 签名密钥库）。敏感字段（password、aliasPassword、binary、checkSum、sha256FingerPrint）会被省略。

    • 访问级别： 读取
    • 无参数。

  • get_provisioning_profiles - 获取组织的配置文件（例如 iOS/macOS）。敏感/大型字段（binary、metaData、certificateThumbPrints、provisionedDevices、connectApiKeyId）会被省略。可选择按应用（包）ID 过滤。

    • 访问级别： 读取
    • app_id：用于过滤配置文件的可选应用（包）ID（例如 com.example.app）。（字符串，可选）
测试分发

  • get_distribution_profiles - 获取当前组织的测试分发配置文件（分页）。可选择按配置文件名称过滤。

    • 访问级别： 读取
    • page：页码（从 1 开始）。默认值：1。（数字，可选）
    • size：每页大小（1-100）。默认值：25，最大 100。（数字，可选）
    • search：用于按名称过滤配置文件的可选搜索词。（字符串，可选）

  • get_distribution_profile_details - 通过 ID 获取单个测试分发配置文件（带有可选的应用版本分页）。

    • 访问级别： 读取
    • profile_id：分发配置文件 ID（例如 UUID）。（字符串，必需）
    • page：应用版本的页码（从 1 开始）。默认值：1。（数字，可选）
    • size：应用版本的每页大小（1-100）。默认值：25，最大 100。（数字，可选）
发布到商店

  • get_publish_profiles - 获取当前组织针对给定平台类型的发布配置文件（分页）。可选择按流程状态过滤。

    • 访问级别： 读取
    • platform_type：发布配置文件的平台类型（"ios" 或 "android"）。（字符串，必需）
    • page：页码（从 1 开始）。默认值：1。（数字，可选）
    • size：每页大小（1-100）。默认值：25，最大 100。（数字，可选）
    • flow_status：用于过滤的可选流程状态代码（例如 0=成功，1=失败，91=运行中）。（数字，可选）

  • get_publish_profile_details - 通过平台类型和 ID 获取单个发布配置文件（带有可选的应用版本分页）。

    • 访问级别： 读取
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必需）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必需）
    • page：应用版本的页码（从 1 开始）。默认值：1。（数字，可选）
    • size：应用版本的每页大小（1-100）。默认值：25，最大 100。（数字，可选）
企业应用商店

  • get_store_profiles - 获取当前组织的企业应用商店配置文件（分页）。

    • 访问级别： 读取
    • page：页码（从 1 开始）。默认值：1。（数字，可选）
    • size：每页大小（1-100）。默认值：25，最大 100。（数字，可选）

  • get_store_profile_details - 通过 ID 获取单个企业应用商店配置文件（带有可选的应用版本分页）。

    • 访问级别： 读取
    • profile_id：企业应用商店配置文件 ID（例如 UUID）。（字符串，必需）
    • page：应用版本的页码（从 1 开始）。默认值：1。（数字，可选）
    • size：应用版本的每页大小（1-100）。默认值：25，最大 100。（数字，可选）
报告- **get_build_history_report** - 获取构建历史报告，可按日期范围、构建配置和组织进行筛选。支持分页。 - **访问级别：** 读取 - `start_date`：可选开始日期 (YYYY-MM-DD)。（字符串，可选） - `end_date`：可选结束日期 (YYYY-MM-DD)。（字符串，可选） - `page`：页码（默认：1）。（数字，可选） - `size`：每页条目数（1-100，默认：50）。（数字，可选） - `build_profile_name`：按构建配置名称筛选。（字符串，可选） - `organization_id`：按组织 UUID 筛选。（字符串，可选）

  • get_build_insights_report - 获取计算后的构建洞察报告（包含健康快照与趋势、根因分析、制品健康度、工作流质量、队列时间及成熟度评估分析），基于构建历史在服务端聚合生成。与 get_build_history_report 不同，此工具会在内部获取所有页面，并返回小型的预聚合结果，而非原始记录。

    • 访问级别： 读取
    • start_date：当前周期的可选开始日期 (YYYY-MM-DD)。默认：最近 30 天。（字符串，可选）
    • end_date：当前周期的可选结束日期 (YYYY-MM-DD)。（字符串，可选）
    • sections：要计算的可选部分列表：health_snapshot、root_cause、artifact_health、workflow_quality、queue_time、maturity_assessment。默认：全部六个。（字符串数组，可选）
    • include_sub_orgs：若为 true，则在历史衍生指标中保留跨组织的构建记录，而非仅筛选令牌所属组织。默认：false。（布尔值，可选）

  • get_distribution_app_version_report - 获取已分发应用版本的每日使用报告。支持分页；可按配置、操作系统、组织筛选。

    • 访问级别： 读取
    • start_date：可选开始日期 (YYYY-MM-DD)。（字符串，可选）
    • end_date：可选结束日期 (YYYY-MM-DD)。（字符串，可选）
    • page：页码（默认：1）。（数字，可选）
    • size：每页条目数（1-100，默认：50）。（数字，可选）
    • profile_name：按分发配置名称筛选。（字符串，可选）
    • os：按操作系统筛选（"ios" 或 "android"）。（字符串，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）

  • get_distribution_sent_report - 获取已分发应用分享的每日使用报告。支持分页；可按配置、操作系统、组织筛选。

    • 访问级别： 读取
    • start_date：可选开始日期 (YYYY-MM-DD)。（字符串，可选）
    • end_date：可选结束日期 (YYYY-MM-DD)。（字符串，可选）
    • page：页码（默认：1）。（数字，可选）
    • size：每页条目数（1-100，默认：50）。（数字，可选）
    • profile_name：按分发配置名称筛选。（字符串，可选）
    • os：按操作系统筛选（"ios" 或 "android"）。（字符串，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）

  • get_enterprise_app_store_app_usage_report - 获取企业应用商店的应用使用报告。start_date 和 end_date 为必填项。支持分页。

    • 访问级别： 读取
    • start_date：开始日期 (YYYY-MM-DD)。（字符串，必填）
    • end_date：结束日期 (YYYY-MM-DD)。（字符串，必填）
    • page：页码（默认：1）。（数字，可选）
    • size：每页条目数（1-100，默认：50）。（数字，可选）
    • organization_id：按组织 UUID 的可选筛选。（字符串，可选）

  • get_publish_resign_report - 获取发布重签报告，可按日期范围、应用名称、组织和状态筛选。支持分页。

    • 访问级别： 读取
    • start_date：可选开始日期 (YYYY-MM-DD)。（字符串，可选）
    • end_date：可选结束日期 (YYYY-MM-DD)。（字符串，可选）
    • page：页码（默认：1）。（数字，可选）
    • size：每页条目数（1-100，默认：50）。（数字，可选）
    • app_name：按应用名称筛选。（字符串，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）
    • status：按重签状态筛选（0=等待中，1=处理中，2=成功，3=失败，4=已取消，5=超时）。（数字，可选）

  • get_publish_status_report - 获取发布状态报告，可按日期范围、应用名称、组织和状态筛选。支持分页。

    • 访问级别： 读取
    • start_date：可选开始日期 (YYYY-MM-DD)。（字符串，可选）
    • end_date：可选结束日期 (YYYY-MM-DD)。（字符串，可选）
    • page：页码（默认：1）。（数字，可选）
    • size：每页条目数（1-100，默认：50）。（数字，可选）
    • app_name：按应用名称筛选。（字符串，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）
    • status：按发布状态筛选（例如 0=成功，1=失败，91=运行中）。（数字，可选）

  • get_signing_report - 获取签名报告，可按日期范围、组织、操作系统和构建状态筛选。支持分页。

    • 访问级别： 读取
    • start_date：可选开始日期 (YYYY-MM-DD)。（字符串，可选）
    • end_date：可选结束日期 (YYYY-MM-DD)。（字符串，可选）
    • page：页码（默认：1）。（数字，可选）
    • size：每页条目数（1-100，默认：50）。（数字，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）
    • os：按操作系统筛选（"ios" 或 "android"）。（字符串，可选）
    • build_status：按构建状态筛选（例如 0=成功，1=失败，91=运行中）。（数字，可选）

运行服务器

从仓库根目录：

python -m src.server

或在 pip install -e . 之后：

appcircle-mcp

服务器通过 stdio（或 SSE/HTTP，具体取决于客户端启动方式）运行。

响应格式

每个工具都返回一个标准信封：

  • 成功： { "success": true, "data": <payload>, "meta": { ... } }
    data 是工具结果；meta 是可选的（例如 count、page、filters）。
  • 错误： { "success": false, "error": { "tool", "type", "message", "details" } }
    所有工具格式相同，以便客户端能一致地解析错误。

完整规范：docs/tool_contract.md。

测试

安装开发依赖：

pip install -e ".[dev]"

单元测试（默认）

使用模拟 API；无需 APPCIRCLE_ACCESS_TOKEN。默认的 pytest 仅运行这些测试（参见 pyproject.toml 中的 testpaths）：

pytest test/unit/ -v
  • 单个文件：pytest test/unit/tools/build_module/test_get_build_profiles.py -v
  • 包含覆盖率：pytest test/unit/ --cov=src --cov-report=term-missing

集成测试

调用真实的 Appcircle API。在环境中设置 APPCIRCLE_ACCESS_TOKEN，然后运行：

pytest test/integration/ -v
  • 所有集成测试：pytest test/integration/ -v
  • 按工具：pytest test/integration/build_module/ -v、pytest test/integration/report/ -v 等。
  • 按标记：pytest -m integration -v（从仓库根目录运行时；如果同时收集了单元测试和集成测试，则仅包含集成测试）

如果未设置 APPCIRCLE_ACCESS_TOKEN，集成测试将被跳过（不会失败）。

集成测试的可选环境变量（当发现失败或测试需要真实 ID 时；省略则跳过这些测试）：

变量描述
APPCIRCLE_TEST_ORGANIZATION_ID组织 UUID。由 test_with_organization_id（企业应用商店应用使用报告）使用。
APPCIRCLE_TEST_BRANCH_ID分支 UUID。当无法从 API 发现分支时，由 get_commits_by_branch 及相关测试使用。
APPCIRCLE_TEST_COMMIT_ID提交 UUID。当无法从 API 发现提交时，由 get_commit_details 测试使用。

安全性

此项目依赖于 pyproject.toml 中列出的第三方开源包。虽然我们固定了依赖版本范围，并提供了包含加密哈希的锁文件 (uv.lock)，但这些包由第三方独立维护，并按“原样”提供。Appcircle 不对第三方依赖项的安全性及可靠性作任何保证。

我们建议在使用前审计已安装的包：

uv run pip-audit