# teslamate-mcp

MCP server built from skeleton-mcp that exposes TeslaMate HTTP APIs.

## What This Server Exposes

TeslaMate endpoints covered by dedicated tools:
- `GET /health_check`
- `PUT /api/car/:id/logging/suspend`
- `PUT /api/car/:id/logging/resume`
- `GET /drive/:id/gpx`

Additional MCP tools:
- `teslamate_connection_info`
- `teslamate_scope_info`
- `teslamate_list_endpoints`
- `teslamate_query_suggestion` (query recommendation + schema discovery across all tools)
- `teslamate_api_request` (generic passthrough to support all currently available TeslaMate routes)

## License

MIT

## Tool Catalog

Each definition below includes usage boundaries, risk level, prerequisites, input constraints, response shape, and examples.

### `teslamate_query_suggestion`

- Purpose: Recommends which TeslaMate MCP tools to call for a natural-language goal and can return schema discovery for all tools.
- Use when:
  - You want a guided sequence before making API calls.
  - You need a quick catalog of each tool's expected inputs and risk profile.
- Do not use when:
  - You already know the exact tool and inputs to invoke.
- Risk: Read-only.
- Permissions and prerequisites:
  - No admin key required.
- Parameters:
  - `query` (optional, string): natural-language intent such as "export drive gpx" or "suspend logging for car 1".
  - `includeSchemas` (optional, boolean, default `true`): include full per-tool schema discovery output.
  - `maxRecommendations` (optional, integer, default `5`, max `8`): number of ranked recommendations.
- Expected response shape:
  - JSON object with ranked recommendations, rationale, safe usage sequence, and optional full schema discovery.
- Recommended prerequisite tools:
  - None.
- Recommended follow-up tools:
  - `teslamate_scope_info`, `teslamate_connection_info`, `teslamate_health_check`, and the top-ranked recommendation.
- Example invocation:

```json
{
  "name": "teslamate_query_suggestion",
  "arguments": {
    "query": "suspend logging for car 1",
    "includeSchemas": true,
    "maxRecommendations": 4
  }
}
```

### `teslamate_connection_info`

- Purpose: Returns sanitized MCP and TeslaMate connection/auth configuration status.
- Use when:
  - You need to verify effective transport/auth wiring.
  - You need a quick preflight check before calling TeslaMate operation tools.
- Do not use when:
  - You need vehicle or drive data.
  - You need to test TeslaMate API responsiveness (`teslamate_health_check` is better).
- Risk: Read-only.
- Permissions and prerequisites:
  - No admin key required.
  - Server must be running with valid env configuration.
- Environment-selection behavior:
  - Uses default user scope unless `userId` is provided.
  - Returns scope-aware effective config status, never raw secrets.
- Parameters:
  - `userId` (optional, string): explicit user profile scope.
- Expected response shape:
  - JSON object with transport/auth/config status fields and redacted secret indicators.
- Common failure conditions:
  - Invalid `userId` scope mapping.
  - Server startup misconfiguration.
- Recommended prerequisite tools:
  - `teslamate_scope_info`
- Recommended follow-up tools:
  - `teslamate_health_check`, `teslamate_list_endpoints`
- Example invocation:

```json
{ "name": "teslamate_connection_info", "arguments": { "userId": "default" } }
```

### `teslamate_list_endpoints`

- Purpose: Lists known TeslaMate routes captured by this MCP server.
- Use when:
  - You need discoverability before invoking `teslamate_api_request`.
  - You need to confirm whether a dedicated tool already exists.
- Do not use when:
  - You need live data from TeslaMate.
- Risk: Read-only.
- Permissions and prerequisites:
  - No admin key required.
- Environment-selection behavior:
  - Independent of TeslaMate user profile; no `userId` required.
- Parameters:
  - None.
- Expected response shape:
  - JSON object/array of endpoint descriptors (method/path and optional notes).
- Common failure conditions:
  - Internal catalog load error (rare).
- Recommended prerequisite tools:
  - None.
- Recommended follow-up tools:
  - `teslamate_api_request`, `teslamate_health_check`
- Example invocation:

```json
{ "name": "teslamate_list_endpoints", "arguments": {} }
```

### `teslamate_scope_info`

- Purpose: Returns the effective scope and profile resolution details for the request.
- Use when:
  - You need to confirm which user profile will be used.
  - You are debugging default-user fallback behavior.
- Do not use when:
  - You need TeslaMate API payloads.
- Risk: Read-only.
- Permissions and prerequisites:
  - No admin key required.
- Environment-selection behavior:
  - Resolves `userId` if provided.
  - Otherwise uses `MCP_CONFIG_DEFAULT_USER_ID` fallback behavior.
- Parameters:
  - `userId` (optional, string): requested user scope.
- Expected response shape:
  - JSON object describing requested scope, resolved scope, and fallback status.
- Common failure conditions:
  - Invalid user scope format.
  - Missing profile data in multi-user overrides.
- Recommended prerequisite tools:
  - None.
- Recommended follow-up tools:
  - `teslamate_connection_info`, any operation tool with the same `userId`
- Example invocation:

```json
{ "name": "teslamate_scope_info", "arguments": { "userId": "user-123" } }
```

### `teslamate_health_check`

- Purpose: Calls `GET /health_check` on the resolved TeslaMate target.
- Use when:
  - You need to verify TeslaMate reachability and basic service health.
  - You want a low-risk connectivity test before mutating calls.
- Do not use when:
  - You need route-specific business data.
- Risk: Read-only.
- Permissions and prerequisites:
  - No admin key required.
  - TeslaMate target must be reachable from the MCP runtime.
- Environment-selection behavior:
  - Uses default scope unless `userId` is provided.
- Parameters:
  - `userId` (optional, string): route request to a user-specific profile.
- Expected response shape:
  - JSON object with status and response metadata from TeslaMate.
- Common failure conditions:
  - Connection refused/timeouts to TeslaMate base URL.
  - Invalid auth credentials for selected profile.
- Recommended prerequisite tools:
  - `teslamate_scope_info`, `teslamate_connection_info`
- Recommended follow-up tools:
  - `teslamate_get_drive_gpx`, `teslamate_api_request`
- Example invocation:

```json
{ "name": "teslamate_health_check", "arguments": { "userId": "default" } }
```

### `teslamate_suspend_logging`

- Purpose: Calls `PUT /api/car/:id/logging/suspend`.
- Use when:
  - You intentionally need to pause TeslaMate logging for a specific car.
- Do not use when:
  - You only need read access.
  - You are uncertain which car is being targeted.
- Risk: Mutating, high-impact operational change.
- Permissions and prerequisites:
  - Requires `authorizationKey` when `MCP_ADMIN_AUTH_KEY` is configured.
  - Caller should verify target scope and car id first.
- Environment-selection behavior:
  - Uses default scope unless `userId` is provided.
- Parameters:
  - `id` (required, integer/string): TeslaMate car id.
  - `authorizationKey` (conditionally required, string): admin mutation guard.
  - `userId` (optional, string): user profile scope.
- Expected response shape:
  - JSON object with operation result and upstream response metadata.
- Common failure conditions:
  - Missing/invalid `authorizationKey`.
  - Unknown car id.
  - TeslaMate auth or connectivity failure.
- Recommended prerequisite tools:
  - `teslamate_scope_info`, `teslamate_connection_info`, `teslamate_health_check`
- Recommended follow-up tools:
  - `teslamate_resume_logging` (rollback), `teslamate_api_request` for verification
- Safety warnings:
  - This changes live data-collection behavior.
  - Confirm car identity and scope before invoking.
- Example invocation:

```json
{
  "name": "teslamate_suspend_logging",
  "arguments": { "id": 1, "authorizationKey": "<admin-key>", "userId": "default" }
}
```

### `teslamate_resume_logging`

- Purpose: Calls `PUT /api/car/:id/logging/resume`.
- Use when:
  - You need to restore TeslaMate logging for a car.
- Do not use when:
  - Logging is already active and no state change is needed.
- Risk: Mutating, high-impact operational change.
- Permissions and prerequisites:
  - Requires `authorizationKey` when `MCP_ADMIN_AUTH_KEY` is configured.
- Environment-selection behavior:
  - Uses default scope unless `userId` is provided.
- Parameters:
  - `id` (required, integer/string): TeslaMate car id.
  - `authorizationKey` (conditionally required, string): admin mutation guard.
  - `userId` (optional, string): user profile scope.
- Expected response shape:
  - JSON object with operation result and upstream response metadata.
- Common failure conditions:
  - Missing/invalid `authorizationKey`.
  - Unknown car id.
  - TeslaMate auth or connectivity failure.
- Recommended prerequisite tools:
  - `teslamate_scope_info`, `teslamate_health_check`
- Recommended follow-up tools:
  - `teslamate_api_request` for post-change verification
- Safety warnings:
  - This changes live data-collection behavior.
  - Verify scope and target car id before invoking.
- Example invocation:

```json
{
  "name": "teslamate_resume_logging",
  "arguments": { "id": 1, "authorizationKey": "<admin-key>", "userId": "default" }
}
```

### `teslamate_get_drive_gpx`

- Purpose: Calls `GET /drive/:id/gpx` and returns GPX content/metadata.
- Use when:
  - You need a drive export for mapping or archival workflows.
- Do not use when:
  - You need generalized JSON endpoint data.
- Risk: Read-only (data retrieval can still expose sensitive location history).
- Permissions and prerequisites:
  - No admin key required.
  - Caller should be authorized to access route/location data.
- Environment-selection behavior:
  - Uses default scope unless `userId` is provided.
- Parameters:
  - `id` (required, integer/string): drive id.
  - `userId` (optional, string): user profile scope.
- Expected response shape:
  - JSON wrapper containing GPX payload and response metadata.
- Common failure conditions:
  - Unknown drive id.
  - TeslaMate auth failure.
  - Large payload transfer interruptions.
- Recommended prerequisite tools:
  - `teslamate_scope_info`, `teslamate_health_check`
- Recommended follow-up tools:
  - External GPX consumers/parsers
- Safety warnings:
  - GPX data may include precise location traces; handle as sensitive output.
- Example invocation:

```json
{ "name": "teslamate_get_drive_gpx", "arguments": { "id": 42, "userId": "default" } }
```

### `teslamate_api_request`

- Purpose: Generic TeslaMate passthrough with configurable `method`, `path`, `query`, `body`, and `headers`.
- Use when:
  - You need a TeslaMate route not covered by dedicated tools.
  - You are iterating quickly on endpoint coverage.
- Do not use when:
  - A dedicated tool already exists and provides stricter validation.
  - You cannot safely validate mutating request intent.
- Risk: Mixed.
  - Read-only for `GET`/`HEAD`.
  - Mutating/high-risk for `POST`/`PUT`/`PATCH`/`DELETE`.
- Permissions and prerequisites:
  - Mutating methods require `authorizationKey` when `MCP_ADMIN_AUTH_KEY` is configured.
  - Caller should understand TeslaMate endpoint contract.
- Environment-selection behavior:
  - Uses default scope unless `userId` is provided.
  - Uses selected scope's base URL and auth mode.
- Parameters:
  - `method` (required, uppercase string): HTTP verb.
  - `path` (required, string): must be a TeslaMate-relative path beginning with `/`.
  - `query` (optional, object): key/value query params.
  - `body` (optional, object/string): request payload for mutating methods.
  - `headers` (optional, object): extra request headers.
  - `authorizationKey` (conditionally required for mutating methods, string).
  - `userId` (optional, string): user profile scope.
- Expected response shape:
  - JSON object with status, headers subset, and parsed/raw response body.
- Common failure conditions:
  - Invalid method/path.
  - Missing/invalid `authorizationKey` for mutating methods.
  - Upstream 4xx/5xx errors.
  - Request timeout or network failure.
- Recommended prerequisite tools:
  - `teslamate_list_endpoints`, `teslamate_scope_info`, `teslamate_connection_info`
- Recommended follow-up tools:
  - Use dedicated tools after confirming recurring endpoint usage
- Safety warnings:
  - Mutating requests can change vehicle/logging state.
  - Avoid sending secrets in custom headers unless required.
  - Prefer dedicated tools for high-value operations to reduce operator error.
- Example invocations:

```json
{
  "name": "teslamate_api_request",
  "arguments": {
    "method": "GET",
    "path": "/health_check",
    "userId": "default"
  }
}
```

```json
{
  "name": "teslamate_api_request",
  "arguments": {
    "method": "PUT",
    "path": "/api/car/1/logging/suspend",
    "authorizationKey": "<admin-key>",
    "userId": "default"
  }
}
```

## Environment

Copy `.env.example` to `.env` and set at least:

- `TESLAMATE_BASE_URL` (default `http://127.0.0.1:4000`)
- `TESLAMATE_AUTH_MODE` (`none`, `bearer`, or `basic`)
- `TESLAMATE_BEARER_TOKEN` if using bearer auth
- `TESLAMATE_BASIC_USERNAME` and `TESLAMATE_BASIC_PASSWORD` if using basic auth

Optional security control for mutating MCP operations:
- `MCP_ADMIN_AUTH_KEY`

Multi-user TeslaMate routing:
- `MCP_CONFIG_DEFAULT_USER_ID` sets the default profile (`default` when unset).
- `TESLAMATE_USER_OVERRIDES_JSON` is a JSON object keyed by user id with per-user TeslaMate overrides.
- For HTTP mode with Vault token auth, authenticated token metadata `userId` is used as request scope automatically.

Example `TESLAMATE_USER_OVERRIDES_JSON`:

```json
{
  "default": {
    "baseUrl": "http://teslamate-default:4000",
    "authMode": "none"
  },
  "user-123": {
    "baseUrl": "http://teslamate-user-123:4000",
    "authMode": "bearer",
    "bearerToken": "token-for-user-123"
  }
}
```

HTTP auth modes and sources:
- `MCP_HTTP_AUTH_MODE` supports `token`, `oauth2`, or `both`.
- `MCP_HTTP_TOKEN_SOURCE=env` keeps static tokens from `MCP_HTTP_AUTH_TOKENS`.
- `MCP_HTTP_TOKEN_SOURCE=vault` validates bearer tokens from Vault token index and can resolve authenticated `userId`.
- `MCP_HTTP_VAULT_TOKEN_INDEX_PATH`, `MCP_HTTP_VAULT_TOKEN_DEFAULT_USER_ID`, `MCP_HTTP_VAULT_TOKEN_REQUIRED_SCOPES`, `MCP_HTTP_VAULT_TOKEN_REQUIRED_AUDIENCE`, `MCP_HTTP_VAULT_TOKEN_CACHE_TTL_MS` configure Vault token verification.
- `MCP_HTTP_OAUTH2_INTROSPECTION_URL`, `MCP_HTTP_OAUTH2_CLIENT_ID`, `MCP_HTTP_OAUTH2_CLIENT_SECRET`, `MCP_HTTP_OAUTH2_REQUIRED_SCOPES`, `MCP_HTTP_OAUTH2_REQUIRED_AUDIENCE`, `MCP_HTTP_OAUTH2_TIMEOUT_MS`, `MCP_HTTP_OAUTH2_CACHE_TTL_MS` configure OAuth2 introspection.

## Run

Install dependencies:

```bash
npm install
```

Start stdio MCP server:

```bash
npm run start:stdio
```

Start HTTP MCP server:

```bash
npm run start:http
```

## External Services Mode

This project still includes `docker-compose.external.yml` for app-only runs that point to external services. If you use that mode, configure at least `POSTGRES_HOST` and `VAULT_ADDR` in your environment before launching the compose file.

## Notes On TeslaMate API Coverage

TeslaMate's native JSON API surface is intentionally small. This MCP includes dedicated tools for all known API-style endpoints and adds `teslamate_api_request` so new/instance-specific routes can be accessed without waiting for a code change.