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 documentosswarms_server.py → Abre el servidor MCP y las herramientas FastMCP
🌟 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
| Versión | Fecha | Reflejos |
|---|
| 2.2 | 2025‑04‑25 | Dividir la incrustación/carga desde el servidor; recuento completo de fragmentos en los resúmenes de carga |
| 1.0 | 2025‑04‑25 | Cargador dinámico de Markdown, registros de color y herramienta de comprobación de estado |
| 0.7 | 2025‑04‑25 | Cargadores de archivos especializados para .py , .ipynb , .md |
| 0.5 | 2025‑04‑10 | Incrustaciones de modelos grandes de OpenAI, herramientas MCP extendidas |
| 0.1 | 2025‑04‑10 | Versión inicial con cargadores genéricos |
📚 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
| Herramienta | Descripción |
|---|
swarm_docs.search | Buscar fragmentos de documentación relevantes |
swarm_docs.list_files | Listar todos los archivos indexados |
swarm_docs.get_chunk | Obtener un fragmento específico por ruta e índice |
swarm_docs.reindex | Forzar reindexación (completa o incremental) |
swarm_docs.healthcheck | Comprobar el estado del servidor MCP |
❓ 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:
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) |
+-----------------+ +----------------+