Skip to content

feat(mcp): accept sourceId in clickstack_sql so $__sourceTable resolves - #3355

Merged
kodiakhq[bot] merged 1 commit into
ClickHouse:mainfrom
squaredg:claude/hdx-5684-sql-source-id
Oct 13, 2026
Merged

kodiakhq[bot] merged 1 commit into
ClickHouse:mainfrom
squaredg:claude/hdx-5684-sql-source-id

Conversation

@squaredg

@squaredg squaredg commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

clickstack_sql takes only a connectionId, so an agent has to write the table name itself, and it often guesses wrong (#3354 covers the guessing). $__sourceTable already exists in common-utils, and raw SQL dashboard tiles resolve it through runConfigTile. The MCP SQL tool just never accepted a source.

This adds an optional sourceId to clickstack_sql and passes it to the tile, so $__sourceTable expands to that source's database.table. It reuses the existing runConfigTile path that dashboard tiles use.

Checks on the input:

  • A sourceId that doesn't exist or belongs to another team is rejected as "Source not found".
  • A source whose connection differs from connectionId is rejected. Otherwise $__sourceTable would expand against a table on another server.
  • $__sourceTable without a sourceId is rejected with an error that says to pass one. Today the renderer's message comes through instead ("requires a source to be selected"), which is written for the dashboard UI.

The time-series example now reads FROM $__sourceTable. The table example keeps FROM <table> to show the path for tables that aren't registered as sources.

Tests (all failed before the change):

  • $__sourceTable resolves to the source's table (counts seeded rows).
  • $__sourceTable without sourceId is rejected, and the error says to pass one.
  • An unknown sourceId and another team's sourceId are both rejected as not found.
  • A source on a different connection than connectionId is rejected.
  • The tool schema exposes an optional sourceId.
  • The time-series example uses $__sourceTable and the table example uses <table>.

This matches the sourceId handling in our enterprise build, which has had it since source filters were added. That build also scopes it with source filters and RBAC, which aren't part of OSS and aren't included here.

How to test on Vercel preview

N/A — non-UI change.

References

🤖 Generated with Claude Code

@changeset-bot

changeset-bot Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 1731b9f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
@hyperdx/api Patch
@hyperdx/app Patch
@hyperdx/otel-collector Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel

vercel Bot commented Oct 12, 2026

Copy link
Copy Markdown

@squaredg is attempting to deploy a commit to the HyperDX Team on Vercel.

A member of the Team first needs to authorize it.

@greptile-apps

greptile-apps Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Medium impact] The PR appears safe to merge, with the existing non-blocking issue around macros in SQL comments still open.

Fix All in Claude CodeFindings

  1. P2 SQL comments block valid queries ▶

Summary

clickstack_sql now accepts an optional sourceId so $__sourceTable can resolve to a saved source's table.

  • MCP SQL queries can use a source ID to fill in the table.

Reviews (2) · Last reviewed commit: "feat(mcp): accept sourceId in clickstack..." · Reviewed by Greptile

'connection or drop sourceId from the call.',
);
}
} else if (hasMacro(input.sql, 'sourceTable')) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 SQL comments block valid queries

hasMacro also matches $__sourceTable inside SQL comments. Without sourceId, a query such as SELECT 1 /* previously FROM $__sourceTable */ now returns an error even though the renderer skips that comment. Use the renderer's comment-aware scan for this check and add a test for a commented-out macro.

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex

clickstack_sql took only a connectionId, so agents had to write table names
themselves and guessed them. $__sourceTable already exists, and raw SQL
dashboard tiles resolve it through runConfigTile; the MCP tool just never
accepted a source.

Add an optional sourceId, passed to the tile. Reject a source that does not
exist or belongs to another team, a source whose connection differs from
connectionId, and $__sourceTable without a sourceId (the renderer's own
message says to select a source in the UI). The time-series example now
reads FROM $__sourceTable.
@squaredg
squaredg force-pushed the claude/hdx-5684-sql-source-id branch from a59ccf6 to 1731b9f Compare October 13, 2026 20:47
@squaredg
squaredg marked this pull request as ready for review October 13, 2026 20:47
@github-actions

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

The change is small and well-scoped: an optional sourceId on clickstack_sql, a team-scoped getSource lookup, a connection-match guard, and a "pass a sourceId" error when $__sourceTable is used without one. Tenant isolation is correct (getSource is team-scoped, and the connection-mismatch check blocks resolving $__sourceTable against another server), the schema addition is backward-compatible (optional field), and the happy path plus the four rejection paths are covered by integration tests.

🔵 P3 nitpicks (1)
  • packages/api/src/mcp/tools/query/sql.ts:138 — hasMacro(input.sql, 'sourceTable') scans raw text and is not comment-aware, so a query whose only $__sourceTable sits inside a SQL comment is now rejected without a sourceId, even though the renderer's expandTemplate skips comments (skipSqlComments defaults to true) and would run it fine; the rejection is benign (clear error, no bad query executes) but misleading.
    • Fix: gate the rejection on a comment-aware scan that mirrors the renderer's comment handling, and add a test for a commented-out macro.
    • correctness, previous-comments

Reviewers (7): correctness, security, testing, maintainability, api-contract, kieran-typescript, previous-comments.

Testing gaps:

  • No test for a comment-only $__sourceTable with no sourceId (the hasMacro-vs-renderer comment-awareness divergence).
  • No test for a metric source passed via sourceId with $__sourceTable(metricType) / bare $__sourceTable, to confirm the new guard composes with the renderer's source-kind validation.
  • No test for a valid sourceId supplied alongside SQL that contains no $__sourceTable, confirming sourceId is accepted without altering plain-query behavior.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

@brandon-pereira brandon-pereira left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@kodiakhq
kodiakhq Bot merged commit b00d410 into ClickHouse:main Oct 13, 2026
32 of 37 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants