Helios Field Service
Helios Field Service — Produktionsreifer MCP-Server und -Client
Modul 4-Labor — Model Context Protocol
Verwandelt die Teile-, Inventar- und RMA-Systeme von Helios Robotics in eine MCP-Fähigkeit, an die jeder MCP-fähige Client andocken kann. Erstellt mit FastMCP 3.x gemäß der MCP-Spezifikation.
Anforderung | Umsetzung |
≥3 Tools | 4 — |
≥2 Ressourcen | 3 — |
≥1 Prompt |
|
Client entdeckt + ruft alle auf |
|
Transport + Begründung | stdio (Standard), HTTP unterstützt — Begründung |
Client-seitige Sicherheit | Beides — Rückfrage beim Schreiben, Roots auf dem Client |
Zusammenfassung des Sicherheitsdesigns | |
Fehlerbehandlung | Ungültige Eingabe, unbekannter Datensatz und nicht erreichbarer zugrunde liegender Datenspeicher |
Dokumentation: Architektur + Transport · Tools/Ressourcen/Prompts · Sicherheit · Logs: logs/
Schnellstart
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 demoKein API-Schlüssel, kein Modell, keine Kosten — MCP ist ein Protokoll, und der Client ruft den Server direkt auf.
Weitere Aufrufe
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 itVon jedem MCP-Host aus verwenden
{
"mcpServers": {
"helios-field-service": {
"command": "python",
"args": ["/absolute/path/to/helios-mcp/server.py"]
}
}
}Das ist der Sinn der Übung — einmal gebaut, für jeden MCP-fähigen Client nutzbar.
Related MCP server: RoboPartPicker
Was die Demo zeigt
logs/demo.log — der vollständige Discovery- und Aufruf-Ablauf:
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)Der Schreibvorgang, per Rückfrage abgesichert:
┌─ 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 — der zugrunde liegende Datenspeicher ist nicht erreichbar. Was der Client sieht:
TOOL UNAVAILABLE — Failure analysis is temporarily unavailable.
Quote reference dddc45d0fc07 to support if this persists.Was der Server auf stderr protokolliert hat (logs/server-errors.log):
ERROR [helios-mcp] [dddc45d0fc07] Failure analysis failed:
OperationalError: could not connect to helios-db-prod-01.internal:5432: timeoutHostname und Port überschreiten niemals die Protokollgrenze. Die Korrelations-ID ist die Brücke zwischen den beiden.
Designhinweise
Ressourcen und Tools sind nicht austauschbar. search_parts findet ein Teil, wenn man dessen ID nicht kennt; helios://parts/{pn} ruft eines ab, das man bereits hat. Gleiche Daten, anderes Zugriffsmuster.
Der Prompt liegt bewusst auf dem Server. Das Diagnoseverfahren ist Helios-Domänenwissen, nicht Host-Logik. Jeder sich verbindende Client erhält dieselben Regeln — erst Firmware ausschließen, bevor Hardware verurteilt wird, niemals ein ersetztes Teil anbieten — statt sie jeweils neu zu implementieren und dabei auseinanderzudriften.
Sämtliche Protokollierung geht an stderr. Bei stdio transportiert stdout die JSON-RPC-Frames. Ein versehentliches print() beschädigt den Protokollstrom; im Server gibt es keine.
Der Client steuert die Umgebung des Servers. Ein gestarteter stdio-Server erbt die Umgebung des Elternprozesses nicht automatisch; deshalb übergibt PythonStdioTransport(env=...) eine explizite Allow-List, anstatt die gesamte Shell des Aufrufers zu übergeben.
Struktur
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 idsTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
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.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceThis MCP server exposes industrial maintenance and work-order intelligence tools, allowing users to search assets, retrieve and correlate alarm events, and query CMMS work orders through a standardized protocol.-
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to search and retrieve source-linked robotics projects, bills of materials, and technical components, compare components, and validate RPPS documents via a remote MCP endpoint.1-
- AlicenseNot gradedqualityCmaintenanceEnables an MCP client to resolve household appliances, retrieve local manual/warranty/incident records, compare a stored warranty date, review persistent service case history, and draft cited repair cases that only a human can approve or close before export.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to browse a read-only catalog of published products and their documented interfaces, listing entries, fetching one by stable ID, and searching names, descriptions, and limitations with optional protocol filters. It also exposes the versioned manifest as a resource and a prompt that helps clients match a task to catalog entries without inventing unsupported capabilities.MIT