Z-BlogPHP MCP 接口插件（ZbpMcp）v1.0.0

原创

alex 42分钟前阅读数 2 #大杂烩

提供标准 MCP（Model Context Protocol）接口，让支持 MCP 的 AI 工具直连博客，

实现对文章、分类、标签、媒体、评论等内容的直接接入。

插件内置 ApiKey 管理、权限控制、请求日志、客户端配置示例和快速接入说明。

可为不同 AI 工具创建独立 ApiKey，按需分配各模块权限，安全便捷。

一、共 18 个工具（五大模块）

文章管理（3 个）

zblog_list_articles 获取文章列表，支持按分类/作者/关键词筛选和分页

zblog_get_article 根据文章 ID 获取单篇文章完整内容

zblog_write_article 创建新文章或更新已有文章（支持 HTML 内容、摘要、标签、别名等）

分类管理（2 个）

zblog_list_categories 获取所有文章分类列表

zblog_create_category 创建新的文章分类（支持别名、父分类、模板）

标签管理（4 个）

zblog_list_tags 查询标签列表及文章使用数量

zblog_get_tag 读取单个标签详情（按 ID 或名称）

zblog_save_tag 创建或更新标签

zblog_delete_tag 删除标签

媒体管理（4 个）

zblog_list_media 查询媒体文件和附件列表

zblog_get_media 读取单个媒体文件详情和访问地址

zblog_upload_media 通过 Base64 上传图片或附件

zblog_delete_media 删除媒体记录及对应文件

评论管理（5 个）

zblog_list_comments 查询评论及审核状态

zblog_get_comment 读取单条评论详情

zblog_create_comment 为文章创建评论或回复（默认进入审核状态）

zblog_review_comment 切换评论的审核状态

zblog_delete_comment 删除评论及其子评论

二、快速开始

在 Z-BlogPHP 后台 -> 插件管理中启用本插件；
进入后台左侧" MCP 接口"菜单；
在"ApiKey 管理"页创建 ApiKey（权限默认全选，可取消勾选后保存）；
点击"复制客户端配置"得到 JSON，或按下方示例手动配置；
在 AI 客户端（Claude Code / Claw / Cline / Cherry Studio 等支持 HTTP transport 的
MCP 客户端）中粘贴配置，重启客户端即可使用 18 个 zblog_* 工具。

注意：插件安装后会在 zb_users/plugin/ZbpMcp/ 下生成随机目录作为 MCP 端点，

实际地址请在后台 “MCP 接口 -> 接入说明” 页查看（每次安装随机，防扫描器直接命中）。

端点地址形如：{bloghost}zb_users/plugin/ZbpMcp/{随机目录}/server.php

认证方式：HTTP 头 Authorization: Bearer

标准客户端配置示例：

{

"mcpServers": {

  "zblog": {

    "type": "http",

    "url": "https://你的域名/{MCP端点}",

    "headers": {

      "Authorization": "Bearer 你的ApiKey"

    }

  }

}

}

Claude Code 命令行接入：

claude mcp add --transport http zblog \

https://你的域名/{MCP端点} \

--header "Authorization: Bearer 你的ApiKey"

三、接口自测（curl）

握手

curl -X POST “https://你的域名/{MCP端点}” \

-H "Authorization: Bearer 你的ApiKey" -H "Content-Type: application/json" \

-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

列出工具

curl -X POST “https://你的域名/{MCP端点}” \

-H "Authorization: Bearer 你的ApiKey" -H "Content-Type: application/json" \

-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

调用工具

curl -X POST “https://你的域名/{MCP端点}” \

-H "Authorization: Bearer 你的ApiKey" -H "Content-Type: application/json" \

-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"zblog_list_articles","arguments":{"page":1,"per_page":5}}}'

四、接口配置说明

文章默认写入状态可在"接口设置"中配置（默认审核中），避免 AI 直接发布误操作；
每个 ApiKey 独立权限：文章读取 / 文章写入 / 分类管理 / 标签管理 / 媒体管理 / 评论管理；
"请求日志"页记录每次 MCP 调用（时间、ApiKey、方法、工具、状态、耗时），支持详情与清空；
日志默认保留 1000 条，可在接口设置中调整上限；
禁用 ApiKey 后立即拒绝所有请求（无需删除）；
MCP 模式无登录会话，写操作归属"接口设置"中配置的默认操作用户（默认管理员 ID 1）。

五、技能配置建议

在 AI 客户端中为 MCP 补充技能说明可获得更好效果：

写文章：标题必填、内容支持 HTML；未指定状态时按站点设置进入"审核中"，不会直接发布；
标签：zblog_save_tag 创建或更新，重名会报错；文章标签参数为逗号分隔的名称；
媒体：zblog_upload_media 接收 Base64（不含 data: 前缀），文件名需含合法扩展名；
评论：新评论默认进入审核状态，zblog_review_comment 切换审核；
删除操作不可恢复，重要删除前先查询详情确认。

六、安全说明

ApiKey 以明文存储于系统 Config 表（后台需回显复制完整密钥），数据库/备份泄露即密钥泄露；
建议定期轮换密钥，并仅向可信 AI 客户端授予必要权限；
权限粒度为模块级（读取/写入合并，删除/发布与写入同权限）：持有 media 权限即可删除任意媒体，
article_write 可按 ID 改写任意文章并直接发布（显式传 status=0）。请勿向不可信方授予写权限；
文章/评论内容按原始 HTML 存储（与后台编辑器一致，等同管理员能力）。
警惕 AI 被网页内容 prompt-injection 诱导写入恶意内容，勿向不可信 AI 授予写权限；
MCP 端点建议部署于 HTTPS 与 WAF/CDN 之后；端点内置认证失败 IP 限流（60 秒内 10 次），
但无全局速率限制，请依据部署环境自行加固；
private(4)/password(8) 状态文章不通过 MCP 读取；上传禁止 svg/html 等可含脚本的类型，
图片类校验文件头魔数（jpg/png/gif/bmp/webp）；
请求日志记录 ApiKey 名称、方法、工具、状态与耗时，不含密钥明文；日志条数受上限裁剪，
单条消息长度受限；
并发说明：ApiKey/日志存储于 Config 表（整表序列化读改写），高并发调用下存在丢失最近写入
（last_used 更新、日志条目）的理论竞争窗口，属设计取舍。

七、自动化测试

插件附带无依赖的轻量测试套件（不需要 Composer / PHPUnit），覆盖

PHP 7.0+ 兼容性、Schema、ApiKey、日志、安全边界、工具行为、HTTP 协议：

运行全部测试（需要本地数据库连接，配置位于 zb_users/c_option.php）

php zb_users/plugin/ZbpMcp/tests/run.php

按关键字过滤（文件名或函数名包含匹配）

php zb_users/plugin/ZbpMcp/tests/run.php --filter=security

跳过 HTTP 协议测试（不启动 php -S）

php zb_users/plugin/ZbpMcp/tests/run.php --no-http

测试约 46 项，运行完成后自动清理创建的测试数据（文章/分类/标签/评论/上传/ApiKey）。

八、分发包构建

插件遵循 Z-BlogPHP 应用打包规范，可生成 .zba 分发包（gzip 压缩的 App XML），

通过后台"应用中心(AppCentre)"上传安装，或解包后手动放入 zb_users/plugin/ 目录。

构建 .zba（输出到项目根 ZbpMcp_{version}_{modified}.zba）

php zb_users/plugin/ZbpMcp/tests/build_zba.php

构建产物已排除 tests/ 与开发文件，仅含运行所需 12 个文件。

安装流程已验证：App::UnPack() 解包 → LoadApp 加载 → 兼容性检查通过

（adapted=170000 即 Z-BlogPHP 1.7.0 起、phpver=7.0）→ 59 项测试全过。

环境与兼容

兼容 Z-BlogPHP 1.7.0 及以上版本（adapted=170000，1.7.0+ 均可安装），要求 PHP 7.0 及以上
（已在 PHP 7.4 / 8.2 实测，语法基线为 PHP 5.4+，零 7.1+/7.4+/8.x 独占语法，跨版本无差异）；
密钥生成优先 random_bytes（PHP 7.0+），低版本自动降级 openssl_random_pseudo_bytes；
字符串比较优先 hash_equals（PHP 5.6+），低版本自动降级恒定时间比较；
不创建数据表，ApiKey 与日志均存储于系统 Config 表；
MCP 协议实现：Streamable HTTP 传输（JSON-RPC 2.0），兼容 MCP 1.x 与 2.x，
支持协议版本 2026-07-28 (2.0) / 2025-11-25 / 2025-06-18 / 2025-03-26 / 2024-11-05，
启动时按客户端声明自动

下载地址：https://pan.quark.cn/s/587c6b5c1483