MCP 接入插件

为 AI Agent 提供 MCP（Model Context Protocol）协议接入，让 AI 能自主理解你的网站结构并操作内容。

什么是 MCP

MCP 是一种标准协议，让 AI Agent（如 Claude、Cursor、CodeArts 等）能连接到外部系统并自主操作。

本插件让你的 1CMS 站点变成一个 MCP Server，AI 连接后可以：

• 看懂你的网站结构（有哪些栏目、每个栏目有哪些字段）
• 发布、修改、删除文章
• 读取栏目配置
• 上传文件（图片等）

快速开始

1. 确保已安装本插件

在 1CMS 后台 → 应用管理 → 找到「MCP接入」→ 确认已安装并启用。

2. 获取 API token

在 后台 → 用户管理 → 选择一个有管理员权限的用户 → 生成 API token。

3. 配置你的 IDE / AI 工具

在 IDE 的 MCP 配置文件中添加：

CodeArts / Cursor（.codeartsdoer/mcp/mcp_settings.json）：

{
  "mcpServers": {
    "1cms-mcp": {
      "url": "http://你的域名/api_你的API路径/mcp:endpoint",
      "headers": {
        "token": "你的token"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "1cms-mcp": {
      "type": "url",
      "url": "http://你的域名/api_你的API路径/mcp:endpoint",
      "headers": {
        "token": "你的token"
      }
    }
  }
}

不知道 URL？ 登录 1CMS 后台 → 点击左侧菜单「MCP接入」→ 引导页面会显示完整的 URL 和可复制的配置。

4. 开始对话

配置好后，直接对 AI 说：

"帮我看看网站有哪些栏目"

AI 会自动调用 get_schema 获取网站结构，然后告诉你结果。

可用工具

AI 连接后可以使用以下工具（基础 10 个 + 草稿箱 3 个）：

基础工具（10 个）

草稿箱工具（3 个，需安装草稿箱插件）

使用流程

第1步：get_schema → 了解网站全貌（栏目树、字段定义）
         ↓
第2步：get_channel_fields → 查看目标栏目要传哪些字段
         ↓
第3步：publish_article / update_article / delete_article → 操作内容

草稿箱流程

存草稿：publish_article 传 draft=true → 文章存入草稿箱（不直接发布）
         ↓
查看草稿：list_drafts → 列出所有草稿
         ↓
发布草稿：publish_draft → 草稿转为正式文章（草稿自动删除）
         ↓
（或）删除草稿：delete_draft → 丢弃不需要的草稿

提示： publish_draft 支持 enable 参数。传 enable="1" 发布后文章直接启用；不传则发布后文章为禁用状态（与 1CMS 官方行为一致）。

示例对话

用户： 帮我看看网站有哪些栏目 AI： （调用 get_schema）→ "你的网站有 Home、Products、News、FAQ 等栏目..."

用户： 在 News 栏目发一篇文章，标题"AI改变世界"，内容写一段介绍 AI： （调用 get_channel_fields 了解字段 → 调用 publish_article）→ "发布成功，文章 id=123"

用户： 把刚才那篇标题改成"AI赋能未来" AI： （调用 list_articles 找到文章 → 调用 update_article）→ "修改成功"

用户： 先存一篇草稿，标题"新品预告"，内容先不公开 AI： （调用 publish_article 传 draft=true）→ "已存为草稿，draft_id=5"

用户： 看看草稿箱里有什么 AI： （调用 list_drafts）→ "草稿箱有 1 篇：新品预告（draft_id=5）"

用户： 把那篇草稿发布了吧 AI： （调用 publish_draft 传 draft_id=5, enable="1"）→ "发布成功，文章 id=124，草稿已自动删除"

技术细节

传输模式

本插件使用 Streamable HTTP 模式（MCP 规范推荐）：

• POST → 同步返回 JSON-RPC 响应（Content-Type: application/json）
• GET → 返回 405（不支持 SSE 推送流）
• DELETE → 返回 200（无状态，直接确认）
• 支持单条请求和批量请求
• 通知（无 id 的请求）返回 202 无响应体

无状态设计

每个请求独立处理，不维护会话状态。这意味着：

• 不需要 session 存储
• 不会因 PHP-CGI worker 耗尽而卡住
• 支持并发请求

文件结构

app/mcp/
├── mcp.config          插件配置
├── mcp.php             主类（HTTP端点、JSON-RPC处理、引导页、上传端点、共享辅助方法）
├── tools.php           工具定义 + 站点结构查询（schema/channels/channelFields/uploadEndpoint）
├── article.php         文章CRUD（list/get/publish/update/delete + draft模式）
├── config.php          栏目配置查询
├── value.php           字段值准备器（处理 datetime/switch/tags/flexible 等特殊格式）
├── draft.php           草稿箱操作（list/publish/delete + 可用性检测）
├── README.md           本文档
└── template/
    └── index.php       引导页面（后台菜单进入）

子类调用机制

1CMS 的多文件插件机制：

• 主类 mcp 在 mcp.php，子类 mcp_tools 在 tools.php，以此类推
• 主类通过 C('this:tools:schema') 调用子类方法（this 自动解析为当前插件 hash）
• 共享辅助方法（param、getChannel、getChannelFields）放在主类，子类通过 C('this:param', ...) 调用
• 字段值准备器 mcp_value 在 value.php，处理 datetime/switch/tags/flexible 等特殊格式，article.php 通过 C('this:value:typeDatetime', ...) 调用
• 草稿箱操作 mcp_draft 在 draft.php，提供草稿列表/发布/删除，article.php 通过 C('this:draft:maxId') 等调用

常见问题

Q: AI 连接不上怎么办？

1. 检查 URL 是否正确（格式：http://域名/api_路径/mcp:endpoint）
2. 检查 token 是否有效且有管理员权限
3. 检查 API 插件是否已安装启用
4. 在后台「MCP接入」引导页面查看完整的 URL 和配置

Q: AI 能发布文章但不能修改/删除？

token 对应的用户权限不足。请在用户管理中确保该用户有管理员角色。

Q: 草稿箱工具不显示？

草稿箱工具（list_drafts、publish_draft、delete_draft）需要安装「草稿箱」插件才会出现。在后台 → 应用管理 → 确认 articledrafts 和 articledraftspublish 两个插件已安装并启用。未安装时 tools/list 只返回 10 个基础工具，安装后自动变为 13 个。

Q: publish_article 传 draft=true 后提示"增加失败"但草稿实际已存？

这是 1CMS 官方钩子机制与 editSave 的交互问题：钩子拦截了 add 操作并存入草稿，但 editSave 收到钩子返回值后误报失败。草稿实际已成功保存，用 list_drafts 可以看到。MCP 插件已内部处理此问题，返回正确的 draft_id。

Q: 支持哪些 IDE？

任何支持 MCP Streamable HTTP 模式的客户端：

• 豆包工作模式
• 各种编程IDE
• workbuddy
• Cursor
• Claude Desktop
• 其他 MCP 兼容工具