chDB-only mode: add introspection tools + safety baseline (P1) - #202
Open
ShawnChen-Sirius wants to merge 1 commit into
Open
chDB-only mode: add introspection tools + safety baseline (P1)#202ShawnChen-Sirius wants to merge 1 commit into
ShawnChen-Sirius wants to merge 1 commit into
Conversation
Author
|
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! |
ShawnChen-Sirius
force-pushed
the
chdb-only-introspection-tools
branch
6 times, most recently
from
July 2, 2026 10:20
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>
ShawnChen-Sirius
force-pushed
the
chdb-only-introspection-tools
branch
from
July 13, 2026 22:59
e3dd3bd to
50ca5e1
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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).