项目介绍
多服务器MCP文档搜索
一个用于从技术文档构建独立可搜索的MCP服务器的框架。创建具有混合向量+关键词搜索功能的独立文档服务器，准备好分发和部署。
🎯 项目概述
该框架使您能够：
- 构建：从任何Markdown/MDX文档源构建可搜索的MCP服务器
- 搜索：通过互反排名融合（Reciprocal Rank Fusion）进行混合语义（向量）+关键词（全文搜索）搜索
- 分发：作为独立仓库或包分发自包含服务器
- 部署：部署到VS Code、Claude Desktop或其他兼容MCP的主机
- 扩展：使用自动化工具支持多个文档源
核心价值主张
- 🔍 混合搜索：智能结合语义相似性（HNSW）和关键词匹配（BM25）
- 📦 自包含服务器：每个MCP服务器都是完全独立且可分发的
- 🚀 多格式支持：适用于MDX、Markdown和其他文档格式
- 🎛️ 配置驱动：所有路径和参数通过YAML配置控制
- 💾 版本化数据：DuckLake提供可重现的文档快照
- 🔄 自动化工具：同步、搭建和构建新服务器的脚本
📐 多服务器架构
此项目支持多个独立的MCP服务器，每个服务器服务于不同的文档源：
/home/james/mcp/
├── servers/ # 独立MCP服务器
│ ├── mojo-manual-mcp/ # Mojo文档服务器
│ │ ├── runtime/ # 服务器代码+索引数据库
│ │ │ ├── mojo_manual_mcp_server.py
│ │ │ ├── search.py
│ │ │ └── mojo_manual_mcp.db
│ │ ├── config/ # YAML配置
│ │ │ ├── processing_config.yaml
│ │ │ └── server_config.yaml
│ │ ├── requirements.txt
│ │ └── README.md
│ │
│ └── [future-servers]/ # DuckDB, Python等
│
├── shared/ # 构建时基础设施（仅开发用）
│ ├── preprocessing/ # 文档处理流水线
│ ├── embedding/ # 嵌入生成脚本
│ ├── templates/ # 新服务器模板
│ └── build/ # 临时构建工件
│
├── source-documentation/ # 文档源
│ ├── mojo/manual/ # Mojo文档（MDX文件）
│ └── [其他源]/
│
└── tools/ # 自动化脚本
├── sync_documentation.sh # 同步上游仓库
├── scaffold_new_mcp.sh # 创建新的服务器结构
└── build_mcp.sh # 构建服务器数据库
关键设计原则：
- 每个在
/servers/{name}/的服务器是完全独立且可分发的 - 共享构建基础设施在
/shared/是仅开发用（不与服务器一起打包） - 所有配置基于YAML并支持变量替换（无硬编码路径）
- 多格式支持通过插拔式处理器架构实现
- 支持使用或不使用pixi（支持pip + venv）
🚀 快速开始
在三步内运行Mojo文档MCP服务器：
使用Pixi（推荐）
1. 克隆并安装依赖
git clone jpotter80/mcp
cd mcp/servers/mojo-manual-mcp
pixi install
2. 配置VS Code
添加Mojo-Manual MCP服务器，通过mcp.json添加配置到您的VS Code设置中，以全局设置。将/absolute/path/to/mojo-manual-mcp替换为您实际的服务器路径。
{
"servers": {
"mojo-manual": {
"type": "stdio",
"command": "pixi",
"args": ["run", "serve"],
"cwd": "/absolute/path/to/mojo-manual-mcp"
}
}
}
3. 如果在VS Code中的mcp.json文件配置正确，服务器会显示启动按钮来启动服务器。之后，VS Code将根据需要管理服务器的启动和停止。
注意：预构建的数据库已包含在存储库中。无需构建步骤即可运行服务器。
📖 详细指南：参见docs/QUICKSTART.md获取完整的设置说明。
环境变量：
MOJO_DB_PATH：索引数据库路径MAX_SERVER_URL：嵌入服务器端点（如果AUTO_START_MAX=1则自动启动）EMBED_MODEL_NAME：句子转换器模型名称AUTO_START_MAX：设置为1以自动启动MAX服务器（推荐）
🏗️ 从源代码构建
如果您想从头重建数据库或创建新的MCP服务器：
重新构建Mojo服务器
# 完整流水线（所有步骤）
pixi run mojo-build
# 或逐步执行
pixi run mojo-process # 处理文档
pixi run mojo-generate-embeddings # 生成向量
pixi run mojo-consolidate # 整合数据
pixi run mojo-load # 加载到DuckLake
pixi run mojo-index # 创建索引
创建新的MCP服务器
# 1. 搭建新的服务器结构
./tools/scaffold_new_mcp.sh --name duckdb --doc-type docs --format markdown
# 2. 将文档添加到source-documentation/duckdb/docs/
# 3. 构建服务器
./tools/build_mcp.sh --mcp-name duckdb
# 4. 测试服务器
python servers/duckdb-docs-mcp/runtime/duckdb_docs_mcp_server.py
📖 开发者指南：
docs/CREATING_NEW_MCP.md- 创建新服务器
📋 已实现的服务器
当前实现：
| 服务器 | 文档源 | 格式 | 状态 |
|---|---|---|---|
| mojo-manual-mcp | Mojo手册 | MDX | ✅ 生产 |
| duckdb-docs-mcp | DuckDB文档 | MD | ✅ 生产 |
🛠️ 关键技术
- Python 3.12+ — 预处理和运行时的核心语言
- DuckDB — 向量相似性搜索（HNSW）+全文搜索（BM25）
- DuckLake — 版本化的数据湖，用于可重现的构建
- MAX — 本地句子转换器嵌入服务器
- MCP — AI代理集成的模型上下文协议
- Pixi — 包管理和任务自动化（可选）
🎓 工作原理
构建流水线
- 预处理：MDX/Markdown → 清洁的块（约350-400个标记，保留结构）
- 嵌入：块 → 通过句子转换器生成768维向量
- 整合：合并块+嵌入到整合的Parquet数据集
- 版本化：加载到DuckLake以形成版本控制的数据湖
- 索引：在DuckDB中生成HNSW（向量）+ FTS（关键词）索引
运行时搜索
- 向量搜索（HNSW）：通过余弦距离进行语义相似性匹配
- 关键词搜索（FTS/BM25）：精确短语和词项匹配，带有字段权重
- 混合融合（RRF）：互反排名融合智能地结合两种排名
- 优雅回退：如果MAX服务器不可用，则回退到仅关键词搜索
示例查询流程
用户："如何在Mojo中声明一个变量？" ↓
- 查询嵌入通过MAX服务器生成
- 向量搜索找到语义相似的块
- 关键词搜索找到包含“声明”+“变量”的块
- RRF融合结合结果
- 返回前5个块，附带片段+URL ↓ 响应：相关文档部分及上下文
🔗 外部资源
- 模型上下文协议 - MCP规范
- DuckDB文档 - 数据库引擎文档
- DuckDB VSS扩展 - 向量相似性搜索
- MAX文档 - 嵌入服务器
- Mojo文档 - 示例文档源
📄 许可证
版权所有 2.0（"许可证"）； 除非符合许可证，否则不得使用此文件。 您可以通过以下方式获得许可证副本：
http://www.apache.org/licenses/LICENSE-2.0
除非适用法律要求或书面同意，根据许可证分发的软件按"原样"分发， 没有任何明示或暗示的保证或条件。具体许可条款规定了权限和限制。
🙏 致谢
由Modular、DuckDB和模型上下文协议社区的灵感所启发——由开源工具驱动。