Servidor de documentación de Swarms MCP

Versión 2.2

📖 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 Expert Server

🌟 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:

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

Swarms MCP Documentation Server