Multi-MCP Enterprise Operations Copilot

Un copiloto para operadores de planta. Responde preguntas en lenguaje natural llamando a una API de Gestión de Alarmas a través de servidores MCP creados con un propósito específico, recuperando pasajes de apoyo de un corpus de documentos operativos y fusionando ambos en una única respuesta fundamentada que incluye citas y un rastro de ejecución visible.

git clone <repository-url> && cd senior-copilot-mcp-rag-assignment
cp .env.example .env
docker compose up --build

Luego abra http://localhost:5173 y haga la pregunta de aceptación. No se requiere clave API: la pila usa por defecto un proveedor determinista que ejecuta el mismo flujo de trabajo sin un LLM. Configure LLM_PROVIDER=anthropic y ANTHROPIC_API_KEY para obtener prosa generada.

1 · Caso de uso seleccionado

Multi-MCP Enterprise Operations Copilot. El copiloto descubre y coordina herramientas a través de dos servidores MCP en lugar de integraciones codificadas, y combina esos datos estructurados con evidencia documental no estructurada en un solo flujo de trabajo.

El escenario de aceptación obligatorio:

Investigue las alarmas recurrentes de alta severidad para la Bomba de Agua de Alimentación 101 durante los últimos 90 días, identifique los factores contribuyentes probables, recupere el procedimiento operativo relevante y proporcione acciones recomendadas con evidencia de origen.

Ese escenario se ejecuta como una prueba automatizada (tests/e2e/test_acceptance_scenario.py) que verifica, sobre la superficie HTTP real, que se ejecutan cinco pasos, que el paso 2 recibió el id de activo que produjo el paso 1, que la recuperación se limitó por el nombre de activo que resolvió el paso 1, y que la respuesta contiene tanto un marcador [tool: …] como un marcador [source: …].

Una nota sobre el sistema fuente

La API de Gestión de Alarmas descrita en el resumen no existe como un servicio en ejecución; las colecciones de Postman proporcionadas son su especificación. Por lo tanto, también se construye aquí, como services/alarm-simulator/: 15 endpoints, autenticación bearer, cabeceras de traza, un envoltorio de error y datos deterministas sembrados diseñados para que cada aserción de encadenamiento en las colecciones proporcionadas devuelva resultados no vacíos. make contract ejecuta las tres colecciones contra él; CI hace lo mismo en cada push.

2 · Capacidades principales

• Chat en lenguaje natural sobre datos de alarmas en vivo y documentos operativos

• Descubrimiento de herramientas en tiempo de ejecución a través de dos servidores MCP — sin lista de herramientas codificada

• Encadenamiento de herramientas en múltiples pasos, donde la salida de una herramienta se convierte en la entrada de la siguiente

• Recuperación híbrida de documentos (BM25 + vectores densos, fusionados por rango recíproco) con citas en línea

• Una respuesta que combina resultados de herramientas estructurados y evidencia documental no estructurada

• Rastro de ejecución completo: qué servidor, qué herramienta, qué argumentos, cuánto tiempo, qué resultado

• Confirmación humana explícita antes de cualquier escritura, impuesta en el contrato de la herramienta

• Degradación gradual ante fallo de herramienta, tiempo de espera, esquema inválido, recuperación vacía, rechazo del modelo o falta de clave API

3 · Pila tecnológica

4 · Resumen de arquitectura

Cinco servicios. La GUI se comunica con un orquestador FastAPI a través de REST y SSE. El orquestador planifica una secuencia de pasos contra un registro de herramientas que descubrió en tiempo de ejecución desde dos servidores MCP, resuelve los argumentos de cada paso (incluyendo valores producidos por pasos anteriores), ejecuta la recuperación de documentos como uno de esos pasos y compone una respuesta citada.

Browser ──HTTP/SSE──▶ backend ──MCP──▶ mcp-alarm-management ──HTTPS+bearer──▶ alarm-simulator
                         │      └────▶ mcp-github-issues    ──────────────▶ GitHub (mocked)
                         └─embedded──▶ Chroma index over rag/documents

Solo los servidores MCP tienen las credenciales de los sistemas detrás de ellos. El copiloto nunca llama directamente a la API de Gestión de Alarmas, por lo que el modelo de lenguaje no tiene ninguna ruta de código hacia el token bearer — no puede leerlo, solicitarlo ni ser inducido por inyección de prompt a revelarlo.

• Flujo de solicitud de extremo a extremo: docs/architecture.md

• Componentes, ADRs, NFRs, riesgos, trazabilidad: docs/hld.md

• Esquemas, firmas, algoritmos, máquinas de estado: docs/lld.md

5 · Servidores MCP y herramientas

Dos servidores construidos por el candidato. Los contratos completos — incluyendo esquemas de entrada/salida, comportamiento de autenticación, comportamiento de error, tiempos de espera y ejemplos reales de solicitudes y respuestas — están en docs/mcp-tool-catalog.md, que se genera a partir de una llamada en vivo a list_tools() y se verifica en CI, por lo que no puede desviarse del código.

alarm-management — 14 herramientas

github-issues — 3 herramientas

Ejecutando uno por sí solo

python -m alarm_mcp                      # stdio, for a local MCP client
python -m alarm_mcp --transport http     # streamable HTTP, as in compose
python scripts/mcp_smoke.py              # chain two tools, no GUI and no LLM

6 · Corpus RAG e ingesta

10 documentos markdown (procedimientos operativos, guías de solución de problemas, estándares, una instrucción de seguridad, un boletín del proveedor) → 49 fragmentos alineados por encabezado → índice Chroma embebido.

python -m rag.ingestion.cli --docs ./rag/documents --reset

La recuperación fusiona BM25 con vectores densos, filtra por el activo que resolvió una llamada de herramienta anterior e informa low_confidence en lugar de disfrazar una coincidencia débil. Un documento del corpus contiene una carga útil de inyección de prompt en vivo para que el límite de confianza se pruebe en lugar de afirmarse.

Diseño completo — fragmentación, metadatos, fusión, construcción de citas, confianza, defensa contra inyección, actualización: docs/rag-design.md.

7 · Configuración

Cada valor es una variable de entorno. .env.example documenta cada clave con un marcador de posición seguro; no se confirma ningún secreto, y no se necesita ninguno para ejecutar la demo.

Referencia completa con tipos, valores por defecto y servicio consumidor: docs/lld.md §9.

8 · Construir y ejecutar

make es canónico y es lo que usa CI. En Windows sin make, tasks.ps1 expone los mismos nombres de objetivo.

Puertos: GUI 5173, backend 8080, simulador 8000 (expuesto para que las colecciones de Postman puedan ejecutarse contra él), servidores MCP 9000 / 9001 (internos).

Si alguno de esos ya está ocupado, sobrescriba el lado del host en .env — los puertos del contenedor nunca cambian. Establezca VITE_API_BASE_URL para que coincida con el puerto del backend, porque Vite lo incrusta en la GUI en tiempo de compilación:

BACKEND_HOST_PORT=8090 VITE_API_BASE_URL=http://localhost:8090 docker compose up --build

Sin Docker: make install, luego ejecute los cuatro servicios Python en terminales separadas — uvicorn alarm_simulator.main:app --port 8000, python -m alarm_mcp --transport http, python -m github_mcp --transport http, make ingest, uvicorn copilot_backend.api.app:app --port 8080 — y npm run dev en apps/frontend.

9 · Pruebas

make contract requiere newman (npm install -g newman) y un simulador en ejecución.

269 pruebas, todas pasan, 89% de cobertura de línea — desglose en docs/coverage.md. Lo que cubren:

El LLM está simulado en todas partes, incluido el extremo a extremo, por lo que el conjunto es rápido, gratuito y repetible. Consulte docs/known-limitations.md para saber qué significa eso.

10 · Interacciones de muestra

Alarmas recurrentes (el escenario de aceptación). Cinco pasos: resolver el activo → resumir sus alarmas de alta gravedad → correlacionar pares co-ocurrentes → encontrar candidatos de racionalización → recuperar el procedimiento, filtrado por el activo recién resuelto. La respuesta informa que Discharge Pressure Low es seguido por Suction Strainer DP High 31 veces (lift 2.29, lag medio 393s) [tool: alarm-management/get_alarm_correlation] y lo empareja con los pasos de aislamiento e inspección de [source: OP-BFP-101#…].

Eficiencia de respuesta del operador. generate_calculation → execute_calculation (encadenado en calculation_id) → tendencia del retraso de acuse de recibo → el estándar aplicable de STD-OPRESP.

Escalada. Alarmas activas → puntuación de prioridad en la principal → acciones recomendadas con contexto de alarma relacionada → la sección de filosofía de alarmas correspondiente.

Registrar una incidencia. Resumen de alarma → comprobación de duplicados → draft_issue. create_issue detiene la ejecución con confirmation.required; la GUI muestra los argumentos exactos y solo continúa después de la aprobación. El servidor MCP rechaza independientemente de lo que haga la UI.

Una pregunta sin documento de soporte. La recuperación informa low_confidence; la respuesta dice claramente que no se encontró ningún procedimiento relevante en lugar de sustituir conocimiento general.

11 · Estructura del repositorio

apps/backend/          FastAPI orchestrator, MCP client, LLM providers
apps/frontend/         React + TypeScript GUI
mcp-servers/           alarm-management (14 tools), github-issues (3 tools)
services/              alarm-simulator — the candidate-built source system
connectors/alarm_api/  Reusable HTTP client, deliberately separate from the MCP server
packages/schemas/      Shared Pydantic tool contracts
rag/                   documents, ingestion, retrieval, tests
tests/                 unit, integration, e2e
docs/                  architecture, HLD, LLD, tool catalog, RAG design, decisions, limits
postman/               The supplied collections — the Alarm API specification

Dos desviaciones documentadas de la estructura en las pautas de envío §3:

• services/alarm-simulator/ — el resumen exige por separado un backend construido por el candidato, que no es una de las carpetas predefinidas. Mantener el simulador (el sistema bajo integración) separado de connectors/ (el cliente que se conecta a él) es una separación más limpia que juntar ambos.

• docs/hld.md y docs/lld.md — añadidos junto con el requerido docs/architecture.md, que sigue siendo el punto de entrada.

Las pautas permiten estructuras equivalentes cuando están claramente documentadas. Debido a que los nombres de directorio obligatorios están separados por guiones y, por lo tanto, no son nombres de paquetes Python válidos, cada uno contiene un paquete con el nombre correcto (mcp-servers/alarm-management/alarm_mcp/) mapeado a una importación de nivel superior en pyproject.toml.

12 · Suposiciones

1. La API de Alarm Management no existe, por lo que las colecciones de Postman se tratan como su especificación y el simulador está construido para satisfacerlas exactamente. Cuando las colecciones eran silenciosas (por ejemplo, los filtros que aparecen solo en la colección de encadenamiento), las aserciones de la colección son la autoridad.

2. Los ids de alarma, ids de activo y marcas de tiempo son reproducibles. La semilla es fija, por lo que una demostración, una prueba y una ejecución de Postman ven los mismos datos.

3. Correlación significa co-ocurrencia dentro de una ventana de retardo en el mismo activo. La prueba de significancia estadística está fuera del alcance para datos sintéticos.

4. Un inquilino, un conjunto de sitios. No se pasa ningún identificador de inquilino a través de la recuperación o la autorización de herramientas.

5. El salto de GUI a backend no está autenticado, lo cual es aceptable para una demostración local y se menciona en las limitaciones.

6. docker compose up es la ruta compatible. La ruta manual está documentada en §8 pero el archivo compose es lo que CI ejecuta.

13 · Limitaciones conocidas y mejoras futuras

Límites de alcance honestos, cada uno con lo que se haría de manera diferente con más tiempo: docs/known-limitations.md. Lo que viene después, en el orden en que lo haría: docs/future-improvements.md.

14 · Demostración

Capturas de pantalla

Capturadas de la pila en ejecución por make screenshots, por lo que se pueden regenerar en lugar de quedarse obsoletas: docs/screenshots/.

También capturado: el estado vacío y la respuesta con chips de cita.

Video

Enlace: por añadir — consulte docs/demo.md para el guion del recorrido grabado.

Cubre el escenario de aceptación de extremo a extremo, descubrimiento de herramientas con inspección de esquema, la línea de tiempo de ejecución, chips de cita que se resuelven en evidencia, la puerta de confirmación de escritura, y luego la ruta de fallo — el simulador se detiene a mitad de sesión para mostrar reintento, respuestas degradadas y lagunas honestas.

Licencia

MIT — consulte LICENSE.