🐝 Swarms MCP Documentation Server

🐝 Swarms MCP 文档服务

---

📖 简介

该程序是一个基于 FastMCP 构建的 Agent 框架文档 MCP 服务，旨在帮助 AI Agent 高效地从文档数据库中检索信息。它结合了语义（向量）与关键词（BM25）混合搜索、分块索引，以及功能强大的 FastMCP 工具 API，实现与 Agent 的无缝集成。

主要功能：

• 通过语义搜索和关键词搜索，高效检索文档块
• Agent 可使用 FastMCP 工具查询、列出和检索文档
• 本地优先、低延迟设计（所有数据均在本地建立索引并进行查询）
• 文件更改时自动重新建立索引
• 模块化：将任意仓库添加到 corpora/，支持所有主流文件类型
• 可扩展：按需添加新工具、检索器或语料库

主要模块：

• embed_documents.py → 加载、分块并嵌入文档
• swarms_server.py → 启动 MCP 服务和 FastMCP 工具

---

---

🌟 主要功能

• 混合检索器 🔍：结合语义搜索和关键词搜索。
• 动态 Markdown 处理 📄：根据文件大小智能加载。
• 专用加载器 ⚙️：支持 .py、.ipynb、.md、.txt、.yaml、.yml。
• 分块和文件摘要 📈：显示分块数量以及文件数量。
• 实时监控 🔥：立即响应 corpora/ 中的任何更改。
• 费用操作前征求用户确认 ✅：在执行高成本嵌入操作前进行确认。
• 健康检查端点 🚑：确保服务已就绪，可供使用。
• 本地优先 🗂️：所有仓库均在本地建立索引，不依赖外部服务。
• 安全删除助手 🔥：自动删除损坏或不匹配的索引。

---

🏗️ 版本历史

版本	日期	更新内容
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.

---

⚙️ 配置

• 语料库：将仓库放入 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 服务状态

---

❓ 故障排除

• 问：启动服务时，我收到“未找到有效的现有索引”。
  • 答：现在服务会提示你对文档进行嵌入和索引。接受提示以继续，或先手动运行 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
  

• 添加新仓库 → 将文件夹放在 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 环境

显式创建环境：

python3.11 -m venv venv

然后安装：

pip install -r requirements.txt

---

✅ MCP 服务已就绪

启动后：

• 提供清晰的加载摘要
• 在执行耗时操作前进行安全确认
• 自动监控文件并重新索引
• Windsurf 插件已就绪
• 提供完整的工具支持

现在可以开始使用 Cascade 了！ 🏄‍♂️

---

📈 流程图

                          +------------------+
                          |    🖥️ 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) |
+-----------------+                                   +----------------+