From cf7b0d8e4002a395d8d8937e1fc836baf848b25f Mon Sep 17 00:00:00 2001 From: George Goldenberg <228832143+squaredg@users.noreply.github.com> Date: Sun, 11 Oct 2026 17:36:36 -0700 Subject: [PATCH 1/5] fix(mcp): stop clickstack_sql callers guessing table and timestamp names Agents writing raw SQL had no tool that named a source's table, and the sql examples hard-coded otel_logs and TimestampTime. Unqualified otel_logs only resolves when tables sit in the connection's default database, and the seed otel_logs schema has no TimestampTime, so the examples fail on most schemas. - clickstack_list_sources returns each source's database-qualified table, and the database for metric sources. - The sql examples use and placeholders. - Unknown-table errors hint at clickstack_list_sources. --- .changeset/mcp-sql-table-names.md | 9 +++ packages/api/src/mcp/__tests__/query.test.ts | 16 +++++ .../src/mcp/__tests__/queryTool.int.test.ts | 63 +++++++++++++++++++ .../api/src/mcp/__tests__/sources.int.test.ts | 28 +++++++++ packages/api/src/mcp/tools/query/helpers.ts | 13 ++++ packages/api/src/mcp/tools/query/sql.ts | 13 ++-- .../api/src/mcp/tools/sources/listSources.ts | 9 +++ 7 files changed, 146 insertions(+), 5 deletions(-) create mode 100644 .changeset/mcp-sql-table-names.md diff --git a/.changeset/mcp-sql-table-names.md b/.changeset/mcp-sql-table-names.md new file mode 100644 index 0000000000..674d945a24 --- /dev/null +++ b/.changeset/mcp-sql-table-names.md @@ -0,0 +1,9 @@ +--- +'@hyperdx/api': patch +--- + +fix(mcp): stop `clickstack_sql` callers from guessing table and timestamp column +names. `clickstack_list_sources` now returns each source's database-qualified +`table` (and `database` for metric sources), the `sql` examples use `
` +and `` placeholders instead of `otel_logs` and `TimestampTime`, +and unknown-table errors point at `clickstack_list_sources`. diff --git a/packages/api/src/mcp/__tests__/query.test.ts b/packages/api/src/mcp/__tests__/query.test.ts index 585ea7551f..3387fef684 100644 --- a/packages/api/src/mcp/__tests__/query.test.ts +++ b/packages/api/src/mcp/__tests__/query.test.ts @@ -229,6 +229,22 @@ describe('errorHint', () => { expect(hint).toBeNull(); }); + it.each([ + "Unknown table expression identifier 'otel_logs' in scope SELECT count() FROM otel_logs", + 'Table default.otel_traces does not exist.', + 'Database o11y does not exist.', + ])('points unknown-table errors at clickstack_list_sources: %s', msg => { + expect(errorHint(msg)).toContain('clickstack_list_sources'); + }); + + it('keeps pointing unknown-column errors at clickstack_describe_source', () => { + const hint = errorHint( + 'Unknown expression or function identifier `TimestampTime` in scope SELECT TimestampTime FROM t', + ); + expect(hint).toContain('clickstack_describe_source'); + expect(hint).not.toContain('clickstack_list_sources'); + }); + it('should NOT match lowercase "as" in cast expressions', () => { const hint = errorHint( 'Syntax error: cannot cast as Float64 near token...', diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index 60bd0352d3..63c73d8d7f 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -813,6 +813,51 @@ describe('MCP Query Tools', () => { }, ); + describe('sql parameter examples', () => { + const getExamples = async () => { + const { tools } = await client.listTools(); + const sqlParam = tools.find(t => t.name === 'clickstack_sql')! + .inputSchema.properties?.sql as { description: string }; + return [ + ...sqlParam.description.matchAll(/^Example \(.+\):\n {2}(.+)$/gm), + ].map(match => match[1]); + }; + + // Agents copy examples literally. A concrete table or column in one + // becomes the guess, and it only exists on some schemas. + it('leave the table and timestamp column as placeholders', async () => { + const examples = await getExamples(); + + expect(examples).toHaveLength(2); + for (const sql of examples) { + expect(sql).toContain('FROM
'); + expect(sql).toContain(''); + expect(sql).not.toMatch(/otel_|TimestampTime/); + } + }); + + it('run once the placeholders are filled from a source', async () => { + const examples = await getExamples(); + + expect(examples).toHaveLength(2); + for (const example of examples) { + const sql = example + .replaceAll('
', `${DEFAULT_DATABASE}.${DEFAULT_LOGS_TABLE}`) + .replaceAll('', 'Timestamp'); + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sql, + startTime: new Date(Date.now() - 60 * 60 * 1000).toISOString(), + endTime: new Date().toISOString(), + }); + expect({ + sql, + error: result.isError ? getFirstText(result) : null, + }).toEqual({ sql, error: null }); + } + }); + }); + it('returns plain query rows unchanged', async () => { const result = await callTool(client, 'clickstack_sql', { connectionId: connection._id.toString(), @@ -865,6 +910,24 @@ describe('MCP Query Tools', () => { /UNKNOWN_TABLE|doesn.t exist|unknown/i, ); }); + + it.each([ + 'nonexistent_table_xyz', + `${DEFAULT_DATABASE}.nonexistent_table_xyz`, + ])( + 'hints that %s should come from clickstack_list_sources', + async table => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sql: `SELECT 1 FROM ${table} LIMIT 1`, + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain( + 'HINT: Use the `table` of a source from clickstack_list_sources', + ); + }, + ); }); describe('clickstack_table errors', () => { diff --git a/packages/api/src/mcp/__tests__/sources.int.test.ts b/packages/api/src/mcp/__tests__/sources.int.test.ts index 7e86e7c3a5..e56e51f259 100644 --- a/packages/api/src/mcp/__tests__/sources.int.test.ts +++ b/packages/api/src/mcp/__tests__/sources.int.test.ts @@ -140,6 +140,21 @@ describe('MCP Source Tools', () => { expect(output.nextStep).toContain('clickstack_describe_source'); }); + // clickstack_sql callers need this for FROM. Without it they guess + // otel_logs, which only resolves when the tables sit in the + // connection's default database. + it('includes the database-qualified table each log and trace source reads', async () => { + const result = await callTool(client, 'clickstack_list_sources'); + const output = JSON.parse(getFirstText(result)); + + const trace = output.sources.find( + (s: any) => s.kind === SourceKind.Trace, + ); + const log = output.sources.find((s: any) => s.kind === SourceKind.Log); + expect(trace.table).toBe(`${DEFAULT_DATABASE}.${DEFAULT_TRACES_TABLE}`); + expect(log.table).toBe(`${DEFAULT_DATABASE}.${DEFAULT_LOGS_TABLE}`); + }); + it('should include keyColumns from source config without ClickHouse queries', async () => { const result = await callTool(client, 'clickstack_list_sources'); const output = JSON.parse(getFirstText(result)); @@ -248,6 +263,19 @@ describe('MCP Source Tools', () => { expect(output.metricsUsage).toContain('metricType + metricName'); }); + it('includes the database its metricTables live in', async () => { + const metricSource = await createMetricSource(); + + const result = await callTool(client, 'clickstack_list_sources'); + const output = JSON.parse(getFirstText(result)); + + const metric = output.sources.find( + (s: any) => s.id === metricSource._id.toString(), + ); + expect(metric.database).toBe(DEFAULT_DATABASE); + expect(metric.table).toBeUndefined(); + }); + it('falls back to a wider lookback when no metrics reported in the last 24h', async () => { const metricSource = await createMetricSource('Sparse Metrics'); const threeDaysAgo = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000); diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 708b96c0f7..9991858556 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -954,6 +954,19 @@ export function errorHint(msg: string, error?: unknown): string | null { 'Add a LIMIT, narrow the time range, or add filters to reduce the result set.' ); } + // Checked before unknown identifiers: "Unknown table expression identifier" + // names a table, so describe_source's column list would not help. + if ( + /Unknown table expression identifier|(Table|Database) \S+ does not exist|UNKNOWN_(TABLE|DATABASE)/.test( + msg, + ) + ) { + return ( + 'Use the `table` of a source from clickstack_list_sources, which is ' + + 'qualified with its database. Unqualified names resolve only in the ' + + "connection's default database." + ); + } if ( /Unknown (expression|identifier)|UNKNOWN_IDENTIFIER|Missing columns/i.test( msg, diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts index eb12492222..eba36245ff 100644 --- a/packages/api/src/mcp/tools/query/sql.ts +++ b/packages/api/src/mcp/tools/query/sql.ts @@ -39,13 +39,16 @@ const sqlSchema = z.object({ ' $__interval_s — raw interval in seconds\n' + ' $__filters — dashboard filter conditions (resolves to 1=1 when no filters)\n' + ' {intervalSeconds:Int64} / {intervalMilliseconds:Int64} — bucket size parameters\n\n' + + "In the examples, replace
with a source's `table` and " + + 'with its `timestampColumn`, both from clickstack_list_sources. Table and column ' + + 'names differ between sources, so do not guess them.\n\n' + 'Example (time-series):\n' + - ' SELECT $__timeInterval(TimestampTime) AS ts, ServiceName, count() ' + - 'FROM otel_logs WHERE $__timeFilter(TimestampTime) GROUP BY ServiceName, ts ORDER BY ts\n\n' + + ' SELECT $__timeInterval() AS ts, ServiceName, count() ' + + 'FROM
WHERE $__timeFilter() GROUP BY ServiceName, ts ORDER BY ts\n\n' + 'Example (table):\n' + - ' SELECT ServiceName, count() AS n FROM otel_logs ' + - 'WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) ' + - 'AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) ' + + ' SELECT ServiceName, count() AS n FROM
' + + 'WHERE >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) ' + + 'AND < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) ' + 'GROUP BY ServiceName ORDER BY n DESC LIMIT 20', ), startTime: startTimeSchema, diff --git a/packages/api/src/mcp/tools/sources/listSources.ts b/packages/api/src/mcp/tools/sources/listSources.ts index b7ce2beac9..e3deed4167 100644 --- a/packages/api/src/mcp/tools/sources/listSources.ts +++ b/packages/api/src/mcp/tools/sources/listSources.ts @@ -244,6 +244,15 @@ export function registerListSources({ timestampColumn: s.timestampValueExpression, }; + // For clickstack_sql's FROM. An unqualified name only resolves in the + // connection's default database. Metric sources keep one table per + // kind in metricTables, so they get the database to qualify them with. + if (s.from.tableName) { + meta.table = `${s.from.databaseName}.${s.from.tableName}`; + } else { + meta.database = s.from.databaseName; + } + if (s.section) { meta.section = s.section; } From 1c68142ed78196b913dbd5794c3473b8e70f832d Mon Sep 17 00:00:00 2001 From: George Goldenberg <228832143+squaredg@users.noreply.github.com> Date: Tue, 13 Oct 2026 12:11:03 -0700 Subject: [PATCH 2/5] test(mcp): read the sql param description without a type assertion The cast tripped no-unsafe-type-assertion and took the api package one warning over the CI lint ceiling. --- packages/api/src/mcp/__tests__/queryTool.int.test.ts | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index 63c73d8d7f..3bcc454cc4 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -817,10 +817,14 @@ describe('MCP Query Tools', () => { const getExamples = async () => { const { tools } = await client.listTools(); const sqlParam = tools.find(t => t.name === 'clickstack_sql')! - .inputSchema.properties?.sql as { description: string }; - return [ - ...sqlParam.description.matchAll(/^Example \(.+\):\n {2}(.+)$/gm), - ].map(match => match[1]); + .inputSchema.properties?.sql; + const description = + sqlParam && typeof sqlParam === 'object' && 'description' in sqlParam + ? String(sqlParam.description) + : ''; + return [...description.matchAll(/^Example \(.+\):\n {2}(.+)$/gm)].map( + match => match[1], + ); }; // Agents copy examples literally. A concrete table or column in one From 5fb24777d21c1fc705e493c77603b3a077331692 Mon Sep 17 00:00:00 2001 From: George Goldenberg <228832143+squaredg@users.noreply.github.com> Date: Tue, 13 Oct 2026 12:22:21 -0700 Subject: [PATCH 3/5] fix(mcp): quote list_sources table names and give every metric source its database Agents paste table into FROM, so a database like observability-prod broke the query. Metric sources that also set from.tableName got a table instead of the database their metricTables live in. --- .../api/src/mcp/__tests__/sources.int.test.ts | 47 +++++++++++++++++++ .../api/src/mcp/tools/sources/listSources.ts | 14 +++--- 2 files changed, 55 insertions(+), 6 deletions(-) diff --git a/packages/api/src/mcp/__tests__/sources.int.test.ts b/packages/api/src/mcp/__tests__/sources.int.test.ts index e56e51f259..59367443b3 100644 --- a/packages/api/src/mcp/__tests__/sources.int.test.ts +++ b/packages/api/src/mcp/__tests__/sources.int.test.ts @@ -155,6 +155,25 @@ describe('MCP Source Tools', () => { expect(log.table).toBe(`${DEFAULT_DATABASE}.${DEFAULT_LOGS_TABLE}`); }); + it('quotes table parts that are not bare identifiers so FROM still parses', async () => { + const source = await Source.create({ + kind: SourceKind.Log, + team: team._id, + from: { databaseName: 'observability-prod', tableName: 'otel.logs' }, + timestampValueExpression: 'Timestamp', + connection: connection._id, + name: 'Quoted logs', + }); + + const result = await callTool(client, 'clickstack_list_sources'); + const output = JSON.parse(getFirstText(result)); + + const log = output.sources.find( + (s: any) => s.id === source._id.toString(), + ); + expect(log.table).toBe('`observability-prod`.`otel.logs`'); + }); + it('should include keyColumns from source config without ClickHouse queries', async () => { const result = await callTool(client, 'clickstack_list_sources'); const output = JSON.parse(getFirstText(result)); @@ -276,6 +295,34 @@ describe('MCP Source Tools', () => { expect(metric.table).toBeUndefined(); }); + // Metric sources may also set from.tableName, but their queryable + // tables are still the ones in metricTables. + it('includes the database for a metric source that also names a table', async () => { + const metricSource = await Source.create({ + kind: SourceKind.Metric, + team: team._id, + from: { + databaseName: DEFAULT_DATABASE, + tableName: 'otel_metrics_gauge', + }, + metricTables: { + [MetricsDataType.Gauge.toLowerCase()]: 'otel_metrics_gauge', + }, + timestampValueExpression: 'TimeUnix', + connection: connection._id, + name: 'Named metrics', + }); + + const result = await callTool(client, 'clickstack_list_sources'); + const output = JSON.parse(getFirstText(result)); + + const metric = output.sources.find( + (s: any) => s.id === metricSource._id.toString(), + ); + expect(metric.database).toBe(DEFAULT_DATABASE); + expect(metric.table).toBeUndefined(); + }); + it('falls back to a wider lookback when no metrics reported in the last 24h', async () => { const metricSource = await createMetricSource('Sparse Metrics'); const threeDaysAgo = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000); diff --git a/packages/api/src/mcp/tools/sources/listSources.ts b/packages/api/src/mcp/tools/sources/listSources.ts index e3deed4167..48cc7a3106 100644 --- a/packages/api/src/mcp/tools/sources/listSources.ts +++ b/packages/api/src/mcp/tools/sources/listSources.ts @@ -7,6 +7,7 @@ import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node'; import { Metadata, MetadataCache, + quoteIdentifierIfNeeded, } from '@hyperdx/common-utils/dist/core/metadata'; import { SourceKind } from '@hyperdx/common-utils/dist/types'; import { z } from 'zod'; @@ -244,13 +245,14 @@ export function registerListSources({ timestampColumn: s.timestampValueExpression, }; - // For clickstack_sql's FROM. An unqualified name only resolves in the - // connection's default database. Metric sources keep one table per - // kind in metricTables, so they get the database to qualify them with. - if (s.from.tableName) { - meta.table = `${s.from.databaseName}.${s.from.tableName}`; + // For clickstack_sql's FROM, so each part is quoted when it needs to + // be. An unqualified name only resolves in the connection's default + // database. Metric sources query the tables in metricTables, even + // when from.tableName is set, so they get the database instead. + if (s.kind !== SourceKind.Metric && s.from.tableName) { + meta.table = `${quoteIdentifierIfNeeded(s.from.databaseName)}.${quoteIdentifierIfNeeded(s.from.tableName)}`; } else { - meta.database = s.from.databaseName; + meta.database = quoteIdentifierIfNeeded(s.from.databaseName); } if (s.section) { From cc07b202e0728ac404db13a036cc7387b857654f Mon Sep 17 00:00:00 2001 From: George Goldenberg <228832143+squaredg@users.noreply.github.com> Date: Tue, 13 Oct 2026 12:22:26 -0700 Subject: [PATCH 4/5] fix(mcp): give the unknown-table hint only to raw SQL and fix placeholder guidance Source-based tools were sent back to clickstack_list_sources, which hands back the same table that just failed. The sql examples now say to use the first timestampColumn expression and how to qualify metric tables. --- packages/api/src/mcp/__tests__/query.test.ts | 24 ++++++-- .../src/mcp/__tests__/queryTool.int.test.ts | 55 ++++++++++++++++--- packages/api/src/mcp/tools/query/helpers.ts | 21 ++++--- packages/api/src/mcp/tools/query/sql.ts | 6 +- 4 files changed, 85 insertions(+), 21 deletions(-) diff --git a/packages/api/src/mcp/__tests__/query.test.ts b/packages/api/src/mcp/__tests__/query.test.ts index 3387fef684..0855c40bc7 100644 --- a/packages/api/src/mcp/__tests__/query.test.ts +++ b/packages/api/src/mcp/__tests__/query.test.ts @@ -229,13 +229,29 @@ describe('errorHint', () => { expect(hint).toBeNull(); }); - it.each([ + const unknownTableErrors = [ "Unknown table expression identifier 'otel_logs' in scope SELECT count() FROM otel_logs", 'Table default.otel_traces does not exist.', 'Database o11y does not exist.', - ])('points unknown-table errors at clickstack_list_sources: %s', msg => { - expect(errorHint(msg)).toContain('clickstack_list_sources'); - }); + ]; + + it.each(unknownTableErrors)( + 'points unknown-table errors in raw SQL at clickstack_list_sources: %s', + msg => { + expect(errorHint(msg, undefined, { rawSql: true })).toContain( + 'clickstack_list_sources', + ); + }, + ); + + // Source-based tools take a sourceId, so the failing table is the source's + // own and listing sources would only hand it back. + it.each(unknownTableErrors)( + 'does not point source-based tools at clickstack_list_sources: %s', + msg => { + expect(errorHint(msg) ?? '').not.toContain('clickstack_list_sources'); + }, + ); it('keeps pointing unknown-column errors at clickstack_describe_source', () => { const hint = errorHint( diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index 3bcc454cc4..c6543a23c3 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -814,18 +814,32 @@ describe('MCP Query Tools', () => { ); describe('sql parameter examples', () => { - const getExamples = async () => { + const getDescription = async () => { const { tools } = await client.listTools(); const sqlParam = tools.find(t => t.name === 'clickstack_sql')! .inputSchema.properties?.sql; - const description = - sqlParam && typeof sqlParam === 'object' && 'description' in sqlParam - ? String(sqlParam.description) - : ''; - return [...description.matchAll(/^Example \(.+\):\n {2}(.+)$/gm)].map( - match => match[1], - ); + return sqlParam && + typeof sqlParam === 'object' && + 'description' in sqlParam + ? String(sqlParam.description) + : ''; }; + const getExamples = async () => + [ + ...(await getDescription()).matchAll(/^Example \(.+\):\n {2}(.+)$/gm), + ].map(match => match[1]); + + // timestampColumn can list several columns ("TimestampTime, Timestamp"), + // which breaks $__timeFilter if pasted whole. Metric sources return a + // database instead of a table. + it('say how to fill placeholders for multi-column timestamps and metric sources', async () => { + const description = await getDescription(); + + expect(description).toMatch( + /first expression in its `timestampColumn`/, + ); + expect(description).toMatch(/metricTables.*`database`/); + }); // Agents copy examples literally. A concrete table or column in one // becomes the guess, and it only exists on some schemas. @@ -946,6 +960,31 @@ describe('MCP Query Tools', () => { /UNKNOWN_IDENTIFIER|Missing columns|unknown/i, ); }); + + it('does not send a source whose table is missing back to clickstack_list_sources', async () => { + const missing = await Source.create({ + kind: SourceKind.Log, + team: team._id, + from: { + databaseName: DEFAULT_DATABASE, + tableName: 'nonexistent_table_xyz', + }, + timestampValueExpression: 'Timestamp', + connection: connection._id, + name: 'Missing logs', + }); + + const result = await callTool(client, 'clickstack_table', { + sourceId: missing._id.toString(), + select: [{ aggFn: 'count' }], + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toMatch( + /UNKNOWN_TABLE|does(n.t| not) exist/i, + ); + expect(getFirstText(result)).not.toContain('clickstack_list_sources'); + }); }); describe('clickstack_timeseries errors', () => { diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 9991858556..fd1b734d40 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -684,7 +684,7 @@ export async function runConfigTile( }); return formatQueryResult(result); } catch (e) { - return clickHouseErrorResult(e); + return clickHouseErrorResult(e, { rawSql: true }); } } @@ -841,11 +841,11 @@ function hasNodeErrorCode(val: unknown, codes: ReadonlySet): boolean { */ export function clickHouseErrorResult( e: unknown, - context?: string | { prefix?: string; suffix?: string }, + context?: string | { prefix?: string; suffix?: string; rawSql?: boolean }, ): McpErrorResult { - const { prefix, suffix } = + const { prefix, suffix, rawSql } = typeof context === 'string' - ? { prefix: context, suffix: undefined } + ? { prefix: context, suffix: undefined, rawSql: undefined } : (context ?? {}); // Prefer .message, but fall back to .cause.message when the wrapper @@ -857,7 +857,7 @@ export function clickHouseErrorResult( (e.cause instanceof Error ? e.cause.message : '') || String(e) : String(e); - const hint = errorHint(raw, e); + const hint = errorHint(raw, e, { rawSql }); const base = hint ? `${raw}\n\nHINT: ${hint}` : raw; const text = `${prefix ? `${prefix}: ` : ''}${base}${suffix ? ` ${suffix}` : ''}`; @@ -897,7 +897,11 @@ export function isQueryOutOfTime(e: unknown): boolean { } /** @internal Exported for testing only. */ -export function errorHint(msg: string, error?: unknown): string | null { +export function errorHint( + msg: string, + error?: unknown, + options?: { rawSql?: boolean }, +): string | null { const unknownVariableError = findCause( error, (e): e is UnknownVariableError => e instanceof UnknownVariableError, @@ -955,8 +959,11 @@ export function errorHint(msg: string, error?: unknown): string | null { ); } // Checked before unknown identifiers: "Unknown table expression identifier" - // names a table, so describe_source's column list would not help. + // names a table, so describe_source's column list would not help. Only raw + // SQL names its own table; source-based tools would be sent back to the + // same source table that just failed. if ( + options?.rawSql && /Unknown table expression identifier|(Table|Database) \S+ does not exist|UNKNOWN_(TABLE|DATABASE)/.test( msg, ) diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts index eba36245ff..14affcdc22 100644 --- a/packages/api/src/mcp/tools/query/sql.ts +++ b/packages/api/src/mcp/tools/query/sql.ts @@ -40,8 +40,10 @@ const sqlSchema = z.object({ ' $__filters — dashboard filter conditions (resolves to 1=1 when no filters)\n' + ' {intervalSeconds:Int64} / {intervalMilliseconds:Int64} — bucket size parameters\n\n' + "In the examples, replace
with a source's `table` and " + - 'with its `timestampColumn`, both from clickstack_list_sources. Table and column ' + - 'names differ between sources, so do not guess them.\n\n' + + 'with the first expression in its `timestampColumn`, both from ' + + 'clickstack_list_sources. For a metric source, use a table from its ' + + 'metricTables qualified with its `database`. Table and column names differ ' + + 'between sources, so do not guess them.\n\n' + 'Example (time-series):\n' + ' SELECT $__timeInterval() AS ts, ServiceName, count() ' + 'FROM
WHERE $__timeFilter() GROUP BY ServiceName, ts ORDER BY ts\n\n' + From faf11efebada4adf86a370afec5d67b02c674301 Mon Sep 17 00:00:00 2001 From: George Goldenberg <228832143+squaredg@users.noreply.github.com> Date: Tue, 13 Oct 2026 12:22:44 -0700 Subject: [PATCH 5/5] chore: scope the changeset's unknown-table hint to clickstack_sql --- .changeset/mcp-sql-table-names.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/mcp-sql-table-names.md b/.changeset/mcp-sql-table-names.md index 674d945a24..110346f367 100644 --- a/.changeset/mcp-sql-table-names.md +++ b/.changeset/mcp-sql-table-names.md @@ -6,4 +6,4 @@ fix(mcp): stop `clickstack_sql` callers from guessing table and timestamp column names. `clickstack_list_sources` now returns each source's database-qualified `table` (and `database` for metric sources), the `sql` examples use `
` and `` placeholders instead of `otel_logs` and `TimestampTime`, -and unknown-table errors point at `clickstack_list_sources`. +and unknown-table errors from `clickstack_sql` point at `clickstack_list_sources`.