检查文档 - FastMCP 文档索引服务器

这是一个使用 ChromaDB 进行语义文档索引和 Git 差异分析的 FastMCP 服务器，用于在代码更改时识别需要更新的文档。

特性

• 📚 文档索引：使用语义搜索功能索引 Markdown 文档
• 🔍 语义搜索：使用自然语言查询搜索文档
• 📝 Git 差异分析：根据代码更改自动识别需要更新的文档
• 🚀 快速嵌入：使用 Ollama 的 nomic-embed-text 模型进行高质量嵌入
• 💾 持久存储：使用 ChromaDB 进行可靠的向量存储
• ☁️ 云支持：通过 ChromaDB Cloud 集成实现可扩展、持久的存储

先决条件

1. Python 3.9+
2. uv（Python 包管理器）

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Ollama 带有 nomic-embed-text 模型

   # 安装 Ollama（macOS）
   brew install ollama
   
   # 启动 Ollama 服务
   ollama serve
   
   # 拉取嵌入模型
   ollama pull nomic-embed-text
   

快速开始

1. 克隆并设置

# 克隆仓库
git clone https://github.com/bdougie/check_the_docs
cd check_the_docs

# 使用 uv 安装依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate  # 在 macOS/Linux 上
# 或
.venv\Scripts\activate  # 在 Windows 上

2. 配置 Continue

在 .continue/mcpServers/mcp-server.yaml 创建一个 YAML 配置文件：

name: 检查文档 MCP 服务器
version: 0.0.1
schema: v1
mcpServers:
  - name: check_the_docs
    command: uv
    args:
      - run
      - python
      - server.py
   cwd: .

用你的实际项目路径替换 /path/to/your/check_the_docs。

使用示例

索引文档

在 Continue Agent 中请求索引示例文档：

index_docs ./docs # 或者指向你的文档文件夹的路径

搜索文档

搜索已索引的文档：

搜索文档中的“git 集成”

分析代码更改

检查基于代码更改哪些文档需要更新：

检查基于最近 Git 更改哪些文档需要更新

自我文档检查

使用该项目本身确保所有功能都被记录下来：

1. 首先，索引项目的自身文档：

   index_docs ./
   

2. 然后检查是否所有代码功能都已被覆盖：

   检查文档以查看 server.py 中的所有功能是否已在文档中被覆盖
   

这将分析代码库并建议任何新功能或工具的缺失文档。

有关可用的 MCP 工具的详细信息，请参阅 available_tools.md。

ChromaDB Cloud 设置

要使用 ChromaDB Cloud 实现可扩展、持久的存储，可以通过 MCP 工具直接配置它：

快速设置（MCP 工具）

# 1. 配置 ChromaDB Cloud 并切换到云模式
configure_chroma_cloud your-tenant-name your-database-name

# 2. 将现有本地数据复制到云端（可选）
copy_to_cloud your-tenant-name your-database-name

# 3. 验证云连接
chroma_status

可用的 MCP 配置工具

• configure_chroma_cloud - 设置并切换到 ChromaDB Cloud
• switch_to_local - 切换回本地 ChromaDB
• copy_to_cloud - 复制本地集合到云端
• copy_from_cloud - 复制云端集合到本地
• chroma_status - 检查当前配置和连接

手动设置（环境变量）

# 设置环境变量
export CHROMA_CLOUD_TENANT="your-tenant-name"
export CHROMA_CLOUD_DATABASE="your-database-name"

# 复制数据并验证
copy_to_cloud your-tenant-name your-database-name
chroma_status

有关详细的设置说明，请参阅 chroma-cloud-setup.md。

开发

运行测试

# 安装开发依赖
uv sync --dev

# 运行测试
uv run pytest

项目结构

check_the_docs/
├── server.py          # 主 FastMCP 服务器实现
├── pyproject.toml     # 项目配置
├── README.md          # 此文件
├── example.md         # 实现指南
├── chroma_db/         # ChromaDB 存储（自动生成）
└── example_docs/      # 示例文档（可选）

环境变量

• OLLAMA_HOST：Ollama API 终点（默认：http://localhost:11434）
• CHROMA_DB_PATH：ChromaDB 存储路径（默认：./chroma_db）
• CHROMA_CLOUD_TENANT：ChromaDB Cloud 租户名称（可选，用于云模式）
• CHROMA_CLOUD_DATABASE：ChromaDB Cloud 数据库名称（可选，用于云模式）
• CHROMA_CLOUD_API_KEY：ChromaDB Cloud API 密钥（可选，用于程序访问）

架构

该服务器使用：

• FastMCP 实现 MCP 协议
• ChromaDB 进行向量存储和相似度搜索
• Ollama 带有 nomic-embed-text 生成嵌入
• GitPython 进行仓库分析
• Pydantic 进行请求/响应验证

故障排除

Ollama 连接错误

如果你看到“连接拒绝”错误：

# 检查 Ollama 是否正在运行
ollama list

# 如需启动 Ollama
ollama serve

ChromaDB 持久化

数据库默认存储在 ./chroma_db。要重置：

rm -rf chroma_db/

内存问题

对于大型文档集，你可能需要：

• 增加块大小以减少总块数
• 批处理文件
• 使用云 ChromaDB 实例

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 使用 uv run pytest 运行测试
5. 提交拉取请求

许可证

MIT 许可证 - 详情见 LICENSE 文件