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

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

✅ 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

⚙️ 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

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

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:

✅ 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