Skip to main content
Glama
Helios Field Service

Helios Field Service

Helios Field Service — 本番MCPサーバー & クライアント

モジュール4 ラボ — Model Context Protocol

Helios Robotics の部品・在庫・RMAシステムを、MCP対応クライアントならどれでも接続できるMCP機能に変えます。FastMCP 3.x を MCP仕様 に準拠して構築。

要件

実装

≥3ツール

4 — search_parts, get_inventory, analyse_failure, create_rma

≥2リソース

3 — helios://catalog/summary + 2つのURIテンプレート

≥1プロンプト

diagnose_fault(fault_code, sku, site)

クライアントが各機能を検出・呼び出し

client.py — 3つすべてを一覧表示し、3つすべてを呼び出す

トランスポート + 根拠

stdio(デフォルト)、HTTP対応 — 根拠

クライアント側の安全性

両方 — 書き込み時のユーザー確認(elicitation)、クライアント側のルート

セキュリティ設計の概要

docs/security.md

エラーハンドリング

不正な入力、未知のレコード、および到達不能なバッキングストア

ドキュメント: アーキテクチャ + トランスポート · ツール/リソース/プロンプト · セキュリティ · ログ: 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 demo

APIキーもモデルもコストも不要 — MCPはプロトコルであり、クライアントがサーバーを直接呼び出します。

その他の実行方法

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

任意のMCPホストから利用する

{
  "mcpServers": {
    "helios-field-service": {
      "command": "python",
      "args": ["/absolute/path/to/helios-mcp/server.py"]
    }
  }
}

それがこの演習のポイントです — 一度構築すれば、あらゆるMCP対応クライアントで利用できます。

Related MCP server: RoboPartPicker

デモの内容

logs/demo.log — 完全な検出と呼び出しのフロー:

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)

ユーザー確認(elicitation)でゲートされた書き込み:

  ┌─ 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 — バッキングストアに到達できない場合。クライアント側の表示:

TOOL UNAVAILABLE — Failure analysis is temporarily unavailable.
                   Quote reference dddc45d0fc07 to support if this persists.

サーバーが stderr (logs/server-errors.log) に記録した内容:

ERROR [helios-mcp] [dddc45d0fc07] Failure analysis failed:
OperationalError: could not connect to helios-db-prod-01.internal:5432: timeout

ホスト名とポートはプロトコル境界を越えることはありません。相関IDが両者を橋渡しします。

設計ノート

リソースとツールは互換ではありません。 search_parts はIDが分からないときに部品を検索し、helios://parts/{pn} はすでにIDが分かっている部品を取得します。同じデータでも、アクセスパターンが異なります。

プロンプトは意図的にサーバー上に置かれます。 診断手順はHeliosのドメイン知識であり、ホスト側のロジックではありません。接続するすべてのクライアントが同じルールを受け取ります — ハードウェアを故障とみなす前にファームウェアを除外する、廃止された部品を提示しない — 各クライアントがそれぞれ再実装してずれていくのではなく。

すべてのログはstderrに出力されます。 stdioでは、stdoutがJSON-RPCフレームを運びます。迷い込んだ print() はプロトコルストリームを破壊するため、サーバー内には一切ありません。

クライアントはサーバーの環境を制御します。 起動されたstdioサーバーは親環境を自動的に継承しないため、PythonStdioTransport(env=...) は呼び出し元のシェル全体を渡すのではなく、明示的な許可リストを渡します。

構成

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