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