MCP 伺服器參考 | EmDash CMS Everything

EmDash 在 /_emdash/api/mcp 包含一個內建的 Model Context Protocol（MCP）伺服器，將內容管理操作作為 AI 助手的工具暴露。

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

認證

MCP 伺服器支援三種認證方法：

方法	運作方式
OAuth 2.1 Authorization Code + PKCE	MCP 用戶端的標準流程。使用者在瀏覽器中批准範圍。
Personal Access Token（PAT）	在管理面板中建立的長期有效 `ec_pat_*` 權杖。
Device Flow	在瀏覽器中批准代碼的 CLI 風格流程。由 `emdash login` 使用。

範圍

範圍	授予存取權限
`content:read`	列出、取得、比較和搜尋內容。列出分類法、術語和選單。
`content:write`	建立、更新、刪除、發佈、取消發佈、排程、取消排程、複製和還原內容。隱含授予 `taxonomies:manage` 和 `menus:manage`。
`media:read`	列出和取得媒體項目。
`media:write`	註冊（建立）、更新和刪除媒體中繼資料。
`schema:read`	列出集合和取得集合結構描述。
`schema:write`	建立和刪除集合及欄位。
`taxonomies:manage`	建立、更新和刪除分類術語。
`menus:manage`	建立、更新和刪除導覽選單及其項目。
`settings:read`	讀取網站設定。
`settings:manage`	更新網站設定。
`mcp:tools`	呼叫任何外掛中明確啟用的 MCP 工具。
`mcp:tools:<pluginId>`	呼叫特定外掛中明確啟用的 MCP 工具。
`admin`	所有操作的完整存取權限。

角色要求

操作	最低角色
內容讀取	Subscriber（10）已發佈項目; Contributor（20）草稿、已排程、資源回收筒、修訂版
內容建立	Contributor（20）
編輯/刪除自己的	Author（30）
內容發佈	Author（30）自己的; Editor（40）他人的
結構描述讀取	Editor（40）
結構描述寫入	Admin（50）
分類管理	Editor（40）
選單管理	Editor（40）
設定讀取	Editor（40）
設定管理	Admin（50）
媒體上傳（`media_upload`）	Contributor（20）
媒體註冊（`media_create`）	Author（30）
媒體使用修復	Admin（50）

參閱認證指南了解角色定義。

傳輸

伺服器使用無狀態模式的 Streamable HTTP 傳輸。每個請求都是獨立的。

POST /_emdash/api/mcp — 傳送 JSON-RPC 工具呼叫
GET /_emdash/api/mcp — 回傳 405
DELETE /_emdash/api/mcp — 回傳 405

工具

伺服器在八個領域暴露工具：內容、結構描述、媒體、搜尋、分類法、選單、修訂版和設定。

內容工具

content_list、content_get、content_create、content_update、content_delete、content_restore、content_permanent_delete、content_publish、content_unpublish、content_schedule、content_unschedule、content_compare、content_discard_draft、content_list_trashed、content_duplicate、content_translations

結構描述工具

schema_list_collections、schema_get_collection、schema_create_collection、schema_delete_collection、schema_create_field、schema_delete_field

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

媒體工具

media_list、media_upload、media_create、media_get、media_update、media_delete、media_usage_repair

搜尋工具

`search`

跨內容集合的全文搜尋。

參數	類型	必要	描述
`query`	`string`	是	搜尋查詢文字
`collections`	`string[]`	否	限制到特定集合
`locale`	`string`	否	按地區設定篩選
`limit`	`integer`	否	最大結果數（1-50，預設 20）

範圍： content:read | 唯讀： 是

分類工具

taxonomy_list、taxonomy_list_terms、taxonomy_create_term、taxonomy_update_term、taxonomy_delete_term

選單工具

menu_list、menu_get、menu_create、menu_update、menu_delete、menu_set_items

修訂版工具

revision_list、revision_restore

設定工具

settings_get、settings_update

OAuth 探索

受保護資源中繼資料

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",
    "taxonomies:manage", "menus:manage",
    "settings:read", "settings:manage",
    "admin"
  ],
  "bearer_methods_supported": ["header"]
}

授權伺服器中繼資料

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

{
  "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"
}

錯誤處理

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

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

{
  "content": [
    { "type": "text", "text": "[INSUFFICIENT_SCOPE] Insufficient scope: requires content:write" }
  ],
  "isError": true,
  "_meta": { "code": "INSUFFICIENT_SCOPE" }
}

傳輸層錯誤回傳 JSON-RPC 錯誤代碼 -32603（內部錯誤），不洩漏實作細節。