# MCP Tools

Six tools are exposed via the Model Context Protocol. Typical workflow: `list_recordings` → `get_schema` → `load_recording` → `query`.

## list_recordings

Discover available MCAP files in the configured data directory.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | string | No | Override scan directory (defaults to `MCAP_DATA_DIR`) |
| `after` | string | No | ISO 8601 datetime — only recordings after this time |
| `before` | string | No | ISO 8601 datetime — only recordings before this time |

Returns a JSON array of recording summaries: filename, size, duration, channel list, message counts, metadata keys.

## get_recording_info

Full metadata, channel details, and attachment list for a specific file. Does not require loading.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | string | Yes | Filename or path to the MCAP file |

Returns file path, size, library, start/end times, duration, message count, per-channel details (schema, encoding, count), metadata records, and attachment names.

## get_schema

Inspect topics, table names, column names and DuckDB types before loading. Essential for query planning.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | string | Yes | Filename or path to the MCAP file |
| `topic` | string | No | Filter to a single topic |

Returns per-topic field information with DuckDB types and a `sql_hint` explaining table naming and JOIN conventions.

## load_recording

Decode an MCAP file and register its data as DuckDB tables. Must be called before `query`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | string | Yes | Filename or path to the MCAP file |
| `alias` | string | No | Table prefix for multi-recording comparison (e.g. `"r1"`) |
| `topics` | string[] | No | Subset of topics to load (defaults to all decodable) |
| `start_time` | string | No | ISO 8601 or epoch microseconds — start of time window |
| `end_time` | string | No | ISO 8601 or epoch microseconds — end of time window |
| `downsample` | integer | No | Keep every Nth message |

Returns table names, row counts, column counts, load time, memory usage (`memory_used_mb`, `memory_budget_mb`), and any `evicted_tables` if the memory budget was exceeded. Topics without a matching decoder are skipped and listed.

### Table naming

Topics are mapped to table names by stripping the leading `/` and replacing `/` with `_`:

| Topic | Table name |
|-------|-----------|
| `/imu` | `imu` |
| `/battery/status` | `battery_status` |
| `/sensors/power` | `sensors_power` |

With an alias `"r1"`, tables become `r1_imu`, `r1_battery_status`, etc.

Every table includes a `timestamp_us` column (BIGINT, microseconds) derived from the MCAP message log time. Use it for cross-topic JOINs.

A `_metadata` table is always created with columns `(record_name, key, value)` containing all MCAP metadata records.

## query

Execute SQL against loaded data. Full DuckDB SQL is supported, including `ASOF JOIN`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sql` | string | Yes | SQL query |
| `limit` | integer | No | Override row limit (default: 1000, max: 10000) |

Returns columns, types, rows, row count, truncation flag, and execution time. If a referenced table does not exist, the error response includes `loaded_tables` and a `hint` to guide the LLM toward loading the correct recording first.

## get_version

Return the server version, list of available decoders, and the upgrade command.

No parameters. Returns:

```json
{
  "version": "0.5.1",
  "decoders": ["JsonDecoder", "ProtobufDecoder", "Ros1Decoder", "Ros2Decoder", "FlatBufferDecoder"],
  "upgrade": "uvx mcap-mcp-server[all] --upgrade"
}
```