docusaurus-plugin-mcp-server - 把 Docusaurus 文档变成 MCP 入口

很多团队已经把产品文档、SDK 手册和内部工程规范放在 Docusaurus 里，但 AI coding agent 真正需要这些资料时，往往还是靠网页搜索、复制粘贴，或者让模型猜。文档在浏览器里很好读，却不一定能被 MCP client 稳定检索和引用。

今天推荐的 scalvert/docusaurus-plugin-mcp-server 正好卡在这个位置。它是一个 Docusaurus 插件，会在 docusaurus build 之后处理已渲染的 HTML 页面，抽取正文、转成 Markdown、构建 FlexSearch 索引，并输出可被 MCP server 使用的 docs.json、search-index.json 和 manifest。之后你可以在 serverless、edge runtime 或本地 Node HTTP server 里加载这些构建产物，让 AI 工具用 docs_search 和 docs_fetch 访问你的文档。

发布时 GitHub 数据显示项目约 28 stars、5 forks，主要语言是 TypeScript，许可为 MIT。仓库创建于 2026-01-24，最近更新时间为 2026-06-16。最新 GitHub release 是 v0.12.0，npm package 版本也是 0.12.0。

项目概览

属性	详情
仓库	scalvert/docusaurus-plugin-mcp-server
定位	把 Docusaurus 文档发布为 MCP 可检索服务
Stars	约 28
Forks	5
主要语言	TypeScript
许可	MIT
最新版本	v0.12.0

它解决的是文档到 agent 的最后一段路

Docusaurus 的优势是给人读：路由、侧边栏、React 组件、MDX、搜索、主题都很成熟。AI agent 需要的却是另一种接口：先根据问题检索相关页面，再拿到完整页面内容，最好能保留标题、描述、目录和可引用 URL。

docusaurus-plugin-mcp-server 做的不是重新发明文档站，而是在现有 Docusaurus 构建流程旁边增加一个 MCP 输出层：

// docusaurus.config.js
module.exports = {
  plugins: [
    [
      'docusaurus-plugin-mcp-server',
      {
        server: {
          name: 'my-docs',
          version: '1.0.0',
        },
      },
    ],
  ],
};

构建完成后，插件会在 build/mcp/ 下生成文档和索引。运行时的 MCP endpoint 不需要再启动完整 Docusaurus，也不需要在请求时读源码或重新解析 HTML。对部署来说，这一点很实际：文档站继续照常发布，MCP 端只加载静态构建产物。

两个工具刚好覆盖常见文档查询流

这个项目暴露的 MCP tool 很克制，只有两个核心动作：

docs_search：按查询词搜索文档，返回匹配页面、URL、摘要、相关标题和 relevance score。
docs_fetch：根据搜索结果里的 URL 获取完整页面 Markdown、标题、描述和目录。

这套接口对 coding agent 很友好。Agent 可以先搜索 “authentication”、“rate limit” 或 “plugin options”，再 fetch 最相关的页面，而不是一次性把整个文档站塞进上下文。对 Docusaurus 这种页面数量可能很大的站点来说，先检索再拉取正文，比把 Markdown 文件夹直接打包给模型更可控。

它也让文档引用更清楚。搜索结果里带完整 URL，fetch 的内容来自构建后的页面，能够覆盖 React component 渲染后的输出。也就是说，agent 看到的更接近线上用户实际看到的文档，而不只是源码里的 MDX 片段。

运行时适配比较务实

README 里给出的部署方式偏现代 Web runtime：Cloudflare Workers、现代 Netlify functions、Vercel Edge、Deno、Bun 这类支持标准 Request / Response 的环境，都可以通过 createWebRequestHandler 接入。因为这些运行时不能像普通服务器那样随便读文件，示例里会把 docs.json 和 search-index.json 当作模块导入。

本地开发则可以用 Node adapter：

import { createNodeServer } from 'docusaurus-plugin-mcp-server/adapters';

createNodeServer({
  docsPath: './build/mcp/docs.json',
  indexPath: './build/mcp/search-index.json',
  name: 'my-docs',
  baseUrl: 'http://localhost:3000',
}).listen(3456);

这让试用成本比较低。你可以先在本地构建 Docusaurus，跑一个 Node MCP server，用 MCP Inspector 或 Claude Code 连接验证；确认效果后，再把 endpoint 放到自己的 edge/serverless 平台。

它不是只做一个搜索索引

项目里有几个细节值得注意。

第一，内容抽取发生在 Docusaurus 已渲染的 HTML 之后。默认 content selector 会优先找 article、main、.main-wrapper、[role="main"]，同时排除 nav、header、footer、aside 等噪声区域。这比直接读 Markdown 更接近最终页面，也更适合有 MDX component 的文档。

第二，搜索层是可替换的。默认会使用 FlexSearch 生成本地索引，但 README 也给出了自定义 ContentIndexer 和 SearchProvider 的接口。团队如果已经把文档同步到 Algolia、Glean 或内部搜索系统，可以在构建时推送文档，在运行时把 MCP search 委托给外部服务。

第三，它提供一个 McpInstallButton theme export。文档站可以在导航里放一个下拉按钮，给用户复制 Claude Code、Cursor / VS Code 等 MCP client 的配置。这不是核心能力，但对公开文档很有用：用户不用自己猜 endpoint URL 和配置格式。

验证链路也写进了工具

很多“把文档变成 AI 可读”的方案，最容易卡在部署后才发现索引缺文件、文档结构不对、MCP server 无法 initialize。这个插件提供了 docusaurus-mcp-verify CLI，在构建后检查 docs.json、search-index.json、manifest.json 是否存在，文档结构是否有效，以及 MCP server 能否加载内容。

这类检查很适合进 CI。文档站一旦把 MCP endpoint 当成正式接口，就不应该只靠手工连一次。构建时产物存在、结构正确、server 能 initialize，是最低限度的发布门槛。

适合什么场景

我认为它适合三类团队先试。

第一类是已经用 Docusaurus 写 SDK / API / 开发者平台文档的团队。你不需要换文档框架，只是在现有构建旁边多一个 MCP 输出。

第二类是希望让 Claude Code、Cursor、VS Code MCP client 或内部 agent 读取官方文档的项目。相比把文档复制进 prompt，MCP endpoint 更像稳定接口，也更容易更新。

第三类是有公开文档生态的开源项目。给用户一个 MCP install button，让他们把项目文档加到自己的 AI 工具里，比单纯告诉用户“去看 docs”更贴近现在的开发流程。

它不太适合拿来替代完整 RAG 平台。项目本身聚焦 Docusaurus 文档，默认搜索也是构建产物内的全文检索。如果你需要跨仓库权限控制、多源同步、用户级访问审计，还是应该接入更完整的搜索或知识库系统。不过它提供了自定义 provider 的入口，可以作为更大系统里的 Docusaurus adapter。

小结

scalvert/docusaurus-plugin-mcp-server 的价值不在于“又一个 MCP server”，而在于它抓住了一个非常具体的入口：Docusaurus 已经是很多开发者文档的事实标准，把这些文档变成 agent 可搜索、可 fetch、可部署的 MCP endpoint，应该尽量贴着现有构建流程走。

它的实现路线也比较稳：构建时抽取和索引，运行时只加载产物；MCP tool 保持少而明确；本地、serverless、edge runtime 都有接入方式；还有 verify CLI 做发布前检查。对已经维护 Docusaurus 文档、又希望 AI 工具能更准确引用自己资料的团队来说，这是一个很值得试跑的小插件。