mcpField
A
Appcircle MCP

Appcircle MCP

远程服务
github.com/appcircleio云与基础设施01 周前更新
代码仓库

关于 Appcircle MCP

Appcircle MCP 将 AI 工具连接到 Appcircle 移动 CI/CD 资源，用于构建、签名、测试分发、应用商店发布和报告任务。它支持托管及本地部署，并可配置工具集和构建操作。

主要功能

  1. 01查看构建配置、工作流和提交
  2. 02检查构建状态与日志
  3. 03访问签名及分发信息
  4. 04查询发布和报告资源
  5. 05通过写入工具触发或取消构建

适用场景

  1. 01监测移动应用构建与发布状态
  2. 02根据日志排查构建失败
  3. 03查看签名配置和证书
  4. 04通过 AI 客户端启动或取消构建

MCP 相关

向 MCP 客户端提供 Appcircle 的构建、签名、测试分发、企业应用商店、发布和报告工具。可通过托管端点连接，也可使用 stdio、Streamable HTTP 或 Docker 在本地运行；客户端需提供 Appcircle 访问令牌。

配置

远程服务无需本地安装。选择你使用的客户端，复制配置或使用一键安装。

服务地址https://mcp.appcircle.io
一键复制安装命令
Claude CodeTerminal
Cursor.cursor/mcp.json
VS Code.vscode/mcp.json
Claude Desktopclaude_desktop_config.json
Windsurf~/.codeium/windsurf/mcp_config.json

命令在终端中运行；JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。

全部服务地址
Streamable HTTPhttps://mcp.appcircle.io需要授权

工具

详细介绍

Appcircle MCP Server

适用于 Appcircle 的 MCP 服务：向任何支持 MCP 的客户端（Claude Desktop、Cursor、VS Code 等）提供构建、签名身份、测试分发、企业应用商店、发布到应用商店和报告工具。Appcircle MCP Server 充当 AI 工具与 Appcircle 之间的桥梁，让 AI Agent、助手和聊天机器人能够通过结构化、受管控且面向具体任务的工具，安全地访问并交互 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）。请参阅下文的工具集。
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。

构建 - **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" 字段）。（字符串，必填）
签名身份

  • 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** - 获取当前组织的测试分发配置文件（分页）。可选按配置文件名称、平台和身份验证类型筛选，也可选择排序。 - **Access level:** 读取 - `page`：页码（从 1 开始）。默认值：1。（数字，可选） - `size`：每页数量（1-100）。默认值：25，最大值：100。（数字，可选） - `search`：可选搜索词，用于筛选配置文件（对配置文件名称进行不区分大小写的部分匹配；API 的搜索也可能匹配其他配置文件字段）。（字符串，可选） - `platform`：可选平台代码列表，用于筛选。允许的值：1=iOS，2=Android。（数字列表，可选） - `authentication_type`：可选身份验证类型代码列表，用于筛选。允许的值：1=None，3=Static Login，4=LDAP，5=SSO。（数字列表，可选） - `sort`：可选排序字段代码。允许的值：1=配置文件名称，2=创建日期，3=最后上传日期。（数字，可选） - `sort_direction`：可选排序方向代码。允许的值：1=升序，2=降序。（数字，可选）

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

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

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

    • Access level: 读取
    • 不接受任何参数。

  • update_app_version_release_notes - 副作用：覆盖向测试人员显示的分发应用版本发布说明（“message”）。返回更新后的应用版本对象（不包括 certThumbPrints）。默认注册；设置 AC_MCP_ENABLE_WRITE_TOOLS=false 可选择禁用。

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

  • send_app_version_to_testers - 副作用：向测试人员／测试组发送真实通知，为指定应用版本分发任务。默认注册；设置 AC_MCP_ENABLE_WRITE_TOOLS=false 可选择禁用。

    • Access level: 写入
    • 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 应用元数据（显示名称、发布者、捆绑包 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 - 获取发布流程运行的日志，可选择限定到单个步骤。默认返回截取末尾的视图，以避免占满模型的上下文。

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

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

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

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

    • Access level: 写入
    • 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 可选择退出。

    • Access level: 写入
    • 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 - 获取当前组织的企业应用商店配置文件（分页）。不支持搜索，但可按平台、发布类型和可见性筛选。也可选择排序。
    • Access level: 读取
    • page：页码（从 1 开始）。默认值：1。（数字，可选）
    • size：每页数量（1-100）。默认值：25，最大值：100。（数字，可选）
    • platform_type：可选的平台代码列表，用于筛选。允许的值：1=iOS，2=Android。（数字列表，可选）
    • publish_type：可选的发布类型代码列表，用于筛选。允许的值：1=发布到 Beta，2=发布到 Live。（数字列表，可选）
    • visibility：可选的筛选条件，用于指定配置文件是否公开列出（true=已列出，false=未列出）。（布尔值，可选）
    • sort：可选的排序字段代码。允许的值：1=应用名称，2=创建日期，3=下载次数，4=二进制文件接收日期。（数字，可选）
    • sort_direction：可选的排序方向代码。允许的值：1=升序，2=降序。（数字，可选）
- **get_store_profile_details** - 按 ID 获取单个企业应用商店配置文件（可选分页获取应用版本）。 - **访问级别：**读取 - `profile_id`：企业应用商店配置文件 ID（例如 UUID）。（字符串，必填） - `page`：应用版本的页码（从 1 开始）。默认值：1。（数字，可选） - `size`：应用版本的每页条目数（1-100）。默认值：25，最大值：100。（数字，可选） - 每个应用版本的 `publishType` 字段是一个 int：0=None，1=Beta，2=Live。
报告

  • 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_queue_waiting_report - 获取构建队列等待报告，可按日期范围筛选。支持分页。注意：在此端点中，buildDuration 表示队列等待时间（分钟），而非执行时间（与 get_build_history_report 不同）。

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

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

    • **访问级别：**读取
    • 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 不同，此工具会在内部获取所有页面，并返回小型预聚合结果，而非原始记录。

    • **访问级别：**读取
    • 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** - 获取已分发应用版本的每日使用报告。支持分页；支持按配置文件、OS 和组织进行筛选。 - **访问级别：** 读取 - `start_date`：可选的开始日期（YYYY-MM-DD）。（字符串，可选） - `end_date`：可选的结束日期（YYYY-MM-DD）。（字符串，可选） - `page`：页码（默认值：1）。（数字，可选） - `size`：每页项目数（1-100，默认值：50）。（数字，可选） - `profile_name`：按分发配置文件名称筛选。（字符串，可选） - `os`：按 OS 筛选（"ios" 或 "android"）。（字符串，可选） - `organization_id`：按组织 UUID 筛选。（字符串，可选）

  • get_distribution_sent_report - 获取已分发应用分享的每日使用报告。支持分页；支持按配置文件、OS 和组织进行筛选。

    • 访问级别： 读取
    • start_date：可选的开始日期（YYYY-MM-DD）。（字符串，可选）
    • end_date：可选的结束日期（YYYY-MM-DD）。（字符串，可选）
    • page：页码（默认值：1）。（数字，可选）
    • size：每页项目数（1-100，默认值：50）。（数字，可选）
    • profile_name：按分发配置文件名称筛选。（字符串，可选）
    • os：按 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 - 获取签名报告，可按日期范围、组织、OS 和构建状态筛选。支持分页。

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

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

    • **访问级别：**读取
    • 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 - 获取发布活动日志（重新签名、发布流程事件等），可按日期范围和其他参数筛选。支持分页。

    • **访问级别：**读取
    • 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

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。