teslamate-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this project is

A single-file FastMCP server (tesla.py, ~5475 lines) that exposes 38 read-only analytics tools over a TeslaMate PostgreSQL database. There is no Tesla Owner API token — every tool reads from the local TeslaMate schema (drives, charging_processes, cars, geofences, addresses, positions, etc.). Multi-car is supported via car_id; v1.2.x adds optional AMAP (高德) geocoding and QWeather (和风天气) enrichment, both of which silently no-op when keys are unset.

Default transport is stdio; set MCP_TRANSPORT=streamable-http for the Docker / HTTP deployment on port 8080.

Build & run

# Editable install (hatchling backend, requires Python ≥3.10)
cd teslamate-mcp
pip install -e .

# Run locally (stdio, used for desktop MCP clients)
python tesla.py

# Run as HTTP server (Docker / NAS)
MCP_TRANSPORT=streamable-http HTTP_PORT=8080 python tesla.py

# Docker
docker build -t teslamate-mcp:dev .
docker run --rm -p 8080:8080 \
  -e TESLAMATE_DB_HOST=... -e TESLAMATE_DB_PASS=... \
  -e MCP_TRANSPORT=streamable-http \
  teslamate-mcp:dev

The Dockerfile builds with ARG VERSION=dev and exposes VERSION to the app — the runtime picks the version via _detect_version() (env VERSION → __version__ constant → git describe).

Tests

cd teslamate-mcp
python test_all.py    # exit 0 = pass, exit 1 = failures

test_all.py runs without a real PostgreSQL — it monkeypatches tesla._query and tesla._query_one with SQL-fingerprint-keyed fakes (_fake_query / _fake_query_one at top of file). Two layers:

• Layer 1 (test_unit, test_review_fixes, test_single_flight): pure-logic assertions covering the historical bug/perf/issue-fix points (BUG-4, PERF-1/2/4, ISSUE-1..5).
• Layer 2 (test_tools): asyncio-smoke every @mcp.tool() registered on the mcp object and assert it returns a str without raising.