插件质量报告

插件：mcp_server

颜色说明：黄色表示有数据读写，红色表示 Hook 在系统循环中执行，浅蓝色表示有文件写入。“列表跳过”表示回调在列表路径会提前返回，“回调内”表示操作位于回调自身或其帮助函数的循环体内。“文件批处理”表示逐个处理用户一次提交的文件，属于必要操作，不标记修正。只有操作实际处于需要优化的循环路径时，才会标记“修正❗️”。

数据字典

未检测到插件数据表声明。

MCP Server 插件

1. 生成 Token

点击上方按钮并保存下载文件；重新生成后旧 Token 失效。

2. 启用服务

填写操作账号和版块范围，勾选“启用 MCP”；需要 AI 回帖时再开启写入权限。

3. 配置 Codex

将下面内容加入 ~/.codex/config.toml，替换 Token 后重新连接。

[mcp_servers.bbs1org]
type = "http"
url = "https://bbs1.org/mcp"

[mcp_servers.bbs1org.http_headers]
Authorization = "Bearer <下载文件中的 Token>"

可以直接说

“使用 bbs1org 列出最新 10 个主题”
“使用 bbs1org 查看未读 @ 通知，并回复需要处理的内容”

将 bbs1org 论坛作为可由 AI 安全检索和按权限操作的 MCP 知识库。

功能

插件使用 Streamable HTTP 和 JSON-RPC 2.0，支持以下 MCP 方法：

• initialize
• ping
• tools/list
• tools/call

提供以下工具：

后台配置

操作账号

MCP 所有读取和写入操作都使用这个论坛账号，并沿用该账号的：

• 用户组权限
• 版块查看权限
• 发主题和回帖权限
• 禁言状态
• 发帖间隔

建议创建一个权限明确的专用账号，不要直接使用超级管理员账号。

版块范围

• 账号可访问的全部版块：允许访问该账号本身有权查看的全部版块。
• 仅选择的版块：在账号权限之外再增加一层版块限制。

返回限制

• 单次最大返回条数：范围为 1 至 50，默认 20。
• 单次正文字符预算：范围为 1000 至 50000，默认 20000。

字符预算由主题正文和本页回复共同使用。达到预算后，剩余正文会被截断。

写入权限

“允许发主题和回帖”默认关闭。关闭时，客户端的工具列表中不会出现 create_topic 和 create_reply。

建议先以只读模式完成连接测试，确认版块权限正确后再开启写入。

生成 Token

点击“生成并下载 Token”，浏览器会下载一个文本文件：

MCP endpoint: https://你的域名/index.php?a=mcp
Authorization: Bearer bbs1_xxxxxxxxx

服务器只保存 Token 的 SHA-256，不保存明文。请妥善保存下载文件；重新生成 Token 后，旧 Token 立即失效。

客户端配置

客户端必须支持：

• MCP Streamable HTTP
• 自定义 HTTP Header
• Bearer Token

通用配置示例：

{
  "mcpServers": {
    "bbs1org": {
      "type": "streamable-http",
      "url": "https://你的域名/index.php?a=mcp",
      "headers": {
        "Authorization": "Bearer bbs1_xxxxxxxxx"
      }
    }
  }
}

部分客户端使用 type: "http"，具体字段名称以客户端文档为准。

可使用 Cherry Studio、LibreChat、支持 MCP 的 VS Code 扩展等客户端。本地免费模型可通过 Ollama 接入，例如 Qwen 系列模型。

连接测试

初始化

curl -X POST 'https://你的域名/index.php?a=mcp' \
  -H 'Authorization: Bearer bbs1_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {
        "name": "test",
        "version": "1.0"
      }
    }
  }'

获取工具列表

curl -X POST 'https://你的域名/index.php?a=mcp' \
  -H 'Authorization: Bearer bbs1_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

工具参数

list_forums

不需要参数：

{}

list_topics

{
  "forum_id": 1,
  "limit": 10,
  "before_id": 100
}

• forum_id：可选，限制版块。
• limit：可选，返回数量。
• before_id：可选，使用上一页返回的 next_cursor。

search_topics

{
  "query": "Docker 部署",
  "field": "title",
  "forum_id": 1,
  "limit": 10,
  "before_id": 100
}

field 支持：

• title：主题标题
• body：主题正文
• reply：回帖内容

搜索使用论坛现有全文索引，不执行全表 LIKE 扫描。

get_topic

{
  "topic_id": 123,
  "limit": 20,
  "after_reply_id": 456
}

• topic_id：必填。
• limit：可选，本页回复数量。
• after_reply_id：可选，使用上一页返回的 next_cursor。

create_topic

{
  "forum_id": 1,
  "title": "主题标题",
  "body": "Markdown 格式的主题正文"
}

create_reply

{
  "topic_id": 123,
  "body": "Markdown 格式的回复内容"
}

写入操作会同步更新全文索引、主题统计、回复统计、通知以及相关插件 Hook。

AI 使用示例

连接成功后，可以向 AI 提出：

列出论坛最新的 10 个主题。
搜索论坛中关于 Docker 部署的讨论。
读取主题 123 及其全部回复并总结主要观点。
找出与“数据库缓存”相关的历史主题。

开启写入权限后：

根据主题 123 的内容生成一条回复，确认后发布。
把整理好的教程发布到“交流”版块。

安全机制

• Bearer Token 认证
• Token 只保存 SHA-256
• Origin 主机校验
• 操作账号和论坛权限校验
• 可限制版块范围
• 写入功能默认关闭
• 请求体最大 1MB
• 严格参数类型和未知字段校验
• 单次请求只执行一个 JSON-RPC 调用
• 不提供删除、编辑、用户管理和后台管理工具

生产环境必须使用 HTTPS，避免 Token 在网络传输过程中泄露。

性能设计

• 没有计划任务和后台轮询
• 不调用任何 AI 模型或外部接口
• 不记录逐次调用日志
• 不新增插件业务数据表
• 不使用 COUNT 分页
• 不使用高开销 OFFSET 分页
• 主题和回复使用 ID 游标分页
• 搜索复用论坛现有全文索引
• 作者信息一次批量读取，不在列表循环中查询
• 普通论坛页面不增加数据库查询

只有 MCP 客户端主动调用时，论坛才会执行相应查询或写入。

常见问题

返回 401

检查：

• MCP 是否已在插件管理页启用。
• Token 是否完整。
• Header 是否为 Authorization: Bearer Token内容。
• 是否重新生成过 Token，导致旧 Token 失效。
• Nginx、反向代理或 CDN 是否保留 Authorization Header。

返回 403 Origin 不受信任

检查后台“站点地址”是否与访问 MCP 使用的域名一致。浏览器环境发出的跨域请求必须使用相同站点域名。

工具列表没有发布功能

后台尚未开启“允许发主题和回帖”。这是默认安全设置。

搜索不到内容

• 搜索词至少需要 3 个字符。
• 确认选择了正确的 field。
• 确认操作账号有权查看目标版块。
• 确认论坛全文索引已经正常建立。

AI 无法连接

确认客户端支持 Streamable HTTP 和自定义 Authorization Header。只支持本地 stdio MCP 的客户端不能直接连接论坛 URL。

当前不支持

• 自动调用 AI 模型
• 自动定时回帖
• 编辑或删除主题、回复
• 上传附件
• 用户和后台管理
• MCP Resources
• MCP Prompts
• 调用历史与统计

这些限制用于保持插件边界清晰，并避免增加论坛服务器的常驻负载。

☝️

🔍 插件审查报告（对照《AI 开发规则》与开发者文档）

整体实现规范、参数化查询到位、版块/用户组权限与发帖间隔校验完整，无 SQL 注入、XSS 或红区 DB 读问题。以下为少量可优化点。

🔒 安全问题

未发现明显问题。Token 采用 SHA-256 存储、hash_equals 比较，写入操作均有权限与频率校验。仅一处可留意：plugin.php:41-44 的 site.closed_allow 对 MCP 端点一律放行，站点关闭维护期间 MCP 仍可访问（开启写入时还能发帖）。建议关闭站点时仅保留只读工具或整体拒绝，并在后台说明该豁免行为。

⚡ 性能问题

未发现明显问题。列表/通知均用 rows_by_ids 批量取用户，forum_by_id 走请求级缓存，无 N+1 查询。

🐛 功能/规范缺陷

1. plugin.php:724-726：在 params 被确认为数组前就读取 $request['params']['protocolVersion']，params 缺失或为字符串时会触发 PHP 8 警告。建议先用 is_array 校验再取值。
2. plugin.php:568-572：reply_notification 将上限 9800 的正文拼上 @用户名 #楼层 前缀后再交给 create_reply（其上限 10000），用户名较长时合计超限会被拒绝。建议按 10000 对拼装后全文统一截断。
3. plugin.php:437/468/500/528：调 topic.before_save/reply.before_save 时 ctx 传 'action'=>''，而核心传的是有意义的 action 值，依赖该字段区分新建/编辑的其他插件会拿到空串。建议与核心 ctx 形状保持一致。

✅ 修复优先级

先修 #1（输入校验）与 #2（长度边界），再对齐 #3 的 ctx 语义；site.closed_allow 豁免可按站点策略决定是否保留。

🔍 插件审查报告（AI 自动审查，对照《AI 开发规则》与开发者文档；本插件未被 8/18 楼上 350 的报告覆盖，属独立首次审查）

插件：MCP Server（mcp_server）v1.1.8

结论：已完成命名规范、生命周期（install/uninstall 幂等）、数据库跨库兼容、红区 Hook 零 DB 读、Hook 真实性（含核心与跨插件依赖核对）、SQL 注入风险、CSRF/权限校验、CSS 变量规范等项审查，未发现安全、性能或功能性问题。

旧格式迁移：已将插件代码转存到开发日志，主题正文改为基础介绍。

版本 1.1.8 更新：
修正回帖楼层

版本 1.1.9 更新：
提升版本号

版本 1.1.10 更新：
修正删除主题的问题

版本 1.1.10 更新：
支持v10

版本 1.1.11 更新：
更新版本号