Skip to main content
Glama
Sign In
enesjakozh
Swarms MCP Documentation Server

Swarms MCP Documentation Server

by Ransom-Alpha
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🐝 Swarms MCP 文档服务器

版本 2.2

📖 描述

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

主要功能：

  • 使用语义和关键字搜索进行高效的块级检索

  • 代理可以使用 FastMCP 工具查询、列出和检索文档

  • 本地优先、低延迟设计（所有数据均在本地索引和查询）

  • 文件更改时自动重新索引

  • 模块化：将任何 repos 添加到corpora/ ，支持所有主要文件类型

  • 可扩展：根据需要添加新工具、检索器或语料库

主要模块：

  • embed_documents.py → 加载、分块和嵌入文档

  • swarms_server.py → 启动 MCP 服务器和 FastMCP 工具

Related MCP server: tech-doc-mcp

🌟 主要特点

  • 混合检索器🔍：结合语义和关键字搜索。

  • 动态 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) |
+-----------------+                                   +----------------+

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • Agentdocs

    Olga4909
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables AI models to search and retrieve up-to-date technical documentation for major agent frameworks (such as LangChain, LlamaIndex, AutoGen, Agno, OpenAI Agents SDK, MCP docs, Camel-AI and CrewAI) by running scoped Google searches and parsing the resulting pages. It can be deployed locally over stdio or remotely over SSE.
    -

Appeared in Searches