Giving AI agents knowledge they were never trained on

为 AI Agent 赋予其训练数据之外的知识

I love coding my own stuff, and my clients typically have lots of internal specifications and libraries to use. But since LLMs haven’t been trained on that, it’s hard to get them to code accurately using those specs, libraries, or frameworks. You can, of course, let the agents parse everything, but that wastes tokens and your patience :) The same goes for well-known libraries, but you are stuck on a specific version that you must follow. You don’t want it to guess the API. docs-mcpserver exists to deal with both. 我热爱编写自己的项目，而我的客户通常有许多内部规范和库需要使用。但由于大语言模型（LLM）并未针对这些内容进行过训练，很难让它们准确地使用这些规范、库或框架进行编码。当然，你可以让 Agent 解析所有内容，但这会浪费 Token 且考验你的耐心 :) 同样的情况也适用于知名库，但如果你必须遵循某个特定版本，你肯定不希望 AI 去猜测 API。docs-mcpserver 的出现正是为了解决这两个问题。

What it is

它是什么

It is an MCP server that provides an agent with accurate knowledge of a framework or specification using documentation as the medium. It reads three kinds of docs: 它是一个 MCP 服务器，通过文档作为媒介，为 Agent 提供关于框架或规范的准确知识。它支持读取三种类型的文档：

Markdown docs — your *.md files.
API reference — C# XML documentation, or TypeDoc JSON.
Schema — JSON Schema, OpenAPI 3.x, Swagger 2.0.
Markdown 文档 — 你的 *.md 文件。
API 参考 — C# XML 文档或 TypeDoc JSON。
Schema — JSON Schema、OpenAPI 3.x、Swagger 2.0。

What the agent gets out of it is the same in every case: the real names, the real signatures, the real shapes. Sources can come from a local folder or straight from a GitHub URL. A single server instance can host several libraries side by side. For instance, your in-house framework, a client’s framework, and a specific version of some public library. The agent picks which one to query. I personally have used it to code against a specification called DATEX (traffic information for roads), which is HUGE, my own SPA library, and against sound format specifications for a sound app I’m building. 无论哪种情况，Agent 获得的结果都是一致的：真实的名称、真实的签名和真实的结构。数据源可以来自本地文件夹，也可以直接来自 GitHub URL。单个服务器实例可以同时托管多个库，例如你的内部框架、客户的框架以及某个公共库的特定版本。Agent 会自行选择查询哪一个。我个人曾用它来针对 DATEX（道路交通信息）规范进行编码（该规范非常庞大），也用它处理过我自己的 SPA 库，以及我正在开发的音频应用的音频格式规范。

Why not just give the agent the files

为什么不直接把文件给 Agent？

You could point the agent to the folders and let it read them. The MCP server does a few things that raw file access does not: 你当然可以直接让 Agent 指向文件夹并读取它们。但 MCP 服务器提供了一些原始文件访问所不具备的功能：

It is sandboxed. Each source is scoped, with path-traversal protection. The agent reads what you exposed, nothing else on the disk.
It reads in pieces. Instead of loading a 4000-line reference file, the agent asks for the table of contents, then pulls the one chapter it needs.
It searches properly. Dedicated search tools with regex and glob support, instead of the agent improvising its own grep.
It is self-describing. With several libraries configured, the agent calls one tool to discover what is available. You do not have to spell out every path.
GitHub works without cloning. Give it a repo URL and it handles the rest.
沙盒化：每个数据源都有作用域限制，并具备路径遍历保护。Agent 只能读取你暴露的内容，无法访问磁盘上的其他部分。
分段读取：无需加载 4000 行的参考文件，Agent 可以先请求目录，然后只提取所需的章节。
精准搜索：提供支持正则表达式和 glob 的专用搜索工具，而不是让 Agent 自己去“即兴”使用 grep。
自描述性：配置多个库后，Agent 只需调用一个工具即可发现可用内容，无需你手动列出每个路径。
无需克隆即可使用 GitHub：只需提供仓库 URL，它会自动处理其余部分。

The multi-library part is the point. Instead of running several MCP servers for documentation, you get one with a small toolset. No token waste. 多库支持是核心所在。你不需要为文档运行多个 MCP 服务器，只需一个带有小型工具集的服务器即可。不会浪费 Token。

Setting it up

如何设置

Install and build: 安装并构建：

npm install
npm run build

The quick way, a single folder: 快速上手（单个文件夹）：

docs-mcpserver ./docs --name "My Docs"

For the real use case — several libraries — use a config file. Here is an in-house framework served from disk, next to a pinned version of a public library pulled from GitHub: 对于实际应用场景（多个库），请使用配置文件。以下是一个从磁盘提供的内部框架，以及一个从 GitHub 拉取的公共库固定版本：

{
  "name": "dev-docs",
  "description": "Frameworks the model has not been trained on",
  "cacheDir": "./cache",
  "libraries": [
    {
      "name": "acme-core",
      "description": "Our internal application framework",
      "sources": [
        { "type": "disk", "origin": "./frameworks/acme-core/docs", "kind": "docs" },
        { "type": "disk", "origin": "./frameworks/acme-core/api", "kind": "api" }
      ]
    },
    {
      "name": "somelib-3.2",
      "description": "SomeLib, pinned to v3.2.0",
      "sources": [
        { "type": "github", "origin": "https://github.com/someorg/somelib/tree/v3.2.0/docs", "kind": "docs" }
      ]
    }
  ]
}

Start it with the config: 使用配置文件启动：

docs-mcpserver --config dev-docs.json

And register it with Claude Code: 并在 Claude Code 中注册：

claude mcp add mydocs -- node /path/to/markdown-docs-mcp/dist/index.js --config /path/to/dev-docs.json

For private GitHub repos, set GITHUB_TOKEN in the environment. 对于私有 GitHub 仓库，请在环境变量中设置 GITHUB_TOKEN。

What the agent actually sees

Agent 实际看到的内容

Each library exposes tools based on the kind of its sources: 每个库根据其数据源类型暴露不同的工具：

docs — get_doc_index, get_sub_index, read_doc_file, get_file_toc, get_chapters, search_docs.
api — get_api_index, get_api_type, get_api_member, search_api.
schema — list_schemas, list_definitions, get_definition, search_definitions, search_all_schemas.

A typical run looks like this. The agent calls list_libraries and sees acme-core and somelib-3.2. It needs to know how acme-core handles configuration, so it calls search_docs with library: "acme-core", finds the right file, asks for its table of contents with get_file_toc, then pulls the one relevant section with get_chapters. It answers the question without ever loading the whole file. 典型的运行流程如下：Agent 调用 list_libraries 并看到 acme-core 和 somelib-3.2。如果它需要了解 acme-core 如何处理配置，它会使用 library: "acme-core" 调用 search_docs，找到正确的文件，通过 get_file_toc 请求目录，然后通过 get_chapters 提取相关章节。它无需加载整个文件即可回答问题。

When multiple libraries are configured, every tool takes a library parameter. When there is only one, the parameter disappears, and the tools behave like a plain single-library server. The same applies to schema sources. For an OpenAPI spec, path operations show up as definitions named like GET /pets, so the agent can ask for one endpoint without reading the whole document. Useful when you want the agent to call your API correctly rather than guess at the shape of it. 当配置了多个库时，每个工具都需要一个 library 参数。如果只有一个库，该参数会自动消失，工具表现得就像一个普通的单库服务器。Schema 数据源也是如此。对于 OpenAPI 规范，路径操作会显示为类似 GET /pets 的定义，因此 Agent 可以只查询一个端点，而无需读取整个文档。当你希望 Agent 正确调用你的 API 而不是猜测其结构时，这非常有用。

Generating the API input

生成 API 输入

One thing worth knowing up front: the api pipeline does not read source code. It consumes a generated documentation file. 有一点需要提前说明：API 流水线不会读取源代码，它消耗的是生成的文档文件。

TypeScript / JavaScript — use TypeDoc’s JSON serializer: typedoc --json api.json src/index.ts. Point the source at that .json file. The markdown output from typedoc-plugin-markdown is not supported — it has to be the JSON serializer output.
C# — enable <GenerateDocumentationFile>true</GenerateDocumentationFile> and point the source at the generated *.xml file, or the build output folder that contains it.
TypeScript / JavaScript — 使用 TypeDoc 的 JSON 序列化器：typedoc --json api.json src/index.ts。将数据源指向该 .json 文件。不支持 typedoc-plugin-markdown 生成的 Markdown 输出，必须是 JSON 序列化器的输出。
C# — 启用 <GenerateDocumentationFile>true</GenerateDocumentationFile>，并将数据源指向生成的 *.xml 文件或包含它的构建输出文件夹。

What it does not do

它不做什么

It does not read source code. If you want API reference, you generate the doc file first, as above. 它不会读取源代码。如果你需要 API 参考，请先按照上述方法生成文档文件。

Try it

尝试一下

The code is on GitHub, or on npm as docs-mcpserver. Feel free to leave feedback, or check my other MCP servers on GitHub. 代码已发布在 GitHub 上，或通过 npm 以 docs-mcpserver 名称提供。欢迎留下反馈，或查看我在 GitHub 上的其他 MCP 服务器。