# open-docs-mcp

**Repository Path**: yunhanhai/open-docs-mcp

## Basic Information

- **Project Name**: open-docs-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenDocs MCP

> Context7 的开源免费替代品 — 完全自托管的库文档查询 MCP 服务器

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## 为什么需要这个项目？

[Context7](https://github.com/upstash/context7) 是一个优秀的 MCP 文档查询服务，但自 2026 年 1 月起开始限制免费额度（1,000 请求/月、60 请求/小时），对于日常开发来说已经不够用。

**OpenDocs MCP** 是一个完全开源、本地运行的替代方案：

- **零成本** — 无请求限制，无需付费
- **零配置启动** — 不依赖任何嵌入模型或外部服务
- **完全离线** — 首次索引后无需网络
- **隐私安全** — 文档数据只存在你的本地磁盘

## 工作原理

```
                     你的 AI 编码助手
                (Claude Code / Cursor / VS Code Copilot)
                            │
                            │ MCP Protocol (stdio)
                            ▼
                    ┌───────────────┐
                    │ OpenDocs MCP  │
                    │    Server     │
                    └───────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
         resolve        query-docs    index
         library        (FTS5搜索)    library
              │             │             │
              ▼             ▼             ▼
         ┌─────────────────────────────────┐
         │         SQLite 本地数据库        │
         │    FTS5 全文索引 + 内容哈希缓存  │
         └─────────────────────────────────┘
```

**文档获取优先级：**

1. **llms.txt** — 如果库提供了 [llms.txt](https://llmstxt.org/) 标准文件，直接使用（最干净）
2. **GitHub docs/** — 从仓库的 `docs/` 目录获取 Markdown 文件
3. **README** — 从 GitHub 获取 README.md
4. **npm registry** — 兜底方案，从 npm 获取包自带的 README

## 快速开始

### 1. 安装

```bash
git clone https://github.com/yunhanhai/open-docs-mcp.git
cd open-docs-mcp
npm install
npm run build
```

### 2. 配置 MCP 客户端

根据你使用的 AI 编码工具，将以下配置添加到对应的 MCP 配置文件中。

#### Claude Code

编辑 `~/.claude/settings.json`（全局）或项目目录下的 `.claude/settings.local.json`：

```json
{
  "mcpServers": {
    "open-docs-mcp": {
      "command": "node",
      "args": ["/你的路径/open-docs-mcp/dist/index.js"]
    }
  }
}
```

#### Cursor

编辑 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "open-docs-mcp": {
      "command": "node",
      "args": ["/你的路径/open-docs-mcp/dist/index.js"]
    }
  }
}
```

#### VS Code (GitHub Copilot)

编辑 `.vscode/mcp.json`：

```json
{
  "servers": {
    "open-docs-mcp": {
      "command": "node",
      "args": ["/你的路径/open-docs-mcp/dist/index.js"]
    }
  }
}
```

### 3. 开始使用

配置完成后，在 AI 对话中即可使用。以下是典型的使用场景：

**场景一：查询 React 的 useEffect 用法**

> AI 助手会自动调用 `resolve-library` 找到 React，然后调用 `query-docs` 搜索文档

**场景二：查询 Express 的路由配置**

> 首次查询时会自动从 GitHub 抓取文档并建立索引，后续查询直接使用本地缓存

## 提供的 MCP Tools

### `resolve-library`

解析库名，返回匹配的库列表。

| 参数 | 类型 | 说明 |
|------|------|------|
| `query` | string | 库名或关键词，如 `react`、`vue`、`express` |

**返回示例：**

```
找到 5 个匹配库:

1. express (npm:express@5.2.1)
   Fast, unopinionated, minimalist web framework
   状态: 已索引 (15 个文档块)

2. @types/express (npm:@types/express@5.0.6)
   TypeScript definitions for express
   状态: 未索引
```

### `query-docs`

查询已索引库的文档。如果库未索引，会自动触发索引。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `libraryId` | string | — | 库标识，由 `resolve-library` 返回 |
| `query` | string | — | 查询内容，如 `useEffect cleanup function` |
| `maxTokens` | number | 5000 | 返回的最大 token 数 |

### `index-library`

手动索引指定库的文档。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `libraryId` | string | — | 库标识 |
| `force` | boolean | false | 是否强制重新索引（忽略缓存） |

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GITHUB_TOKEN` | GitHub Personal Access Token，提升 API 限额（未认证 60次/小时，认证后 5000次/小时） | — |
| `OPEN_DOCS_DB` | 自定义数据库文件路径 | `~/.open-docs-mcp/docs.db` |
| `LOG_LEVEL` | 日志级别：`debug` / `info` / `warn` / `error` | `info` |

**强烈建议设置 `GITHUB_TOKEN`**，否则 GitHub API 的未认证限额很容易耗尽。

生成方式：https://github.com/settings/tokens → Generate new token (classic) → 勾选 `public_repo` 即可。

配置示例（Claude Code）：

```json
{
  "mcpServers": {
    "open-docs-mcp": {
      "command": "node",
      "args": ["/你的路径/open-docs-mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}
```

## 项目结构

```
open-docs-mcp/
├── src/
│   ├── index.ts              # 入口，启动 MCP Server
│   ├── server.ts             # MCP Server 定义，注册 3 个 tools
│   ├── core/
│   │   ├── resolver.ts       # 库名解析（别名 → 本地 → 远程）
│   │   ├── indexer.ts        # 文档索引（抓取 → 清洗 → 分块 → 存储）
│   │   └── searcher.ts       # 搜索引擎（FTS5 + 加权排序）
│   ├── sources/
│   │   ├── adapter.ts        # 数据源适配器接口
│   │   └── npm.ts            # npm registry 适配器
│   ├── pipeline/
│   │   ├── cleaner.ts        # HTML → Markdown 清洗
│   │   └── chunker.ts        # 按标题语义分块
│   ├── storage/
│   │   ├── database.ts       # SQLite 连接管理
│   │   ├── migrations.ts     # 数据库 Schema
│   │   └── fts.ts            # FTS5 搜索 + CRUD 操作
│   └── utils/
│       ├── logger.ts         # 日志（输出到 stderr）
│       ├── hash.ts           # SHA-256 内容哈希
│       └── tokens.ts         # 轻量 token 估算
├── 01-research.md            # 调研报告
├── 02-architecture.md        # 架构设计文档
├── package.json
├── tsconfig.json
└── tsup.config.ts
```

## 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| MCP 协议 | `@modelcontextprotocol/sdk` | 官方 MCP TypeScript SDK |
| 数据库 | `better-sqlite3` + FTS5 | 高性能嵌入式数据库 + 全文搜索 |
| HTML 提取 | `@mozilla/readability` | Mozilla 的内容提取算法 |
| HTML → MD | `turndown` | HTML 转 Markdown |
| DOM 环境 | `linkedom` | 轻量级 DOM 实现 |
| 构建 | `tsup` | 快速 TypeScript 打包 |

## 与 Context7 的对比

| 特性 | Context7 | OpenDocs MCP |
|------|----------|--------------|
| 价格 | 免费 1,000 次/月 | **完全免费，无限制** |
| 部署 | SaaS 托管 | **本地自托管** |
| 隐私 | 查询发送到云端 | **数据不出本地** |
| 离线使用 | 不支持 | **支持** |
| llms.txt 支持 | 否 | **是（优先使用）** |
| 嵌入模型依赖 | 内置 | **不需要（FTS5）** |
| 搜索方式 | 语义搜索 | 全文搜索（BM25 + 加权） |
| 预索引库数量 | 数千 | 按需索引 |

## 路线图

- [x] MVP：npm 适配器 + FTS5 搜索 + llms.txt 支持
- [ ] PyPI 适配器（Python 库支持）
- [ ] 通用网站爬取适配器
- [ ] sqlite-vec 向量搜索（混合 RRF 融合排序）
- [ ] 从 lockfile 自动匹配项目依赖版本
- [ ] 社区文档索引配方（Recipes）
- [ ] `npx open-docs-mcp` 一条命令启动
- [ ] Docker 镜像

## 参与贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feat/new-adapter`)
3. 提交更改 (`git commit -m 'feat: 添加 PyPI 适配器'`)
4. 推送分支 (`git push origin feat/new-adapter`)
5. 发起 Pull Request

## 许可证

[MIT](LICENSE)