You are viewing a plain text version of this content. The canonical link for it is here.
Posted to reviews@impala.apache.org by "Jiyoung Yoo (Code Review)" <ge...@cloudera.org> on 2026/09/10 23:03:14 UTC

[Impala-ASF-CR] Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries

Jiyoung Yoo has uploaded this change for review. ( http://gerrit.cloudera.org:8080/24816


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.

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, 379 insertions(+), 0 deletions(-)



  git pull ssh://gerrit.cloudera.org:29418/Impala-ASF refs/changes/16/24816/2
-- 
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: newchange
Gerrit-Change-Id: I516f33ceee3827ecdae613db79e40991af74a6fd
Gerrit-Change-Number: 24816
Gerrit-PatchSet: 2
Gerrit-Owner: Jiyoung Yoo <ji...@cloudera.com>
Gerrit-Reviewer: Abhishek Rawat <ar...@cloudera.com>
Gerrit-Reviewer: Kurt Deschler <kd...@cloudera.com>
Gerrit-Reviewer: Michael Smith <mi...@cloudera.com>

[Impala-ASF-CR] Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries

Posted by "Impala Public Jenkins (Code Review)" <ge...@cloudera.org>.
Impala Public Jenkins has posted comments on this change. ( http://gerrit.cloudera.org:8080/24816 )

Change subject: Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries
......................................................................


Patch Set 3:

(3 comments)

gerrit-auto-critic failed. You can reproduce it locally using command:

  python3 bin/jenkins/critique-gerrit-review.py --dryrun

To run it, you might need a virtual env with Python3's venv installed.

http://gerrit.cloudera.org:8080/#/c/24816/3/tpch-claude-mcp/server.py
File tpch-claude-mcp/server.py:

http://gerrit.cloudera.org:8080/#/c/24816/3/tpch-claude-mcp/server.py@117
PS3, Line 117: a
flake8: E501 line too long (112 > 90 characters)


http://gerrit.cloudera.org:8080/#/c/24816/3/tpch-claude-mcp/server.py@153
PS3, Line 153: ,
flake8: E501 line too long (91 > 90 characters)


http://gerrit.cloudera.org:8080/#/c/24816/3/tpch-claude-mcp/setup.sh
File tpch-claude-mcp/setup.sh:

http://gerrit.cloudera.org:8080/#/c/24816/3/tpch-claude-mcp/setup.sh@17
PS3, Line 17:   || { echo "FAILED: mcp package did not import as expected. See README.md's Troubleshooting section."; exit 1; }
line too long (113 > 90)



-- 
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: comment
Gerrit-Change-Id: I516f33ceee3827ecdae613db79e40991af74a6fd
Gerrit-Change-Number: 24816
Gerrit-PatchSet: 3
Gerrit-Owner: Jiyoung Yoo <ji...@cloudera.com>
Gerrit-Reviewer: Abhishek Rawat <ar...@cloudera.com>
Gerrit-Reviewer: Impala Public Jenkins <im...@cloudera.com>
Gerrit-Reviewer: Kurt Deschler <kd...@cloudera.com>
Gerrit-Reviewer: Michael Smith <mi...@cloudera.com>
Gerrit-Comment-Date: Fri, 11 Sep 2026 03:57:25 +0000
Gerrit-HasComments: Yes

[Impala-ASF-CR] Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries

Posted by "Impala Public Jenkins (Code Review)" <ge...@cloudera.org>.
Impala Public Jenkins has posted comments on this change. ( http://gerrit.cloudera.org:8080/24816 )

Change subject: Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries
......................................................................


Patch Set 2:

Build Failed 

https://jenkins.impala.io/job/gerrit-code-review-checks/23970/ : Initial code review checks failed. See linked job for details on the failure.


-- 
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: comment
Gerrit-Change-Id: I516f33ceee3827ecdae613db79e40991af74a6fd
Gerrit-Change-Number: 24816
Gerrit-PatchSet: 2
Gerrit-Owner: Jiyoung Yoo <ji...@cloudera.com>
Gerrit-Reviewer: Abhishek Rawat <ar...@cloudera.com>
Gerrit-Reviewer: Impala Public Jenkins <im...@cloudera.com>
Gerrit-Reviewer: Kurt Deschler <kd...@cloudera.com>
Gerrit-Reviewer: Michael Smith <mi...@cloudera.com>
Gerrit-Comment-Date: Thu, 10 Sep 2026 23:15:07 +0000
Gerrit-HasComments: No

[Impala-ASF-CR] Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries

Posted by "Jiyoung Yoo (Code Review)" <ge...@cloudera.org>.
Jiyoung Yoo has abandoned this change. ( http://gerrit.cloudera.org:8080/24816 )

Change subject: Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries
......................................................................


Abandoned
-- 
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: abandon
Gerrit-Change-Id: I516f33ceee3827ecdae613db79e40991af74a6fd
Gerrit-Change-Number: 24816
Gerrit-PatchSet: 3
Gerrit-Owner: Jiyoung Yoo <ji...@cloudera.com>
Gerrit-Reviewer: Abhishek Rawat <ar...@cloudera.com>
Gerrit-Reviewer: Impala Public Jenkins <im...@cloudera.com>
Gerrit-Reviewer: Kurt Deschler <kd...@cloudera.com>
Gerrit-Reviewer: Michael Smith <mi...@cloudera.com>

[Impala-ASF-CR] Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries

Posted by "Impala Public Jenkins (Code Review)" <ge...@cloudera.org>.
Impala Public Jenkins has posted comments on this change. ( http://gerrit.cloudera.org:8080/24816 )

Change subject: Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries
......................................................................


Patch Set 3:

Build Failed 

https://jenkins.impala.io/job/gerrit-code-review-checks/23971/ : Initial code review checks failed. See linked job for details on the failure.


-- 
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: comment
Gerrit-Change-Id: I516f33ceee3827ecdae613db79e40991af74a6fd
Gerrit-Change-Number: 24816
Gerrit-PatchSet: 3
Gerrit-Owner: Jiyoung Yoo <ji...@cloudera.com>
Gerrit-Reviewer: Abhishek Rawat <ar...@cloudera.com>
Gerrit-Reviewer: Impala Public Jenkins <im...@cloudera.com>
Gerrit-Reviewer: Kurt Deschler <kd...@cloudera.com>
Gerrit-Reviewer: Michael Smith <mi...@cloudera.com>
Gerrit-Comment-Date: Fri, 11 Sep 2026 04:07:01 +0000
Gerrit-HasComments: No

[Impala-ASF-CR] Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries

Posted by "Jiyoung Yoo (Code Review)" <ge...@cloudera.org>.
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 <ji...@cloudera.com>
Gerrit-Reviewer: Abhishek Rawat <ar...@cloudera.com>
Gerrit-Reviewer: Impala Public Jenkins <im...@cloudera.com>
Gerrit-Reviewer: Kurt Deschler <kd...@cloudera.com>
Gerrit-Reviewer: Michael Smith <mi...@cloudera.com>

[Impala-ASF-CR] Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries

Posted by "Impala Public Jenkins (Code Review)" <ge...@cloudera.org>.
Impala Public Jenkins has posted comments on this change. ( http://gerrit.cloudera.org:8080/24816 )

Change subject: Add tpch-claude-mcp: demo MCP server for natural-language TPC-H queries
......................................................................


Patch Set 2:

(2 comments)

gerrit-auto-critic failed. You can reproduce it locally using command:

  python3 bin/jenkins/critique-gerrit-review.py --dryrun

To run it, you might need a virtual env with Python3's venv installed.

http://gerrit.cloudera.org:8080/#/c/24816/2/tpch-claude-mcp/server.py
File tpch-claude-mcp/server.py:

http://gerrit.cloudera.org:8080/#/c/24816/2/tpch-claude-mcp/server.py@119
PS2, Line 119: ,
flake8: E501 line too long (91 > 90 characters)


http://gerrit.cloudera.org:8080/#/c/24816/2/tpch-claude-mcp/setup.sh
File tpch-claude-mcp/setup.sh:

http://gerrit.cloudera.org:8080/#/c/24816/2/tpch-claude-mcp/setup.sh@17
PS2, Line 17:   || { echo "FAILED: mcp package did not import as expected. See README.md's Troubleshooting section."; exit 1; }
line too long (113 > 90)



-- 
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: comment
Gerrit-Change-Id: I516f33ceee3827ecdae613db79e40991af74a6fd
Gerrit-Change-Number: 24816
Gerrit-PatchSet: 2
Gerrit-Owner: Jiyoung Yoo <ji...@cloudera.com>
Gerrit-Reviewer: Abhishek Rawat <ar...@cloudera.com>
Gerrit-Reviewer: Impala Public Jenkins <im...@cloudera.com>
Gerrit-Reviewer: Kurt Deschler <kd...@cloudera.com>
Gerrit-Reviewer: Michael Smith <mi...@cloudera.com>
Gerrit-Comment-Date: Thu, 10 Sep 2026 23:05:30 +0000
Gerrit-HasComments: Yes