AgileHero
官方從您的代理程式運行敏捷工作區：建立和移動卡片、整理史詩、規劃路線圖、執行回顧、繪製白板及撰寫Wiki頁面。
你可以用 AgileHero MCP 做什麼？
-
透過 OAuth 連線 — 將
https://mcp.agilehero.io/mcp加入任何 MCP 用戶端，並使用您的 AgileHero 帳號登入，無需 API 金鑰。 -
跨專案搜尋 — 請您的助理使用全域全文
search工具，依內容尋找卡片、史詩或 Wiki 頁面。 -
管理卡片與史詩 — 透過 或 讀取完整的卡片或史詩詳細資訊，包括描述、檢查清單、標籤與留言。
-
安全編輯 Wiki 頁面 — 預覽變更，然後使用回傳的 token 套用變更。
-
建立與轉換白板 — 使用 繪製圖表，或將便利貼轉換為待辦事項。
-
執行回顧會議 — 使用 列出既有回顧，或建立新的回顧。
託管 MCP 伺服器
npx add-mcp 'https://mcp.agilehero.io/mcp'可安裝到 Claude Code、Codex、Cursor 等客戶端
文件
AgileHero 內建一個 MCP 伺服器：將一個 URL 加入任何支援 MCP 的 AI 助理，使用您的 AgileHero 帳號登入，它就會以您的權限操作您的專案——涵蓋看板、待辦清單、Epic、Wiki、白板、回顧與路線圖，共 49 個工具。本參考文件由伺服器本身產生，因此永遠保持最新。
初次使用？請從 AI 代理程式總覽 開始，或直接跳到下方的 連接您的用戶端。此伺服器上的所有豐富文字皆為 AgileHero Markup (AHM)——一種嚴格且經過驗證的 XML 方言，專為確保代理程式絕不破壞人類內容而設計。想撰寫指令碼而非連接助理？REST API 參考文件 使用相同的 OAuth 登入方式。
連接您的 AI 用戶端
連接包含兩件事：將端點 URL 加入您的用戶端，然後在用戶端要求時使用您的 AgileHero 帳號登入。無需建立或貼上金鑰。連接後，用戶端將以您的身分、以您的權限運作；每個已連接的用戶端都會列在應用程式中的 設定 → AI 用戶端 下，您可以隨時撤銷其存取權。觀察者無法使用 MCP 伺服器：您身為觀察者的工作區不會被列出，其中的所有內容都會顯示為找不到。
端點
https://mcp.agilehero.io/mcp
傳輸方式
Streamable HTTP (POST)
登入
您的 AI 用戶端會開啟瀏覽器視窗；核准一次，隨時可在設定 → AI 用戶端中撤銷。
Claude Code
在終端機中執行一次；Claude Code 會將伺服器儲存在您的使用者層級設定中，並透過瀏覽器登入。
claude mcp add --transport http --scope user agilehero https://mcp.agilehero.io/mcp
- 所有旗標都必須放在伺服器名稱之前。
- 然後在 Claude Code 工作階段中執行
/mcp並選擇 Authenticate（或執行claude mcp login agilehero），然後在瀏覽器中核准登入。
驗證： 執行 claude mcp list——agilehero 應顯示為已連接。若顯示「需要驗證」，請執行 claude mcp login agilehero。
Claude Code 文件 · 已於 2026-09-15 對照廠商文件驗證
VS Code (GitHub Copilot)
在工作區中新增至 .vscode/mcp.json，或執行「MCP: Open User Configuration」以套用至所有工作區。伺服器首次啟動時會開啟瀏覽器視窗進行登入。
.vscode/mcp.json
{
"servers": {
"agilehero": {
"type": "http",
"url": "https://mcp.agilehero.io/mcp"
}
}
}
- 「type」: "http" 為必填——缺少時 VS Code 會將 URL 視為要執行的指令。
驗證： 執行「MCP: List Servers」，啟動 agilehero，在瀏覽器中完成登入，並確認其工具出現在 Chat 檢視中。
VS Code (GitHub Copilot) 文件 · 已於 2026-09-15 對照廠商文件驗證
Codex
從終端機新增，然後登入——此設定由 Codex CLI、IDE 擴充功能及 ChatGPT 桌面應用程式共用。
codex mcp add agilehero --url https://mcp.agilehero.io/mcp
codex mcp login agilehero
- Codex 不會自行啟動登入——新增伺服器後請執行
codex mcp login agilehero。
驗證： 執行 codex mcp list——agilehero 應顯示為已驗證；然後要求 Codex 列出您的 AgileHero 專案。
Codex 文件 · 已於 2026-09-15 對照廠商文件驗證
Zed
新增至 settings.json，或使用 設定 → AI → MCP Servers → Add Remote Server；Zed 會提示您登入。
~/.config/zed/settings.json
{
"context_servers": {
"agilehero": {
"url": "https://mcp.agilehero.io/mcp"
}
}
}
- 請勿加入 headers——Zed 僅在未設定 Authorization header 時才會啟動登入。
驗證： 重新啟動 Zed，在瀏覽器中核准登入，並要求它列出您的 AgileHero 專案——首次成功呼叫即確認連線。
Zed 文件 · 已於 2026-09-15 對照廠商文件驗證
GitHub Copilot CLI
新增至 ~/.copilot/mcp-config.json，或儲存庫內的 .mcp.json。
~/.copilot/mcp-config.json
{
"mcpServers": {
"agilehero": {
"type": "http",
"url": "https://mcp.agilehero.io/mcp"
}
}
}
- 需要 GitHub Copilot CLI 1.0.83 或更新版本（支援 Client ID Metadata Document）。
- Copilot CLI 會在伺服器首次要求時開啟登入；您也可以在工作階段內執行
/mcp auth agilehero。
驗證： 在 Copilot CLI 內執行 /mcp——agilehero 應顯示為已連接並列出其工具。
GitHub Copilot CLI 文件 · 已於 2026-09-15 對照廠商文件驗證
Claude（網頁、桌面版、Cowork）
將 AgileHero 新增為自訂連接器並登入；此連接器可用於 Claude 網頁版、Claude Desktop、Cowork 及行動應用程式。
Settings → Connectors → Add custom connector
Name: AgileHero
URL: https://mcp.agilehero.io/mcp
Sign in now
- 當 Claude Code 使用相同的 Claude 帳號登入時，此連接器也會出現在其中。
- 免費方案：一個自訂連接器。Team 和 Enterprise：由 Owner 新增連接器，每位成員使用自己的 AgileHero 帳號登入。
驗證： 開始新聊天——AgileHero 會列在連接器下方，且要求 Claude 列出您的 AgileHero 專案即可運作。
Claude（網頁、桌面版、Cowork）文件 · 已於 2026-09-15 對照廠商文件驗證
ChatGPT
在開發者模式中建立連接器並使用 OAuth 登入。
Settings → Connectors → Create (Developer mode)
Name: AgileHero
MCP server URL: https://mcp.agilehero.io/mcp
Authentication: OAuth
- 適用於啟用開發者模式的 Plus、Pro、Business、Enterprise 和 Edu 方案；在工作區中，管理員或擁有者會為成員發佈連接器。
驗證： 開啟啟用 AgileHero 連接器的新聊天，並要求 ChatGPT 列出您的 AgileHero 專案。
ChatGPT 文件 · 已於 2026-09-15 對照廠商文件驗證
其他用戶端
任何支援 Client ID Metadata Documents 的 OAuth 的 MCP 用戶端：將端點新增為遠端（Streamable HTTP）伺服器，並在瀏覽器中核准登入。
Transport: Streamable HTTP
URL: https://mcp.agilehero.io/mcp
Authentication: OAuth (sign in when the client asks)
- 僅支援靜態 token 或 headers 的用戶端無法連接——AgileHero 僅使用 OAuth 登入。
驗證： 重新啟動用戶端，在瀏覽器中核准登入，並要求它列出您的 AgileHero 專案——首次成功呼叫即確認連線。
其他用戶端文件 · 已於 2026-09-15 對照廠商文件驗證
尚不支援
這些用戶端目前無法登入 AgileHero。其中大多數缺乏對 Client ID Metadata Documents 的支援，這是 AgileHero 使用的 OAuth 用戶端註冊方法（目前 MCP 的建議做法）；我們會定期重新檢查廠商文件，一旦符合資格便會立即將用戶端升級。
Cursor尚未支援
Cursor 尚不支援 Client ID Metadata Documents（其 OAuth 登入需要 Dynamic Client Registration 或預先註冊的用戶端），因此目前無法連接 AgileHero。
Cursor 文件 · 已於 2026-09-15 對照廠商文件驗證
OpenCode尚未支援
OpenCode 尚不支援 Client ID Metadata Documents（其 OAuth 登入需要 Dynamic Client Registration 或預先註冊的用戶端），因此目前無法連接 AgileHero。
OpenCode 文件 · 已於 2026-09-15 對照廠商文件驗證
Gemini CLI尚未支援
Gemini CLI 尚不支援 Client ID Metadata Documents（其 OAuth 登入需要 Dynamic Client Registration 或預先註冊的用戶端），因此目前無法連接 AgileHero。
Gemini CLI 文件 · 已於 2026-09-15 對照廠商文件驗證
Cline尚未支援
Cline 尚不支援 Client ID Metadata Documents（其 OAuth 登入需要 Dynamic Client Registration 或預先註冊的用戶端），因此目前無法連接 AgileHero。
Cline 文件 · 已於 2026-09-15 對照廠商文件驗證
Google Antigravity尚未支援
Google Antigravity 尚不支援 Client ID Metadata Documents（其 OAuth 登入需要 Dynamic Client Registration 或預先註冊的用戶端），因此目前無法連接 AgileHero。
Google Antigravity 文件 · 已於 2026-09-15 對照廠商文件驗證
Amp尚未支援
Amp 尚不支援 Client ID Metadata Documents（其 OAuth 登入需要 Dynamic Client Registration 或預先註冊的用戶端），因此目前無法連接 AgileHero。
Amp 文件 · 已於 2026-09-15 對照廠商文件驗證
Raycast AI尚未支援
Raycast AI 尚不支援 Client ID Metadata Documents（其 OAuth 登入需要 Dynamic Client Registration 或預先註冊的用戶端），因此目前無法連接 AgileHero。
Raycast AI 文件 · 已於 2026-09-15 對照廠商文件驗證
Kiro尚未支援
Kiro 使用您提供的 Client ID Metadata Document URL 登入，而 AgileHero 尚未為其託管 Client ID Metadata Document。
Kiro 文件 · 已於 2026-09-15 對照廠商文件驗證
Warp尚未支援
Warp 尚無針對使用者新增伺服器的 OAuth 登入，因此目前無法連接 AgileHero。
Warp 文件 · 已於 2026-09-15 對照廠商文件驗證
JetBrains AI Assistant尚未支援
JetBrains AI Assistant 尚無針對遠端伺服器的 OAuth 登入，且 mcp-remote 橋接器需要託管的用戶端文件——AgileHero 尚未為其託管 Client ID Metadata Document。
JetBrains AI Assistant 文件 · 已於 2026-09-15 對照廠商文件驗證
Continue尚未支援
Continue 尚無針對 Streamable HTTP 伺服器的 OAuth 登入，且 mcp-remote 橋接器需要託管的用戶端文件——AgileHero 尚未為其託管 Client ID Metadata Document。
Continue 文件 · 已於 2026-09-15 對照廠商文件驗證
伺服器指示
每個 MCP 用戶端在初始化時都會收到這些慣例：
AgileHero MCP 伺服器。
每個 id 參數和回應中的每個 id 都是短 uid——一律使用 list/get/search 工具傳回的 uid，切勿自行編造。大多數工具需要專案 uid——請先呼叫 list_projects 以探索工作區和專案。偏好使用 search（全文、所有內容類型）而非 search_cards（標題子字串、單一專案）。
在更新工具中，偏好使用 add_*/remove_* 增量欄位來處理集合（增量、安全）；純集合欄位（assigned_to、labels、checklists、cards_relations、links、attachments）會取代先前的狀態，且無法與其增量欄位合併。Checklist 項目為 { description, checked }。使用 list_cards / list_epics 上的 updated_since 來掌握變更。
使用 move_card（而非 update_card）來變更卡片所在的清單或位置；空的 list_id 表示待辦清單。
Wiki、白板、回顧和路線圖工具要求專案的工作區為 Pro 或試用方案。白板元素寫入為批次工具且為全有或全無；元素 uid 來自 get_whiteboard。回顧項目使用 add_retro_items 和 move_retro_item 管理（move_card 會拒絕回顧卡片）。
每日限制：工具呼叫按每位使用者、每個工作區計量——免費方案每天 500 次，Pro 或試用方案每天 5,000 次，於 00:00 UTC 重置。get_ahm_spec 和 list_projects 永遠不計入（任何無法歸屬於單一工作區的呼叫也不計入，例如未限定範圍的搜尋）。超過限制時，工具會傳回每日限制錯誤，直到重置或升級。
所有豐富文字（Wiki 頁面、卡片/Epic 描述、留言）皆為 AgileHero Markup (AHM)——嚴格的 XML，絕非 markdown 或 HTML；在撰寫任何內容前請先呼叫 get_ahm_spec 一次。豐富文字編輯依設計分兩步驟：preview_wiki_page_update / preview_description_update（後果 + preview_token），然後使用該 token 呼叫對應的更新工具。
完整工具文件：https://agilehero.io/docs/mcp
AHM 規格：https://agilehero.io/docs/mcp/agilehero-markup
工具（49）
list_projects唯讀
列出 token 使用者可存取的所有工作區和專案，讓代理程式能解析大多數其他工具所需的專案 uid。每當不知道專案 uid 時請先呼叫此工具——切勿要求使用者貼上。傳回工作區（uid、名稱、方案、您的角色）及其專案（uid、名稱、url）。Pro 支柱工具（wiki、metrics）需要工作區方案為 pro 或試用。
search唯讀
產品的全域全文搜尋（OpenSearch）：卡片、epic、wiki 頁面與專案，比對標題、描述、留言、檢查清單項目與附件檔名，依相關性排序並帶有近期加權。用這個功能依內容尋找任何東西（「我們討論遷移的那張卡片」）；search_cards 僅用於在單一專案內依標題子字串查詢。每個結果都帶有類型、可立即操作的 uid（卡片供 get_card/update_card、epic 供 get_epic、wiki_pages 供 show_wiki_page、專案供 project_id 參數）、深層連結網址，以及 <mark> 標示的片段，說明為何符合。可選擇以 project_id 或 assigned_to_me 限定範圍。使用 page/per_page 分頁；total_count 是完整符合數。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| query | string | 是 | 自由文字搜尋查詢 |
| project_id | string | 可選的專案 uid，用於限定搜尋範圍 | |
| assigned_to_me | boolean | 僅限指派給該 token 使用者的結果 | |
| page | integer | 頁碼（預設 1） | |
| per_page | integer | 每頁結果數，1-50（預設 20） |
get_card唯讀
完整讀取一張卡片：其 AgileHero Markup 描述（含區塊 id）與 description_version（preview_description_update / update_description 這兩個輸入所接受的）、清單位置、epic、標籤、指派對象、回報者、類型、估算、截止日期、檢查清單、連結、附件、相關卡片與討論串留言。僅接受卡片 uid——沒有 project_id 參數。卡片 uid 來自 list_cards、search 或 search_cards。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 卡片的唯一識別碼 |
get_epic唯讀
完整讀取一個 epic：其 AgileHero Markup 描述（含區塊 id）與 description_version（preview_description_update / update_description 這兩個輸入所接受的）、名稱、編號、顏色、開始/結束日期、指派對象、檢查清單、連結、附件、其上的每張卡片（uid、編號、標題及其清單與類別——null 清單代表待辦——依看板順序，因此這是列出 epic 所有卡片並查看哪些是待辦、進行中或已完成的方式）與討論串留言。僅接受 epic uid——沒有 project_id 參數。Epic uid 來自 list_epics 或 search。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | epic 的唯一識別碼 |
list_wiki_pathsPro · wiki唯讀
以顯示順序列出專案的整個 wiki 樹——每個資料夾與頁面及其 uid、名稱、類型（頁面或資料夾）與 parent_id——讓代理程式能解析 show_wiki_page 所需的頁面 uid，並為 create_wiki_page 挑選 parent_id。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼 |
show_wiki_pagePro · wiki唯讀
以 AgileHero Markup（AHM）格式擷取 wiki 頁面及其 document_version。內容是 AHM，而非 markdown——區塊 id、<discussion> 錨點，以及 <image/>/<attachment/> 參照都是文件的一部分；編輯前請先閱讀 get_ahm_spec。透過 preview_wiki_page_update 再 update_wiki_page 編輯，使用此處回傳的區塊 id 與 document_version。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 頁面路徑的唯一識別碼 |
get_ahm_spec唯讀
AgileHero Markup（AHM）v1.0 規格——AgileHero 唯一接受的豐富文字格式（markdown 與 HTML 會被拒絕）。在撰寫或編輯任何豐富文字（wiki 頁面、卡片/epic 描述、留言）前，請先閱讀此規格一次：詞彙、屬性、跳脫規則與完整範例。網路上相同文字：https://agilehero.io/docs/mcp/agilehero-markup
create_wiki_pagePro · wiki
以 AgileHero Markup（AHM）內容建立 wiki 頁面（可選擇放在資料夾內）。內容必須包在 <agile-hero-markup version="1.0"> 中——markdown 與 HTML 會被拒絕；請先閱讀 get_ahm_spec。回傳新頁面的 uid、網址、document_version 與內容。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼（uid） |
| name | string | 是 | 頁面標題 |
| parent_id | string | 可選的資料夾 uid（來自 list_wiki_paths） | |
| content | string | 頁面內文為 AHM；省略則建立空白頁面 |
preview_wiki_page_updatePro · wiki唯讀
每次 wiki 頁面更新的必要第一步：驗證操作並回傳伺服器計算的後果（新增/移除/變更的區塊、將被永久刪除的檔案、會失去錨點的團隊討論、可能的 markdown 警告）以及 update_wiki_page 所需的 preview_token。不會修改任何內容。操作以區塊為定址（replace_block / insert_after / delete_block / move_block）並帶有 AHM 內容——請先閱讀 get_ahm_spec，並從 show_wiki_page 取得區塊 id 與 document_version。儲存前請檢視後果：列出的檔案刪除或討論取消錨點，僅在使用者要求時才可接受。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 頁面路徑 uid |
| document_version | string | 是 | 來自 show_wiki_page——證明文件為最新狀態 |
| operations | array of object | 是 | 依序套用於不斷演進的文件 |
update_wiki_pagePro · wiki具破壞性
將先前預覽的更新套用至 wiki 頁面。需要 preview_wiki_page_update 的 preview_token，且必須完全對應這些操作與此 document_version——設計上無法不預覽就儲存。每次儲存都會建立頁面版本，使用者可在應用程式中還原。回傳更新後的頁面（AHM + 新的 document_version）與已套用的後果。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 頁面路徑 uid |
| document_version | string | 是 | 預覽所依據的版本 |
| operations | array of object | 是 | 已預覽的確切操作 |
| preview_token | string | 是 | 來自 preview_wiki_page_update |
preview_description_update唯讀
每次卡片或 epic 描述編輯的必要第一步：驗證區塊操作並回傳伺服器計算的後果，以及 update_description 所需的 preview_token。不會修改任何內容。內容是 AgileHero Markup（AHM，描述介面：無表格、顏色、對齊、討論或檔案附件）——請先閱讀 get_ahm_spec；區塊 id 與 document_version 來自 get_card / get_epic。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| resource_type | enum: card | epic | 是 | |
| id | string | 是 | 卡片或 epic uid |
| document_version | string | 是 | 來自 get_card / get_epic |
| operations | array of object | 是 | 依序套用於不斷演進的描述 |
update_description具破壞性
將先前預覽的描述更新套用至卡片或 epic。需要 preview_description_update 的 preview_token，且必須完全對應這些操作與此 document_version——設計上無法不預覽就儲存。回傳更新後的描述（AHM + 新的 document_version）。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| resource_type | enum: card | epic | 是 | |
| id | string | 是 | 卡片或 epic uid |
| document_version | string | 是 | 預覽所依據的版本 |
| operations | array of object | 是 | 已預覽的確切操作 |
| preview_token | string | 是 | 來自 preview_description_update |
list_whiteboardsPro · whiteboard唯讀
列出專案的白板（uid、名稱、元素數量、網址）。使用 get_whiteboard 讀取白板的元素。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼 |
create_whiteboardPro · whiteboard
在專案上建立空白白板。使用 create_whiteboard_elements 新增內容。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼 |
| name | string | 是 | 白板名稱 |
get_whiteboardPro · whiteboard唯讀
以精簡文字表示法讀取白板：板面邊界加上每個元素一行——「<type> <uid> 位於 <x>,<y> 尺寸 <w>x<h> [顏色] [父層 <frame-uid>] [連結 <card|epic> <uid>] \"文字\"」，連接器為「connector <uid> <from> -> <to>」。此處的元素 uid 是所有白板寫入工具所使用的手柄。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 白板的唯一識別碼 |
create_whiteboard_elementsPro · whiteboard
在單一交易呼叫中建立最多 100 個白板元素（全有或全無，單一即時事件）。原生尺寸、顏色與文字位置由伺服器端套用——通常只需提供類型 + 文字（+ 顏色）。省略 x/y 則元素會自動排列（預設為網格；arrange: row|column|grid，可用 origin_x/origin_y/gap 調整）；提供 x/y 則可完全控制。框架透過 parent_id（現有框架 uid）或 parent_ref（本次呼叫中較早框架的 ref）包含元素。連接器以 uid（source_id/target_id）或批次 ref（source_ref/target_ref）綁定元素——絕不使用座標；錨點由 UI 計算。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| whiteboard_id | string | 是 | 白板的唯一識別碼 |
| elements | array of object | 是 | 依陣列順序建立——ref 僅能向後解析 |
| arrange | enum: grid | row | column | 無明確 x/y 元素的版面（預設 grid） | |
| origin_x | number | 自動排列起始 x（預設 100） | |
| origin_y | number | 自動排列起始 y（預設 100） | |
| gap | number | 自動排列間距，單位 px（預設 20） |
create_whiteboard_diagramPro · whiteboard
從語意圖（節點、邊、可選群組，無座標）在白板上繪製圖表（流程圖、流程、依賴關係圖）：伺服器會以原生尺寸進行由上而下的分層版面配置，並回傳以您的節點 id 為鍵的已建立元素 uid。放置於現有白板內容下方。具交易性（全有或全無，單一即時事件）。最多 20 個節點——較大的流程請拆成兩個圖表。除非語意需要，否則保持形狀為單純矩形（菱形 = 決策、圓角矩形 = 開始/結束、圓柱體 = 資料儲存）。使用 update_whiteboard_elements 編輯結果——版面配置不會再次執行。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| whiteboard_id | string | 是 | 白板的唯一識別碼 |
| title | string | 圖表標題（框架標題，或使用群組時的標題） | |
| nodes | array of object | 是 | |
| edges | array of object | ||
| groups | array of object | ||
| origin_x | number | 可選的左上角 x；預設在現有內容下方 | |
| origin_y | number | 可選的左上角 y；預設在現有內容下方 |
update_whiteboard_elementsPro · whiteboard
一次全有或全無的呼叫中更新最多 100 個白板元素：移動（x/y）、調整大小、重新分層（z_index）、重新文字化、重新著色、重新指定父層（parent_id — 一個框架 uid，或 "" 以分離），以及連接器的箭頭/路徑/標籤。元素 uid 來自 get_whiteboard；元素類型無法變更。僅變更提供的欄位 — 無關的屬性會被保留。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| whiteboard_id | string | 是 | 白板的唯一識別碼 |
| updates | array of object | 是 |
delete_whiteboard_elementsPro · whiteboarddestructive
在一次交易式呼叫中刪除最多 100 個白板元素。刪除框架或心智圖節點會將其子元素釋放到畫布上（它們不會被刪除 — 若要一併刪除，請明確包含它們的 uid）。連接到已刪除元素的連接器不會被移除，並會懸空。元素 uid 來自 get_whiteboard。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| whiteboard_id | string | 是 | 白板的唯一識別碼 |
| ids | array of string | 是 | 要刪除的元素 uid |
review_whiteboardPro · whiteboardread-only
對白板執行確定性品質檢查：可能溢出其元素的文字、明顯重疊的元素、具有未綁定或懸空端點的連接器、UI 調色盤之外的顏色、離網格的位置，以及其父層已被刪除的元素。此為建議性質 — 發現結果是建議而非錯誤，且帶有發現結果的畫布可能正是使用者想要的。在繪製後使用以進行合理性檢查，最多修正一次，不要為了追求空報告而循環。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 白板的唯一識別碼 |
convert_whiteboard_elementPro · whiteboard
將白板元素轉換為待辦事項：將便利貼轉換為卡片或史詩，或將框架轉換為史詩（框架的便利貼子元素會成為該史詩上的卡片；已轉換的子元素會被重新指派，而非複製）。該元素會留在畫布上，並連結到其轉換後的結果 — get_whiteboard 會顯示該連結。一個元素只能轉換一次。除非您傳入標題，否則便利貼/框架的文字會成為標題。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 元素 uid（sticky_note 或 frame，來自 get_whiteboard） |
| to | enum: card | epic | 是 | 要建立的內容 |
| title | string | 卡片標題 / 史詩名稱；預設為元素的文字 | |
| list_id | string | 僅限卡片：目標清單 uid；省略則使用待辦清單 | |
| color | string | 僅限史詩：十六進位顏色；預設為元素的顏色 |
convert_mind_mapPro · whiteboard
將心智圖轉換為待辦事項，並具有每個節點的對應：根節點可以成為新的史詩（角色 "epic"）或附加到現有的史詩（角色 "existing_epic" + target_epic_id）；其他節點成為該史詩上的卡片（角色 "card"）或專案標籤（角色 "label" — 樹中卡片節點上方的標籤節點會套用到該卡片）；角色 "skip" 會忽略節點。將 ROOT 元素 uid 作為 id 傳入，並將您想要轉換的每個節點放入 nodes（未列出的節點會被忽略）。每個節點僅轉換一次：已轉換的節點會事先被拒絕 — 請在不包含它們的情況下重新提交。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | ROOT 心智圖節點 uid（來自 get_whiteboard） |
| nodes | array of object | 是 | |
| target_epic_id | string | 史詩 uid，與根節點上的角色 "existing_epic" 一起使用時為必填 |
list_retrospectivesPro · retrospectivesread-only
列出專案的回顧：工作區具有新模型回顧和健康檢查時顯示這些，否則顯示經典回顧看板。新模型條目具有 uid、名稱、種類（retro | health_check）、狀態（open | live | closed）、日期（starts_on；健康檢查為 closes_on）、目前階段、範本、引導者 uid、其建立的動作計數，以及 url；回應會加入專案的 open_actions_count。使用 get_retrospective 以取得完整資訊。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼 |
create_retrospectivePro · retrospectives
建立回顧：工作區具有新模型回顧時建立新模型回顧，否則建立經典回顧看板；回應是 get_retrospective 所回傳的回顧（包含其 uid 的欄），因此 add_retro_items 可以立即接續。新模型回顧來自範本（預設 went_well），立即開放筆記，並以您為引導者；可選：焦點、匿名性（預設：範本的）、participant_ids（Selected-members 回顧；省略則為所有具有寫入權限的專案成員）、check_in 和 feedback 問題種類，以及投票。引導者在應用程式中啟動它並執行其階段。經典看板僅接受 name、date 和 previous_retrospective_id，並拒絕新模型參數。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼 |
| name | string | 是 | 回顧名稱 |
| template | enum: went_well | start_stop_continue | four_ls | mad_sad_glad | kalm | daki | starfish | plus_delta | sailboat | rose_thorn_bud | wrap | hot_air_balloon | three_pigs | project_retro | postmortem | kudos_lessons | 範本金鑰；預設 went_well | |
| starts_on | string | 日期，ISO-8601（YYYY-MM-DD）；預設為今天 | |
| starts_at | string | starts_on 的已棄用別名 | |
| focus | string | 此回顧的主題，顯示在其名稱下方 | |
| anonymity | enum: anonymous | optional | named | 筆記上顯示的對象：anonymous（匿名）、optional（作者可加入其名稱）或 named（具名） | |
| participant_ids | array of string | 參與者的使用者 uid（list_project_users）；您永遠是其中之一 | |
| check_in | enum: safety | mood | esvp | one_word | 簽到問題（預設 safety） | |
| feedback | enum: roti | pulse | one_word | 結束回饋問題（預設 roti） | |
| votes | object | 投票設定：budget（auto | fixed | unlimited）、per_person（1-20）、max_per_topic（1-10） | |
| previous_retrospective_id | string | 僅限經典看板：先前回顧的 uid，其 Actions 欄會顯示為 "Past actions" |
get_retrospectivePro · retrospectivesread-only
以您可能看到的方式讀取回顧：工作區具有新模型回顧或健康檢查時顯示這些，否則顯示經典回顧看板。新模型回顧會回傳設定、階段（目前階段、計時器、進度）、欄（含 uid）中的主題（筆記群組，含 uid）、簽到和回饋統計、您剩餘的投票、Discuss 佇列和擱置主題、提案、動作（其建立的加上專案未結的），以及關閉後的摘要。隱私遵循房間：在揭示前您只會看到自己的筆記（每個欄會計算每個人的數量）、僅在具名筆記上顯示作者、僅在投票揭示後顯示投票總數。健康檢查會回傳其維度和參與度、開放時您自己的評分，以及關閉後每個維度的彙總。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 回顧 uid（來自 list_retrospectives） |
add_retro_itemsPro · retrospectives
以您自己的身分一次新增多個項目到回顧：工作區具有新模型回顧時在該回顧上新增筆記，否則在經典回顧看板上新增卡片。每個項目為 { column, text, recipient_id? }：column 是欄標題（不區分大小寫）或來自 get_retrospective 的 uid；text 最多 1000 個字元（經典看板為 255 個）；recipient_id（被感謝的隊友的使用者 uid）在新模型 kudos 欄中為必填，在經典看板上則被拒絕。新模型筆記會開始自己的主題，其他人會在筆記揭示後看到；僅在回顧開放筆記或處於 Write 階段時才能記錄筆記，否則呼叫會被拒絕並回傳代碼 wrong_stage 和目前階段。部分失敗：有效的項目會被新增，無效的項目會按索引回報 — 請檢查 "failed" 陣列。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| retrospective_id | string | 是 | 回顧 uid |
| items | array of object | 是 |
move_retro_itemPro · retrospectives
移動回顧項目：工作區具有新模型回顧時重新分組筆記，否則將經典回顧看板上的卡片移動到另一欄。新模型，僅限 Group 階段：topic_id 將筆記放入該主題（筆記群組）；column（標題或 uid）使其在該欄中成為自己的主題，位於該欄主題中的 position 位置（省略則為最後）。傳入 expected_updated_at（筆記主題的 updated_at，來自 get_retrospective），若有人同時重新分組，則會被拒絕並回傳代碼 stale。在 Group 之外，呼叫會被拒絕並回傳代碼 wrong_stage 和目前階段；kudos 和其他筆記永遠不會混合。經典看板僅接受 column 和 position（省略 position = 頂部）。需要 Pro 或試用工作區。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 筆記 uid（經典看板：項目 uid）來自 get_retrospective |
| topic_id | string | 目標主題 uid；請省略 column | |
| column | string | 目標欄標題或 uid | |
| position | integer | 目標欄中的索引（0 = 第一個） | |
| expected_updated_at | string | 上次讀取的筆記主題 updated_at（衝突檢查） |
list_project_usersread-only
列出專案的成員 — 標準專案為每個工作區成員；私人專案為建立者、工作區擁有者和管理員，以及任何明確加入的人 — 以便代理程式可以解析受指派者 uid，而不是猜測名稱。回傳每個成員的 uid、全名、電子郵件和工作區角色（owner、admin、member 或 observer）。這些 uid 是 create_card、update_card、create_epic、update_epic 和 create_roadmap_slot 中 assigned_to 所接受的值。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼 |
list_board_listsread-only
列出專案看板的清單，以便代理程式可以解析有效的 move_card 目的地。以顯示順序回傳每個作用中清單及其 uid（可作為 move_card 目標）和顯示名稱。待辦清單會以空字串 id 作為可選項目包含在內。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼（uid） |
list_epicsread-only
列出專案的史詩，以便代理程式可以解析 get_epic 和卡片指派用的史詩 uid。以顯示順序（位置遞增）回傳每個史詩及其 uid、編號、名稱、說明（Markdown）、顏色、開始/結束日期和卡片計數。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼（uid） |
| updated_since | string | 僅回傳記錄在此 ISO-8601 日期或日期時間或之後變更的史詩。注意：集合編輯（檢查清單、連結）可能不會更新史詩的變更時間；名稱/日期/說明編輯則一定會。 |
list_labelsread-only
列出專案的標籤，以便代理程式可以重用現有的分類法，而不是在卡片寫入時建立近乎重複的標籤。以顯示順序（位置遞增）回傳每個標籤及其 uid、名稱和位置。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼（uid） |
list_cards唯讀
列出某個看板清單中的卡片，若省略或傳入空的 list_id，則列出專案待辦清單（backlog）中的卡片，依看板顯示順序排列（欄位頂端優先，即放置位置遞減——與產品 UI 顯示的順序相同）。篩選條件以 AND 組合：epic_id、label_id、assigned_user_id 和 reporter_id 接受 uid（未知的 uid 不會比對到任何結果）；due_date 保留到期日早於或等於指定日期的卡片。回傳足以執行後續操作的卡片摘要（uid、標題、清單與位置、epic、標籤、指派對象、回報者、到期日），可直接用於 get_card / move_card / update_card，並以 limit（預設 50，最大 100）和 offset 分頁；total_count 為完整篩選後的總數。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼（uid） |
| list_id | string | 要讀取的清單 uid；省略或傳入空字串則讀取待辦清單 | |
| epic_id | string | 僅限所選清單或待辦清單中屬於此 epic（epic uid）的卡片；若要列出某個 epic 跨所有清單的每張卡片，請使用 get_epic | |
| label_id | string | 僅限帶有此標籤（label uid）的卡片 | |
| assigned_user_id | string | 僅限指派給此使用者（user uid）的卡片 | |
| reporter_id | string | 僅限由此使用者（user uid）回報（建立）的卡片 | |
| due_date | string | 僅限到期日早於或等於此日期（ISO-8601，例如 2026-06-10）的卡片 | |
| updated_since | string | 僅限記錄在此 ISO-8601 日期或日期時間之後變更的卡片——「自上次執行以來變更了什麼」的篩選條件。注意：對附加集合（標籤、檢查清單、連結）的編輯可能不會更新卡片的變更時間；標題/描述/純量欄位的編輯則一定會更新。 | |
| limit | integer | 頁面大小，1-100（預設 50） | |
| offset | integer | 要跳過的卡片數（預設 0） |
search_cards唯讀
在單一專案（看板與待辦清單）內依標題子字串搜尋卡片，與產品內專案即時卡片搜尋完全一致（資料庫對卡片標題進行不區分大小寫的子字串比對——不搜尋描述和留言；若要跨所有內容類型進行全文搜尋，請使用 search 工具），依建立時間新到舊排序。回傳足以執行後續操作的卡片摘要（uid、標題、清單位置 + 位置、epic、標籤、指派對象、回報者、到期日）；查詢無相符結果時回傳空的 cards 陣列，而非錯誤。以 limit（預設 50，最大 100）和 offset 分頁；total_count 為完整相符數。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼（uid） |
| query | string | 是 | 要與卡片標題比對的文字（不區分大小寫的子字串） |
| limit | integer | 頁面大小，1-100（預設 50） | |
| offset | integer | 要跳過的相符卡片數（預設 0） |
list_attention_cardsPro · metrics唯讀
列出專案看板上需要關注的卡片——與產品 Metrics 頁面的清單相同。種類：stuck（停留在某欄、非待辦清單/Done、超過 7 天未移動；卡最久者優先）、blocking（其他卡片被其阻擋的未完成卡片）、overdue（到期日在未來 7 天內或已逾期；最急者優先）。kind 選擇一個清單或 'all'（預設）。可選擇以指派對象 uid 或字面值 'unassigned' 篩選。每個要求的區段回傳可直接用於 get_card / move_card / update_card 的卡片摘要，以 limit 為上限並附完整 total_count。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼（uid） |
| kind | enum: stuck | blocking | overdue | all | 要回傳的關注清單（預設 'all' = 每個清單各自成一個區段） | |
| assignee_id | string | 僅限指派給此使用者 uid 的卡片，或 'unassigned' 表示無指派對象的卡片 | |
| limit | integer | 每個區段的最大卡片數，1-100（預設 50） |
get_metrics_summaryPro · metrics唯讀
一次呼叫取得專案看板上需要關注的卡片計數：overdue_cards_count、blocking_cards_count 和 stuck_cards_count——與 list_attention_cards 的定義相同，後者會回傳每個計數背後的卡片。此操作成本低；可先呼叫此工具來判斷是否值得深入檢視。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼（uid） |
list_roadmap_slotsPro · roadmap唯讀
列出專案路線圖中與日期視窗重疊的時段（預設：本月起至未來五個月）。一個時段在兩個日期之間排定一個 epic，並可帶有指派對象；一個 epic 可持有多個時段，包含重疊——這是設計使然。最多回傳 200 個時段——若超過上限請縮小視窗。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼 |
| start_date | string | 視窗開始，ISO-8601（YYYY-MM-DD）；預設：本月開始 | |
| end_date | string | 視窗結束，ISO-8601；預設：start_date + 6 個月 |
create_roadmap_slotPro · roadmap
在專案路線圖上排定一個 epic：一個從 start_date 到 end_date 的時段，可選擇帶有指派對象。一個 epic 可持有多個時段，且允許重疊是設計使然——若您是想延伸現有時段而非新增，請先檢查 list_roadmap_slots。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 專案的唯一識別碼 |
| epic_id | string | 是 | Epic uid（來自 list_epics）；必須屬於此專案 |
| start_date | string | 是 | ISO-8601（YYYY-MM-DD） |
| end_date | string | 是 | ISO-8601；允許與 start_date 同一天 |
| assigned_to | array of string | 要指派的使用者 uid（專案成員——請參閱 list_project_users） |
update_roadmap_slotPro · roadmap
更新路線圖時段：重新排程或調整大小（start_date/end_date）、移至同一專案的另一個 epic（epic_id），或設定其指派對象。僅變更提供的欄位，但 assigned_to 除外，它會取代完整的指派對象集合——請先讀取時段，並傳送所有應保留的使用者。時段 uid 來自 list_roadmap_slots。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 路線圖時段 uid |
| epic_id | string | 新的 epic uid（同一專案） | |
| start_date | string | ISO-8601（YYYY-MM-DD） | |
| end_date | string | ISO-8601 | |
| assigned_to | array of string | 取代所有指派對象（使用者 uid、專案成員）；[] 表示清除 |
delete_roadmap_slotPro · roadmap破壞性
永久刪除路線圖時段（及其指派對象連結）。此操作無法復原——路線圖時段沒有資源回收桶。epic 本身不受影響；若要重新排程，請優先使用 update_roadmap_slot。需要 Pro 或試用版工作區。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 路線圖時段 uid（來自 list_roadmap_slots） |
create_label
依名稱在專案上建立新標籤。若相同名稱的標籤已存在（不區分大小寫），則回傳現有標籤而不建立近似重複的標籤。新標籤會附加在顯示順序的末尾。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 標籤所屬的專案 uid |
| name | string | 是 |
create_card
在專案的看板上建立卡片。僅 project_id 和 title 為必填。省略 list_id 會將卡片放入待辦清單；省略 position 會加入佇列末尾（move_card 說明了位置契約）。description 使用 AgileHero Markup——絕非 markdown 或 HTML；請先閱讀 get_ahm_spec。epic_id 和指派對象 uid 必須已存在（list_epics、list_project_users），而尚不存在的標籤名稱會在專案上建立。estimation 是費氏數列複雜度（0/1/2/3/5/8/13），非時間估算。檢查清單、連結、附件和卡片關聯皆可在同一次呼叫中提供。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | 卡片所屬的專案 uid（卡片建立在專案的看板上） |
| list_id | string | 清單 uid；省略則放入待辦清單 | |
| position | integer | ||
| type | enum: story | bug | chore | research | ||
| title | string | 是 | |
| description | string | AgileHero Markup（AHM）——絕非 markdown 或 HTML；請先閱讀 get_ahm_spec。描述表面：不支援表格、顏色、對齊或討論。 | |
| epic_id | string | Epic uid；必須已存在於專案上 | |
| estimation | enum: 0 | 1 | 2 | 3 | 5 | 8 | 13 | 複雜度估算（故事點，費氏數列），非時間估算 | |
| due_date | string | ISO-8601 日期 | |
| assigned_to | array of string | 指派對象使用者 uid，可透過 list_project_users 查詢 | |
| labels | array of string | 標籤名稱；未知名稱會在專案上建立 | |
| checklists | array of object | 每個 { name, items: [{ description, checked }] }；items 保留提供的順序 | |
| cards_relations | array of object | 每個 { type, target_card_id（同一看板上的卡片 uid） } | |
| links | array of object | 每個 { url, description } | |
| attachments | array of object | 每個 { url, name }；檔案會從 url 擷取 |
update_card破壞性
依 uid 更新現有卡片。對於集合，請優先使用 add_*/remove_* 增量欄位（安全的小幅編輯：add_labels、remove_assignees、add_checklist_items、check_items 等）；純集合欄位（labels、assigned_to、checklists、cards_relations、links、attachments）會破壞性取代先前的狀態，且無法與其增量欄位合併使用。請使用 move_card 變更清單或位置，並使用 preview_description_update / update_description 編輯描述。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 卡片 uid |
| type | enum: story | bug | chore | research | ||
| title | string | ||
| epic_id | string | ||
| estimation | enum: 0 | 1 | 2 | 3 | 5 | 8 | 13 | 以故事點表示的複雜度估算（費氏數列），非時間估算 | |
| due_date | string | ISO-8601 日期 | |
| assigned_to | array of string | 指派對象的使用者 uid，可透過 list_project_users 查詢；取代卡片目前的指派對象 | |
| labels | array of string | 標籤名稱；未知名稱會在專案中建立；取代卡片目前的標籤 | |
| checklists | array of object | 每個 { name, items: [{ description, checked }] }；項目維持提供的順序；取代卡片目前的核對清單 | |
| cards_relations | array of object | 每個 { type, target_card_id（同一看板上的卡片 uid）}；取代卡片目前的關聯 | |
| links | array of object | 每個 { url, description }；取代卡片目前的連結 | |
| attachments | array of object | 每個 { url, name }；檔案會從 url 取得；取代卡片目前的附件 | |
| add_labels | array of string | 依名稱新增標籤（未知名稱會建立）；保留既有標籤 | |
| remove_labels | array of string | 依名稱移除標籤（不分大小寫）；不存在的名稱不執行任何動作 | |
| add_assignees | array of string | 依使用者 uid 新增指派對象；保留既有指派對象 | |
| remove_assignees | array of string | 依使用者 uid 移除指派對象；不存在的 uid 不執行任何動作 | |
| add_checklist_items | array of object | 附加項目：每個 { checklist, description, checked? } — 若指定的核對清單不存在則建立 | |
| check_items | array of object | 在指定的核對清單中，依確切描述比對並將項目標記為已完成 | |
| uncheck_items | array of object | 將項目標記為未完成（比對方式與 check_items 相同） | |
| remove_checklist_items | array of object | 刪除項目；不存在的項目不執行任何動作 | |
| add_relations | array of object | 新增關聯；保留既有關聯 | |
| remove_relations | array of object | 移除相符的關聯；不存在的關聯不執行任何動作 | |
| add_links | array of object | 新增連結：每個 { url, description? }；保留既有連結 | |
| remove_links | array of string | 依確切 url 移除連結；不存在的 url 不執行任何動作 |
delete_carddestructive
依卡片 uid 軟刪除卡片：卡片會從看板及所有列表中移除，與其他卡片的關聯會被刪除，任何相關的估算工作階段會停用，且連結到該卡片的白板元素會解除連結。其所屬的 epic 不會被刪除。MCP 不提供取消刪除的功能。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 卡片 uid |
move_card
將卡片移至不同列表（或變更其在同一列表中的位置）。只有看板（kanban）上的卡片可以移動；回顧（retrospective）看板上的卡片會被拒絕。將 list_id 傳入空字串可將卡片移至看板的待辦（backlog）區。列表從最高位置由上而下顯示，因此位置 0 是列表的底部。省略 position 時，在待辦區及 to_do、in_progress 列表中會加入佇列尾端（底部，位置 0），在 done 列表中則加入頂端。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 卡片 uid |
| list_id | string | 是 | 目標列表 uid；空字串表示移至待辦區（僅限看板） |
| position | integer | 在目標中的位置：0 是底部，最高位置是頂端。必須介於 0 與目標中既有其他卡片的數量之間。省略時，在待辦區及 to_do、in_progress 列表中會加入佇列尾端（位置 0），在 done 列表中則加入頂端。 |
create_epic
在專案上建立 epic。只有 project_id 和 name 為必填。description 使用 AgileHero Markup — 絕非 markdown 或 HTML；請先閱讀 get_ahm_spec。指派對象 uid 來自 list_project_users。核對清單、連結和附件可在同一次呼叫中提供。回傳新的 epic uid — 即 create_card / update_card 所接受的 epic_id，也是 create_roadmap_slot 排程的對象。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| project_id | string | 是 | epic 所屬的專案 uid |
| name | string | 是 | |
| description | string | AgileHero Markup（AHM）— 絕非 markdown 或 HTML；請先閱讀 get_ahm_spec。描述介面：不支援表格、顏色、對齊或討論。 | |
| color | string | 十六進位顏色，例如 #0060F0 | |
| start_date | string | ISO-8601 日期 | |
| end_date | string | ISO-8601 日期 | |
| assigned_to | array of string | 指派對象的使用者 uid，可透過 list_project_users 查詢 | |
| checklists | array of object | 每個 { name, items: [{ description, checked }] }；項目維持提供的順序 | |
| links | array of object | 每個 { url, description } | |
| attachments | array of object | 每個 { url, name }；檔案會從 url 取得 |
update_epicdestructive
依 epic uid 更新既有 epic；只會變更提供的欄位。對於集合欄位，建議優先使用 add_*/remove_* 增量欄位（安全的部分編輯）；一般集合欄位（assigned_to、checklists、links、attachments）會以破壞性方式取代先前的狀態，且不能與其增量欄位合併使用。請使用 preview_description_update / update_description 編輯描述。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | Epic uid |
| name | string | ||
| color | string | 十六進位顏色，例如 #0060F0 | |
| start_date | string | ISO-8601 日期 | |
| end_date | string | ISO-8601 日期 | |
| assigned_to | array of string | 指派對象的使用者 uid，可透過 list_project_users 查詢；取代 epic 目前的指派對象 | |
| checklists | array of object | 每個 { name, items: [{ description, checked }] }；取代 epic 目前的核對清單 | |
| links | array of object | 每個 { url, description }；取代 epic 目前的連結 | |
| attachments | array of object | 每個 { url, name }；檔案會從 url 取得；取代 epic 目前的附件 | |
| add_assignees | array of string | 依使用者 uid 新增指派對象；保留既有指派對象 | |
| remove_assignees | array of string | 依使用者 uid 移除指派對象；不存在的 uid 不執行任何動作 | |
| add_checklist_items | array of object | 附加項目：每個 { checklist, description, checked? } — 若指定的核對清單不存在則建立 | |
| check_items | array of object | 在指定的核對清單中，依確切描述比對並將項目標記為已完成 | |
| uncheck_items | array of object | 將項目標記為未完成（比對方式與 check_items 相同） | |
| remove_checklist_items | array of object | 刪除項目；不存在的項目不執行任何動作 | |
| add_links | array of object | 新增連結：每個 { url, description? }；保留既有連結 | |
| remove_links | array of string | 依確切 url 移除連結；不存在的 url 不執行任何動作 |
delete_epicdestructive
依 epic uid 軟刪除 epic。其卡片不會被刪除 — 它們會留在看板上，但與 epic 脫離關聯。epic 的路徑圖時段（roadmap slots）會被永久刪除（時段是用來排程 epic 的，沒有 epic 就沒有意義），且連結到該 epic 的白板元素會解除連結。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | Epic uid |
create_comment
在卡片或 epic 上新增留言。請只提供 card_id 或 epic_id 其中一個。內容使用 AgileHero Markup（AHM，留言介面：不支援表格、媒體、顏色、對齊或討論）— 絕非 markdown 或 HTML；請先閱讀 get_ahm_spec。留言會歸屬於此用戶端所代表的已登入使用者，並會出現在後續的 get_card / get_epic 回應中。留言無法透過 MCP 編輯；delete_comment 可刪除您自己的留言（修正錯誤的方式是刪除後重新張貼）。傳入 parent_comment_id 可回覆既有留言。討論串只有一層深度：回覆一則回覆時，新留言會附加到該回覆的討論串根節點，因此請勿嘗試巢狀回覆。父留言必須位於同一張卡片或同一個 epic 上 — 來自其他位置的 uid 會被拒絕。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| card_id | string | 要留言的卡片 uid（與 epic_id 互斥） | |
| epic_id | string | 要留言的 epic uid（與 card_id 互斥） | |
| content | string | 是 | 以 AgileHero Markup（AHM）撰寫的留言內容 |
| parent_comment_id | string | 可選，同一張卡片或同一個 epic 上某則留言的 uid，用於回覆。省略則為頂層留言。回覆一則回覆時，會正規化到該回覆的討論串根節點（討論串只有一層深度）。 |
delete_commentdestructive
刪除您自己張貼的留言（留言會歸屬於此用戶端所代表的已登入使用者 — 無法刪除他人的留言）。修正模式是刪除後再用 create_comment 張貼修正後的留言。已刪除但仍有回覆的留言會以墓碑形式保留在討論串中。留言 uid 來自 get_card / get_epic。
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| id | string | 是 | 留言 uid |