hydris-mcp-integration

Hydris Pulse Bridge track, Work Item 1: el esqueleto del servidor MCP de diagnóstico que residirá en lite/diagnostic_mcp/ dentro del monorepo Lite. Este implementa BRIDGE-2 (autorización por fábrica por llamada), BRIDGE-5 (registro de auditoría por llamada) y NFR-4 (seguridad), y aplica estructuralmente BRIDGE-1 (conjunto de herramientas de solo lectura).

Consulte docs/scope.md para saber exactamente qué se construye y qué no aquí, y docs/decisions.md para las decisiones sobre elementos abiertos (latencia de revocación, comportamiento ante fallos del sumidero de auditoría, la forma del error sin fuga de información, el esquema de versiones del conjunto de herramientas) que este esqueleto adoptó, pendientes de la ratificación de Nematullah.

Arquitectura

• Dos identidades, mantenidas separadas (diagnostic_mcp/auth/): un JWT de principal de servicio (ámbitos de solo lectura, verificado de forma independiente) y un JWT de contexto de usuario por llamada. El token de servicio nunca amplía el acceso.

• Una canalización para cada llamada (diagnostic_mcp/registry/pipeline.py): autenticar ambas identidades, validar argumentos, comprobar la concesión de fábrica activa del usuario (sin almacenamiento en caché), enviar, registrar el resultado de la auditoría (éxito, rechazo o error) en cada ocasión.

• Puerta de solo lectura en el momento del registro (diagnostic_mcp/registry/tool_registry.py): una herramienta sin classification="read_only" o sin un argumento factory_id requerido es rechazada cuando se registra, no cuando se invoca.

• FastMCP para la publicidad del esquema, una anulación para el envío (diagnostic_mcp/server.py): tools/list proviene de FastMCP como de costumbre; tools/call es interceptado una vez, a nivel de servidor de bajo nivel, de modo que cada herramienta (presente o futura) pasa por la misma canalización sin código repetitivo por herramienta.

• Una herramienta de demostración, get_plant_overview (diagnostic_mcp/tools/plant_overview.py), respaldada por un simulacro en memoria de la capa de servicio de solo lectura de Lite, sembrada con los mismos datos de prueba que los documentos fuente nombran (u-ops-alpha con concesión fx-mbr-01; u-ops-beta con concesión fx-beta-01).

Related MCP server: system-monitor

Inicio rápido

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

Ejecute el servidor:

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

Escucha en streamable-http en http://127.0.0.1:8765/mcp por defecto.

Verifíquelo de extremo a extremo

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

Para invocar el servidor en ejecución manualmente con el cliente MCP oficial, genere un token de servicio y un token de contexto de usuario con los mismos secretos con los que se está ejecutando el servidor:

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}")

Luego invoque get_plant_overview con factory_id=fx-mbr-01 (concedido - tiene éxito) o factory_id=fx-beta-01 (no concedido - denegado, y ambos intentos quedan registrados en audit.jsonl).

Definición de completado del Work Item 1