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 + URI 템플릿 2개

프롬프트 ≥1개

diagnose_fault(fault_code, sku, site)

클라이언트가 각 항목을 검색 및 호출

client.py — 세 가지 모두 나열, 세 가지 모두 호출

전송 + 근거

stdio(기본값), HTTP 지원 — 근거

클라이언트 측 안전

둘 다 — 쓰기 작업에 대한 유도, 클라이언트의 루트

보안 설계 요약

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: Latchbook

데모가 보여주는 것

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)

유도로 게이트된 쓰기:

  ┌─ 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

호스트 이름과 포트는 프로토콜 경계를 절대 넘지 않습니다. correlation id가 둘 사이의 다리 역할을 합니다.

설계 노트

리소스와 도구는 서로 대체할 수 없습니다. search_parts는 ID를 모를 때 부품을 찾고, helios://parts/{pn}은 이미 알고 있는 부품을 가져옵니다. 같은 데이터, 다른 접근 패턴입니다.

프롬프트는 의도적으로 서버에 있습니다. 진단 절차는 호스트 로직이 아니라 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
      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
    • A
      license
      B
      quality
      C
      maintenance
      Enables MCP clients to search and manage customer support tickets, customer records, and knowledge base articles, with read-only and human-approved write workflows.
      8
      1
      MIT