docbot
一个智能MCP(模型上下文协议)服务器,通过智能文档管理让Claude和Cursor等AI助手深入了解您的项目。
什么是docbot?
doc-bot是一个文档服务器,通过提供以下功能来增强AI编码助手:
- 🧠 智能搜索 通过您的项目文档
- 📖 上下文文档 基于你正在研究的表面制导
- 🔄 实时更新 随着文档的更改
- 📚 API参考 来自官方文件(通过Docsets)
- 🤖 MCP工具 让AI代理查询和理解您的项目
- ✍️ 代理驱动的更新 因此,新知识被捕获在文档中
为什么是docbot?
传统的人工智能助手的上下文窗口有限,无法理解您的特定项目。docbot通过以下方式解决了这个问题:
- 提供项目特定知识 -你的惯例、模式和决定
- 智能搜索 -AI在不扰乱上下文的情况下准确地找到它需要的东西
- 无限缩放 -数千个没有令牌限制的文档
- 保持最新状态 -实时重新加载确保AI始终拥有最新信息
运作原理
doc-bot充当您的文档和AI助手之间的桥梁:```
Your Project Documentation → doc-bot → MCP Protocol → AI Assistant (Claude, Cursor, etc.)
当你要求你的AI助手编写代码时,它可以:
1. 搜索相关文档
1. 阅读项目文档以了解模式和示例
1. 查找API参考和示例
1. 发现新模式时更新文档
## 快速开始
### 1.安装docbot
将doc-bot添加到AI助手的配置中:
**对于克劳德桌面或克劳德代码:**```json
{
"mcpServers": {
"doc-bot": {
"command": "npx",
"args": ["@afterxleep/doc-bot@latest"]
}
}
}
配置文件的位置:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
对于光标:
- 添加一个
mcp.json将上述内容归档到您的.cursor文件夹
2.创建文档
创建一个 doc-bot 在项目根目录下的文件夹中添加markdown文件:```
your-project/
├── doc-bot/
│ ├── coding-standards.md
│ ├── api-patterns.md
│ ├── testing-guide.md
│ └── architecture.md
├── src/
└── package.json
### 3.测试一下!
问你的人工智能助理:“这个项目的编码标准是什么?”
## 版本控制和兼容性
docbot 2.0是一个突破性的变化。规则执行被取消,取而代之的是文件优先指导。作为传统的回退,文档标记 `alwaysApply: true` (或 `always_apply: true`)在系统提示中显示 `get_file_docs` 结果。
- 如果您需要传统规则执行流程,请固定到 `@afterxleep/doc-bot@1` 或从 `1.x` 支。
- 新安装应使用最新的2.x行(`@afterxleep/doc-bot@latest`).
## 项目文档
doc-bot将您的项目文档视为AI助手的可搜索知识库。
### 代理驱动的更新
docbot旨在让代理在工作时保持文档的最新状态。当助理发现新模式或更改时,它可以直接添加或更新文档:```json
{
"fileName": "auth-flow.md",
"title": "Auth Flow",
"description": "OAuth flow and token handling",
"keywords": ["auth", "oauth", "tokens"],
"filePatterns": ["src/auth/**"],
"content": "# Auth Flow\n\nDocument the new flow here."
}
代理文档循环
使用此快速循环扩展项目知识并保持文档最新:
- 快速定向:呼叫
doc_bot(task)或get_document_index()当项目不熟悉时。 - 查找具体信息:使用
search_documentation具体术语(API名称、类名称、错误)。 - 阅读全文:开放比赛
read_specific_document或get_file_docs. - 获取新知识:当行为发生变化或出现新模式时,用
create_or_update_rule. - 需要时刷新:如果文档是手动编辑的,请运行
refresh_documentation().
使用清晰的标题、关键字和 filePatterns.
文档格式
使用frontmatter元数据创建markdown文件:```markdown
title: "React Component Guidelines"
description: "Standards for building React components"
keywords: ["react", "components", "frontend", "jsx"]
React Component Guidelines
- Use functional components with hooks
- Follow PascalCase naming
- Keep components under 200 lines
- Write tests for all components
### 前台选项
|字段|类型|描述|示例|
|-------|------|-------------|---------|
| `title` |string|文档标题(必需)|“API指南”|
| `description` |string|简要说明|“REST API设计模式”|
| `keywords` |array |搜索关键字|\[“api”、“rest”、“http”\]|
| `topics` |array |可选主题标签|\[“架构”、“后端”\]|
| `filePatterns` |array |应用于特定文件|\[“*.test.js“,”\*\*/*.spec“\]|
| `alwaysApply` |boolean |始终将此文档包含在系统提示+文件文档中(别名: `always_apply`)|真的|
### 搜索工作原理
1. **智能解析** -解析查询,删除停用词
1. **多字段匹配** -搜索标题、描述、关键字和内容
1. **相关性评分** -按相关性排名的结果(精确匹配得分最高)
1. **上下文提取** -返回显示匹配内容的片段
docbot为代理提供文档;它不执行规则。标记的文档 `alwaysApply: true` 总是被特工发现。代理应在出现新模式或更改时更新文档。
### 文件类型
#### 一般文件```markdown
---
title: "Coding Standards"
---
Project-wide guidance and conventions
上下文文档```markdown
title: "Testing Guide"
filePatterns: [".test.js", ".spec.ts"]
Documentation that only applies to test files
#### 可搜索的参考文献```markdown
---
title: "Database Schema"
keywords: ["database", "postgres", "schema", "migrations"]
---
Documentation found through search queries
文档集(API文档)
doc-bot还可以从Docset中搜索API官方文档,让您的人工智能助手访问全面的框架和库参考资料。
什么是Docset?
Docset是预先构建的文档数据库,包含以下官方文档:
- 编程语言(Python、JavaScript、Go等)
- 框架(React、Vue、Django、Rails等)
- 库(NumPy、Express、jQuery等)
- 平台(iOS、Android、AWS等)
设置文档集
- 选项A:让你的AI助手直接安装:
从URL:```
Use the add_docset tool to install Swift documentation from https://kapeli.com/feeds/Swift.tgz
从本地文件:```
Use the add_docset tool to install the docset at /Users/me/Downloads/React.docset
- 管理您的文档集:```
List all installed docsets
Remove docset with ID abc123
文档集自动存储在 `~/Developer/DocSets` 默认情况下。
### 文档集来源
- **用户贡献的文档集**: https://github.com/Kapeli/Dash-User-Contributions
- **文档集生成工具**: https://github.com/Kapeli/docset-generator
可用的热门文档集:
- 编程语言:Python、JavaScript、Go、Rust、Swift
- Web框架:React、Vue、Angular、Django、Rails
- 移动端:iOS、Android、React Native、Flutter
- 数据库:PostgreSQL、MySQL、MongoDB、Redis
- 云:AWS、谷歌云、Azure
3. **配置自定义路径** (可选):```json
{
"mcpServers": {
"doc-bot": {
"command": "npx",
"args": ["@afterxleep/doc-bot@latest", "--docsets", "/path/to/docsets"]
}
}
}
Docset搜索的工作原理
- 统一搜索:一个查询同时搜索您的文档和API文档
- 智能优先级:您的项目文档的相关性提高了5倍
- API勘探:使用
explore_api用于发现相关类、方法的工具 - 演出:使用缓存跨多个文档集进行并行搜索
可用工具
doc-bot为AI助手提供了以下工具:
| 工具 | 目的 | 示例使用 |
|---|---|---|
doc_bot |
获取文档指导 | “我应该如何进行身份验证?” |
search_documentation |
搜索所有文档 | “如何实现身份验证?” |
get_file_docs |
获取特定于文件的文档 | “Button.test.jsx的文档” |
read_specific_document |
按文件名阅读完整文档 | “Open coding standards.md” |
get_document_index |
列出所有文档 | “显示文档索引” |
create_or_update_rule |
添加/更新文档 | “捕获身份验证流更新” |
refresh_documentation |
从磁盘重新加载文档 | “刷新文档存储” |
explore_api |
浏览API文档 | “显示URLSession方法” |
add_docset |
安装新的docset | “从URL添加Swift文档” |
remove_docset |
删除已安装的docset | “删除docset abc123” |
list_docsets |
列出所有文档集 | “显示已安装的文档集” |
配置选项
CLI选项```bash
doc-bot [options]
Options:
-d, --docs Path to docs folder (default: ./doc-bot)
-s, --docsets Path to docsets folder (default: ~/Developer/DocSets)
-v, --verbose Enable verbose logging
-w, --watch Watch for file changes
-h, --help Display help
### 高级配置```json
{
"mcpServers": {
"doc-bot": {
"command": "npx",
"args": [
"@afterxleep/doc-bot@latest",
"--docs", "./documentation",
"--docsets", "/Library/Application Support/Dash/DocSets",
"--verbose",
"--watch"
]
}
}
}
文档
- API 参考 -所有MCP工具的完整参考
- 架构指南 -技术架构和组件
- 配置指南 -所有配置选项
- 故障排除指南 -常见问题和解决方案
- 示例和最佳实践 -实际使用示例
- 贡献指南 -如何为docbot做出贡献
最佳实践
撰写有效文件
1. 使用描述性标题和关键字```markdown
title: "Authentication Flow"
keywords: ["auth", "login", "jwt", "security", "authentication"]
1. **对上下文文档使用文件模式**```markdown
---
filePatterns: ["**/auth/**", "*.auth.js"]
---
-
保持文档集中 -每个文件一个主题
-
包括示例 -表演,不要只说
优化搜索
- 在关键字中包含同义词:
["test", "testing", "spec", "jest"] - 使用清晰的节标题以更好地提取代码段
- 添加描述以提高搜索相关性
为什么MCP优于静态指令文件?
与静态不同 .cursorrules 或 .github/copilot-instructions.md 文件夹:
- 动态的:AI搜索它需要的东西,而不是阅读所有东西
- 可扩展的:无令牌限制的无限文档
- 智能:基于当前文件的上下文感知文档
- 统一:适用于任何与MCP兼容的AI工具
- 生活:文档更改时的热重新加载
贡献
查看我们的 贡献指南 用于开发设置和指南。
许可证
麻省理工学院-参见 许可证 了解详情。
支持
- 问题: GitHub 问题
- 讨论: GitHub讨论
发布
我们发布自 stable 通过GitHub Actions进行分支。使用 Publish to npm 工作流(手动触发)或合并到 stable 释放。
传统代理强制执行(可选)
这不是主要的工作流程;docbot侧重于文档优先的指导和代理驱动的更新。如果您仍然需要代理主机强制执行的传统“始终应用”流,请复制 templates/AGENTS.md 进入你的项目 AGENTS.md。这迫使代理人打电话 doc_bot() 首先,遵循docbot的工具顺序,确保 alwaysApply 在工作开始之前,文档就会浮出水面。
注意:docbot不强制执行规则。你的代理主持人必须尊重 AGENTS.md 为了使其发挥作用。
建于❤️ 在西班牙
