spelunk-mcp

# Spelunk A **multi-source DuckDB query + transformation-pipeline MCP server.** Point it at files (CSV/Parquet/JSON/Excel) and databases (SQLite/PostgreSQL/MySQL), and an agent like Claude Code can query across all of them — and build step-by-step pipelines — through one DuckDB engine. ## Architecture in one line A single DuckDB session is both the query engine and the workspace: every source is `ATTACH`ed (databases) or scanned (files) into one connection, so one query can join a Parquet file to a Postgres table to a result you built two steps ago — all in DuckDB SQL. | Path | Role | |---|---| | `spelunk/core/duck.py` | `DuckSession` — the one DuckDB connection: query / profile / export / catalog / drop / lineage / replay + introspection. | | `spelunk/core/sources.py` | Source registry — maps a spec to a DuckDB attach/scan. DuckDB-only: a source it can't attach (e.g. SQL Server) is rejected. | | `spelunk/core/guard.py` | sqlglot AST safety: read-only enforcement (`assert_read_only`). | | `spelunk/mcp/server.py` | Thin FastMCP wrapper over `DuckSession`. | | `tests` | Acceptance tests. | ## Tools ``` query(sql, name, flow?) # run a read-only SELECT over sources + results; store the full # result as table `name` for immediate reuse. The ONE tool for # looking and building — every result is named and chainable. profile(sql, flow?) # per-column stats (null_rate, min/max/mean/std, percentiles, top/freq) export(target, fmt, path) # write a saved result name OR a full SELECT to csv/json/parquet catalog(flow?) # list flows, or the results in one flow drop(name?, flow?) # drop one result, or a whole flow lineage(name?, flow?) # provenance DAG: the SQL + deps that built a result (or a whole flow) replay(flow?, into?) # rebuild a flow from its recorded SQL, in dependency order ``` Discovery resources: `db://tables` (queryable source objects) and `db://{table}` …