Skip to main content
Glama
Helios Field Service

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 — search_parts, get_inventory, analyse_failure, create_rma

≥2 Ressourcen

3 — helios://catalog/summary + zwei URI-Vorlagen

≥1 Prompt

diagnose_fault(fault_code, sku, site)

Client entdeckt + ruft alle auf

client.py — listet alle drei auf, ruft alle drei 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

docs/security.md

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 demo

Kein 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 it

Von 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: timeout

Hostname 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 ids

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      This 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.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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