connected-car-mcp

합성 커넥티드 차량 플릿(fleet)을 위한 MCP(Model Context Protocol) 서버입니다. 텔레메트리(telemetry), 규칙 기반 이상 탐지, 유지보수 권장 사항을 하나의 개방형 쿼리 인터페이스 대신 다섯 개의 좁은 도구로 노출합니다.

특정 설계 습관을 보여주기 위한 작고 자족적인 예시로 만들어졌습니다: 무엇이 도구 경계 뒤에 속하는지 결정하고, 그 경계를 넘는 모든 호출을 로깅하는 습관입니다. 전적으로 로컬에서 생성된 합성 데이터로 실행됩니다 — 외부 API도, 계정도, 독점 소스도 없습니다.

왜 이런 형태인가

전체 데이터셋을 단일 run_query(sql: str) 도구로 노출할 수도 있습니다. 하지만 이는 에이전트가 안정적으로 호출하기에 잘못된 형태입니다. 호출 시점에 모델이 스키마를 학습하도록 강제하고, 기능별로 "무엇을 질문할 수 있는지"를 범위 지정하거나 감사(audit)할 방법이 없기 때문입니다. 대신:

모델은 원시 행에 대해 자유 형식 쿼리를 작성하는 대신, 이 도구들을 조합합니다 — 요약 → 플래그된 차량 선택 → 텔레메트리 가져오기 → 권장 사항 얻기. 또한 감사(audit) 스토리를 단순하게 만듭니다. 로깅할 잘 정의된 호출이 다섯 개뿐이므로, audit_log.jsonl( connected_car_mcp/audit.py 참조)은 호출당 한 줄 — 타임스탬프, 도구, 인자, 지속 시간, 성공/실패 — 이며 도구별 커스텀 로직이 없습니다. 프로덕션 배포에서는 로컬 파일 대신 MCPServer의 middleware 훅(모든 JSON-RPC 호출, 도구 또는 리소스를 볼 수 있음)을 통해 동일한 레코드를 구조화된 로그로 내보낼 수 있습니다. 여기서의 데코레이터는 추가 인프라 없이 데모를 실행 가능하게 유지합니다.

이상 임계값은 의도적으로 단순하고 설명 가능합니다(engine_temp_c >= 110, 훈련된 모델이 아님) — 플릿 모니터의 플래그는 정확하기만 하면 안 되고, 사람이 감사할 수 있어야 합니다.

Related MCP server: mcp-live-telemetry

데이터

data/generate_telemetry.py는 결정적(고정 시드)이고 완전히 합성된 데이터셋을 생성합니다: 12대의 차량, 3일 동안 10분 간격의 측정값. 일부 차량에는 고장이 시드되어 이상 탐지기가 실제 신호를 찾을 수 있게 합니다:

• CCV-004 — 엔진 온도가 임계 범위로 상승(냉각 시스템 고장)

• CCV-009 — 배터리 전압이 시간에 따라 저하(배터리/알터네이터 고장)

• CCV-002, CCV-011 — 간헐적 DTC 고장 코드

• CCV-006 — 가끔 발생하는 급격한 운전 속도 급증

data/telemetry.csv는 저장소가 즉시 실행될 수 있도록 커밋되어 있습니다. 다음으로 재생성합니다:

python data/generate_telemetry.py

실행 방법

python -m venv .venv
.venv/Scripts/activate        # .venv/bin/activate on macOS/Linux
pip install -r requirements.txt

python -m connected_car_mcp.server   # starts the MCP server over stdio

Claude Desktop 또는 다른 MCP 클라이언트에서 시도하려면, cwd를 저장소 루트로 설정한 상태로 모듈을 가리키세요. 예를 들어 claude_desktop_config.json에서:

{
  "mcpServers": {
    "connected-car-fleet": {
      "command": "python",
      "args": ["-m", "connected_car_mcp.server"],
      "cwd": "/path/to/connected-car-mcp"
    }
  }
}

그런 다음 "현재 플릿에서 주의가 필요한 차량은 무엇이고, 그 이유는 무엇인가요?" 같은 질문을 해보세요 — 모델이 fleet_health_summary를 호출하고, 플래그된 차량에 대해 detect_anomalies로 후속 조치를 취하며, get_maintenance_recommendations를 호출하여 다음 조치로 전환할 수 있습니다.

테스트

pip install pytest
pytest tests/

MCP 프로토콜 계층을 왕복하는 대신 데이터 계층을 직접 다룹니다(플릿 크기, 알 수 없는 차량 처리, 시드된 고장이 실제로 플래그되는지 여부).

프로젝트 구조

connected_car_mcp/
  server.py       MCP tool + resource definitions
  data_store.py   Query layer over the telemetry CSV (pandas)
  audit.py        Per-call audit log decorator
data/
  generate_telemetry.py   Synthetic dataset generator
  telemetry.csv            Generated dataset (committed)
tests/
  test_data_store.py

라이선스

MIT — LICENSE 참조.