Crate hyperdb_mcp 

MCP (Model Context Protocol) server that exposes the Hyper columnar database as an instant SQL analytics engine for LLM workflows.

Architecture

The crate is layered bottom-up:

• error — Structured error codes with recovery suggestions for LLM self-correction.
• attach — Registry of additional .hyper databases attached to the primary workspace for cross-database JOINs and copy_query. Replays attachments after a ConnectionLost reconnect.
• stats — Performance telemetry (throughput, timing) attached to every response.
• schema — Three-tier schema inference: exact (Arrow/Parquet), structural (JSON), heuristic (CSV). Also handles user-provided schema overrides.
• engine — Manages the HyperProcess lifecycle, connection, table CRUD, and query execution. Supports ephemeral and persistent workspace modes.
• ingest — Loads inline JSON (row-by-row INSERT) and CSV (COPY FROM) into Hyper.
• ingest_arrow — Loads Parquet and Arrow IPC files via the Arrow crate.
• inspect — Dry-run file inspection powering the inspect_file MCP tool.
• export — Writes query results to CSV, Parquet, Arrow IPC, or .hyper files.
• chart — Renders SQL query results as PNG/SVG charts via the plotters crate.
• saved_queries — Named read-only SQL queries exposed via tools and hyper://queries/... resources.
• subscriptions — Per-URI registry of MCP clients that asked for resource-update notifications.
• table_catalog — User-visible catalog of data tables (_table_catalog) tracking source, purpose, and load history so workspaces are self-documenting. Disabled by --bare.
• version — Compile-time-captured version strings for the MCP crate and the underlying hyperdb-api, with a git-hash suffix.
• readme — Static LLM-facing README returned by the get_readme tool.
• watcher — Monitors directories for incremental ingest via a .ready sentinel protocol.
• server — MCP tool definitions and the rmcp server handler that ties everything together.

Modules

attach

Registry of attached databases for cross-database queries.

chart

Chart rendering for query results.

daemon

Single-instance daemon for sharing a hyperd process across MCP clients.

engine

Core database engine that owns the HyperProcess and its connection.

error

Structured error types for MCP tool responses.

export

Export query results or whole tables to files.

ingest

Ingest inline data (JSON strings, CSV strings) and CSV files into Hyper tables.

ingest_arrow

Ingest Parquet and Arrow IPC files into Hyper tables.

inspect

Dry-run file inspection for the inspect_file MCP tool.

lakehouse

Ingest Apache Iceberg tables into Hyper using hyperd’s native external(..., format => 'iceberg') scan.

paths

Cross-platform resolution for the persistent-database default path.

readme

LLM-facing README returned by the get_readme tool.

saved_queries

Named read-only SQL queries exposed via the save_query / delete_query tools and the hyper://queries/{name}/definition + hyper://queries/{name}/result resources.

schema

Schema inference and type mapping.

server

MCP server implementation and tool parameter types.

stats

Performance telemetry attached to every MCP tool response.

subscriptions

Resource-update subscription registry backing the server-side hooks for resources/subscribe, resources/unsubscribe, and the two MCP notifications the server emits after workspace mutations.

table_catalog

User-visible catalog of data tables in the workspace.

version

Version reporting for the HyperDB MCP server.

watcher

Directory watcher for incremental ingest.