本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/docs/mcp_server插件开发方案_2026-10-11.md。

mcp_server 插件开发方案（让 FlintHub 成为 MCP Server）

文档性质：评估稿（只做方案，不写代码）

目标读者：站长 / 项目评审

依据：docs/插件开发规范.md（权威规范）、app/Helpers/Plugin.php、app/Core/Router.php、app/Models/*、现有插件实现（ai_assistant / forum_required_tag / content_review / mod_system / user_level）、MCP 官方规范

原始输入：站长提供的《MCP Server 插件规划（供 Agent 参考）》

版本：v1（2026-10-11）

0. 一句话结论

可行，且比原规划更简单 — 但必须改两处关键设计。

1. 传输必须做成「无状态 Streamable HTTP + 纯 JSON 响应」，不启用 SSE / 长连接 / 会话。这样插件在普通 php-fpm 请求模型下即可跑通，不需要 Swoole / ReactPHP / 常驻进程。（MCP 规范明确允许服务器用 application/json 返回单对象而不开 SSE。）
2. 「动态 Schema」不能直接去读 forum_required_tag 的库或类——那违反《插件开发规范》「插件间禁止直耦」。正确做法是新增一个自定义钩子契约 mcp_tool_schema，由关心规则的一方（如 forum_required_tag）自己订阅、自己上报规则；无人订阅时工具走「最小 schema + 可读错误」。

除此之外，原规划的判断（插件形态、Token 体系、走 Model 层、不做管理操作）全部成立，可以直接沿用。

建议分期：P0（Token + 只读工具）→ P1（发帖 / 回帖）→ P2（生态联动）→ P3（审计 / 限流 / 后台）→ P4（点赞 / 收藏等高级工具）。

1. 前提验证（先答「能不能插件全包」）

1.1 结论

能。 不需要动核心：/mcp 走 route_register 注册；Token 存插件独立 SQLite；写操作全部落到核心 Model 层。

1.2 证据链（逐条可复核）

1.3 由此产生的三条硬边界（必须写进插件自检）

1. 不碰核心：/mcp 只注册路由；不修改任何 app/ 下文件；不新增核心钩子名（用自定义钩子名做扩展点）。
2. 不自己写业务表：所有帖子/回复必须经 Thread::insert() / Post::insert()，禁止插件直写核心业务库（否则插件生态的钩子全部不会触发）。
3. 不给 /mcp 加 CSRF：第三方 Agent 拿不到 CSRF token；鉴权只能靠 Authorization: Bearer <token>。（与 oidc_provider 的 token 端点同理——那处也明确不调 Csrf::verifyOrDie()。）

2. 总体设计

2.1 定位与边界

2.2 命名与目录硬约束（含必须先踩平的坑）

• 插件目录名：mcp_server（全小写 + 下划线，符合 /^[a-z0-9_]+$/）。
• ⚠️ 目录名含下划线 → 核心生命周期类名推导会失败（规范 §4.1 / docs/插件开发规范.md:350-390）→ 必须在 Plugin.php 末尾加 class_alias：
• 命名空间统一写 Plugin\McpServer（PascalCase 段）
• class_alias(\Plugin\McpServer\Plugin::class, '\Plugin\mcp_server\Plugin')
• 这条与 oidc_provider / oidc_client 完全同款，已是本库既定写法。
• ⚠️ 路由前缀不能与真实目录同名（规范 §11.34b）：/mcp 站点根无同名目录，安全。

2.3 路由规划表

⚠️ 注册顺序：/mcp-token/* 必须早于任何 /mcp-token 通配；/mcp 与 /mcp-token 不冲突（精确匹配优先）。

3. 协议与传输设计（本方案的技术核心）

3.1 协议版本策略

落地口径：

• initialize 时若客户端 protocolVersion 在此表内 → 原样回；否则回我们支持的最新版本（规范要求服务器必须返回一个自己支持的版本）。
• 容忍客户端跳过 initialize 直接 tools/list（无状态服务器的自然行为），不做「必须先握手」的强校验。

3.2 传输形态：无状态 Streamable HTTP

⚠️ 这是本方案能否落地的前提。若要做 SSE / 服务器推送，就得上 Swoole/ReactPHP 常驻进程——本期不做。

3.3 JSON-RPC 方法最小集（只做 tools）

错误口径（重要，直接决定 Agent 能否自我修正）：

• 协议级错误（未知方法 / 未知工具 / 参数结构非法）→ JSON-RPC error（如 -32602）。
• 业务级错误（版块要前缀、积分不足、无权限、被限流、被封禁）→ result.isError: true + content[0].text 写人类可读中文，让模型自己改参数重试。
• 例：{"isError":true,"content":[{"type":"text","text":"该版块要求选择标题前缀，请从 [BUG提交] [优化提交] 中选一个"}]}

3.4 鉴权：自定义 Bearer Token

• 规范中 Authorization 是 OPTIONAL；只有在「支持鉴权」时才 SHOULD 遵循 OAuth 章。→ 自定义静态 Bearer 不违规。
• 规范同时禁止 token passthrough（不得接受/透传非本服务签发的令牌）→ 我们只认本插件签发的 token，符合要求。
• 三家客户端均支持静态请求头：
• Cursor：mcp.json 的 headers
• Trae：HTTP 类型的 headers
• Claude：Custom Connector → 「No sign-in」+ Request headers（beta）

3.5 客户端接入配置（示例）

{
  "mcpServers": {
    "flinthub": {
      "url": "https://www.flinthub.top/mcp",
      "headers": { "Authorization": "Bearer fh_mcp_xxxxxxxx" }
    }
  }
}

本地 stdio 形态本期不做（PHP CLI 桥接需要额外分发一个脚本，收益低、维护成本高）。

4. 详细方案

4.1 目录结构

plugins/mcp_server/
├── plugin.json               # permissions: ["route:admin"]
├── Plugin.php                # 生命周期 + class_alias（目录含下划线）
├── McpServer.php             # JSON-RPC 2.0 分发（initialize/ping/tools.list/tools.call）
├── Transport.php             # HTTP 层：Origin 校验、Accept 校验、Bearer 解析、202/405/400 语义
├── TokenManager.php          # Token 生成 / 校验 / 撤销 / 限流 / 额度
├── ToolRegistry.php          # 工具清单 + 权限过滤 + 动态 schema 合并
├── Tools/
│   ├── ReadTools.php         # list_categories / search_threads / get_thread / list_replies / get_user
│   └── WriteTools.php        # create_thread / reply_thread / edit_post / delete_post
├── Audit.php                 # 审计日志写入（截断 + 保留期）
├── FrontController.php       # 前台：Token 管理页
├── AdminController.php       # 后台：开关 / 限流 / 策略 / 审计
├── hook/
│   ├── init_after.php        # 幂等建表
│   ├── route_register.php    # /mcp + /mcp-token*
│   └── admin_route_register.php
├── views/
│   ├── token.php             # 前台 Token 页
│   └── admin.php             # 后台
├── assets/{script.js,style.css}
├── lang/{zh,en,zh_tw}.php
└── data/mcp_server.sqlite    # 独立库（Web 层已被 Plugin::db() 自动拦截）

4.2 plugin.json 关键字段

{
    "name": "MCP 服务",
    "version": "1.0.0",
    "author": "FlintHub",
    "description": "让本机 AI Agent（Claude Desktop / Cursor / Trae）以你的账号读写论坛",
    "activated": false,
    "category": "integration",
    "icon": "robot",
    "admin_url": "/admin/mcp-server",
    "hooks": {
        "init_after": "hook/init_after.php",
        "route_register": "hook/route_register.php",
        "admin_route_register": "hook/admin_route_register.php"
    },
    "permissions": ["route:admin"]
}

• icon 必须是核心图标表里真实存在的项（robot 已在 ai_assistant 使用，开发前需再 grep 核对）。
• 不声明 net:fetch（MCP 不主动外呼；纯 JSON 响应无需外网）；不声明 system:settings。
• 权限强制模式：permission_enforce 默认 1（app/Helpers/Plugin.php:155-160）→ 声明必须准确，否则后台路由会被拒。

4.3 Token 体系（用户级）

用户在前台生成 Token → 只在生成时展示一次 → 库里只存 hash

校验链：Bearer → 取 hash → 查库 → 校验 enabled/expires → 取 user_id → 载入用户 → 权限/封禁/限流校验 → 执行。

4.4 权限对齐（核心原则）

MCP 请求 → Token 验证 → 用户身份 → 调核心 Model（与「用户正常发帖」同一条路径）→ 落库
                                          ↑
                            版块权限 / 等级 / 积分 / 审核 全部自然生效

• 绝不自己写库（否则 content_review、points_mall、user_level 的钩子全部不触发）。
• 审计独立：审计日志额外记录「本次写操作由 MCP 发起」（token_id / tool / 结果）。
• ⚠️ Model 调用方式必须逐一实测：ai_assistant 的踩坑记录明确写着「Model 读取必须使用实例方法」（plugins/ai_assistant/说明.md:157-164）。Thread::insert() / Post::insert() 是实例方法还是静态方法，开发第一步就核实，不要照抄本方案的写法。

4.5 工具清单

只读工具

可写工具

P4 候选（见 §4.6，可能不是核心能力）

⚠️ 重要修正：like_points 与 post_favorite 都出现在官方插件市场清单里，说明点赞/收藏很可能是插件能力而非核心能力。若如此，vote / favorite 不应写进 P0/P1，而应放到 P4，并做成「提供方插件在线才注册该工具」的动态注册（见 §4.6）。开发前必须先核实这两个能力的归属。

4.6 动态 Schema 机制（★ 与原规划的关键差异）

问题：forum_required_tag 会在发帖时强制前缀/标签；Agent 不知道规则 → 发帖被拒 → 体验差。

原规划的解法：MCP 直接读 forum_required_tag 的配置。

问题所在：该插件的数据在它自己的独立库（plugins/forum_required_tag/data/forum_required_tag.sqlite，表 frt_forum_tags / frt_forum_prefixes），需要调它的静态方法 Plugin\ForumRequiredTag\Plugin::getForumTags($forumId)。这属于插件间直耦，违反《插件开发规范》§11.6。

正确解法：自定义钩子契约 mcp_tool_schema

                    ┌──────────────────────────────────────┐
  tools/list ──────►│ ToolRegistry                          │
                    │  1. 内置基础 schema                    │
                    │  2. Plugin::hook('mcp_tool_schema', …) │──► 各插件订阅
                    │  3. 合并 → 返回给 Agent                │     （forum_required_tag
                    └──────────────────────────────────────┘      上报前缀 enum / 标签规则）

• McpServer 在 tools/list 与 tools/call 前调用 Plugin::hook('mcp_tool_schema', $ctx)（$ctx 含 category_id、tool_name）。
• 任何插件想参与，只需在自己 plugin.json 里加一行 "hooks": { "mcp_tool_schema": "hook/mcp_tool_schema.php" }。
• forum_required_tag 上报：该版块的前缀列表（enum）与标签规则（required / 数量下限），前缀展示形式为 [xxx]，库内存储不含方括号。
• 无人订阅时零影响：退回基础 schema；发帖被拒时，由核心/插件的拒绝信息转成可读中文回给 Agent。
• ✅ 这样 mcp_server 不认识 forum_required_tag，两个插件永不直耦，未来任何插件都能自助接入。

同样的机制可用于三件事：

1. 动态 schema（版本前缀 enum、标签必填）
2. 动态工具注册（like_points / post_favorite 在线时才暴露 vote / favorite）
3. 动态前置提示（content_review 上报「本版块发帖将进入审核」）

⚠️ 契约的两个硬约束：① 钩子参数用引用回传（Plugin::hook() 的 extract(..., EXTR_REFS) 支持），② 钩子文件必须 include_once 安全（不声明全局符号，或接受只执行一次）。

4.7 安全约束

4.8 内容归属与标注

• 内容归属 Token 绑定用户（无独立「MCP 用户」概念）。
• 可选标注「此帖由 MCP 客户端发布」：不改核心 → 用渲染钩子注入；标记存独立库（mcp_post_marks 表，记 thread_id/post_id）。
• 后台总开关：是否允许 AI 发帖（有些站长不想让 AI 灌水）。

4.9 独立库 schema（初稿，SQLite 语法）

-- Token
CREATE TABLE IF NOT EXISTS mcp_tokens (
  id           INTEGER PRIMARY KEY,
  user_id      INTEGER NOT NULL,
  token_hash   TEXT    NOT NULL UNIQUE,
  name         TEXT    NOT NULL DEFAULT '',
  scope        TEXT    NOT NULL DEFAULT 'read',   -- read | write
  enabled      INTEGER NOT NULL DEFAULT 1,
  daily_quota  INTEGER NOT NULL DEFAULT 10,
  last_used_at INTEGER,
  expires_at   INTEGER,
  created_at   INTEGER NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_mcp_tokens_user ON mcp_tokens(user_id);

-- 审计
CREATE TABLE IF NOT EXISTS mcp_logs (
  id         INTEGER PRIMARY KEY,
  token_id   INTEGER NOT NULL,
  user_id    INTEGER NOT NULL,
  tool       TEXT    NOT NULL,
  params     TEXT    NOT NULL DEFAULT '',   -- 截断
  result     TEXT    NOT NULL DEFAULT '',   -- 截断
  ip_hash    TEXT    NOT NULL DEFAULT '',
  created_at INTEGER NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_mcp_logs_created ON mcp_logs(created_at);
CREATE INDEX IF NOT EXISTS idx_mcp_logs_token   ON mcp_logs(token_id, created_at);

-- 限流计数（Token 级）
CREATE TABLE IF NOT EXISTS mcp_rate (
  id       INTEGER PRIMARY KEY,
  token_id INTEGER NOT NULL,
  action   TEXT    NOT NULL,       -- 如 write / tool:create_thread
  window_at INTEGER NOT NULL,      -- 窗口起点（分钟/天）
  counter  INTEGER NOT NULL DEFAULT 0
);
CREATE UNIQUE INDEX IF NOT EXISTS uq_mcp_rate ON mcp_rate(token_id, action, window_at);

-- 内容标记（「由 MCP 发布」）
CREATE TABLE IF NOT EXISTS mcp_post_marks (
  id        INTEGER PRIMARY KEY,
  kind      TEXT    NOT NULL,      -- thread | post
  ref_id    INTEGER NOT NULL,
  token_id  INTEGER NOT NULL,
  created_at INTEGER NOT NULL
);
CREATE UNIQUE INDEX IF NOT EXISTS uq_mcp_marks ON mcp_post_marks(kind, ref_id);

建表走 Plugin::ensureSchema('mcp_server', $ddl)；表名统一 mcp_ 前缀防冲突。

4.10 前台 / 后台

前台（用户侧）：生成 Token（一次性展示 + 复制）、权限范围（只读/可写）、最近使用记录、撤销。

后台（管理员侧）：

5. 与现有插件生态的交互

总原则：MCP 走 Model 层 → 插件钩子自然触发；规则读取走 mcp_tool_schema 钩子 → 插件自己上报；两者都不产生直耦。

6. 风险清单与规避

7. 分期实施与验收标准

验收标准 = 逐条勾选，全绿才算过。

P0：Token 体系 + 只读工具（先跑通「读」）

1. 插件可激活；Plugin::db('mcp_server') 建库成功；data/.htaccess 自动生成
2. 前台可生成 Token（明文只显示一次）；库里只有 hash
3. initialize 握手通过（Claude / Cursor / Trae 至少 1 个真实客户端连上）
4. tools/list 返回 5 个只读工具
5. search_threads / get_thread / list_replies / list_categories / get_user 均返回正确数据
6. 无 Token / 错 Token → 401；get_user 不含邮箱等私密字段
7. GET /mcp → 405；Origin 非法 → 403

P1：可写工具（跑通「发帖 / 回帖」）

1. create_thread 落库成功，且帖子归属 Token 绑定用户
2. reply_thread 落库成功，reply_count / last_reply_time 正确
3. edit_post / delete_post 只能操作自己的帖；操作别人的 → 可读拒绝
4. 审计日志记录 token_id / user / tool / 结果 / ip_hash
5. Token 级限流生效（超限返回可读中文）；无关 CSRF 报错

P2：生态联动

1. 开启 forum_required_tag 后，create_thread 的 schema 出现前缀 enum（且 mcp_server 代码里零 forum_required_tag 字样）
2. 不填前缀发帖 → 错误信息列出可选前缀，Agent 能据此重试成功
3. 开启 content_review 后，发帖返回体标注「已提交审核」
4. mod_system 封禁用户 → 全部工具拒绝

P3：审计 / 限流 / 后台

1. 后台总开关可关闭整个 MCP（关闭后 /mcp 一律 401/503）
2. 后台可配限流/额度/冷静期/审核策略，改完立即生效
3. 后台审计列表可翻页、可按 Token / 用户筛选
4. 站长可一键撤销某 Token 全部权限

P4：高级工具

1. 点赞/收藏归属核实完成；若为插件能力 → 做成「插件在线才注册工具」
2. vote / favorite 与前台行为一致（积分、通知等钩子均触发）

出包

1. php cli/release_build.php --type=plugin --name=mcp_server --version=1.0.0 --dry-run → 9 项门禁全 PASS（含 #9 命名空间一致性）
2. data/（含 sqlite）不进包；plugin.json / 表单 / zip 名三处版本号一致

8. 待拍板决策（建议，供评审确认）

附：本方案用到的规范条目索引

§三条硬规则（basename 校验 / SQL 预处理 / 转义） / §红线 8（AJAX 必须 CSRF，但协议端点例外需注明） / §2 目录结构 / §3 plugin.json（icon 必须真实存在） / §4.1 生命周期类名推导 + class_alias / §5.1 自动加载器方向不对称 / §8 语言包（键前缀 plugin.{插件名}.*） / §9 钩子清单与通信约定 / §10.3 SQLite DDL / §11.6 插件间禁止直耦 / §11.10 后台 Tab 标准 / §11.15 建表兜底 / §11.28 登录回跳 / §11.31 禁止每请求写库 / §11.34 命名空间逐字节 / §11.34b 前台路由避开真实目录 / §11.35 三条发布路径 / §12.2 出包前自检

外部依据：MCP 规范 Versioning / Transports(2025-06-18) / Authorization / Tools / Security Best Practices；Claude · Cursor · Trae 的 MCP 接入文档。