Servidor de documentación de Swarms MCP

📖 Descripción

Este programa es un servidor MCP de documentación de Agent Framework basado en FastMCP , diseñado para que los agentes de IA recuperen información de su base de datos de documentación de forma eficiente. Combina búsqueda híbrida semántica (vectorial) y por palabras clave (BM25), indexación fragmentada y una robusta API de herramientas FastMCP para una integración fluida con los agentes.

Capacidades clave:

• Recuperación eficiente a nivel de fragmentos mediante búsqueda semántica y de palabras clave

• Los agentes pueden consultar, enumerar y recuperar documentación utilizando las herramientas FastMCP

• Diseño local de baja latencia (todos los datos se indexan y consultan localmente)

• Reindexación automática al cambiar archivos

• Modular: agregue cualquier repositorio a corpora/ , soporte para todos los tipos de archivos principales

• Extensible: agregue nuevas herramientas, recuperadores o corpus según sea necesario

Módulos principales:

• embed_documents.py → Carga, fragmenta e incrusta documentos

• swarms_server.py → Abre el servidor MCP y las herramientas FastMCP

Related MCP server: mcp-agno

🌟 Características principales

• Hybrid Retriever 🔍: Combina búsqueda semántica y por palabras clave.

• Manejo dinámico de Markdown 📄: Cargador inteligente basado en el tamaño del archivo.

• Cargadores especializados ⚙️: .py , .ipynb , .md , .txt , .yaml , .yml .

• Resúmenes de fragmentos y archivos 📈: muestra los recuentos de fragmentos junto con los recuentos de archivos.

• Live Watchdog 🔥: responde instantáneamente a cualquier cambio en corpora/ .

• Confirmación de Usuario para Costos ✅: Confirma antes de incorporaciones costosas.

• Punto final de comprobación de estado 🚑: asegúrese de que el servidor esté listo para usarse.

• Local-First 🗂️: Todos los repositorios indexados localmente sin dependencias externas.

• Asistente de eliminación segura 🔥: Elimina automáticamente índices rotos o no coincidentes.

🏗️ Historial de versiones

📚 Administrar sus corpus (repositorios locales)

Debido a que Swarms y otros marcos son muy grandes , los corpus completos no se envían a GitHub.

En lugar de ello, los clona manualmente en 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

✅ Notas:

• Agregue cualquier repositorio : público, privado o personalizado.

• Cree su propia base de conocimiento de IA personalizada a nivel local.

• Los repositorios grandes (>500 MB) están bien; toda la indexación es local.

🚀 Inicio rápido

# 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.

⚙️ Configuración

• Corpus : Colocar repositorios dentro de corpora/

• Variables de entorno :

  • .env debe contener OPENAI_API_KEY

• Compatibilidad con archivos de índice :

  • Se admiten tanto chroma-collections.parquet como chroma.sqlite3 . Se prefiere .parquet si ambos existen.

• Incorporación automática :

  • Si no se encuentra ningún índice, el servidor le solicitará que incorpore e indexe sus documentos automáticamente.

• Opcional :

  • Deshabilite la compactación de croma si lo prefiere:

    setx CHROMA_COMPACTION_SERVICE__COMPACTOR__DISABLED_COLLECTIONS "swarms_docs"

• Banderas de la línea de comandos :

  • --reindex → activa una reindexación de actualización durante la ejecución del servidor.

🔄 Vigilancia de archivos y reindexación automática

El servidor MCP supervisa corpora/ para detectar cualquier cambio en los archivos:

• Cualquier modificación, creación o eliminación desencadena una reindexación en vivo .

• No es necesario reiniciar el servidor.

🛠️ Herramientas FastMCP disponibles

❓ Solución de problemas

• P: Obtengo el mensaje "No se encontró ningún índice existente válido" cuando inicio el servidor.

  • A: El servidor le solicitará que incruste e indexe los documentos. Acepte la solicitud para continuar o ejecute primero manualmente python embed_documents.py .

• P: ¿Qué archivo de índice se utiliza?

  • A: El servidor utilizará chroma-collections.parquet si está disponible, de lo contrario, chroma.sqlite3 .

• P: Quiero forzar una reindexación.

  • A: Ejecute python swarms_server.py --reindex o utilice la herramienta swarm_docs.reindex .

📋 Ejemplo de uso

# 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"])

🧰 Ampliación y reconstrucción

• Agregar nuevos documentos → colocarlos en corpora/ , luego:

  python swarms_server.py --reindex

• Cambios de esquema → (por ejemplo, estructura de metadatos diferente):

  python swarms_server.py --reindex --full

• Agregar nuevo repositorio → Arrastrar la carpeta a corpora/ y reindexar.

• Recomendado para repositorios mayoritariamente de solo lectura :

  setx CHROMA_COMPACTION_SERVICE__COMPACTOR__DISABLED_COLLECTIONS "swarms_docs"

🔗 Integración IDE

Conéctelo directamente a Windsurf Cascade:

"swarms": {
  "command": "C:/…/Swarms/venv/Scripts/python.exe",
  "args": ["swarms_server.py"]
}

Luego puedes acceder a las herramientas swarm_docs.* desde las automatizaciones de Cascade.

📦 Requisitos

💡 Se requiere entorno Python 3.11

Crea tu entorno explícitamente:

python3.11 -m venv venv

Luego instala con:

pip install -r requirements.txt

✅ Servidor MCP listo

Después del arranque:

• Resúmenes de carga adecuados

• Confirmación segura antes de acciones costosas

• Vigilancia y reindexación automática de archivos

• Preparado para conectar windsurf

• Cobertura completa de herramientas

¡Estás listo para ponerlo en cascada! 🏄‍♂️

Diagrama de flujo

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