MCP 伺服器參考

EmDash 內建一個 Model Context Protocol（MCP）伺服器，位於 /_emdash/api/mcp，將內容管理操作以工具形式公開給 AI 助手使用。

本頁涵蓋通訊協定詳情：驗證、傳輸、工具規格、OAuth 探索與錯誤處理。

驗證

MCP 伺服器支援三種驗證方式：

工作階段 cookie（來自管理 UI）也可使用，但對外部 MCP 用戶端不太實用。

Scope

權杖使用 scope 來限制用戶端可執行的操作。Scope 在 OAuth 授權期間請求，並在每次工具呼叫時強制執行。

admin scope 授予所有操作的存取權。基於工作階段的驗證（無權杖）也擁有基於使用者角色的完整存取權。

角色要求

除了 scope 之外，部分工具需要最低 RBAC 角色：

角色定義見驗證指南。

傳輸

伺服器使用無狀態模式的 Streamable HTTP 傳輸。每個請求都是獨立的——沒有工作階段或長連線。

• POST /_emdash/api/mcp — 傳送 JSON-RPC 工具呼叫
• GET /_emdash/api/mcp — 回傳 405（無狀態模式下無 SSE）
• DELETE /_emdash/api/mcp — 回傳 405（無工作階段可關閉）

回應遵循 JSON-RPC 2.0 格式。錯誤使用標準 JSON-RPC 錯誤碼，並以 MCP 特定碼表示 scope 與權限失敗。

工具

伺服器公開 33 個工具，涵蓋七個領域。每個工具以 JSON 文字內容回傳結果，失敗時則回傳帶有 isError: true 的錯誤訊息。

內容工具

content_list

列出集合中的內容項目，支援選用的篩選與分頁。

Scope： content:read | 唯讀： 是

content_get

透過 ID 或 slug 取得單一內容項目。回傳所有欄位值、中繼資料和用於樂觀並行控制的 _rev 權杖。

Scope： content:read | 唯讀： 是

content_create

建立新的內容項目。data 物件應包含符合集合 schema 的欄位值——使用 schema_get_collection 檢查可用欄位。項目預設以 draft 狀態建立。

Scope： content:write

content_update

更新現有內容項目。僅包含你要變更的欄位——未指定的欄位保持不變。

Scope： content:write

content_delete

透過移至回收桶來軟刪除內容項目。使用 content_restore 復原，或使用 content_permanent_delete 永久移除。

Scope： content:write | 破壞性： 是

content_restore

從回收桶還原軟刪除的內容項目。

Scope： content:write

content_permanent_delete

永久且不可逆地刪除已移至回收桶的內容項目。項目必須先在回收桶中。

Scope： content:write | 破壞性： 是

content_publish

發布內容項目，使其在網站上線。從目前草稿建立已發布的修訂版。後續編輯會建立新草稿，不影響線上版本，直到重新發布為止。

Scope： content:write

content_unpublish

將已發布的項目恢復為草稿狀態。它將不再在線上網站中顯示，但內容會保留。

Scope： content:write

content_schedule

排程內容項目在未來發布。它將在指定的日期/時間自動發布。

Scope： content:write

content_compare

比較內容項目的已發布（線上）版本與目前草稿。回傳兩個版本以及指示是否有變更的旗標。

Scope： content:read | 唯讀： 是

content_discard_draft

捨棄目前草稿並恢復到最後發布的版本。僅適用於至少發布過一次的項目。

Scope： content:write | 破壞性： 是

content_list_trashed

列出集合回收桶中已軟刪除的內容項目。

Scope： content:read | 唯讀： 是

content_duplicate

建立現有內容項目的副本。副本以草稿建立，標題附加「(Copy)」，slug 自動產生。

Scope： content:write

content_translations

取得內容項目的所有語系變體。回傳翻譯群組和每個語系版本的摘要。僅在啟用 i18n 時相關。

Scope： content:read | 唯讀： 是

Schema 工具

schema_list_collections

列出 CMS 中定義的所有內容集合。回傳 slug、標籤、支援的功能和時間戳記。

無參數。

Scope： schema:read | 最低角色： 編輯 | 唯讀： 是

schema_get_collection

取得集合的詳細資訊，包括所有欄位定義。欄位描述資料模型：名稱、類型、約束和驗證規則。使用此工具了解 content_create 和 content_update 預期的內容。

Scope： schema:read | 最低角色： 編輯 | 唯讀： 是

schema_create_collection

建立新的內容集合。這會建立資料庫表和 schema 定義。slug 必須是以字母開頭的小寫英數字加底線。

Scope： schema:write | 最低角色： 管理員

schema_delete_collection

刪除集合及其資料庫表。此操作不可逆，會刪除集合中的所有內容。

Scope： schema:write | 最低角色： 管理員 | 破壞性： 是

schema_create_field

在集合的 schema 中新增欄位。這會在資料庫表中新增一個欄。

欄位類型：string、text、number、integer、boolean、datetime、select、multiSelect、portableText、image、file、reference、json、slug。

對於 select 和 multiSelect 類型，在 validation.options 中提供允許的值。

Scope： schema:write | 最低角色： 管理員

schema_delete_field

從集合中移除欄位。這會刪除該欄位中的欄和所有資料。不可逆。

Scope： schema:write | 最低角色： 管理員 | 破壞性： 是

媒體工具

media_list

列出已上傳的媒體檔案，支援選用的 MIME 類型篩選與分頁。

Scope： media:read | 唯讀： 是

media_get

透過 ID 取得單一媒體檔案的詳情。回傳包括檔名、MIME 類型、大小、尺寸、替代文字和 URL 的中繼資料。

Scope： media:read | 唯讀： 是

media_update

更新已上傳媒體檔案的中繼資料。檔案本身無法變更。

Scope： media:write

media_delete

永久刪除媒體檔案。移除資料庫記錄和儲存中的檔案。參照此媒體的內容會出現斷裂參照。

Scope： media:write | 破壞性： 是

搜尋工具

search

跨內容集合的全文搜尋。集合必須在 supports 列表中包含 search，且欄位必須標記為 searchable。

Scope： content:read | 唯讀： 是

分類法工具

taxonomy_list

列出所有分類法定義（例如分類、標籤）。回傳名稱、標籤、是否階層式，以及關聯的集合。

無參數。

Scope： content:read | 唯讀： 是

taxonomy_list_terms

列出分類法中的詞彙，支援分頁。

Scope： content:read | 唯讀： 是

taxonomy_create_term

在分類法中建立新詞彙。對於階層式分類法，指定 parentId 以建立子詞彙。

Scope： content:write

選單工具

menu_list

列出所有導覽選單。回傳名稱、標籤和時間戳記。

無參數。

Scope： content:read | 唯讀： 是

menu_get

透過名稱取得選單，包含所有項目的順序。項目具有標籤、URL、類型和選用的父項以進行巢狀。

Scope： content:read | 唯讀： 是

修訂工具

revision_list

列出內容項目的修訂歷史記錄，最新在前。集合必須支援 revisions。

Scope： content:read | 唯讀： 是

revision_restore

將內容項目還原到先前的修訂版。用指定修訂版的資料取代目前草稿。不會自動發布——如需要請在之後使用 content_publish。

Scope： content:write

OAuth 探索

支援 OAuth 2.1 的 MCP 用戶端可以自動探索驗證方式。伺服器發布兩份中繼資料文件：

受保護資源中繼資料

GET /.well-known/oauth-protected-resource

{
  "resource": "https://example.com/_emdash/api/mcp",
  "authorization_servers": ["https://example.com/_emdash"],
  "scopes_supported": [
    "content:read", "content:write",
    "media:read", "media:write",
    "schema:read", "schema:write",
    "admin"
  ],
  "bearer_methods_supported": ["header"]
}

授權伺服器中繼資料

GET /_emdash/.well-known/oauth-authorization-server

{
  "issuer": "https://example.com/_emdash",
  "authorization_endpoint": "https://example.com/_emdash/oauth/authorize",
  "token_endpoint": "https://example.com/_emdash/api/oauth/token",
  "scopes_supported": ["content:read", "content:write", "..."],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "device_authorization_endpoint": "https://example.com/_emdash/api/oauth/device/code"
}

當未驗證的請求到達 MCP 端點時，伺服器回傳：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"

這會觸發標準的 MCP 用戶端探索流程。

錯誤處理

工具錯誤以帶有 isError: true 的文字內容回傳：

{
  "content": [{ "type": "text", "text": "Collection 'nonexistent' not found" }],
  "isError": true
}

Scope 與權限錯誤會拋出 MCP 通訊協定錯誤：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Insufficient scope: requires content:write"
  },
  "id": 1
}

傳輸層錯誤（伺服器設定錯誤、未處理的例外）回傳 JSON-RPC 錯誤碼 -32603（內部錯誤），不會洩漏實作細節。