hydris-mcp-integration

Hydris Pulse Bridge 트랙, 작업 항목 1: Lite 모노레포 내 lite/diagnostic_mcp/에 위치할 진단 MCP 서버 스켈레톤입니다. BRIDGE-2 (호출별 팩토리 권한 부여), BRIDGE-5 (호출별 감사 로깅), NFR-4 (보안)을 이행하며, 구조적으로 BRIDGE-1 (읽기 전용 도구 세트)을 강제합니다.

여기서 구축하는 내용과 구축하지 않는 내용은 docs/scope.md를, 열린 항목 결정 사항(취소 지연 시간, 감사 저장소 실패 동작, 정보 누출 없는 오류 형태, 도구 세트 버전 체계)은 docs/decisions.md를 참조하십시오. 이 스켈레톤은 해당 결정 사항에 대해 입장을 취했으며, Nematullah의 승인을 기다리고 있습니다.

아키텍처

• 두 개의 ID, 분리 유지 (diagnostic_mcp/auth/): 서비스 주체 JWT(읽기 전용 범위, 독립적으로 검증)와 호출별 사용자 컨텍스트 JWT. 서비스 토큰은 접근 권한을 확장하지 않습니다.

• 모든 호출에 대한 단일 파이프라인 (diagnostic_mcp/registry/pipeline.py): 두 ID를 인증하고, 인수를 검증하며, 사용자의 실시간 팩토리 권한을 확인(캐싱 없음)하고, 전달하며, 결과(성공, 거부, 오류)를 매번 감사 로그에 기록합니다.

• 등록 시 읽기 전용 게이트 (diagnostic_mcp/registry/tool_registry.py): classification="read_only"가 없거나 필수 factory_id 인수가 없는 도구는 호출 시가 아닌 등록 시 거부됩니다.

• 스키마 광고용 FastMCP, 디스패치용 하나의 오버라이드 (diagnostic_mcp/server.py): tools/list는 평소처럼 FastMCP에서 제공되며, tools/call은 저수준 서버에서 한 번 가로채어 모든 도구(현재 및 미래)가 도구별 상용구 없이 동일한 파이프라인을 통과하도록 합니다.

• 하나의 데모 도구, get_plant_overview (diagnostic_mcp/tools/plant_overview.py): Lite의 읽기 서비스 계층의 인메모리 스텁으로 구현되며, 소스 문서에 명시된 정확한 픽스처(u-ops-alpha에 fx-mbr-01 부여, u-ops-beta에 fx-beta-01 부여)로 시드됩니다.

Related MCP server: system-monitor

빠른 시작

python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"      # .venv/bin/pip on macOS/Linux
cp .env.example .env                        # then edit the two secrets

서버 실행:

set -a; source .env; set +a                 # or export the vars another way
python -m diagnostic_mcp.server

기본적으로 streamable-http로 http://127.0.0.1:8765/mcp에서 수신 대기합니다.

엔드투엔드 확인

pytest -v            # includes a real streamable-HTTP client/server round trip
ruff check .
mypy diagnostic_mcp tests
python scripts/check_no_write_imports.py

실행 중인 서버를 공식 MCP 클라이언트로 수동 호출하려면 서버가 사용 중인 동일한 비밀에 대해 서비스 토큰과 사용자 컨텍스트 토큰을 발급하십시오:

from diagnostic_mcp.auth.service_principal import issue_service_token
from diagnostic_mcp.auth.user_context import issue_user_context_token

service_token = issue_service_token("<LITE_MCP_SERVICE_TOKEN_SECRET>")
user_token = issue_user_context_token("<LITE_MCP_USER_CONTEXT_SECRET>", "u-ops-alpha", "org-alpha")
print(f"Authorization: Bearer {service_token}")
print(f"X-Pulse-User-Context: {user_token}")

그런 다음 factory_id=fx-mbr-01(권한 있음 - 성공) 또는 factory_id=fx-beta-01(권한 없음 - 거부됨, 두 시도 모두 audit.jsonl에 기록됨)로 get_plant_overview를 호출하십시오.

작업 항목 1 완료 정의