Hello Kurt Deschler, Abhishek Rawat, Michael Smith, Impala Public Jenkins,
I'd like you to reexamine a change. Please visit
http://gerrit.cloudera.org:8080/24816
to look at the new patch set (#3).
Change subject: Add tpch-claude-mcp: demo MCP server for natural-language TPC-H
queries
......................................................................
Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries
Standalone package, not part of the Impala build: an MCP server exposing
one tool, run_tpch_query, so a Claude client can answer natural-language
TPC-H questions by writing SQL itself and running it against an Impala
cluster over HS2 -- no other integration code needed on the client side.
Whether the query runs on Impala's own planner or is routed to GQE is
controlled purely by env vars at server startup (ROUTE_TO_GQE,
GQE_ENDPOINT); the tool has no other GQE-specific logic, so flipping GQE
on once it's reachable is a restart, not a code change.
- server.py: the MCP server (mcp.server.mcpserver.MCPServer -- the
current SDK's FastMCP-renamed class), connecting via impyla.
- setup.sh: one-shot venv + dependency install, prints the exact
`claude mcp add` command for wherever it's unpacked.
- requirements.txt: pinned mcp==2.2.0/impyla==0.24.0/thrift_sasl==0.4.3.
Deliberately no checked-in .venv/: a virtualenv bakes absolute paths
into its shebangs at creation time, so one built here would silently
break once copied elsewhere.
- README.md: setup, the env-var table, a troubleshooting section for the
FastMCP/MCPServer rename this was built against, and a "flipping on
GQE" section.
- SAMPLE_QUESTIONS.md: four natural-language questions verified
end-to-end against SF1 tpch data, with their generated SQL and exact
expected answers -- a script to fall back on live.
- mcp-config-example.json: drop-in .mcp.json block.
Testing:
- Ran the full setup.sh -> claude mcp add -> ask-a-question path against
a live single-node cluster loaded with SF1 tpch data.
- Verified the packaged tarball itself (built via `tar czf
tpch-claude-mcp.tar.gz tpch-claude-mcp/`, not committed here --
regenerate from this directory when sharing), not just this source
tree: extracted it to an unrelated path, ran setup.sh there, and
confirmed the resulting server connects and runs a real query.
- Confirmed the tool's SELECT-only guard rejects a DELETE, and that a
query referencing an unknown column surfaces Impala's own
AnalysisException message rather than crashing or hanging.
Also make the SF1 assumption in the tool description explicit rather than
hardcoded: add TPCH_SCALE_FACTOR (purely descriptive, defaults unset) so
the description Claude sees says "scale factor N" when set, or otherwise
notes that table/column names and how to write SQL are identical at
every scale -- a user asking a question never needs to mention scale
either way, only the tool's own self-description needed the caveat.
Also wire in GQE routing correctly and expand demo coverage, based on
testing against a live GQE-routed remote cluster:
- _connect() now issues the full documented recipe (PLANNER=CALCITE,
FALLBACK_PLANNER=NONE, ROUTE_TO_GQE, GQE_ENDPOINT), not just the last
two. FALLBACK_PLANNER=NONE matters specifically: without it, a query
Calcite's grammar/exporter can't handle silently falls back to
Impala's original planner and runs there instead of on GQE, which
would make a broken query look like a working demo.
- Quote ROUTE_TO_GQE and GQE_ENDPOINT's values in the SET statements.
The documented recipe says not to for impala-shell, but this package's
HS2 client (impyla) reproducibly fails to parse the 3rd+ SET in a
session when its value is unquoted (ParseException on the SET keyword
itself, regardless of which option is 3rd) -- quoting avoids that and
was confirmed, end to end against live GQE, to still resolve to the
correct value.
- run_tpch_query's read-only guard rejected any query starting with
"with" -- a common table expression is a read like any SELECT, and
TPC-H Q15's canonical form is exactly this shape. Broadened the guard
to accept both.
- SAMPLE_QUESTIONS.md: added a GQE-routed section with natural-language
questions for the seven TPC-H queries (Q1, Q6, Q10, Q11, Q12, Q14, Q15)
confirmed working end to end through ROUTE_TO_GQE against a live
~SF10 remote cluster, plus notes on two real gaps found while
verifying them: Q10 needs its full canonical column set or GQE hits an
internal range-check error on a narrower projection, and Q15's CTE
form silently returns an empty (wrong) result through GQE even though
it is accepted without error -- confirmed correct on Impala's normal
planner and via an inlined-subquery rewrite through GQE, so this is a
GQE-side correctness gap, not a mistake in the query.
- README.md: documented the routing recipe, the quoting behavior above,
and both of the gaps above under "Known Calcite/GQE gaps".
Change-Id: I516f33ceee3827ecdae613db79e40991af74a6fd
---
A tpch-claude-mcp/README.md
A tpch-claude-mcp/SAMPLE_QUESTIONS.md
A tpch-claude-mcp/mcp-config-example.json
A tpch-claude-mcp/requirements.txt
A tpch-claude-mcp/server.py
A tpch-claude-mcp/setup.sh
6 files changed, 559 insertions(+), 0 deletions(-)
git pull ssh://gerrit.cloudera.org:29418/Impala-ASF refs/changes/16/24816/3
--
To view, visit http://gerrit.cloudera.org:8080/24816
To unsubscribe, visit http://gerrit.cloudera.org:8080/settings
Gerrit-Project: Impala-ASF
Gerrit-Branch: master
Gerrit-MessageType: newpatchset
Gerrit-Change-Id: I516f33ceee3827ecdae613db79e40991af74a6fd
Gerrit-Change-Number: 24816
Gerrit-PatchSet: 3
Gerrit-Owner: Jiyoung Yoo <[email protected]>
Gerrit-Reviewer: Abhishek Rawat <[email protected]>
Gerrit-Reviewer: Impala Public Jenkins <[email protected]>
Gerrit-Reviewer: Kurt Deschler <[email protected]>
Gerrit-Reviewer: Michael Smith <[email protected]>
