Helios Field Service
Helios Field Service — 本番MCPサーバー & クライアント
モジュール4 ラボ — Model Context Protocol
Helios Robotics の部品・在庫・RMAシステムを、MCP対応クライアントならどれでも接続できるMCP機能に変えます。FastMCP 3.x を MCP仕様 に準拠して構築。
要件 | 実装 |
≥3ツール | 4 — |
≥2リソース | 3 — |
≥1プロンプト |
|
クライアントが各機能を検出・呼び出し |
|
トランスポート + 根拠 | stdio(デフォルト)、HTTP対応 — 根拠 |
クライアント側の安全性 | 両方 — 書き込み時のユーザー確認(elicitation)、クライアント側のルート |
セキュリティ設計の概要 | |
エラーハンドリング | 不正な入力、未知のレコード、および到達不能なバッキングストア |
ドキュメント: アーキテクチャ + トランスポート · ツール/リソース/プロンプト · セキュリティ · ログ: 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 demoAPIキーもモデルもコストも不要 — 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 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