星战科技xingzhan.cloud
返回市场
MCP文档服务器

MCP文档服务器

作者：ruan1122334449 星标更新：2025-03-31
安装使用来源：spider==github.com

项目介绍

McpDocServer

英文文档

基于MCP协议的开发文档服务器，专门设计用于各种开发框架文档。提供多线程文档爬取、本地文档加载、关键词搜索及文档详情检索等功能。

核心功能演示

1. 文档爬取演示

文档爬取演示

从配置到执行npm run crawl的完整文档爬取过程

2. MCP服务调用演示

MCP调用演示

通过光标查询API并获取精确文档结果的过程

解决光标幻觉问题

在使用光标进行各种框架开发时，我们经常遇到由AI对框架API理解不准确导致的“幻觉”问题：

  • 准确性问题AI可能会推荐不存在或过时的框架API和组件
  • 版本混淆混合不同版本的API文档会导致代码无法正常运行
  • 参数错误对方法参数理解不准确，特别是关于框架特定功能
  • 兼容性误判无法准确判断API在不同环境或平台上的兼容性

此MCP服务器通过提供精准的文档检索能力有效解决了上述问题：

  • 实时且准确的查询直接从官方文档来源获取最新且准确的API信息
  • 上下文关联关联并展示相关的API和组件文档，提供完整的参考
  • 准确的参数匹配提供完整的方法签名和参数列表以消除参数错误
  • 跨平台兼容性标签明确标识API在不同平台上的兼容性
  • 示例代码提供官方示例代码确保正确使用

通过集成此MCP服务器，可以显著提高光标在各种框架开发过程中的准确性和效率，避免因“幻觉”而产生的开发障碍。

特性

  • 支持从本地JSON文件加载框架文档数据
  • 提供强大的文档搜索功能
  • 提供文档详情查询
  • 自动识别可用文档来源
  • 支持针对特定文档来源的目标查询
  • 支持爬取外部文档并自动转换为本地可用格式
  • 支持重新加载文档（通过搜索'reload'触发）

目录结构

/
├── server.js              # 服务器入口文件
├── docs/                  # 文档数据目录
│   ├── taro-docs.json     # Taro框架文档
│   └── taroify-docs.json  # Taroify组件库文档
├── scripts/               # 脚本目录
│   └── crawl.js           # 文档爬取脚本
├── tests/                 # 测试目录
│   └── mcp.test.js        # MCP测试脚本
├── config/                # 配置文件目录
│   └── doc-sources.js     # 文档源配置
└── package.json           # 项目配置

安装与操作

如果你已经安装了Chrome浏览器，并希望puppeteer使用你已有的版本，你可以设置PUPPETEER_SKIP_OWNLOAD环境变量：

macOS/Linux:

export PUPPETEER_SKIP_DOWNLOAD=true
npm install

Windows (命令提示符)：

set PUPPETEER_SKIP_DOWNLOAD=true
npm install

Windows (PowerShell)：

$env:PUPPETEER_SKIP_DOWNLOAD = $true
npm install
  1. 爬取文档数据

爬虫用于获取框架文档，是使用服务器之前的重要步骤。你需要首先创建一个爬虫配置文件，然后运行爬虫脚本。

创建爬虫配置

在config目录中创建doc-sources.js文件，参考以下格式：

// config/doc-sources.js

// 文档源配置
export const docSources = [
    {
        // 文档源名称 - 作为搜索时的source参数
        name: "taro",
        // 文档网站基础URL
        url: "https://docs.taro.zone/docs",
        // 包含模式 - 指定要爬取的URL路径（空数组表示所有页面）
        includePatterns: [
        ],
        // 排除模式 - 指定不爬取的URL路径（支持正则表达式）
        excludePatterns: [
            /\d\.x/,   // 排除版本号页面
            /apis/     // 排除API页面
        ]
    },
    {
        name: "taroify",
        url: "https://taroify.github.io/taroify.com/introduce/",
        includePatterns: [
            "/components/",          // 所有组件页面
            "/components/*/",        // 组件子页面
            "/components/*/*/"       // 组件子子页面
        ],
        excludePatterns: []
    },
    {
        name: "jquery",
        url: "https://www.jquery123.com/",
        includePatterns: [],         // 空数组表示爬取所有页面
        excludePatterns: [
            /version/               // 排除版本相关页面
        ]
    }
];

// 爬虫全局配置
export const crawlerConfig = {
    // 并行抓取的线程数
    maxConcurrency: 40,
    // 页面加载超时时间(毫秒)
    pageLoadTimeout:  30000,
    // 内容加载超时时间(毫秒)
    contentLoadTimeout: 5000,
    // 是否显示浏览器窗口（false为无界面模式）
    headless: false,
    // 重试次数
    maxRetries: 3,
    // 重试间隔(毫秒)
    retryDelay: 2000,
    // 请求间隔(毫秒)
    requestDelay: 1000
};

运行爬虫

配置完成后，执行以下命令启动爬虫：

npm run crawl

爬虫将根据配置自动爬取指定的文档网站，并保存符合MCP服务器要求的JSON格式的结果。

爬虫输出示例

爬虫完成后，将在docs目录生成如下格式的JSON文件：

{
  "source": {
    "name": "taro",
    "url": "https://docs.taro.zone/docs"
  },
  "lastUpdated": "2024-05-20T12:00:00.000Z",
  "pages": {
    "https://docs.taro.zone/docs/components-desc": {
      "title": "组件库说明 | Taro 文档",
      "content": "页面内容...",
      "lastCrawled": "2024-05-20T12:00:00.000Z"
    },
    "https://docs.taro.zone/docs/components/viewcontainer/view": {
      "title": "View | Taro 文档",
      "content": "View 组件是一个容器组件...",
      "lastCrawled": "2024-05-20T12:00:00.000Z"
    }
    // ... 更多页面
  }
}

自定义爬虫

如果需要自定义爬虫行为，可以修改scripts/crawl.js文档。你可以添加特定网站的解析逻辑，自定义内容处理，或增强爬取能力。

  1. 启动MCP服务器
npm start

启动后，服务器将检测并加载docs目录中的文档文件，并通过MCP协议提供接口服务。服务器将输出加载的文档源信息和页面数量。

  1. 运行测试
npm test

执行测试脚本来验证MCP服务器的基本功能和接口是否正常工作。

文档格式

文档文件应为包含以下结构的JSON文件：

{
  "source": {
    "name": "taro",
    "url": "https://docs.taro.zone/docs"
  },
  "lastUpdated": "2024-03-27T12:00:00.000Z",
  "pages": {
    "https://docs.taro.zone/docs/components-desc": {
      "title": "组件库说明 | Taro 文档",
      "content": "页面内容..."
    },
    // 更多页面...
  }
}

文档加载过程：

  1. 服务器启动时将自动检测并加载docs目录中的JSON文件
  2. 如果项目目录中找不到文档，则尝试从当前工作目录加载
  3. 页面ID默认使用URL作为键，无需额外指定URL字段
  4. 所有源名称将自动转换为小写以确保一致性

爬虫功能

系统内置的爬虫支持从各种框架官方文档站点爬取内容并将其转换为本地可用的文档格式。爬虫特性包括：

  1. 多站点支持支持任何框架和库的文档网站，完全可配置
  2. 选择性爬取可以通过配置包含和排除模式来精确控制需要爬取的内容
  3. 智能内容提取自动识别文档页面的标题、正文内容和结构
  4. 多线程爬取支持高并发爬取以提高效率
  5. 自动转换将爬取的内容转换为标准文档JSON格式
  6. 容错机制提供超时处理和重试机制以增强稳定性

MCP工具

服务器提供了以下MCP工具：

  1. search_docs - 搜索文档

    • 参数：
      • query：搜索关键词（字符串，必填）
      • source：文档源名称（字符串，可选）
      • limit：最大结果数（数字，可选，默认值为10）
    • 特殊功能：
      • 当查询为'reload'时，将触发文档重新加载

  2. get_doc_detail - 获取文档详情

    • 参数：
      • id：文档ID（字符串，必填）
      • source：文档源名称（字符串，可选）

使用示例

// 搜索文档
const searchRequest = {
  jsonrpc: "2.0",
  id: "search1",
  method: "tools/call",
  params: {
    name: "search_docs",
    arguments: { 
      query: "组件", 
      source: "taro", 
      limit: 5 
    }
  }
};

// 获取文档详情
const detailRequest = {
  jsonrpc: "2.0",
  id: "detail1",
  method: "tools/call",
  params: {
    name: "get_doc_detail",
    arguments: { 
      id: "https://docs.taro.zone/docs/components-desc", 
      source: "taro" 
    }
  }
};

// 重新加载文档
const reloadRequest = {
  jsonrpc: "2.0",
  id: "reload1",
  method: "tools/call",
  params: {
    name: "search_docs",
    arguments: { 
      query: "reload" 
    }
  }
};

配置光标

要在光标中使用此服务器，需要添加以下配置mcp.json：

{
  "mcpServers": {
    "文档 MCP 服务器": {
      "command": "node",
      "args": ["/绝对路径/server.js"],
      "env": { "NODE_ENV": "development" }
    }
  }
}

注意：请确保使用服务器文件的完整绝对路径而不是相对路径。当服务器启动时，它将自动输出适用于光标的配置示例。

测试

项目包含自动化测试，可以使用以下命令运行：

npm test

测试将检查服务器的基本功能：

  • 初始化MCP服务器
  • 调用搜索工具
  • 调用文档详情工具

未来计划

该项目目前处于持续开发中，以下是我们的计划增加的功能：

  1. 本地文档加载 - 添加直接加载和解析本地文档文件而不依赖网络资源的功能
  2. 国际化支持 - 添加对多语言文档的支持

如果您有任何功能建议或问题，请随时提交Issue或Pull Request。