Appcircle MCP Server

官方

Appcircle 官方 MCP 伺服器

你可以用 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 token（例如 `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，並在請求中傳送其 token。
4. 本機（Docker）	在您的機器上執行官方 Docker 映像檔。需要 Docker。使用映像檔的預設連接埠，或使用 `--port` 覆寫；請參閱映像檔文件以了解確切用法。

詳細的用戶端設定（Cursor、Claude 等）位於專屬的安裝指南中；本節僅提供高層級摘要。

安裝

各用戶端專屬的設定指南：

Claude Applications - Claude Desktop 和 Claude Code CLI 的安裝指南。
Cursor IDE - Cursor IDE 的安裝指南。
Codex - Codex 應用程式和 Codex CLI 的安裝指南。
Antigravity IDE - Antigravity IDE 的安裝指南。
VS Code (GitHub Copilot) - 搭配 GitHub Copilot 使用 VS Code 的安裝指南。
Windsurf IDE - Windsurf IDE 的安裝指南。
Gemini CLI - Gemini CLI 的安裝指南。
GitHub Copilot CLI - GitHub Copilot CLI 的安裝指南。

設定（環境變數）

變數	必要	說明
`APPCIRCLE_ACCESS_TOKEN`	是（僅 stdio）	Appcircle API 存取 token。使用 stdio 傳輸時為必要。對於 streamable-http，每個用戶端會傳送自己的 token。請參閱取得 token了解如何取得。
`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）。可選擇按應用程式（套件）ID 進行篩選。
- 存取層級： 讀取
- app_id：可選的應用程式（套件）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 - 取得單一應用程式版本可用的商店中繼資料地區（名稱、代碼、已在地化、isPrimary）。
- 存取層級： 讀取
- 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 - 取得發佈流程執行的記錄，可選擇只限於單一步驟。預設為擷取結尾的檢視，避免淹沒模型的上下文。
- 存取層級： 讀取
- 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／Google Play／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）。（string，required）
- page：應用程式版本的頁碼（從 1 開始）。預設值：1。（number，optional）
- size：應用程式版本的每頁項目數（1-100）。預設值：25，最大值 100。（number，optional）
- 每個應用程式版本的 publishType 欄位是 int：0=None、1=Beta、2=Live。

Report

get_build_history_report - 取得建置歷史報告，可依日期範圍、建置設定檔和組織篩選。已分頁。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- build_profile_name：依建置設定檔名稱篩選。（string，optional）
- organization_id：依組織 UUID 篩選。（string，optional）
get_build_queue_waiting_report - 取得建置佇列等待報告，可依日期範圍篩選。已分頁。注意：在此端點上，buildDuration 表示佇列等待時間（分鐘），而非執行時間（與 get_build_history_report 不同）。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。若兩者皆提供，必須 <= end_date。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
get_build_activity_log - 取得建置活動記錄（工作流程／設定檔變更、CodePush 發行等），可依日期範圍和其他參數篩選。已分頁。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。若兩者皆提供，必須 <= end_date。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- organization_id：依組織 UUID 篩選。（string，optional）
- platform：依平台類型篩選（整數代碼，例如 0=Android、1=iOS）。（number，optional）
- email：依操作使用者的電子郵件篩選。（string，optional）
- profile_name：依建置設定檔名稱篩選。（string，optional）
- action：依活動動作代碼篩選（整數；完整對應請參閱工具原始碼中的 BUILD_ACTIVITY_ACTIONS）。（number，optional）
get_build_insights_report - 取得計算後的建置洞察報告（健康狀態快照＋趨勢、根本原因、成品健康、工作流程品質、佇列時間和成熟度評估分析），涵蓋建置歷史，並在伺服器端彙總。與 get_build_history_report 不同，此工具會在內部擷取每一頁，並回傳小型預先彙總的結果，而非原始記錄。
- 存取層級： read
- start_date：目前期間的選用開始日期（YYYY-MM-DD）。預設值：最近 30 天。（string，optional）
- end_date：目前期間的選用結束日期（YYYY-MM-DD）。（string，optional）
- sections：選用的區段清單以進行計算：health_snapshot、root_cause、artifact_health、workflow_quality、queue_time、maturity_assessment。預設值：全部六個。（array of strings，optional）
- include_sub_orgs：若為 true，則在歷史衍生指標中保留跨組織的建置記錄，而非僅篩選至權杖所屬的組織。預設值：false。（boolean，optional）
get_distribution_app_version_report - 取得已發行應用程式版本的每日使用量報告。已分頁；支援依設定檔、作業系統、組織篩選。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- profile_name：依發行設定檔名稱篩選。（string，optional）
- os：依作業系統篩選（"ios" 或 "android"）。（string，optional）
- organization_id：依組織 UUID 篩選。（string，optional）
get_distribution_sent_report - 取得已發行應用程式分享的每日使用量報告。已分頁；支援依設定檔、作業系統、組織篩選。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- profile_name：依發行設定檔名稱篩選。（string，optional）
- os：依作業系統篩選（"ios" 或 "android"）。（string，optional）
- organization_id：依組織 UUID 篩選。（string，optional）
get_enterprise_app_store_app_usage_report - 取得企業應用程式商店的應用程式使用量報告。start_date 和 end_date 為必填。已分頁。
- 存取層級： read
- start_date：開始日期（YYYY-MM-DD）。（string，required）
- end_date：結束日期（YYYY-MM-DD）。（string，required）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- organization_id：選用的組織 UUID 篩選。（string，optional）
get_publish_resign_report - 取得發行重新簽署報告，可依日期範圍、應用程式名稱、組織和狀態篩選。已分頁。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- app_name：依應用程式名稱篩選。（string，optional）
- organization_id：依組織 UUID 篩選。（string，optional）
- status：依重新簽署狀態篩選（0=waiting、1=processing、2=succeeded、3=failed、4=cancelled、5=timeout）。（number，optional）
get_publish_status_report - 取得發行狀態報告，可依日期範圍、應用程式名稱、組織和狀態篩選。已分頁。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- app_name：依應用程式名稱篩選。（string，optional）
- organization_id：依組織 UUID 篩選。（string，optional）
- status：依發行狀態篩選（例如 0=Success、1=Failed、91=Running）。（number，optional）
get_signing_report - 取得簽署報告，可依日期範圍、組織、作業系統和建置狀態篩選。已分頁。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- organization_id：依組織 UUID 篩選。（string，optional）
- os：依作業系統篩選（"ios" 或 "android"）。（string，optional）
- build_status：依建置狀態篩選（例如 0=Success、1=Failed、91=Running）。（number，optional）
get_signing_activity_log - 取得簽署活動記錄（例如憑證／描述檔／金鑰庫到期通知），可依日期範圍和其他參數篩選。已分頁。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。若兩者皆提供，必須 <= end_date。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- organization_id：依組織 UUID 篩選。（string，optional）
- platform：依平台篩選（例如 "iOS"、"Android"）。（string，optional）
- email：依操作使用者的電子郵件篩選。（string，optional）
- action：依活動動作代碼篩選（整數；完整對應請參閱工具原始碼中的 SIGNING_ACTIVITY_ACTIONS）。（number，optional）
get_publish_activity_log - 取得發行活動記錄（重新簽署、發行流程事件等），可依日期範圍和其他參數篩選。已分頁。
- 存取層級： read
- start_date：選用的開始日期（YYYY-MM-DD）。若兩者皆提供，必須 <= end_date。（string，optional）
- end_date：選用的結束日期（YYYY-MM-DD）。（string，optional）
- page：頁碼（預設值：1）。（number，optional）
- size：每頁項目數（1-100，預設值：50）。（number，optional）
- organization_id：依組織 UUID 篩選。（string，optional）
- platform：依平台篩選（例如 "iOS"、"Android"）。（string，optional）
- email：依操作使用者的電子郵件篩選。（string，optional）
- profile_name：依發行設定檔名稱篩選。（string，optional）
- action：依活動動作代碼篩選（整數；完整對應請參閱工具原始碼中的 PUBLISH_ACTIVITY_ACTIONS）。（number，optional）

執行伺服器

從儲存庫根目錄：

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