🐝 Swarms MCP 文档服务器

版本 2.2

📖 描述

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

主要功能：

使用语义和关键字搜索进行高效的块级检索
代理可以使用 FastMCP 工具查询、列出和检索文档
本地优先、低延迟设计（所有数据均在本地索引和查询）
文件更改时自动重新索引
模块化：将任何 repos 添加到corpora/ ，支持所有主要文件类型
可扩展：根据需要添加新工具、检索器或语料库

主要模块：

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

Related MCP server: MCP Expert Server

🌟 主要特点

混合检索器🔍：结合语义和关键字搜索。
动态 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/中
环境变量：
- .env必须包含OPENAI_API_KEY
索引文件支持：
- 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 环境

明确创建您的环境：

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

Swarms MCP Documentation Server