Server Hub

Server Hub는 두 가지 인터페이스를 통해 서버 관리 및 운영 데이터를 노출하는 Python 서비스입니다:

• REST API, FastAPI로 구현

• MCP server, MCP를 지원하는 클라이언트와 AI 에이전트를 위한 도구 제공

두 인터페이스 모두 비즈니스 로직을 중복 구현하는 대신 동일한 기본 애플리케이션 기능을 노출하도록 설계되었습니다.

아키텍처

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와 MCP는 애플리케이션 계층을 둘러싼 인터페이스 경계입니다. 영속성 세부 사항은 해당 경계 뒤에 남아 있습니다.

Related MCP server: quads-mcp

MCP 도구

MCP 인터페이스는 다음을 노출합니다:

• search_servers

• get_server

• get_server_metrics

• get_active_alerts

• get_system_stats

• create_alert

MCP 계층은 영속성 구현 세부 사항을 노출하는 대신 내부 애플리케이션 데이터를 클라이언트 지향 응답으로 매핑합니다.

REST API

REST 인터페이스는 다음 작업을 제공합니다:

• 서버 검색 및 조회

• 서버 상태

• 서버 메트릭

• 활성 알림

• 알림 생성

• 시스템 통계

테스트

다음 명령으로 전체 테스트 스위트를 실행합니다:

pytest -q

저장소에는 공개 인터페이스에 대한 별도의 테스트와 REST ↔ MCP 동등성 테스트 스위트가 포함되어 있습니다.

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

REST ↔ MCP 동등성 테스트는 응답 형식이 동일할 것을 요구하지 않으면서 두 인터페이스가 동등한 기능과 데이터를 노출하는지 검증합니다.

프로젝트 구조

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

tests/
docs/

구현은 애플리케이션/도메인 로직과 인터페이스 어댑터를 중심으로 구성됩니다.

문서

프로젝트가 발전함에 따라 docs/ 아래에 추가적인 아키텍처 및 결정 기록을 작성할 수 있습니다.

개발

가상 환경을 만들고 프로젝트 의존성을 설치한 다음 테스트를 실행합니다:

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

저장소에는 REST 및 MCP 서비스를 로컬에서 실행하기 위한 스크립트/구성 요소도 포함되어 있습니다.

설계 원칙

• 애플리케이션 동작을 전송 프로토콜과 독립적으로 유지합니다.

• REST와 MCP를 인터페이스 어댑터로 취급합니다.

• 영속성 세부 사항을 애플리케이션 경계 뒤에 유지합니다.

• MCP 관련 작업에서는 의미 있는 도메인 식별자를 우선적으로 사용합니다.

• 공개 인터페이스와 이들의 의미적 동등성을 테스트합니다.

라이선스

현재 프로젝트 자료에는 라이선스가 명시되어 있지 않습니다.