Server Hub

Server Hub is a Python service that exposes server-management and operational data through two interfaces:

• REST API, implemented with FastAPI

• MCP server, providing tools for MCP-aware clients and AI agents

Both interfaces are intended to expose the same underlying application capabilities rather than duplicate business logic.

Architecture

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 and MCP are interface boundaries around the application layer. Persistence details remain behind that boundary.

Related MCP server: quads-mcp

MCP tools

The MCP interface exposes:

• search_servers

• get_server

• get_server_metrics

• get_active_alerts

• get_system_stats

• create_alert

The MCP layer maps internal application data into client-oriented responses rather than exposing persistence implementation details.

REST API

The REST interface provides operations for:

• server discovery and lookup

• server status

• server metrics

• active alerts

• alert creation

• system statistics

Testing

Run the complete test suite with:

pytest -q

The repository includes separate tests for the public interfaces and a REST ↔ MCP equivalence suite.

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

The REST ↔ MCP equivalence tests verify that the two interfaces expose equivalent capabilities and data without requiring their response envelopes to be identical.

Project structure

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

tests/
docs/

The implementation is organized around application/domain logic and interface adapters.

Documentation

Additional architecture and decision records can be added under docs/ as the project evolves.

Development

Create a virtual environment, install the project dependencies, and run the tests:

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

The repository also contains scripts/components for running the REST and MCP services locally.

Design principles

• Keep application behavior independent from transport protocols.

• Treat REST and MCP as interface adapters.

• Keep persistence details behind the application boundary.

• Prefer meaningful domain identifiers in MCP-facing operations.

• Test public interfaces and their semantic equivalence.

License

No license is specified in the current project materials.