Repository navigation
chDB-only mode: add introspection tools + safety baseline (P1) - #202
ShawnChen-Sirius wants to merge 1 commit into
Conversation
|
Hi @iskakaushik and @serprex, Could you take a look of this PR when you have a chance? My view is that chDB is a special deployment form within the ClickHouse ecosystem, so from a user perspective it makes more sense to expose it as an option in the same MCP package. This PR adds chDB APIs to It also introduces Thanks! |
0858e4c to
e3dd3bd
Compare
…ts.ChDBTool Adds a richer chDB-only tool surface (registered only when CLICKHOUSE_ENABLED=false and CHDB_ENABLED=true), alongside the existing run_chdb_select_query: - list_databases / list_tables / describe_table / get_sample_data / list_functions as bare, ClickHouse-server-parity tool names (collision-free in chDB-only mode). - Capability layer unified on chdb.agents.ChDBTool (chdb>=4.2.0): query execution, identifier quoting, parameter binding, result caps, typed errors, engine read-only, timeout, and the file-path allowlist all come from ChDBTool — mcp re-implements none of it. (database, table) maps to ChDBTool's database=. - Presentation aligned to the ClickHouse-server tools: success is bare JSON, and any failure is raised as ToolError (like run_query). max_result_bytes and allow_write are read from ChDBConfig (single source), and allow_write is passed to register so the shared session is not clobbered to readonly=2 in write mode. - CHDB_FILE_ALLOWLIST is a *path* allowlist (DuckDB allowed_directories style), enforced via chdb.agents.safety so raw SQL and ChDBTool agree: file-like paths under an allowed prefix are permitted, paths outside and DSN-based external sources are refused. run_chdb_select_query stays on its own executor (routing it through ChDBTool would flip 64-bit ints to quoted strings — a visible change). Security baseline retained on the session (SET readonly=2 unless writes allowed, max_result_bytes, timeout). Both-engine mode unchanged. Tests: 64 chDB tests pass against a clean install of chdb 4.2.0. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
e3dd3bd to
50ca5e1
Compare
|
Hey @ShawnChen-Sirius! Thanks for this. I lke the idea. The standalone file-analysis use case makes sense and I think it'd be a good fit in this repo. For P1, the let's air for as simple as possible. An agent can inspect a CSV or Parquet file and query it without a ClickHouse server. TO get there, I'd like to build on this PR with the following changes.
Let's keep source configuration, named collections, runtime attach/detach, and DataFrames for P2/P3. P1 should give us a useful file workflow with predictable results and clear limits. Let me know if you have any other questions! Nice work so far. |
What
Implements P1 of the chDB-in-mcp-clickhouse design: a richer chDB-only tool surface plus a chDB-session security baseline. Adds the five introspection tools alongside the existing
run_chdb_select_query, in self-contained modules with no changes to the ClickHouse-server path.New tools (registered only in chDB-only mode —
CLICKHOUSE_ENABLED=false,CHDB_ENABLED=true):list_databaseslist_tablesdescribe_tableget_sample_datalist_functionsSecurity baseline:
quote_ident/quote_stringhelpers and resulttruncate()(inchdb_safety.py).Why
Discussion and full design: Refs #201
Today mcp-clickhouse ships only a single blind
run_chdb_select_queryon the chDB side — no way for an agent to discover what's queryable, while the ClickHouse-server side already haslist_databases/list_tables. This brings parity, using bare canonical names (collision-free since the CH-server tools aren't registered in chDB-only mode).Scope / safety
CLICKHOUSE_ENABLED=true, nothing is registered beyond the existing 0.4.0 tools — behavior is unchanged.mcp_clickhouse/chdb_tools.pyandmcp_clickhouse/chdb_safety.py; the ClickHouse path has no dependency on them.Files
mcp_clickhouse/chdb_tools.py(new) — the five introspection toolsmcp_clickhouse/chdb_safety.py(new) — pure safety helpersmcp_clickhouse/mcp_server.py— chDB-only registrationtests/test_chdb_tools.py(new),tests/test_chdb_safety.py(new)README.md— document the chDB-only introspection toolsTests
test_chdb_tools,test_chdb_safety,test_chdb_tool,test_optional_chdb).test_system_database_access, unrelated to this change — reproduces identically onmainbecause the test assumessystem.tablesfits in the first page, while this ClickHouse build has 120 system tables).This is the first of three planned phases (P1 introspection; P2 federated source catalog; P3 co-located DataFrame query).