read-docs-mcp

read-docs-mcp

一种模型上下文协议（MCP）服务，可通过结构化接口帮助 AI Agent 访问和理解软件包文档。

功能

• 根据文档结构自动生成 MCP 工具
• 支持多个文档模块（hooks、components、utilities 等）
• 可配置文档文件和模块文件夹的命名模式
• 提供列表、概览和详细文档访问
• 根据已配置的模块动态生成工具
• 从 package.json 获取版本信息作为备用
• 可自定义文档路径
• 支持模糊搜索，可通过关键词查找文件并智能排序

双模式

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

1. 读取文档模式（read-docs-{name}）：同时提供 name 和 git-repo-path 时，服务将作为指定仓库的文档阅读器，生成用于访问文档的工具。

2. 创建文档模式（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 仓库。使用此工具前，请确保你有权访问该仓库。对于私有仓库，你可以选择以下几种身份验证方式：

1. 使用个人访问令牌（推荐）：使用 --personal-token 参数传入个人访问令牌。这是最可靠的方式，适用于所有主流 Git 托管服务提供商。
2. SSH 密钥：为 SSH URL 在本地计算机上配置 SSH 密钥
3. Git 凭据存储：为 HTTPS URL 在计算机上配置 Git 凭据存储

使用个人访问令牌：

# With 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

# With SSH URL (automatically converted to HTTPS)
npx -y read-docs-mcp --name=MyDocs [email protected]: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 托管服务：使用 OAuth2 格式（GitLab 风格）

SSH URL： 提供个人令牌后，SSH URL 会自动转换为经过正确身份验证的 HTTPS URL：

• SSH：[email protected]:frontend/repo.git
• HTTPS：https://oauth2:[email protected]/frontend/repo.git

如果身份验证配置不正确，MCP 将无法克隆私有仓库。

运行模式

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

普通模式（默认）

npx -y read-docs-mcp --name=MyDocs --git-repo-path=https://github.com/user/repo
# or explicitly:
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

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

1. get-overview - 获取项目概览（与普通模式相同）
2. get-overall-list - 获取所有可用模块的列表
3. get-module-overview - 获取特定模块的概览（以模块名称为参数）
4. get-module-list - 获取特定模块中的项目列表（以模块名称为参数）
5. 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"
      ]
    }
  }
}

使用 SSH URL 的自托管 GitLab

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

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

安全提示：请妥善保管个人访问令牌。可考虑使用环境变量，而不是将令牌硬编码在配置中。

文档结构

对于阅读文档模式，MCP 服务需要采用以下结构：

repository/
├── docs/ (configurable)
│   ├── 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": "A library for some purpose",
  "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：完全使用 moduleList 中提供的名称，不做转换

  • 示例：moduleList 中的名称将原样用作目录名称

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

{
  "get-all": {
    "name": "get-hook-list",
    "description": "Get a list of hooks",
    "fileName": "list.md"
  },
  "get-details": {
    "name": "get-hook-details",
    "description": "Get details of a hook",
    "paramDescription": "A hook name",
    "namingPattern": "kebab"
  },
  "get-overview": {
    "name": "get-hook-overview",
    "description": "Get an overview of the hook module",
    "fileName": "overview.md"
  }
}

与 Agent 协作

使用阅读文档模式

使用仓库设置好 MCP 服务后，可以用它来浏览文档：

Using the read-docs-{YourLibName} MCP, I'd like to explore the documentation for {YourLibName}. Can you:

1. Get an overview of the available modules
2. Show me the list of hooks available
3. Provide details on a specific hook
4. Give me an overview of the components module

使用创建文档模式

不使用仓库时，可以向 MCP 服务寻求创建文档方面的帮助：

Using the create-read-docs MCP, I need to create documentation for my library that can be used with read-docs-mcp.
Can you help me set up the required structure and files?

阅读文档模式的提示词示例

浏览软件包文档

Using the read-docs-{PackageName} MCP, I'd like to explore the documentation for [Package Name]. Can you:

1. Get an overview of the available modules
2. Show me the list of hooks available
3. Provide details on the useAuth hook
4. Give me an overview of the components module

I'm particularly interested in understanding how authentication works in this library.

了解如何使用组件

Using the read-docs-{PackageName} MCP, I need to implement a form with validation using the [Package Name] library. Please:

1. Show me the available components
2. Get details on the Form component
3. Get details on the Input component
4. Explain how to use form validation with these components

If there are any code examples in the documentation, please highlight those.

使用模糊搜索查找文档

Using the read-docs-{PackageName} MCP, I'm looking for documentation about authentication in the library. Can you:

1. Use fuzzy search to find all files related to "auth"
2. Based on the search results, get the details for the most relevant authentication documentation
3. Show me how to implement authentication using the library

The fuzzy search should help us quickly locate the relevant documentation files.

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

Using the read-docs-{PackageName} MCP (configured with --include-src=true), I need to understand how the useAuth hook is implemented. Please:

1. First, get the documentation details for the useAuth hook
2. Based on the documentation, read the source code file for useAuth to understand the implementation
3. Explain how the authentication flow works based on both the documentation and source code

Remember to prioritize the documentation first, then use source code only for additional implementation details.

创建文档模式的提示词示例

Using the create-read-docs MCP, I need to set up documentation for my React component library. Can you help me create the folder structure and necessary configuration files?

Using the create-read-docs MCP, I've started creating documentation for my utility functions. How should I structure the detailed documentation for individual utility functions?

工具

阅读文档模式工具

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. 文件内容部分匹配

结果格式如下：

type: module
name: someModule

或

type: detail
name: someDetail
module: someModule

两步模式工具

在两步模式下，MCP 会生成 5 个通用工具，而不是为每个模块单独生成工具，另外还可以选择生成一个源文件读取工具：

{name}-get-overview

获取项目概览。

参数：

• 无

返回：

• 主概览文件的内容

{name}-get-overall-list

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

参数：

• 无

返回：

• 文档中所有可用模块的列表

{name}-get-module-overview

获取特定模块的概览。

参数：

• module（字符串）：模块名称

返回：

• 模块概览文件的内容

{name}-get-module-list

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

参数：

• module（字符串）：模块名称

返回：

• 模块列表文件的内容

{name}-get-module-detail

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

参数：

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

返回：

• 条目详细信息文件的内容

{name}-fuzzy-search

根据关键词搜索文件，并智能排序。

参数：

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

返回：

• 匹配文件的格式化列表，优先级系统和格式与上文“普通模式”部分所述相同

{name}-read-source-file

读取源代码文件内容。注意：只有在初始化服务时使用 --include-src=true 参数，才会提供此工具。

参数：

• filePath（字符串）：项目仓库中源文件的相对路径（例如，'src/components/Button.tsx'、'lib/utils.js'）

返回：

• 源文件内容，并进行安全检查，确保访问范围仅限于项目目录

**重要：**应先查阅文档，再使用此工具。文档应作为首要信息来源。只有在需要文档未涵盖的其他实现细节或示例时，才读取源代码。

创建文档模式工具

MCP 提供一个工具来帮助创建文档：

get-create-docs-instructions

获取有关创建文档结构的详细说明。

参数：

• 无

返回：

• 有关如何设置文档文件和结构的详细说明

为读取文档模式创建文档

你可以手动创建文档结构，也可以使用创建文档模式获取指导。请按照以下步骤创建可通过读取文档模式访问的文档：

步骤 1：创建主配置文件

在文档目录中创建一个 read-docs-mcp.json 文件：

{
  "name": "YourLibrary",
  "description": "Description of your library",
  "version": "1.0.0",
  "moduleList": ["hooks", "components", "utils"],
  "moduleFolderNamingPattern": "kebab"
}

moduleFolderNamingPattern 决定模块文件夹名称的转换方式。例如，如果你的 moduleList 包含 ["FormControl", "useHooks"]，并选择了 "kebab" 模式，系统将创建 form-control/ 和 use-hooks/ 文件夹。

步骤 2：创建模块目录和配置

为每个模块创建一个目录和一个 read-module-docs-mcp.json 文件：

{
  "get-all": {
    "name": "get-component-list",
    "description": "Get a list of components",
    "fileName": "list.md"
  },
  "get-details": {
    "name": "get-component-details",
    "description": "Get details of a component",
    "paramDescription": "A component name",
    "namingPattern": "kebab"
  },
  "get-overview": {
    "name": "get-component-overview",
    "description": "Get an overview of components",
    "fileName": "overview.md"
  }
}

**注意：**生成的实际工具名称会以你的软件包名称作为前缀。例如，如果你的软件包名称是 "MyLibrary"，工具将命名为 MyLibrary-get-component-list、MyLibrary-get-component-details 等。

步骤 3：创建文档文件

创建所需的 Markdown 文件：

• list.md - 模块中所有项目的列表
• overview.md - 模块概览
• 各项的详细信息文件（例如，button.md、input.md 等）

许可证

MIT