Laboratorio del Módulo 4 — Model Context Protocol
Convierte los sistemas de piezas, inventario y RMA de Helios Robotics en una capacidad MCP a la que cualquier cliente compatible con MCP pueda conectarse. Construido con FastMCP 3.x conforme a la especificación MCP.
Requisito | Implementación |
≥3 herramientas | 4 — |
≥2 recursos | 3 — |
≥1 prompt |
|
El cliente descubre e invoca cada uno |
|
Transporte + justificación | stdio (predeterminado), con soporte HTTP — justificación |
Seguridad del lado del cliente | Ambas — elicitación en la escritura, raíces en el cliente |
Resumen del diseño de seguridad | |
Manejo de errores | Entrada no válida, registro desconocido y almacén de respaldo inaccesible |
Documentación: arquitectura + transporte ·
herramientas/recursos/prompts ·
seguridad · registros: logs/
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python seed_data.py
python client.py # spawns the server over stdio and runs the full demoSin clave de API, sin modelo, sin coste — MCP es un protocolo y el cliente invoca el servidor directamente.
AUTO_APPROVE=1 python client.py # non-interactive (CI, log capture)
SIMULATE_DB_OUTAGE=1 python client.py # backing data source unreachable
MCP_TRANSPORT=http python server.py # serve on 127.0.0.1:8000
MCP_TRANSPORT=http python client.py # ...and connect to it{
"mcpServers": {
"helios-field-service": {
"command": "python",
"args": ["/absolute/path/to/helios-mcp/server.py"]
}
}
}Ese es el objetivo del ejercicio — construirlo una vez y que sea utilizable por cualquier cliente compatible con MCP.
Related MCP server: mcp-lab
logs/demo.log — flujo completo de descubrimiento e invocación:
1. DISCOVERY — tools
• search_parts [read-only] Search the Helios spare parts catalogue...
• get_inventory [read-only] Stock level and lead time for a part...
• analyse_failure [read-only] Correlate a fault code with known issues...
• create_rma [WRITE] Raise a Return Material Authorisation.
1. DISCOVERY — resources
• helios://catalog/summary Catalogue summary
• helios://parts/{part_number} Catalogue entry (template)
• helios://kb/{doc_id} Knowledge base article (template)
1. DISCOVERY — prompts
• diagnose_fault(fault_code, sku, site)La escritura, condicionada por la elicitación:
┌─ SERVER REQUESTS CONFIRMATION ──────────────────────────────────
│ Raise an RMA for 1 x HX2-BMS-03 (HX-200 Battery Management Board rev C)?
│ Serial: HX200-PHX-0442
│ Total value: $1,240.00
└─────────────────────────────────────────────────────────────────
{"created": true, "rma_id": "RMA-00001", "value_usd": 1240.0,
"requested_by": "mahesh.s"}logs/demo-db-outage.log — el almacén de respaldo inaccesible. Lo que ve el cliente:
TOOL UNAVAILABLE — Failure analysis is temporarily unavailable.
Quote reference dddc45d0fc07 to support if this persists.Lo que el servidor registró en stderr (logs/server-errors.log):
ERROR [helios-mcp] [dddc45d0fc07] Failure analysis failed:
OperationalError: could not connect to helios-db-prod-01.internal:5432: timeoutEl nombre de host y el puerto nunca cruzan la frontera del protocolo. El id de correlación es el puente entre ambos.
Los recursos y las herramientas no son intercambiables. search_parts encuentra una pieza cuando no conoces su id; helios://parts/{pn} obtiene una que ya tienes. Mismos datos, distinto patrón de acceso.
El prompt reside en el servidor intencionadamente. El procedimiento de diagnóstico es conocimiento del dominio de Helios, no lógica del host. Todos los clientes que se conectan reciben las mismas reglas — descartar el firmware antes de condenar el hardware, no cotizar nunca una pieza sustituida — en lugar de que cada uno las reimplemente por su cuenta y acaben divergiendo.
Todo el registro va a stderr. En stdio, stdout transporta las tramas JSON-RPC. Un print() suelto corrompe el flujo del protocolo; no hay ninguno en el servidor.
El cliente controla el entorno del servidor. Un servidor stdio lanzado no hereda automáticamente el entorno del proceso padre, por lo que PythonStdioTransport(env=...) pasa una lista explícita de permitidos en lugar de entregar todo el shell del llamador.
server.py MCP server: 4 tools, 3 resources, 1 prompt
client.py MCP client: discovery, invocation, elicitation, roots
seed_data.py Creates data/helios.db
docs/
architecture.md Diagrams + transport justification
capabilities.md Every tool, resource and prompt documented
security.md Auth, least privilege, error redaction
logs/
demo.log Successful discovery-and-invocation flow
demo-db-outage.log Backing store unreachable, client view
server-errors.log Server-side detail with correlation idsThis server cannot be deployed
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Search multi-merchant supply, checkout, and track orders via MCP.
Remote MCP server for product discovery catalog and retrieving product details.
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
