Docs Fetch MCP Server

Docs Fetch MCP Server

一个基于 Bun 的 Model Context Protocol（MCP）服务，用于获取文档页面并进行有界文档爬取。

该服务提供一个 MCP 工具 fetch_doc_content。它会获取根 URL，提取易读的 Markdown，对链接进行排序，并可在明确的深度、页面数量、超时和范围限制内爬取关联页面。结果以结构化 JSON 返回，包含爬取元数据、页面内容、排序后的链接、截断标记和各页面的错误。

功能

• 使用 axios 实现快速静态获取
• 可选使用 Puppeteer 渲染客户端渲染或内容较少的页面
• 提取包含标题、列表、代码块、表格、引用块和链接的 Markdown
• 真实的爬取深度语义：
  • depth: 1 仅返回根页面
  • depth: 2 包含直接子链接
  • depth: 3 包含孙辈页面，最大值为 5
• 去重前规范化 URL：移除片段、跟踪参数、默认端口和尾部斜杠重复项
• 按同源和可选的 pathPrefix 限定爬取范围
• 限定 maxPages、maxConcurrency、全局超时、单页超时和单页内容截断
• 返回包含明确单页失败信息的部分结果
• 运行时参数验证与公布的工具架构共用

要求

• Bun >=1.3.0
• 当 render 为 auto 或 always 时，需要安装 Puppeteer 浏览器

本项目使用 Bun 进行依赖管理、运行时执行、构建和测试。

安装

bun install
bun run build

配置 MCP 客户端：

{
  "mcpServers": {
    "docs-fetch": {
      "command": "bun",
      "args": ["/path/to/docs-fetch-mcp/build/index.js"]
    }
  }
}

无需构建即可进行本地开发：

{
  "mcpServers": {
    "docs-fetch": {
      "command": "bun",
      "args": ["/path/to/docs-fetch-mcp/src/index.ts"]
    }
  }
}

工具

fetch_doc_content

获取一个 URL，并可选择爬取其关联页面。

参数：

名称	类型	默认值	限制	说明
url	string	必填	仅限 HTTP/HTTPS	要获取的根 URL。
depth	number	1	1 到 5	与根页面的链接距离。
maxPages	number	10	1 到 50	整次爬取最多返回的页面数。
maxConcurrency	number	3	1 到 8	同时获取的最大页面数。
timeoutMs	number	45000	5000 到 120000	全局爬取超时时间。
perPageTimeoutMs	number	10000	1000 到 60000	单页获取超时时间。
render	string	auto	auto、always、never	浏览器渲染策略。
sameOrigin	boolean	true	不适用	将爬取的链接限制为同源。
pathPrefix	string	省略	不适用	可选的路径前缀爬取范围，例如 /docs。
contentLimit	number	12000	1000 到 50000	截断前每页的 Markdown 字符数。
includeLinks	boolean	true	不适用	在返回的页面对象中包含排序后的链接。

请求示例：

{
  "url": "https://example.com/docs",
  "depth": 2,
  "maxPages": 8,
  "pathPrefix": "/docs",
  "render": "auto"
}

响应结构：

{
  "rootUrl": "https://example.com/docs",
  "normalizedRootUrl": "https://example.com/docs",
  "explorationDepth": 2,
  "maxPages": 8,
  "pagesExplored": 3,
  "pagesFailed": 1,
  "timedOut": false,
  "durationMs": 1234,
  "crawl": {
    "sameOrigin": true,
    "pathPrefix": "/docs",
    "maxConcurrency": 3,
    "render": "auto",
    "perPageTimeoutMs": 10000
  },
  "content": [
    {
      "url": "https://example.com/docs",
      "finalUrl": "https://example.com/docs",
      "depth": 0,
      "status": 200,
      "title": "Documentation",
      "description": "Example documentation",
      "canonicalUrl": "https://example.com/docs",
      "headings": ["Documentation"],
      "content": "# Documentation\n\n...",
      "contentLength": 2400,
      "truncated": false,
      "fetchedWith": "http",
      "links": [
        {
          "url": "https://example.com/docs/api",
          "text": "API reference",
          "score": 18.5,
          "internal": true
        }
      ]
    }
  ],
  "errors": [
    {
      "url": "https://example.com/docs/missing",
      "depth": 1,
      "error": "Request failed with status code 404",
      "status": 404
    }
  ]
}

爬取行为

• 爬取采用广度优先方式。
• URL 在去重和加入队列前会先进行规范化。
• sameOrigin: true 会拒绝来源与规范化根 URL 不同的链接。
• pathPrefix 会进一步将链接限制在根来源的指定路径前缀内。
• includeLinks: false 会隐藏返回页面对象中的链接，但不会禁用用于爬取的链接发现。
• render: "never" 仅使用 HTTP 获取方式。
• render: "always" 对每个获取的页面都使用 Puppeteer。
• render: "auto" 会先尝试 HTTP；当 HTTP 失败或提取的内容非常少时，再使用 Puppeteer。
• 浏览器回退目前会保留渲染后的响应状态，并提取页面正文，即使页面状态码不是 2xx。

架构

src/index.ts                         CLI entrypoint
src/server.ts                        MCP server wiring and tool registration
src/config/tool-options.ts           Shared tool schema/default/range metadata
src/tool/fetch-doc-content-args.ts   Runtime argument validation
src/crawler/docs-crawler.ts          Crawl orchestration and queue management
src/crawler/page-fetcher.ts          HTTP fetch, browser fallback, extraction coordination
src/browser/browser-manager.ts       Reusable Puppeteer browser/page handling
src/content/content-extractor.ts     Page metadata/content extraction facade
src/content/main-content-selector.ts Main content selection
src/content/link-extractor.ts        Link normalization, dedupe, and ranking
src/content/markdown-renderer.ts     HTML-to-Markdown rendering
src/content/text-cleanup.ts          Shared text normalization helpers
src/utils/url.ts                     URL normalization and scope utilities
src/types/index.ts                   Shared TypeScript types

MCP 架构和运行时选项规范化共用 src/config/tool-options.ts 中的元数据源。添加新选项时，先在此处定义，再通过验证和爬虫选项接入相应行为。

开发

bun install
bun run dev
bun run test
bun run typecheck
bun run build

脚本：

• bun run dev：从 TypeScript 源代码运行 MCP 服务。
• bun run test：运行 src 下的 Bun 测试。
• bun run typecheck：使用 --noEmit 运行 TypeScript。
• bun run build：生成带有 Bun shebang 的 build/index.js。
• bun run start：运行构建后的 MCP 服务。

测试

测试与其覆盖的模块放在一起：

• src/crawler/docs-crawler.test.ts：爬取深度、范围限定、故障和链接可见性。
• src/crawler/page-fetcher.test.ts：抓取/渲染回退特征。
• src/content/content-extractor.test.ts：Markdown 提取和截断。
• src/tool/fetch-doc-content-args.test.ts：边界验证以及架构/默认值同步。
• src/utils/url.test.ts：URL 规范化和范围辅助函数。

更改行为时，请先添加或更新特征测试。进行重构时，确保 bun run test、bun run typecheck 和 bun run build 均通过。

注意事项

• 对于快速的静态文档爬取和测试，请使用 render: "never"。
• 对于与营销页面、博客或应用共享域名的文档站点，请使用 pathPrefix。
• 仅当调用方使用 render: "never" 时，才可以跳过 Puppeteer 浏览器安装。
• 自定义 Markdown 渲染器有意通过特征测试进行覆盖；除非明确更改行为，否则请保持输出兼容性。

许可证

MIT