🐝 Swarms MCP 文档服务器
📖 描述
此程序是一个基于FastMCP构建的代理框架文档 MCP 服务器，旨在使AI 代理能够高效地从您的文档数据库中检索信息。它结合了混合语义（向量）和关键词（BM25）搜索、分块索引以及强大的 FastMCP 工具 API，可实现代理的无缝集成。
主要功能：
- 使用语义和关键字搜索进行高效的块级检索
- 代理可以使用 FastMCP 工具查询、列出和检索文档
- 本地优先、低延迟设计（所有数据均在本地索引和查询）
- 文件更改时自动重新索引
- 模块化：将任何 repos 添加到
corpora/ ，支持所有主要文件类型 - 可扩展：根据需要添加新工具、检索器或语料库
主要模块：
embed_documents.py → 加载、分块和嵌入文档swarms_server.py → 启动 MCP 服务器和 FastMCP 工具
🌟 主要特点
- 混合检索器🔍：结合语义和关键字搜索。
- 动态 Markdown 处理📄：基于文件大小的智能加载器。
- 专用加载器⚙️：
.py ， .ipynb ， .md ， .txt ， .yaml ， .yml 。 - 块和文件摘要📈：显示块计数以及文件计数。
- 实时监控🔥：立即响应
corpora/中的任何变化。 - 用户确认成本✅：在昂贵的嵌入之前确认。
- 健康检查端点🚑：确保服务器已准备好使用。
- 本地优先🗂️：所有存储库均在本地建立索引，无需外部依赖。
- 安全删除助手🔥：自动删除损坏/不匹配的索引。
🏗️ 版本历史记录
| 版本 | 日期 | 亮点 |
|---|
| 2.2 | 2025年4月25日 | 拆分嵌入/从服务器加载；加载摘要中的完整块计数 |
| 1.0 | 2025年4月25日 | 动态 Markdown 加载器、颜色日志、健康检查工具 |
| 0.7 | 2025年4月25日 | .py 、 .ipynb 、 .md的专用文件加载器 |
| 0.5 | 2025年4月10日 | OpenAI 大型模型嵌入，扩展 MCP 工具 |
| 0.1 | 2025年4月10日 | 带有通用加载器的初始版本 |
📚 管理你的语料库（本地存储库）
由于 Swarms 和其他框架非常庞大，完整的语料库不会推送到 GitHub。
相反，您可以在corpora/下手动克隆它们：
# Inside your project folder:
cd corpora/
# Clone useful frameworks:
git clone https://github.com/SwarmsAI/Swarms
git clone https://github.com/SwarmsAI/Swarms-Examples
git clone https://github.com/microsoft/autogen
git clone https://github.com/langchain-ai/langgraph
git clone https://github.com/openai/openai-agent-sdk
✅注意事项：
- 添加任何 repo — 公共、私有、自定义。
- 在本地构建您自己的自定义 AI 知识库。
- 大型存储库（>500MB）没问题；所有索引都是本地的。
🚀 快速入门
# 1. Activate virtual environment
venv\Scripts\Activate.ps1
# 2. Install all dependencies
pip install -r requirements.txt
# 3. Configure OpenAI API Key
echo OPENAI_API_KEY=sk-... > .env
# 4. (Load and embed documents
python embed_documents.py
# 5. Start MCP server
python swarms_server.py
# If no index is found, the server will prompt you to embed documents automatically.
⚙️ 配置
- Corpus ：将 repos 放在
corpora/中 - 环境变量：
- 索引文件支持：
chroma-collections.parquet和chroma.sqlite3均受支持。如果两者都存在，则优先使用.parquet 。
- 自动嵌入：
- 如果没有找到索引，服务器将提示您自动嵌入和索引您的文档。
- 选修的：
- 如果您愿意，请禁用色度压缩：
setx CHROMA_COMPACTION_SERVICE__COMPACTOR__DISABLED_COLLECTIONS "swarms_docs"
- 命令行标志：
--reindex → 在服务器运行期间触发刷新重新索引。
🔄 文件监视和自动重建索引
MCP 服务器监视corpora/的任何文件更改：
- 任何修改、创建或删除都会触发实时重新索引。
- 不需要重新启动服务器。
🛠️ 可用的 FastMCP 工具
| 工具 | 描述 |
|---|
swarm_docs.search | 搜索相关文档块 |
swarm_docs.list_files | 列出所有索引文件 |
swarm_docs.get_chunk | 通过路径和索引获取特定块 |
swarm_docs.reindex | 强制重新索引（完整或增量） |
swarm_docs.healthcheck | 检查 MCP 服务器状态 |
❓ 故障排除
- 问：启动服务器时出现“未找到有效的现有索引”提示。
- 答：服务器现在会提示您嵌入并索引文档。请接受提示继续，或者先手动运行
python embed_documents.py 。
- 问：使用哪个索引文件？
- 答：如果可用，服务器将使用
chroma-collections.parquet ，否则使用chroma.sqlite3 。
- 问：我想强制重新索引。
- 答：运行
python swarms_server.py --reindex或使用swarm_docs.reindex工具。
📋 使用示例
# Search the documentation
result = swarm_docs.search("How do I load a notebook?")
print(result)
# List all available files
files = swarm_docs.list_files()
print(files)
# Get a specific document chunk
chunk = swarm_docs.get_chunk(path="examples/agent.py", chunk_idx=2)
print(chunk["content"])
🧰 扩展和重建
- 添加新文档→ 放入
corpora/ ，然后：python swarms_server.py --reindex
- 模式更改→（例如不同的元数据结构）：
python swarms_server.py --reindex --full
- 添加新的 repo → 将文件夹拖放到
corpora/下，重新索引。 - 推荐用于大多数只读存储库：
setx CHROMA_COMPACTION_SERVICE__COMPACTOR__DISABLED_COLLECTIONS "swarms_docs"
🔗 IDE 集成
直接插入 Windsurf Cascade：
"swarms": {
"command": "C:/…/Swarms/venv/Scripts/python.exe",
"args": ["swarms_server.py"]
}
然后您可以从 Cascade 自动化访问swarm_docs.*工具。
📦要求
💡 需要 Python 3.11 环境
明确创建您的环境：
然后安装：
pip install -r requirements.txt
✅ MCP 服务器就绪
启动后：
- 正确的装载摘要
- 采取昂贵行动之前进行安全确认
- 自动文件监视和重新索引
- Windsurf 插件就绪
- 全面覆盖工具
你很擅长级联它！ 🏄♂️
📈 流程图
+------------------+
| 🖥️ MCP Server |
+------------------+
|
+---------------------------------------------------+
| |
+-------------+ +-----------------+
| 📁 Corpora | | 🔎 FastMCP Tools |
| Folder | | (search, list, |
| (markdown, | | get_chunk, etc.) |
| code, etc) | +-----------------+
+-------------+ |
| |
+-----------------+ +----------------+
| 📚 Loaders | | 🧠 Ensemble |
| (Python, MD, TXT)| | Retriever (BM25|
| Split into Chunks| | + Chroma) |
+-----------------+ +----------------+
| |
+-----------------+ +----------------+
| ✂️ Text Splitter | | 🧩 Similarity |
| (RecursiveCharacter) | | Search (chunks) |
+-----------------+ +----------------+
| |
+-----------------+ +----------------+
| 💾 Embed chunks | —OpenAI Embedding (small)—> | 🛢️ Chroma Vector |
| via OpenAI API | | DB (Local Store) |
+-----------------+ +----------------+
| |
+-----------------+ +----------------+
| 📡 Reindex Watcher| | 👀 File Watchdog |
| (Auto detect | | (Auto reindex |
| new/modified files| | on file events) |
+-----------------+ +----------------+