Server Hub

Server Hub es un servicio de Python que expone datos de gestión y operación de servidores a través de dos interfaces:

• API REST, implementada con FastAPI

• servidor MCP, que proporciona herramientas para clientes compatibles con MCP y agentes de IA

Ambas interfaces están diseñadas para exponer las mismas capacidades subyacentes de la aplicación, en lugar de duplicar la lógica de negocio.

Arquitectura

flowchart LR
    RESTClient["REST Client"] --> REST["REST API"]
    MCPClient["MCP Client / AI Agent"] --> MCP["MCP Server"]

    REST --> App["Application Layer"]
    MCP --> App

    App --> Domain["Domain / Models"]
    App --> Persistence["Persistence"]
    Persistence --> DB[("Database")]

REST y MCP son límites de interfaz alrededor de la capa de aplicación. Los detalles de persistencia permanecen detrás de ese límite.

Related MCP server: quads-mcp

Herramientas MCP

La interfaz MCP expone:

• search_servers

• get_server

• get_server_metrics

• get_active_alerts

• get_system_stats

• create_alert

La capa MCP convierte los datos internos de la aplicación en respuestas orientadas al cliente, en lugar de exponer detalles de implementación de la persistencia.

API REST

La interfaz REST proporciona operaciones para:

• descubrimiento y búsqueda de servidores

• estado de servidores

• métricas de servidores

• alertas activas

• creación de alertas

• estadísticas del sistema

Pruebas

Ejecute la suite de pruebas completa con:

pytest -q

El repositorio incluye pruebas separadas para las interfaces públicas y una suite de equivalencia REST ↔ MCP.

tests/
├── test_api.py
├── test_mcp.py
└── test_rest_mcp_equivalence.py

Las pruebas de equivalencia REST ↔ MCP verifican que las dos interfaces exponen capacidades y datos equivalentes sin exigir que sus envoltorios de respuesta sean idénticos.

Estructura del proyecto

app/
├── api/
│   ├── domain/
│   ├── routes/
│   └── ...
├── mcp/
└── ...

tests/
docs/

La implementación está organizada en torno a la lógica de aplicación/dominio y a los adaptadores de interfaz.

Documentación

Se pueden añadir registros adicionales de arquitectura y decisiones en docs/ a medida que el proyecto evolucione.

Desarrollo

Cree un entorno virtual, instale las dependencias del proyecto y ejecute las pruebas:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
pytest -q

El repositorio también contiene scripts/componentes para ejecutar los servicios REST y MCP localmente.

Principios de diseño

• Mantener el comportamiento de la aplicación independiente de los protocolos de transporte.

• Tratar REST y MCP como adaptadores de interfaz.

• Mantener los detalles de persistencia detrás del límite de la aplicación.

• Preferir identificadores de dominio significativos en las operaciones orientadas a MCP.

• Probar las interfaces públicas y su equivalencia semántica.

Licencia

No se especifica ninguna licencia en los materiales actuales del proyecto.