内容
# AnyDocsMCP
> 爬取任意文档站点并将其注入到您的 AI 编程代理的上下文中。
与 **Windsurf**、**Cursor**、**Claude Code** 和 **Antigravity (Jules/Gemini)** 兼容。
[主页](https://jusedit.github.io/any-docs-mcp) | [MCP 服务器文档](mcp-server/README.md) | [爬虫文档](scraper/README.md)
## 为什么有效
灵感来自 [`@gaojude/next-agents-md`](https://github.com/gaojude/next-agents-md) 和 Vercel 关于 [检索导向推理](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) 的研究：
> 直接嵌入到 `AGENTS.md` 中的压缩 8KB 文档索引实现了 **100% 通过率**，而技能最多达到 79%。被动上下文优于主动检索，因为没有决策点 - 代理不需要决定“是否应该查找？”信息已经存在。
AnyDocsMCP 将此模式应用于 **任意** 文档站点，而不仅仅是 Next.js。爬虫生成一个紧凑的管道分隔索引，大小约为 500 字节，指向代理可以按需读取的单个文档文件。这将代理从预训练导向推理转变为检索导向推理。
## 工作原理
```
您 AnyDocs MCP 您的项目
│ │ │
│ "爬取 react 文档" │ │
├──────────────────────────────>│ │
│ 运行爬取命令 │ │
│<──────────────────────────────┤ │
│ │ │
│ （运行爬取命令） │ │
├──────────────────────────────>│ 存储在 AppData │
│ ├─────────────────> │
│ "将 react-docs 添加到项目" │ │
├──────────────────────────────>│ 复制文档 + 注入索引 │
│ ├─────────────────────────────>│
│ │ │
│ AI 代理现在具有持久的 │ .windsurf/rules/ │
│ 访问 react 文档 │ .windsurf/docs/react-docs/ │
```
1. **爬取** -- MCP 服务器返回一个 CLI 命令。您运行它来爬取一个文档站点。
2. **存储** -- 爬取的文档存储在 `%APPDATA%/AnyDocsMCP/v2/`（跨项目共享）。
3. **注入** -- 文档复制到您的项目中，并添加一个紧凑的索引（~500 字节）作为始终启用的 IDE 规则。
4. **使用** -- AI 代理在每次对话中看到索引，并按需读取单个文档文件。
## 快速入门
### 先决条件
- Python 3.10+（用于爬虫）
- Node.js 18+（用于 MCP 服务器）
- [OpenRouter API 密钥](https://openrouter.ai/)（用于 LLM 驱动的爬取）
- Chrome/Chromium（可选，用于 SPA 站点）
### 安装
```bash
git clone https://github.com/jusedit/any-docs-mcp.git
cd any-docs-mcp
# 爬虫
cd scraper && pip install -r requirements.txt
# MCP 服务器
cd ../mcp-server && npm install && npm run build
```
### 配置您的 IDE
将以下内容添加到您的 IDE 的 MCP 配置中：
```json
{
"mcpServers": {
"anydocs": {
"command": "node",
"args": ["/path/to/any-docs-mcp/mcp-server/dist/index.js"],
"env": {
"OPENROUTER_API_KEY": "sk-or-...",
"ANYDOCS_IDE": "windsurf"
}
}
}
}
```
将 `ANYDOCS_IDE` 设置为您的 IDE：`windsurf`（默认）、`cursor`、`claude` 或 `antigravity`。
参见 [MCP 服务器 README](mcp-server/README.md) 以获取完整的 IDE 配置示例。
### 用法
配置完成后，AI 代理有 6 种工具可用：
| 工具 | 描述 |
|------|-------------|
| `scrape_docs` | 返回用于爬取文档站点的 CLI 命令 |
| `list_docs` | 列出全局存储中的所有文档集 |
| `remove_docs` | 从全局存储中删除文档集 |
| `add_docs_to_project` | 将文档复制到项目中 + 将索引注入为 IDE 规则 |
| `remove_docs_from_project` | 从项目中删除文档 + 规则 |
| `list_project_docs` | 列出当前添加到此项目的文档 |
## IDE 支持
| IDE | 文档路径 | 规则路径 | 格式 |
|-----|-----------|------------|--------|
| **Windsurf** | `.windsurf/docs/<name>/` | `.windsurf/rules/docs-<name>.md` | `trigger: always_on` |
| **Cursor** | `.cursor/docs/<name>/` | `.cursor/rules/docs-<name>.mdc` | `alwaysApply: true` |
| **Claude Code** | `.docs/<name>/` | `CLAUDE.md` | `<!-- ANYDOCS -->` 标记 |
| **Antigravity** | `.agent/docs/<name>/` | `.agent/rules/docs-<name>.md` | 始终启用 |
## 爬虫管道
爬虫使用 7 步 LLM 辅助管道：
1. **引擎选择** -- cURL 与 Selenium（自动检测 SPA，使用的链接计数启发式算法）
2. **URL 发现** -- 站点地图 + BFS 快速采样（对 SPA 使用 Selenium）
3. **LLM 分析** -- 范围规则 + CSS 选择器，带有重试循环
4. **样本爬取** -- 5 页用于选择器优化
5. **LLM 优化** -- 从实际输出中改进剪枝选择器
6. **完整爬取** -- 所有页面，带有质量检查 + 跨页面重复数据删除
7. **索引生成** -- 紧凑的 AGENTS.md（~500 字节，无 LLM）
## 项目结构
```
any-docs-mcp/
scraper/ # Python 爬虫引擎
cli.py # CLI 入口点
pipeline.py # 7 步编排器
engine_selector.py # cURL 与 Selenium 决策
discovery.py # URL 发现（站点地图 + BFS）
llm_analyzer.py # LLM 驱动的范围 + 选择器分析
crawler.py # 并行页面获取器 + HTML 转 MD
content_cleaner.py # UI 伪影移除
dedup.py # 跨页面重复数据删除
grouper.py # AGENTS.md 索引生成器
tests/ # 单元测试（53 个测试）
requirements.txt
mcp-server/ # TypeScript MCP 服务器
src/
index.ts # MCP 工具 + 处理程序
storage.ts # AppData 文档管理
ide-adapter.ts # IDE 特定适配器
package.json
docs/ # GitHub Pages 主页
.env.example # 环境变量模板
LICENSE # MIT
```
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `OPENROUTER_API_KEY` | 是* | -- | LLM 驱动的爬取 API 密钥 |
| `ANYDOCS_IDE` | 否 | `windsurf` | 目标 IDE |
| `ANYDOCS_STORAGE_ROOT` | 否 | `%APPDATA%/AnyDocsMCP/v2/` | 重写存储路径 |
| `ANYDOCS_SCRAPER_PATH` | 否 | 自动检测 | 重写爬虫路径 |
## 安全
**自担风险。** 爬取的内容被注入到您的 AI 代理的上下文中。仅从受信任的来源爬取文档。在生产中使用前请查看内容。
## 许可证
MIT -- 参见 [LICENSE](LICENSE)
