Appcircle MCP Server

官方

Appcircle 官方 MCP 服务器

GitHub

你可以用 Appcircle MCP 做什么？

  • 监控构建状态和日志 — 使用 get_build_status 和 get_build_logs 检查流水线运行情况并调试失败。
  • 触发或取消构建 — 使用 trigger_build 和 cancel_build 启动或停止实际的构建运行。
  • 生成CI/CD健康洞察 — 使用 get_build_insights_report 获取聚合的健康快照、趋势和根因分析。
  • 管理测试分发 — 使用 get_distribution_profiles 和 send_app_version_to_testers 将构建发送给测试人员。
  • 检查签名身份 — 使用 get_certificates、get_keystores 和 get_provisioning_profiles 审查签名设置。
  • 跟踪商店发布 — 使用 get_publish_profiles 和 get_publish_details 监控发布流程运行。

文档

Appcircle MCP Server

面向 Appcircle 的 MCP 服务器：将 Build、Signing Identities、Testing Distribution、Enterprise App Store、Publish to Stores 和 Reporting 工具开放给任何支持 MCP 的客户端（Claude Desktop、Cursor、VS Code 等）。Appcircle MCP Server 充当 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 请求头。localhost 时省略。
APPCIRCLE_MCP_PORT否（仅 streamable-http）HTTP 服务器的绑定端口（默认：8000）。如果提供了 --port，则会被覆盖。当需要特定端口时，对本地部署或 Docker 很有用。
LOG_LEVEL否日志级别，例如 DEBUG、INFO（默认：INFO）。
APPCIRCLE_EXCLUDED_TOOLSETS否要排除的工具集，以逗号分隔（例如 build_module,report）。请参阅下面的工具集。
AC_MCP_ENABLE_WRITE_TOOLS否写入/操作工具（例如 trigger_build、cancel_build）默认注册。设置为 false/0/no/off 可选择退出并完全不注册它们（而不仅仅是在调用时禁用）。

在您的 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。

Build

  • get_build_profiles - 获取当前组织的构建配置文件（分页）。可选按配置文件名称、平台、上次构建状态和仓库来源进行筛选。可选排序。

    • 访问级别： 读取
    • page：页码（从 1 开始）。默认：1。（数字，可选）
    • size：每页大小（1-100）。默认：25。超过 100 的值上限为 100。（数字，可选）
    • search：可选的搜索词，用于筛选配置文件（对配置文件名称进行不区分大小写的部分匹配；API 的搜索也可能匹配其他配置文件字段）。（字符串，可选）
    • platform：可选的平台代码列表，用于筛选。允许的值：1=iOS，2=Android。（数字列表，可选）
    • last_build_status：可选的上次构建状态代码列表，用于筛选。允许的值：0=成功，1=失败，2=已取消，3=超时，90=等待中，91=运行中。（数字列表，可选）
    • repository_source：可选的仓库来源代码列表，用于筛选。允许的值：1=GitHub，2=Bitbucket，3=GitLab，4=Azure DevOps，6=公共仓库，7=私有仓库，8=SSH。（数字列表，可选）
    • sort：可选的排序字段代码。允许的值：1=配置文件名称，2=创建日期，3=上次构建日期。（数字，可选）
    • sort_direction：可选的排序方向代码。允许的值：1=升序，2=降序。（数字，可选）

  • 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_last_commit - 获取构建分支上最近的提交。

    • 访问级别： 读取
    • branch_id：分支 ID（例如 UUID）。（字符串，必填）

  • get_build_status - 获取构建的状态（例如 0=成功，1=失败，2=已取消，3=超时，90=等待中，91=运行中，92=完成中，99=未知）。

    • 访问级别： 读取
    • commit_id：提交 ID（UUID）。（字符串，必填）
    • build_id：构建 ID（UUID）。（字符串，必填）

  • get_build_logs - 获取构建的日志，可选限定到单个步骤。默认返回尾部截断的视图，以避免淹没模型的上下文。

    • 访问级别： 读取
    • commit_id：提交 ID（UUID）。（字符串，必填）
    • build_id：构建 ID（UUID）。（字符串，必填）
    • step：可选的精确步骤名称（不区分大小写），用于将输出限定到单个步骤的日志块。（字符串，可选）
    • full_log：如果为 true，则返回完整日志而不是默认的尾部。仍以 256 KB 为上限。默认：false。（布尔值，可选）
    • tail_lines：不使用 full_log 时，从末尾保留的行数。默认：200，最大 1000。（数字，可选）
    • grep：在截断之前应用于行的不区分大小写的子字符串筛选器。（字符串，可选）

  • get_variable_groups - 获取组织的所有构建环境变量组，包括每个组的变量（key、value、isSecret、isFile）。密钥值已由 API 脱敏。

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

  • trigger_build - 副作用：启动新的真实构建运行（排队一个实际构建，消耗构建分钟数/额度），可以在分支上（最新同步的提交）或针对一个特定提交。默认注册；设置 AC_MCP_ENABLE_WRITE_TOOLS=false 可选择退出。

    • 访问级别： 写入
    • profile_id：构建配置文件 ID（例如 UUID）。分支模式下必填（未提供 commit_id 时）；提交模式下不使用。（字符串，可选）
    • workflow_id：工作流 ID（例如 UUID）。分支模式下必填。提交模式下可选（如果省略，则使用上次使用的/默认工作流）。（字符串，可选）
    • branch_name：可选的分支名称（例如 "main"）。仅分支模式；如果省略，则回退到配置文件的默认分支。不能与 commit_id 同时提供。（字符串，可选）
    • commit_id：提交自身的 ID（不是其 git 哈希），用于针对特定提交而不是分支上的最新提交触发构建。不能与 branch_name 同时提供。（字符串，可选）
    • configuration_id：可选的构建配置 ID（例如 UUID），用于替代默认配置。（字符串，可选）

  • cancel_build - 副作用：取消排队中或运行中的构建（真实的、进行中的工作会被停止；无法恢复）。默认注册；设置 AC_MCP_ENABLE_WRITE_TOOLS=false 可选择退出。

    • 访问级别： 写入
    • task_id：构建的任务 ID（trigger_build 返回的 "taskId" 字段）。（字符串，必填）
Signing Identities

  • 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）将被省略。可选地按应用（bundle）ID 进行筛选。

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

  • get_distribution_profiles - 获取当前组织的测试分发配置文件（分页）。可选地按配置文件名称、平台和认证类型进行筛选。可选地排序。

    • 访问级别： 读取
    • page：页码（从 1 开始）。默认值：1。（数字，可选）
    • size：每页大小（1-100）。默认值：25，最大 100。（数字，可选）
    • search：可选的搜索词，用于筛选配置文件（对配置文件名称进行不区分大小写的部分匹配；API 的搜索也可能匹配其他配置文件字段）。（字符串，可选）
    • platform：可选的平台代码列表，用于筛选。允许的值：1=iOS，2=Android。（数字列表，可选）
    • authentication_type：可选的认证类型代码列表，用于筛选。允许的值：1=无，3=静态登录，4=LDAP，5=SSO。（数字列表，可选）
    • sort：可选的排序字段代码。允许的值：1=配置文件名称，2=创建日期，3=最后上传日期。（数字，可选）
    • sort_direction：可选的排序方向代码。允许的值：1=升序，2=降序。（数字，可选）

  • get_distribution_profile_details - 按 ID 获取单个测试分发配置文件（可选地包含应用版本分页）。

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

  • get_testing_groups - 获取组织的所有测试分发组，包括每个组的成员测试者电子邮件和组类型。

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

  • update_app_version_release_notes - 副作用：覆盖向测试者显示的发布说明（"message"），针对某个分发应用版本。返回更新后的应用版本对象（排除 certThumbPrints）。默认注册；设置 AC_MCP_ENABLE_WRITE_TOOLS=false 可选择退出。

    • 访问级别： 写入
    • profile_id：分发配置文件 ID（例如 UUID）。（字符串，必填）
    • app_version_id：应用版本 ID（例如 UUID）。（字符串，必填）
    • message：新的发布说明文本。（字符串，必填）

  • send_app_version_to_testers - 副作用：向测试者/测试组发送真实通知，为特定应用版本调度分发任务。默认注册；设置 AC_MCP_ENABLE_WRITE_TOOLS=false 可选择退出。

    • 访问级别： 写入
    • profile_id：分发配置文件 ID（例如 UUID）。（字符串，必填）
    • app_version_id：应用版本 ID（例如 UUID）。（字符串，必填）
    • message：向测试者显示的通知消息。（字符串，必填）
    • testers：要发送到的测试者列表。每个条目可以是测试者的电子邮件地址或测试组 ID（来自 get_testing_groups 的 "id" 字段）。（字符串列表，必填）
发布到商店

  • get_publish_profiles - 获取当前组织在给定平台类型下的发布配置文件（分页）。可选地按流程状态、目标市场、候选发布二进制文件是否存在以及商店状态进行筛选。可选地排序。

    • 访问级别： 读取
    • platform_type：发布配置文件的平台类型（"ios" 或 "android"）。（字符串，必填）
    • page：页码（从 1 开始）。默认值：1。（数字，可选）
    • size：每页大小（1-100）。默认值：25，最大 100。（数字，可选）
    • flow_status：可选的流程状态代码，用于筛选（例如 0=成功，1=失败，91=运行中）。（数字，可选）
    • market_place_type：可选的目标市场代码列表，用于筛选。允许的值取决于 platform_type -- ios：0=不可用，1=App Store Connect，4=Intune；android：0=不可用，2=Google Play，3=AppGallery，4=Intune。（数字列表，可选）
    • has_rc_binary：可选的筛选条件，用于判断配置文件是否具有候选发布二进制文件。（布尔值，可选）
    • store_status：可选的商店状态代码列表，用于筛选。允许的值取决于 platform_type（ios 的代码比 android 多得多，例如 ios："IN_REVIEW"、"READY_FOR_SALE"、"REJECTED"；android："NOT_AVAILABLE"、"DRAFT"、"IN_PROGRESS"、"HALTED"、"COMPLETED"）。（字符串列表，可选）
    • sort：可选的排序字段代码。允许的值：1=配置文件名称，2=创建日期。（数字，可选）
    • sort_direction：可选的排序方向代码。允许的值：1=升序，2=降序。（数字，可选）

  • get_publish_profile_details - 按平台类型和 ID 获取单个发布配置文件（可选地包含应用版本分页）。

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

  • get_app_version_metadata - 获取单个应用版本的商店列表元数据（应用审核信息、本地化、发布信息、应用版本信息）。appReviewInformation.demoPassword 被排除。

    • 访问级别： 读取
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必填）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必填）
    • app_version_id：应用版本 ID（例如 UUID）。（字符串，必填）

  • get_metadata_locales - 获取单个应用版本的可用商店元数据区域设置（名称、代码、是否本地化、是否为主要）。

    • 访问级别： 读取
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必填）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必填）
    • app_version_id：应用版本 ID（例如 UUID）。（字符串，必填）

  • get_intune_metadata - 获取单个应用版本的 Microsoft Intune 应用元数据（显示名称、发布者、bundle ID、版本、发布状态、适用的设备类型、类别等）。

    • 访问级别： 读取
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必填）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必填）
    • app_version_id：应用版本 ID（例如 UUID）。（字符串，必填）

  • get_publish_metadata_lock_status - 获取发布配置文件的商店元数据是否已锁定以进行编辑。

    • 访问级别： 读取
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必填）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必填）

  • get_publish_details - 获取单个应用版本的发布流程运行详情（状态、时间、带有运行历史/工件/日志资源 ID 的有序步骤）。

    • 访问级别： 读取
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必填）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必填）
    • app_version_id：应用版本 ID（例如 UUID）。（字符串，必填）

  • get_publish_step_logs - 获取发布流程运行的日志，可选地限定到单个步骤。默认使用尾部截断视图，以避免淹没模型的上下文。

    • 访问级别： 读取
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必填）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必填）
    • publish_id：发布流程运行 ID（来自 get_publish_details 的 "id" 字段）。（字符串，必填）
    • step_id：步骤 ID（来自 get_publish_details 的步骤列表中的步骤 "id" 字段）。（字符串，必填）
    • step：可选的精确步骤名称（不区分大小写），用于将输出限定到单个步骤的日志块。（字符串，可选）
    • full_log：如果为 true，则返回完整日志而不是默认的尾部。仍限制为 256 KB。默认值：false。（布尔值，可选）
    • tail_lines：不使用 full_log 时从末尾保留的行数。默认值：200，最大 1000。（数字，可选）
    • grep：在截断之前应用于行的不区分大小写的子字符串过滤器。（字符串，可选）

  • get_publish_flows - 获取为发布配置文件配置的发布流程（名称、ID、完整流程文档 YAML）。

    • 访问级别： 读取
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必填）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必填）

  • start_publish - 副作用：启动发布流程运行（或从特定步骤重新启动）——真实的发布工作（例如上传到 App Store/Play Store/Intune）。默认注册；设置 AC_MCP_ENABLE_WRITE_TOOLS=false 可选择退出。

    • 访问级别： 写入
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必填）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必填）
    • publish_id：发布流程运行 ID（来自 get_publish_details 的 "id" 字段）。（字符串，必填）
    • step_id：可选的步骤 ID，从该步骤开始而不是从流程开头开始。（字符串，可选）
    • organization_pool_id：可选的运行所在组织池 ID（例如 UUID）。（字符串，可选）

  • stop_publish - 副作用：取消正在运行的发布流程运行（真实的进行中工作将被停止；无法恢复）。默认注册；设置 AC_MCP_ENABLE_WRITE_TOOLS=false 可选择退出。

    • 访问级别： 写入
    • platform_type：平台类型（"ios" 或 "android"）。（字符串，必填）
    • profile_id：发布配置文件 ID（例如 UUID）。（字符串，必填）
    • publish_id：发布流程运行 ID（来自 get_publish_details 的 "id" 字段）。（字符串，必填）
    • step_id：可选的步骤 ID。（字符串，可选）
    • organization_pool_id：可选的运行所在组织池 ID（例如 UUID）。（字符串，可选）
企业应用商店
  • get_store_profiles - 获取当前组织的企业应用商店配置文件（分页）。不支持搜索，但可以按平台、发布类型和可见性进行筛选。可选地排序。
    • 访问级别： 读取
    • page：页码（从 1 开始）。默认值：1。（数字，可选）
    • size：每页大小（1-100）。默认值：25，最大 100。（数字，可选）
    • platform_type：可选的平台代码列表，用于筛选。允许的值：1=iOS，2=Android。（数字列表，可选）
    • publish_type：可选的发布类型代码列表，用于筛选。允许的值：1=发布到 Beta，2=发布到正式版。（数字列表，可选）
    • visibility：可选的筛选条件，用于判断配置文件是否公开列出（true=已列出，false=未列出）。（布尔值，可选）
    • sort：可选的排序字段代码。允许的值：1=应用名称，2=创建日期，3=下载次数，4=二进制文件接收日期。（数字，可选）
    • sort_direction：可选的排序方向代码。允许的值：1=升序，2=降序。（数字，可选）
  • get_store_profile_details - 按 ID 获取单个企业应用商店配置文件（可选应用版本分页）。
    • 访问级别： read
    • profile_id：企业应用商店配置文件 ID（例如 UUID）。（字符串，必填）
    • page：应用版本页码（从 1 开始）。默认值：1。（数字，可选）
    • size：应用版本每页数量（1-100）。默认值：25，最大 100。（数字，可选）
    • 每个应用版本的 publishType 字段为整数：0=None，1=Beta，2=Live。
报告

  • get_build_history_report - 获取构建历史报告，可选按日期范围、构建配置文件和组织筛选。分页。

    • 访问级别： read
    • start_date：可选的开始日期（YYYY-MM-DD）。（字符串，可选）
    • end_date：可选的结束日期（YYYY-MM-DD）。（字符串，可选）
    • page：页码（默认值：1）。（数字，可选）
    • size：每页项目数（1-100，默认值：50）。（数字，可选）
    • build_profile_name：按构建配置文件名称筛选。（字符串，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）

  • get_build_queue_waiting_report - 获取构建队列等待报告，可选按日期范围筛选。分页。注意：在此端点上，buildDuration 表示队列等待时间（分钟），而非执行时间（与 get_build_history_report 不同）。

    • 访问级别： read
    • start_date：可选的开始日期（YYYY-MM-DD）。如果同时给出，必须 <= end_date。（字符串，可选）
    • end_date：可选的结束日期（YYYY-MM-DD）。（字符串，可选）
    • page：页码（默认值：1）。（数字，可选）
    • size：每页项目数（1-100，默认值：50）。（数字，可选）

  • get_build_activity_log - 获取构建活动日志（工作流/配置文件更改、CodePush 发布等），可选按日期范围和其他参数筛选。分页。

    • 访问级别： read
    • start_date：可选的开始日期（YYYY-MM-DD）。如果同时给出，必须 <= end_date。（字符串，可选）
    • end_date：可选的结束日期（YYYY-MM-DD）。（字符串，可选）
    • page：页码（默认值：1）。（数字，可选）
    • size：每页项目数（1-100，默认值：50）。（数字，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）
    • platform：按平台类型筛选（整数代码，例如 0=Android，1=iOS）。（数字，可选）
    • email：按操作者电子邮件筛选。（字符串，可选）
    • profile_name：按构建配置文件名称筛选。（字符串，可选）
    • action：按活动操作代码筛选（整数；完整映射请参阅工具源码中的 BUILD_ACTIVITY_ACTIONS）。（数字，可选）

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

    • 访问级别： read
    • 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 - 获取分发应用版本的每日使用报告。分页；支持按配置文件、操作系统、组织筛选。

    • 访问级别： read
    • 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 - 获取分发应用共享的每日使用报告。分页；支持按配置文件、操作系统、组织筛选。

    • 访问级别： read
    • 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 为必填。分页。

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

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

    • 访问级别： read
    • start_date：可选的开始日期（YYYY-MM-DD）。（字符串，可选）
    • end_date：可选的结束日期（YYYY-MM-DD）。（字符串，可选）
    • page：页码（默认值：1）。（数字，可选）
    • size：每页项目数（1-100，默认值：50）。（数字，可选）
    • app_name：按应用名称筛选。（字符串，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）
    • status：按重签名状态筛选（0=waiting，1=processing，2=succeeded，3=failed，4=cancelled，5=timeout）。（数字，可选）

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

    • 访问级别： read
    • start_date：可选的开始日期（YYYY-MM-DD）。（字符串，可选）
    • end_date：可选的结束日期（YYYY-MM-DD）。（字符串，可选）
    • page：页码（默认值：1）。（数字，可选）
    • size：每页项目数（1-100，默认值：50）。（数字，可选）
    • app_name：按应用名称筛选。（字符串，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）
    • status：按发布状态筛选（例如 0=Success，1=Failed，91=Running）。（数字，可选）

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

    • 访问级别： read
    • 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=Success，1=Failed，91=Running）。（数字，可选）

  • get_signing_activity_log - 获取签名活动日志（例如证书/配置文件/密钥库过期通知），可选按日期范围和其他参数筛选。分页。

    • 访问级别： read
    • start_date：可选的开始日期（YYYY-MM-DD）。如果同时给出，必须 <= end_date。（字符串，可选）
    • end_date：可选的结束日期（YYYY-MM-DD）。（字符串，可选）
    • page：页码（默认值：1）。（数字，可选）
    • size：每页项目数（1-100，默认值：50）。（数字，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）
    • platform：按平台筛选（例如 "iOS"、"Android"）。（字符串，可选）
    • email：按操作者电子邮件筛选。（字符串，可选）
    • action：按活动操作代码筛选（整数；完整映射请参阅工具源码中的 SIGNING_ACTIVITY_ACTIONS）。（数字，可选）

  • get_publish_activity_log - 获取发布活动日志（重新签名、发布流程事件等），可选按日期范围和其他参数筛选。分页。

    • 访问级别： read
    • start_date：可选的开始日期（YYYY-MM-DD）。如果同时给出，必须 <= end_date。（字符串，可选）
    • end_date：可选的结束日期（YYYY-MM-DD）。（字符串，可选）
    • page：页码（默认值：1）。（数字，可选）
    • size：每页项目数（1-100，默认值：50）。（数字，可选）
    • organization_id：按组织 UUID 筛选。（字符串，可选）
    • platform：按平台筛选（例如 "iOS"、"Android"）。（字符串，可选）
    • email：按操作者电子邮件筛选。（字符串，可选）
    • profile_name：按发布配置文件名称筛选。（字符串，可选）
    • action：按活动操作代码筛选（整数；完整映射请参阅工具源码中的 PUBLISH_ACTIVITY_ACTIONS）。（数字，可选）

运行服务器

从仓库根目录：

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 测试使用。
写入/操作集成测试（trigger_build、cancel_build 等）标记为 integration_write，并且是在 APPCIRCLE_ACCESS_TOKEN 之上的可选启用——它们会修改真实数据（触发真实构建等），因此绝不会仅通过 pytest test/integration/ -v 运行。设置 APPCIRCLE_RUN_WRITE_INTEGRATION_TESTS=true（将 APPCIRCLE_ACCESS_TOKEN 指向专用测试组织，而非生产环境）即可启用它们。

安全

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

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

uv run pip-audit