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（内部错误），不泄露实现细节。