🐝 Swarms MCP文档服务器
______________________________________________________________________
📖 描述
这个程序是一个 代理框架 文档MCP服务器构建于 FastMCP，旨在实现 AI代理 从文档数据库中高效检索信息。它结合了混合语义（向量）和关键字（BM25）搜索、分块索引和强大的FastMCP工具API，实现了无缝代理集成。
关键能力：
- 使用语义和关键字搜索进行高效的块级检索
- 代理可以使用FastMCP工具查询、列出和检索文档
- 本地优先、低延迟设计（所有数据都在本地索引和查询）
- 对文件更改自动重新索引
- 模块化：添加任何仓库
corpora/，支持所有主要文件类型 - 可扩展：根据需要添加新的工具、检索器或语料库
主要模块：
embed_documents.py→ 加载、分块和嵌入文档swarms_server.py→ 介绍MCP服务器和FastMCP工具
______________________________________________________________________
______________________________________________________________________
🌟 主要特点
- 杂交寻回犬 🔍: 结合语义搜索和关键字搜索。
- 动态Markdown处理 📄: 基于文件大小的智能加载器。
- 专用装载机 ⚙️:
.py,.ipynb,.md,.txt,.yaml,.yml. - 块和文件摘要 📈: 显示块计数和文件计数。
- 实时监视器 🔥: 立即响应任何更改
corpora/. - 用户确认费用 ✅: 在昂贵的嵌入之前确认。
- 健康检查端点 🚑: 确保服务器已准备好使用。
- 本地优先 🗂️: 所有repos都在本地索引，没有外部依赖关系。
- 安全删除助手 🔥: 自动删除损坏/不匹配的索引。
______________________________________________________________________
🏗️ 版本历史记录
| 版本 | 日期 | 亮点 |
|---|---|---|
| 2.2 | 2025‑04‑25 | 从服务器上剥离嵌入/加载；加载摘要中的完整块计数 |
| 1.0 | 2025‑04‑25 | 动态Markdown加载器、颜色日志、健康检查工具 |
| 0.7 | 2025‑04‑25 | 专用文件加载器 .py, .ipynb, .md |
| 0.5 | 2025-04-10 | OpenAI大型模型嵌入，扩展MCP工具 |
| 0.1 | 2025‑04‑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✅ 笔记：
- 添加 任何回购 --公共、私人、习俗。
- 在本地建立自己的自定义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.______________________________________________________________________
⚙️ 配置
- 语料库：将repos放入其中
corpora/ - 环境变量:
- .env 必须包含 OPENAI_API_KEY
- 索引文件支持:
- 两者 chroma-collections.parquet 和 chroma.sqlite3 支持。 .parquet 如果两者都存在，则首选。
- 自动嵌入:
- 如果找不到索引，服务器将提示您自动嵌入和索引文档。
- 可选的:
- 如果您愿意，请禁用Chroma压缩：
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服务器状态 |
______________________________________________________________________
❓ 故障排除
- Q： 启动服务器时，我得到“找不到有效的现有索引”。
- A： 服务器现在将提示您嵌入和索引文档。接受继续的提示，或运行 python embed_documents.py 手动第一。
- Q： 使用哪个索引文件？
- A： 服务器将使用 chroma-collections.parquet 如果可用，否则 chroma.sqlite3.
- Q： 我想强制重新索引。
- A： 快跑 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- 添加新仓库 → 将文件夹放到
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"]
}然后，您可以访问 swarm_docs.* Cascade自动化的工具。
______________________________________________________________________
📦 需求
💡 需要Python 3.11环境
明确地创建您的环境：
python3.11 -m venv venv然后安装：
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) |
+-----------------+ +----------------+