本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/plugins/mcp_server/说明.md。

MCP 服务（mcp_server）插件说明

版本：1.3.0 ｜ 作者：FlintHub ｜ 状态：⏸ 未启用（activated: false）

功能：把 FlintHub 变成 MCP Server，让本机 AI Agent（Claude Desktop / Cursor / Trae 等）

以用户本人账号读写论坛——Token 鉴权、只读/可写分级、滚动 24h 发帖额度、写操作幂等、

全链路审计、与插件生态（审核 / 前置标签 / 积分 / 通知 / 搜索）联动。

一、功能简介

1.1 传输与协议

• 端点：POST {BASE_PATH}/mcp，无状态 Streamable HTTP，JSON-RPC 2.0（单条 + 批量）
• 协议基线 2025-06-18，兼容 2025-03-26 / 2025-11-25（initialize 时宽容协商）
• 鉴权：Authorization: Bearer fh_mcp_xxx（绝不使用 CSRF——MCP 端点无会话）
• 非 POST 一律 405 + Allow: POST；Origin 做 DNS rebinding 白名单校验

1.2 工具清单（16 个）

只读（9）

可写（7，需 allow_ai_post=1 且 Token scope=write）

1.3 结构化错误码

失败结果同时保留旧契约（isError: true + 中文 content[0].text）与新增结构化字段：

result.structuredContent = { "code": "QUOTA_EXCEEDED", "retry_after": 6399, "data": … }

协议级错误放在 error.data = { code, retry_after }。业务码共 13 个：

UNAUTHORIZED FORBIDDEN NOT_FOUND INVALID_ARGUMENT RATE_LIMITED COOLDOWN

QUOTA_EXCEEDED IDEMPOTENCY_CONFLICT IDEMPOTENCY_IN_PROGRESS WRITE_DISABLED

BANNED DISABLED INTERNAL。

1.4 写操作守卫（顺序固定）

服务开关 → Token 有效 → 账号 active → 未封禁 → scope 足够 → allow_ai_post

→ 每分钟限流 → 同工具冷静期 → 幂等键 → 滚动 24h 额度（仅 create_thread）→ 执行

1.5 幂等重放

写工具都接受可选 client_token（8~128 字符，[A-Za-z0-9._:-]）：

⚠️ 不承诺跨进程强原子性：进程若在「业务写库成功」与「写 done」之间被杀，TTL 过后重试理论上仍可能重复一次；单进程 / 正常重试不会重复。

1.6 额度语义（滚动 24 小时「成功」发帖数）

• 不是固定日窗，不是尝试计数。窗口 = 现在往前 24 小时。
• 账本三态：reserve() 预占 → 成功 commit() / 失败 release()。只有 committed 计入额度。
• 预占 TTL 300s：进程崩溃后自动过期，不会永久吃掉一个名额。
• 并发：预占 + 计数 + 判定在 BEGIN IMMEDIATE 内完成，两个请求不会同时抢到最后一个名额。

1.7 审计

mcp_logs 一次调用写两行（start → finish），或一次性事件一行。记录 request_id / event /

status / code / retry_after / duration_ms / scope，覆盖：工具调用、认证失败、参数错误、

未知工具、限流拒绝、令牌创建 / 本人撤销 / 管理员撤销、协议错误。

写库前强制脱敏（不依赖调用方自觉）：

• 任何形如 fh_mcp_xxxx 的串 → fh_mcp_***
• 正文类字段（content / body / text / html / markdown）→ [len=N]
• 二进制类字段（image / image_base64 / base64 / data / file / avatar）→ [blob=NB]

后台「调用审计」支持按 令牌 / 用户 ID / 事件类型 三条件筛选，翻页自动带上筛选条件。

1.8 令牌

• 形态 fh_mcp_<base64url(32B)>，库内只存 sha256，明文仅创建时返回一次
• 软撤销：enabled=0 + revoked_at + revoked_by（0 = 本人，>0 = 管理员 uid），行保留

→ 历史日志里的 token_id 永远查得到名字，也能回答「谁在什么时候撤了哪个令牌」

• 单用户有效令牌上限 20 个；已撤销的不占名额

二、请求流程

POST /mcp
  └─ McpServer::handle()
        ├─ 服务开关关 → 503（audit: DISABLED）
        ├─ Origin 白名单 → 403
        ├─ Bearer 校验失败 → 401（audit: auth_fail）
        ├─ JSON 解析 / 协议版本 / method 分发
        └─ tools/call
              ├─ 工具存在？→ 否则 tool_not_found
              ├─ 参数校验 → 否则 param_error
              ├─ 写工具？→ 写守卫链（限流 / 冷静期 / 幂等）
              ├─ Audit::start()  ← 先落一行 status=started（进程被杀也留痕）
              ├─ Tools::xxx()    ← 全部经核心 Model/Helper
              ├─ Idempotency::commit() / abort()
              └─ Audit::finish() → 补 status / code / duration_ms / result

核心写入路径复用（不自造 SQL）：

Thread::insert/update/softDelete、Post::insert/update/softDelete、Vote::toggle/getCounts、

Tag::saveForThread、Search::indexThread/removeFromIndex、User::increment/decrementPostCount、

Points::award、Notification::notifyReplyAggregated/notifyQuote/notifyVote，

并触发 thread_create_after / post_create_after / post_edit_after / thread_edit_after / vote_after 钩子。

三、路由与接口

3.1 前台（hook/route_register.php）

3.2 后台（hook/admin_route_register.php，路径不写 /admin 前缀）

门禁来自继承 app\Controllers\Admin\BaseController → 构造函数完成「管理员 + 二次验证」双重校验。

四、后台可配项

存 mcp_config 表（键值对，非核心 settings），默认值由 Plugin::configDefaults() 兜底：

五、数据表

独立库：plugins/mcp_server/data/mcp_server.sqlite（WAL，busy_timeout=5000）

六、数据库迁移（1.1.0 起版本化）

• 唯一权威版本标记 = 库内 mcp_schema.version（不是文件）。旧版 data/.mcp_table_cache 布尔门控已废弃，升级成功后自动删除。
• 迁移文件：migrations/1.1.0.sql（schema v1 → v2，19 条语句），唯一 DDL 事实源。
• Migrator::migrate() 流程：Plugin::ddl() 基线（CREATE TABLE IF NOT EXISTS）→ 逐版本 applyStep()。
• applyStep()：BEGIN IMMEDIATE → 事务内重读版本（等锁期间可能已被另一请求升完）→ 逐语句执行 → 写版本 → COMMIT。中途失败 = 版本不变 + 全量回滚。
• ALTER TABLE ... ADD COLUMN 前用 PRAGMA table_info 探列，已存在则跳过 → 手工补跑 / 并发补跑都安全。
• 每请求最多查一次版本（static $checked 守卫），已是最新则 0 条 DDL。
• 改 schema 必须同时改两处：Plugin::SCHEMA_VERSION 与 Migrator::STEPS。只改一处会被 validate() 抛异常拦下，不会静默半迁移。

七、目录结构

plugins/mcp_server/
├── plugin.json                     # 6 钩子 / min_core 1.1.19 / permissions: route:admin
├── Plugin.php                      # 主类：独立库 / 配置 / 用户装载 / 封禁判定 / 请求 id / withUser
├── McpServer.php                   # JSON-RPC 入口：分发 / 写守卫 / 幂等 / 结构化出参
├── Transport.php                   # 响应输出（JSON-RPC error 支持 error.data）
├── ToolRegistry.php                # 16 个工具的 schema 与描述（tools/list 的唯一来源）
├── Tools/ReadTools.php             # 9 个只读工具
├── Tools/WriteTools.php            # 7 个可写工具
├── TokenManager.php                # 令牌生成 / 校验 / 软撤销 / 限流 / 冷静期 / effectiveScope
├── Quota.php                       # 滚动 24h 额度账本（reserve / commit / release / status）
├── Idempotency.php                 # 幂等键（begin / commit / abort / hashArgs / validateKey）
├── Audit.php                       # 审计写入 + 脱敏 + 后台筛选 + 过期清理
├── ErrorCode.php                   # 13 个稳定业务码 + fail() / ok() / normalize()
├── Migrator.php                    # 版本化迁移器（mcp_schema.version 门控）
├── migrations/1.1.0.sql            # v1 → v2 DDL（唯一事实源）
├── FrontController.php             # 前台令牌页 / 创建 / 撤销（+ 审计）
├── AdminController.php             # 后台三 Tab（+ 审计筛选 / 用户名装载 / 撤销审计）
├── hook/
│   ├── init_after.php              # Migrator::migrate()（已是最新 → 0 条 DDL）
│   ├── route_register.php          # /mcp + /mcp-token*
│   ├── admin_route_register.php    # 3 条后台路由
│   ├── layout_head_end.php         # 注入 assets/style.css
│   └── post_mark_badge.php         # 「由 MCP 发布」徽章（机器人图标；主帖/回帖同位置触发）
├── views/  token.php · admin.php
├── assets/ style.css · script.js
├── lang/   zh.php · en.php · zh_tw.php
└── data/   mcp_server.sqlite

八、注意事项

1. 目录名含下划线（mcp_server）→ Plugin.php 末尾必须保留

class_alias(Plugin::class, 'Plugin\mcp_server\Plugin')，否则核心按目录名硬拼的类名找不到，

activate() / uninstall() 被静默跳过。

1. 改 Plugin::ddl() 对老库无效。CREATE TABLE IF NOT EXISTS 对已存在的表完全不生效 →

新增列/索引一律写进 migrations/<版本>.sql，并同步 +1 Plugin::SCHEMA_VERSION 与 Migrator::STEPS。

1. list_threads 依赖核心 Thread::getIndexByCreateCursor()（核心 1.1.25 起提供）。

⚠️ 1.2.0 起有显式能力探测：ReadTools::supportsIndexCreateCursor() 用 method_exists()

判定（不用版本号字符串比较 —— 版本号可能被手工改过、站点也可能跑二次分发的核心）。

方法缺失时 list_threads 返回 code=CORE_TOO_OLD 并提示「升级核心或改用 search_threads」，

不再笼统报 INTERNAL。与 INTERNAL 分开的理由：INTERNAL 意味着「重试可能有用」，

而 CORE_TOO_OLD 意味着「重试一万次也没用，只能升级核心」—— 混在一起会让调用方白重试、

站长在审计日志里也查不出根因。

⚠️ 插件不得直接查 topic_index —— 分片、权限、软删口径全在核心模型里。

1. getIndexByCreateCursor() 与 getIndexCursor() 语义不同，不可互换：

后者混入 is_pinned / last_reply_time 排序，用于增量巡查会漏帖。

且空白名单返回 []（与 getIndexCursor 的「空 = 不限」故意相反，防权限泄漏）。

1. 额度只认 committed。release() 只在写库失败时调；成功路径必须 commit()，

否则名额会随 reserved 的 TTL 过期而"莫名归还"，额度形同虚设。

1. 撤销是软撤销。verify() 只认 enabled = 1，软撤销立即失效；

listForUser() / countForUser() 都带 enabled = 1，已撤销的不占 20 个名额。

1. 审计脱敏在写入层（Audit::flatten/scrub/redact），不依赖调用方自觉。

新增参数时不要绕过 Audit::start/event 直接拼 SQL，否则正文与令牌明文会进库。

1. mcp_post_marks 的 markedPostIds() 是请求级缓存，整页只查 1 次（满足单插件每请求查询上限）。
2. Plugin::withUser() 用于只认 $_SESSION['user_id'] 的核心 Helper（Vote::toggle/getCounts、Points）。

finally 里严格还原原会话 —— MCP 端点正常无会话，还原后必须回到「无 user_id」状态。

1. 后台弹层/表单 markup 必须留在 <main class="admin-content"> 内，放到外面 = 无 UI、零日志。
2. **CSS 只用既有 --mn-* 变量。--mn-tag-success-bg / --mn-tag-danger-bg / --mn-bg-subtle 不存在**，

状态色请用 --mn-alert-success-bg/text、--mn-comp-tag-danger-bg/text、--mn-bg-tag。

1. 改前端静态资源必须 bump plugin.json 的 version：?v=filemtime 是唯一破缓存手段。

九、当前状态

回归套件（.workbuddy-ai/tmp/，改动本插件后必跑）

已知取舍（非缺陷）

• 不支持博客创建、管理员二次验证相关管理操作（留到后续版本）。
• 不支持点踩：vote 只有 1 = 点赞 / 0 = 取消。
• 不在 JSON-RPC 里做图片上传（避免 Base64 撑爆上下文与审计库）。
• 不自造批量写入工具（批量 = 客户端多次调用 + client_token 保证不重复）。
• 幂等不承诺跨进程强原子性（见 §1.5）。

更新记录