From 312503790df8562d9b5a8cfdbfb99e3afa42829d Mon Sep 17 00:00:00 2001 From: George Goldenberg <228832143+squaredg@users.noreply.github.com> Date: Sun, 11 Oct 2026 15:12:35 -0700 Subject: [PATCH 1/2] fix(mcp): bind interval params in clickstack_sql clickstack_sql rendered its query as a table tile, and raw SQL only binds {intervalSeconds} and {intervalMilliseconds} for time-series display types. Every interval parameter and macro the tool description advertises ($__interval_s, $__timeInterval, $__timeInterval_ms), including its own time-series example, failed with "Substitution intervalSeconds is not set". Render as a line tile instead. displayType only picks which params to bind, rows come back the same, and ClickHouse ignores params a query never uses. --- .changeset/mcp-sql-interval-params.md | 9 +++ .../src/mcp/__tests__/queryTool.int.test.ts | 55 +++++++++++++++++++ packages/api/src/mcp/tools/query/sql.ts | 6 +- 3 files changed, 69 insertions(+), 1 deletion(-) create mode 100644 .changeset/mcp-sql-interval-params.md diff --git a/.changeset/mcp-sql-interval-params.md b/.changeset/mcp-sql-interval-params.md new file mode 100644 index 0000000000..36ee9c4270 --- /dev/null +++ b/.changeset/mcp-sql-interval-params.md @@ -0,0 +1,9 @@ +--- +'@hyperdx/api': patch +--- + +fix(mcp): `clickstack_sql` now binds the bucket-size parameters its description +advertises. `{intervalSeconds:Int64}`, `{intervalMilliseconds:Int64}`, +`$__interval_s`, `$__timeInterval` and `$__timeInterval_ms` used to fail with +"Substitution intervalSeconds is not set", including the tool's own time-series +example. diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index 0efcb681d8..20be67e219 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -754,6 +754,61 @@ describe('MCP Query Tools', () => { expect(result.isError).toBeFalsy(); }); + + // The tool description advertises these bucket-size parameters and + // macros, so each one has to resolve to a value rather than fail with + // "Substitution intervalSeconds is not set". + it('binds the interval parameters and $__interval_s to the same bucket size', async () => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sql: + 'SELECT {intervalSeconds:Int64} AS s, ' + + '{intervalMilliseconds:Int64} AS ms, ' + + '$__interval_s AS macro_s', + startTime: new Date(Date.now() - 60 * 60 * 1000).toISOString(), + endTime: new Date().toISOString(), + }); + + expect(result.isError).toBeFalsy(); + const [row] = JSON.parse(getFirstText(result)).result.data; + const seconds = Number(row.s); + expect(seconds).toBeGreaterThan(0); + expect(Number(row.ms)).toBe(seconds * 1000); + expect(Number(row.macro_s)).toBe(seconds); + }); + + it.each(['$__timeInterval', '$__timeInterval_ms'])( + 'runs a time-series query bucketed with %s', + async macro => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sql: + `SELECT ${macro}(Timestamp) AS ts, count() AS cnt ` + + `FROM ${DEFAULT_DATABASE}.${DEFAULT_TRACES_TABLE} ` + + 'WHERE $__timeFilter(Timestamp) GROUP BY ts ORDER BY ts LIMIT 10', + startTime: new Date(Date.now() - 60 * 60 * 1000).toISOString(), + endTime: new Date().toISOString(), + }); + + expect(getFirstText(result)).not.toContain('Substitution'); + expect(result.isError).toBeFalsy(); + expect(JSON.parse(getFirstText(result)).result.meta).toEqual( + expect.arrayContaining([expect.objectContaining({ name: 'ts' })]), + ); + }, + ); + + it('returns plain query rows unchanged', async () => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sql: "SELECT 1 AS value, 'a' AS label", + }); + + expect(result.isError).toBeFalsy(); + expect(JSON.parse(getFirstText(result)).result.data).toEqual([ + { value: 1, label: 'a' }, + ]); + }); }); // ─── ClickHouse query errors ────────────────────────────────────────────────── diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts index 8c36fd4c72..eb12492222 100644 --- a/packages/api/src/mcp/tools/query/sql.ts +++ b/packages/api/src/mcp/tools/query/sql.ts @@ -100,9 +100,13 @@ export function registerSql({ context, registerTool }: ToolRegistrar) { ); } + // Raw SQL only uses displayType to pick which query params to bind, and + // only time-series types bind the interval params this tool advertises + // ({intervalSeconds}, $__interval_s, $__timeInterval). Rows come back + // the same either way, and ClickHouse ignores params a query never uses. const tile = buildTile('MCP SQL', 24, 6, { configType: 'sql' as const, - displayType: 'table' as const, + displayType: 'line' as const, connectionId: input.connectionId, sqlTemplate: input.sql, }); From a5aa7af63aff0872de571bd453fc99a0071d01fa Mon Sep 17 00:00:00 2001 From: George Goldenberg <228832143+squaredg@users.noreply.github.com> Date: Sun, 11 Oct 2026 17:05:29 -0700 Subject: [PATCH 2/2] test(mcp): assert clickstack_sql returns aligned interval buckets The $__timeInterval tests queried otel_traces, which this suite never seeds, so they passed on an empty result. Seed logs and assert each bucket starts on an interval boundary and holds one row. --- .../src/mcp/__tests__/queryTool.int.test.ts | 31 ++++++++++++++----- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index 20be67e219..60bd0352d3 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -780,21 +780,36 @@ describe('MCP Query Tools', () => { it.each(['$__timeInterval', '$__timeInterval_ms'])( 'runs a time-series query bucketed with %s', async macro => { + const now = Date.now(); + await bulkInsertLogs( + [5, 10, 15, 20].map(minutesAgo => ({ + Body: 'bucketed', + ServiceName: 'sql-buckets', + SeverityText: 'INFO', + Timestamp: new Date(now - minutesAgo * 60 * 1000), + })), + ); + const result = await callTool(client, 'clickstack_sql', { connectionId: connection._id.toString(), sql: - `SELECT ${macro}(Timestamp) AS ts, count() AS cnt ` + - `FROM ${DEFAULT_DATABASE}.${DEFAULT_TRACES_TABLE} ` + - 'WHERE $__timeFilter(Timestamp) GROUP BY ts ORDER BY ts LIMIT 10', - startTime: new Date(Date.now() - 60 * 60 * 1000).toISOString(), - endTime: new Date().toISOString(), + `SELECT ${macro}(Timestamp) AS ts, ` + + 'toUnixTimestamp(ts) % $__interval_s AS offset, count() AS cnt ' + + `FROM ${DEFAULT_DATABASE}.${DEFAULT_LOGS_TABLE} ` + + "WHERE $__timeFilter(Timestamp) AND ServiceName = 'sql-buckets' " + + 'GROUP BY ts ORDER BY ts LIMIT 10', + startTime: new Date(now - 60 * 60 * 1000).toISOString(), + endTime: new Date(now).toISOString(), }); expect(getFirstText(result)).not.toContain('Substitution'); expect(result.isError).toBeFalsy(); - expect(JSON.parse(getFirstText(result)).result.meta).toEqual( - expect.arrayContaining([expect.objectContaining({ name: 'ts' })]), - ); + const rows: { offset: unknown; cnt: unknown }[] = JSON.parse( + getFirstText(result), + ).result.data; + expect(rows).toHaveLength(4); + expect(rows.map(row => Number(row.offset))).toEqual([0, 0, 0, 0]); + expect(rows.map(row => Number(row.cnt))).toEqual([1, 1, 1, 1]); }, );