阅读文档-MCP

Name: 阅读文档-MCP
Author: ZebraRoy

作者：ZebraRoy4 星标更新：2025-06-17

安装使用来源：spider==github.com

项目介绍

技术文档摘要

read-docs-mcp

一个模型上下文协议（MCP）服务器，使AI代理能够通过结构化接口访问和理解包文档。

功能

自动从文档结构生成MCP工具
支持多个文档模块（钩子、组件、实用工具等）
可配置的文档文件和模块文件夹命名模式
提供列表、概述和详细文档访问
根据配置的模块动态生成工具
使用package.json作为版本信息的回退
可自定义的文档路径
模糊搜索功能，根据关键词智能优先级查找文件

双重使用模式

此MCP服务器有两种不同的使用模式：

阅读文档模式 (read-docs-{name})：当同时提供name和git-repo-path时，服务器作为指定仓库的文档阅读器，生成访问文档的工具。
创建文档模式 (create-read-docs)：当没有提供仓库信息时，服务器作为创建文档结构的指南，提供如何设置文档文件的说明。

配置

MCP支持以下命令行参数：

--name：包或库的名称（在阅读文档模式下必需）
--git-repo-path：git仓库路径（http或ssh）（在阅读文档模式下必需）
- 如果未提供，MCP服务器仅提供构建说明
--personal-token：用于git认证的个人访问令牌（可选）
- 推荐用于私有仓库
- 支持GitHub、GitLab、Bitbucket和通用Git托管
--branch：读取文档的分支
- 默认值：main
--docs-path：文档文件夹路径
- 默认值：docs
--clone-location：克隆git仓库的路径
- 默认值：{os home directory}/.temp-repo
--mode：MCP服务器的操作模式
- 选项：normal（默认），two-step
- 详情见操作模式部分
--include-src：包含源代码阅读能力（可选）
- 设置为true以启用从仓库中读取源文件
- 默认值：false
- 启用后，添加一个工具来读取源代码文件以获取额外的实现细节

关于Git认证的重要说明

此MCP需要直接克隆目标git仓库。您必须确保在使用此工具前拥有对仓库的适当访问权限。对于私有仓库，您有几个认证选项：

使用个人访问令牌（推荐）：通过--personal-token参数传递您的个人访问令牌。这是最可靠的方法，并且适用于所有主要的Git托管提供商。
SSH密钥：在本地机器上配置SSH密钥以用于SSH URL
Git凭证存储：在机器上配置Git凭证存储以用于HTTPS URL

使用个人访问令牌：

# 使用HTTPS URL
npx -y read-docs-mcp --name=MyDocs --git-repo-path=https://github.com/user/private-repo --personal-token=your_personal_access_token_here

# 使用SSH URL（自动转换为HTTPS）
npx -y read-docs-mcp --name=MyDocs --git-repo-path=git@gitlab.service-hub.tech:frontend/private-repo.git --personal-token=your_personal_access_token_here

MCP支持个人访问令牌用于HTTPS和SSH URL：

HTTPS URL：

GitHub：直接在HTTPS URL中使用令牌
GitLab（包括自托管）：使用带有令牌的OAuth2格式
Bitbucket：使用token-auth格式
通用Git托管：使用GitLab风格的OAuth2格式

SSH URL： 当提供个人令牌时，SSH URL会自动转换为带适当认证的HTTPS：

SSH：git@gitlab.service-hub.tech:frontend/repo.git
HTTPS：https://oauth2:token@gitlab.service-hub.tech/frontend/repo.git

如果没有适当的认证，MCP将无法克隆私有仓库。

操作模式

运行MCP服务器时，您可以使用--mode参数指定不同的模式：

正常模式（默认）

npx -y read-docs-mcp --name=MyDocs --git-repo-path=https://github.com/user/repo
# 或显式地：
npx -y read-docs-mcp --name=MyDocs --git-repo-path=https://github.com/user/repo --mode=normal

在正常模式下，服务器为每个模块和操作创建单独的工具（例如，get-hooks-list，get-hooks-details，get-components-list等）。

两步模式

npx -y read-docs-mcp --name=MyDocs --git-repo-path=https://github.com/user/repo --mode=two-step

在两步模式下，服务器不会为每个模块创建单独的工具，而是创建这五个通用工具：

get-overview - 获取项目概述（与正常模式相同）
get-overall-list - 获取所有可用模块的列表
get-module-overview - 获取特定模块的概述（参数为模块名称）
get-module-list - 获取特定模块中的项目列表（参数为模块名称）
get-module-detail - 获取模块中特定项目的详细信息（参数为模块和项目名称）

这种方法显著减少了工具总数，使得MCP服务器更高效且易于管理。

在Cursor中设置

要在Cursor中使用此MCP，请向您的Cursor设置添加以下配置：

阅读文档模式（Mac/Linux）

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName"
      ]
    }
  }
}

阅读文档模式（带源码访问）（Mac/Linux）

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName",
        "--include-src=true"
      ]
    }
  }
}

创建文档模式（Mac/Linux）

{
  "mcpServers": {
    "create-read-docs": {
      "command": "npx",
      "args": ["-y", "read-docs-mcp"]
    }
  }
}

阅读文档模式（Windows）

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName"
      ]
    }
  }
}

阅读文档模式（带源码访问）（Windows）

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName",
        "--include-src=true"
      ]
    }
  }
}

创建文档模式（Windows）

{
  "mcpServers": {
    "create-read-docs": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "read-docs-mcp"]
    }
  }
}

自定义文档路径

如果您想指定自定义文档目录：

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName",
        "--docs-path=documentation"
      ]
    }
  }
}

两步模式配置

为了更好地处理大型文档集，使用两步模式：

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName",
        "--mode=two-step"
      ]
    }
  }
}

私有仓库与个人令牌

使用个人访问令牌访问私有仓库：

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/private-repo",
        "--name=YourLibName",
        "--personal-token=your_personal_access_token_here"
      ]
    }
  }
}

自托管GitLab与SSH URL

对于使用SSH URL的自托管GitLab实例：

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=git@gitlab.some-host.com:some-group/your-repo.git",
        "--name=YourLibName",
        "--personal-token=your_gitlab_access_token_here"
      ]
    }
  }
}

安全提示：安全地存储您的个人访问令牌。考虑使用环境变量而不是在配置中硬编码令牌。

文档结构

MCP服务器期望以下结构用于阅读文档模式：

仓库/
├── docs/ （可配置）
│   ├── read-docs-mcp.json
│   ├── hooks/
│   │   ├── read-module-docs-mcp.json
│   │   ├── list.md
│   │   ├── overview.md
│   │   ├── use-state.md
│   │   └── ...
│   ├── components/
│   │   ├── read-module-docs-mcp.json
│   │   └── ...
│   └── ...
└── package.json

主配置：read-docs-mcp.json

{
  "name": "SomeLibrary",
  "description": "一个用于某种目的的库",
  "version": "1.0.1",
  "moduleList": ["hooks", "components", "directives", "utils"],
  "fileName": "overview.md",
  "moduleFolderNamingPattern": "kebab"
}

name，description：用于MCP服务器构建
version：如果未提供，则回退到package.json中的版本，或默认为"0.1.0"
moduleList：文档模块列表；如果未提供，则使用docs目录下的所有文件夹
fileName：用于概述的文件。如果未提供，默认为"overview.md"
moduleFolderNamingPattern：模块文件夹的命名模式。可以是"kebab"，"camel"，"snake"，"pascal"或"original"。默认为"kebab"

命名模式规则

支持以下命名模式用于模块文件夹和详细文件：

kebab-case（默认）：单词小写并用连字符分隔
- 示例："form-control"，"use-state"，"data-table"
camelCase：第一个单词小写，后续单词大写且无分隔符
- 示例："formControl"，"useState"，"dataTable"
snake_case：单词小写并用下划线分隔
- 示例："form_control"，"use_state"，"data_table"
PascalCase：每个单词大写且无分隔符
- 示例："FormControl"，"UseState"，"DataTable"
original：使用模块列表中提供的名称，不做任何转换
- 示例：模块列表中的名称将直接用于目录名称

模块配置：read-module-docs-mcp.json

{
  "get-all": {
    "name": "get-hook-list",
    "description": "获取钩子列表",
    "fileName": "list.md"
  },
  "get-details": {
    "name": "get-hook-details",
    "description": "获取钩子的详细信息",
    "paramDescription": "钩子名称",
    "namingPattern": "kebab"
  },
  "get-overview": {
    "name": "get-hook-overview",
    "description": "获取钩子模块的概述",
    "fileName": "overview.md"
  }
}

与代理合作

使用阅读文档模式

当您已设置MCP服务器与仓库一起使用时，可以使用它来探索文档：

使用read-docs-{YourLibName} MCP，我想探索{YourLibName}的文档。你能：

1. 获取可用模块的概述
2. 显示可用的钩子列表
3. 提供特定钩子的详细信息
4. 给我组件模块的概述

我对了解这个库中的身份验证工作原理特别感兴趣。

使用创建文档模式

当您使用MCP服务器而没有仓库时，可以请求帮助创建文档：

使用create-read-docs MCP，我需要为我的库创建可用于read-docs-mcp的文档。你能帮我设置所需的结构和文件吗？

阅读文档模式示例提示

探索包文档

使用read-docs-{PackageName} MCP，我想探索[包名称]的文档。你能：

1. 获取可用模块的概述
2. 显示可用的钩子列表
3. 提供useAuth钩子的详细信息
4. 给我组件模块的概述

我对了解这个库中的身份验证工作原理特别感兴趣。

学习如何使用组件

使用read-docs-{PackageName} MCP，我需要用[包名称]库实现一个带有验证的表单。请：

1. 显示可用的组件
2. 获取Form组件的详细信息
3. 获取Input组件的详细信息
4. 解释如何使用这些组件进行表单验证

如果有文档中的代码示例，请高亮显示它们。

使用模糊搜索查找文档

使用read-docs-{PackageName} MCP，我在寻找关于库中身份验证的文档。你能：

1. 使用模糊搜索找到所有与“auth”相关的文件
2. 根据搜索结果，获取最相关身份验证文档的详细信息
3. 展示如何使用库实现身份验证

模糊搜索应帮助我们快速定位相关文档文件。

阅读源代码以了解实现细节

使用read-docs-{PackageName} MCP（配置为--include-src=true），我需要了解useAuth钩子是如何实现的。请：

1. 首先，获取useAuth钩子的文档详细信息
2. 根据文档，阅读useAuth的源代码文件以了解实现
3. 根据文档和源代码解释身份验证流程的工作方式

请记住，首先优先考虑文档，然后仅在需要额外实现细节时才使用源代码。

创建文档模式示例提示

使用create-read-docs MCP，我需要为我的React组件库设置文档。你能帮我创建文件夹结构和必要的配置文件吗？

使用create-read-docs MCP，我已经开始为我的实用函数创建文档。应该如何为各个实用函数创建详细的文档？

工具

阅读文档模式工具

MCP根据文档结构和操作模式动态生成工具。所有工具都以前缀为包名称，以避免在使用多个read-docs-mcp实例时发生冲突。

正常模式工具

在正常模式下，对于moduleList中的每个模块，最多可以生成三个工具，加上一个可选的源文件阅读工具：

{name}-get-[module]-list

获取模块中的所有项目列表。

参数：

列表文件的内容（默认：list.md）

{name}-get-[module]-details

获取模块中特定项目的详细信息。

参数：

name（字符串）：要获取详细信息的项目名称

根据namingPattern命名的详细文件内容（默认为kebab-case）

{name}-get-[module]-overview

获取模块的概述。

参数：

概述文件的内容（默认：overview.md）

{name}-fuzzy-search

按关键词智能优先级搜索文件。

参数：

keyword（字符串）：在文件名和内容中搜索的关键词

匹配文件的格式化列表，优先级如下：
1. 文件名完全匹配
2. 文件名部分匹配
3. 文件内容完全匹配
4. 文件内容部分匹配

结果格式如下：

类型：模块
名称：someModule

或

类型：详细
名称：someDetail
模块：someModule

两步模式工具

在两步模式下，MCP生成五个通用工具，而不是为每个模块生成单独的工具，加上一个可选的源文件阅读工具：

{name}-get-overview

获取项目概述。

参数：

主概述文件的内容

{name}-get-overall-list

获取所有可用模块的列表。

参数：

文档中所有模块的列表

{name}-get-module-overview

获取特定模块的概述。

参数：

module（字符串）：模块名称

模块概述文件的内容

{name}-get-module-list

获取特定模块中的项目列表。

参数：

module（字符串）：模块名称

模块列表文件的内容

{name}-get-module-detail

获取模块中特定项目的详细信息。

参数：

module（字符串）：模块名称
name（字符串）：要获取详细信息的项目名称

项目详细文件的内容