执念

外观

MCP 服务器：让 AI 直接查这套文档 ​

这个文档站自带一个 MCP 服务器。它把整站 markdown（guide/ + api/）读进来，暴露成 AI 能直接调用的工具。

开发插件时连上它，就不用再把文档复制粘贴进上下文了 —— AI 会自己去查组件签名、开发规范、检查表。

什么时候用

你在用支持 MCP 的客户端写插件（Claude Code / DSH / Cursor / Codex / Windsurf …）—— 接上它，AI 就能自己确认「这个组件到底有哪些参数」，而不是凭印象写出编译不过的代码。

它提供什么 ​

工具干什么
start_here开发新插件时第一个调用：8 步流程 + 「按问题找文档」索引 + 三条最常踩的硬规范
search_docs(query, limit?)整站全文检索（中文按二元组切词，中英混合也行），返回页面 + 小节 + 摘要
list_docs(prefix?)列出全部文档页，可按路径前缀过滤（如 guide/shared）
get_doc(path)读一整页 markdown
get_section(path, heading)只读某一节 —— 页太长、只关心一段时用它，省上下文
list_components()组件库全部组件清单
get_component(name)读某个组件的真实签名与用法。写 UI 之前必做
get_checklist()发布前 Checklist

除了工具，还注册了两样东西：

  • 资源：每一页都能作为 zhinian-docs://<路径> 被客户端直接读取、列出（当前 59 页）；
  • Prompt：new-plugin，一步把「开发一个新插件」的完整流程拉起来（含阅读顺序和硬约束）。

怎么接 ​

方式一：stdio（推荐） ​

仓库里已经写好配置，两个位置各一份、内容一样：

  • obsession-docs-vue/.mcp.json —— 在文档目录里工作时用
  • <仓库根>/.mcp.json —— 在仓库根目录干活时用这一份（多数客户端只认项目根的 .mcp.json）
json
{
  "mcpServers": {
    "zhinian-plugin-docs": {
      "command": "node",
      "args": ["D:/MyFile/Projects/ZhiNian/obsession-docs-vue/mcp/server.mjs"],
      "env": { "ZN_DOCS_SITE": "https://doc.yihualuo.cn" }
    }
  }
}

照这个格式抄进你客户端的配置就行：

客户端配置位置
Claude Code项目根目录的 .mcp.json，或 claude mcp add
Cursor.cursor/mcp.json
DSH / 其它客户端的 MCP 配置项，格式同上

args 写成绝对路径最稳（客户端的工作目录不一定在项目里）。也可以手动跑一次确认能起来：

bash
node mcp/server.mjs --list

它会打印索引到多少页文档，然后退出 —— 不启动服务，纯自检。

方式二：HTTP ​

客户端和文档不在同一台机器、或者要同时给多个客户端用：

bash
node mcp/server.mjs --http 7331

然后把 MCP 客户端指向 http://127.0.0.1:7331/mcp（Streamable HTTP）。

自检 ​

改完服务器，跑一遍自检 —— 它会用真的 MCP 客户端把每个工具都调一遍，并断言关键结果。两个模式各一份：

bash
node mcp/selftest.mjs        # stdio
node mcp/selftest-http.mjs   # HTTP：自己起服务器进程、跑完自己关掉（默认端口 7331）

stdio 那份覆盖：工具数量、get_component("textfield") 能带回参数表、get_section 能取到 ### 小节、 不存在的组件返回错误态、无命中给出提示而不是报错、资源与 prompt 都注册上了。

HTTP 那份额外盯一件必须单独测的事：多个独立客户端依次连。无状态 HTTP 模式下客户端每次请求都是 一条新的 POST，服务器必须能重复处理 —— 复用同一个 server 实例反复 connect() 会直接抛 Already connected to a transport，症状是「第一个客户端正常、第二个 500」。 所以 HTTP 模式的实现是每个请求新建一套 server + transport（server.mjs 里那段注释写了原因和代价）。

它是怎么工作的 ​

  • 启动时扫 guide/**/*.md 和 api/**/*.md，运行时读盘、3 秒缓存 —— 所以文档改完不用重启 MCP 服务器，它下一轮就读到新的。
  • 检索不依赖任何检索库：ASCII 按词切，中文按二元组切（「自动加载更多」→ 自动/动加/加载/载更/更多）， 标题权重高于正文，命中的检索词越多越靠前，最后再砍掉分数低于最高分 12% 的噪声。
  • stdio 模式下所有日志走 stderr —— stdout 是协议通道，不能被日志污染。
  • 只依赖 @modelcontextprotocol/sdk（obsession-docs-vue 的 devDependency）。

会不会出现「文档站一套、MCP 又一套」 ​

不会。MCP 服务器读的就是文档站自己的 markdown：

obsession-docs-vue/
├── guide/          ← 站点页面，同时也是 MCP 的知识源
├── api/            ← 同上
├── mcp/server.mjs  ← 只读不写
└── .mcp.json

npm run build 出站点、npm run deploy（或手动传 FTP）发布 —— MCP 那边读的是同一批文件。 改文档 = 改 MCP 的回答，不存在两份内容对不上的情况。

相关文件 ​

文件作用
mcp/server.mjs服务器本体（工具、资源、prompt、stdio + HTTP 两种启动方式）
mcp/selftest.mjsstdio 自检客户端
mcp/selftest-http.mjsHTTP 自检：自己起服务器进程、多个客户端依次连、跑完自己关掉
.mcp.json现成的客户端配置（仓库根和 obsession-docs-vue/ 各一份，内容一样）