SkillMCP (Sistema de gestión de habilidades)

Un servidor Model Context Protocol (MCP) contenerizado y horizontalmente escalable para distribuir y gestionar habilidades de los agentes de IA.

Descripción general y motivación

Los agentes de IA dependen de habilidades específicas de dominio (instrucciones, metadatos, esquemas y recursos de referencia) para realizar tareas complejas de ingeniería y análisis. Sin embargo, gestionar habilidades en equipos diversos y flotas de agentes suele introducir retos operativos críticos:

• Habilidades fragmentadas y obsoletas: Las habilidades almacenadas en repositorios individuales dispersos o copiadas manualmente se desincronizan rápidamente, dejando a los agentes ejecutando flujos de trabajo obsoletos o incompatibles.

• Cuellos de botella en la distribución y actualización: Distribuir actualizaciones de habilidades entre instancias de agentes distribuidas requiere sincronización manual o pasos frágiles de copia de archivos.

• Falta de versionado y fricción en el diagnóstico: Cuando las habilidades se editan sin un versionado inmutable, diagnosticar regresiones o cambios de comportamiento de los agentes resulta casi imposible.

• Límites de escalabilidad en un solo host: Los servidores MCP tradicionales basados en stdio están ligados a procesos locales de un solo host, lo que bloquea el escalado horizontal y la alta disponibilidad.

SkillMCP resuelve estos retos ofreciendo un sistema de gestión de habilidades centralizado, contenerizado y escalable horizontalmente, impulsado por Streamable HTTP sin estado (con compatibilidad SSE compatible con versiones anteriores).

Related MCP server: skilldb-mcp

Capacidades y características clave

1. Empaquetado centralizado y versionado de habilidades

• Publicaciones de contenedor inmutables: Las habilidades (SKILL.md, references/ y examples/) se empaquetan directamente dentro de imágenes Docker etiquetadas con semver explícito (v1.2.0), lo que garantiza entornos 100 % reproducibles y auditabilidad.

• Repositorio unificado de habilidades: Elimina la deriva fragmentada de múltiples repositorios al gestionar, validar y agrupar todas las habilidades de dominio en un único repositorio mantenible.

• Diagnóstico rápido y trazabilidad: Las etiquetas de contenedor versionadas permiten diagnosticar fácilmente los problemas de los agentes, reproducir el comportamiento histórico y revertir los cambios al instante.

2. MCP sin estado sobre Streamable HTTP (escalabilidad horizontal)

• Arquitectura de petición/respuesta verdaderamente sin estado: Streamable HTTP utiliza peticiones POST HTTP estándar en las que las instancias backend no mantienen un estado de socket en memoria de larga duración entre llamadas de cliente.

• Desacoplamiento de sesiones y escalado horizontal: Las peticiones individuales pueden enrutarse a cualquier réplica de contenedor backend detrás de un proxy inverso Nginx o balanceador de carga sin necesidad de sesiones fijas.

• Streaming de corta duración: Las respuestas que requieren streaming se actualizan a text/event-stream solo durante la duración de esa carga útil concreta y se cierran inmediatamente cuando termina la respuesta JSON-RPC.

• Compatibilidad con SSE heredado: Admite Server-Sent Events heredados (/sse) con omisión configurada del búfer del proxy (proxy_buffering off) y tiempos de espera de lectura ampliados para clientes que requieren canales persistentes.

• Balanceo de carga de Nginx Ingress: Configurado con enrutamiento least_conn, agrupación de conexiones keepalive y comprobaciones de salud /healthz dedicadas para actualizaciones continuas sin tiempo de inactividad.

[!WARNING] Transporte y escalabilidad horizontal:

• Streamable HTTP (default, recomendado): Verdaderamente sin estado. Permite el autoescalado horizontal y un balanceo de carga arbitrario entre réplicas sin afinidad de sesión.

• SSE nativo (SKILLMCP_TRANSPORT=sse): Con estado debido al enlace de flujo TCP persistente. En el modo SSE nativo, el escalado horizontal detrás de balanceadores de carga estándar round-robin/least-connections provocará errores de enrutamiento en POST /messages a menos que se usen sesiones fijas (por ejemplo, ip_hash de Nginx o afinidad por cookies) o un despliegue de una sola réplica.

3. Herramientas para desarrolladores y agentes

• CLI integrado de validación de habilidades: skillmcp validate ./skills verifica automáticamente las estructuras de directorio, el frontmatter YAML y los enlaces de recursos antes del empaquetado.

• Descubrimiento y búsqueda dinámicos:

  • Herramientas MCP: list_skills, get_skill, search_skills, read_skill_reference, read_skill_example.

  • Recursos MCP: skill://{name} para la inspección directa de documentos markdown.

• Entornos Compose duales: docker-compose.local.yml para el desarrollo local inmediato con recarga en caliente mediante volúmenes montados, y docker-compose.yml para despliegues de producción.

• Estándar Python TREM: Construido siguiendo estrictamente los principios Testable, Readable, Extensible y Maintainable (TREM) con uv, pydantic-settings, la biblioteca estándar logging y pytest.

• Publicación automatizada de CI/CD: pipeline de GitHub Actions que valida las pruebas y publica lanzamientos semver inmutables en Docker Hub con etiquetas de versión (v*.*.*).

Inicio rápido

Requisitos previos

• Python 3.11+

• uv

• Docker y Docker Compose

Instalación local

# Sync dependencies
uv sync

# Run tests
uv run pytest -v

# Validate skills
uv run skillmcp validate ./skills

# List discovered skills
uv run skillmcp list --skills-path ./skills

Ejecutar el servidor localmente

# Start MCP server directly (Streamable HTTP on port 8000)
uv run skillmcp serve --host 0.0.0.0 --port 8000

Topologías Docker

Desarrollo local (recarga en caliente e Ingress)

docker compose -f docker-compose.local.yml up -d --build

• Nginx Ingress: http://localhost:8080 (comprobación de salud /healthz)

• Aplicación de backend: http://localhost:8000 (comprobación de salud /healthz)

Despliegue en producción

docker compose up -d

Puntos de prueba

• Punto 1: Servicio de dominio: tests/test_domain_service.py (Valida el escáner, el analizador, la seguridad del recorrido y el motor de consultas)

• Punto 2: Protocolo MCP y herramientas: tests/test_mcp_server.py y tests/test_mcp_http.py (Valida las herramientas y recursos FastMCP, y las rutas de transporte ASGI)

• Punto 3: CLI e integración: tests/test_cli.py (Valida los comandos validator, list y serve de la CLI)