From 1731b9f71e95e3060f5ec56887d44d602f078787 Mon Sep 17 00:00:00 2001 From: George Goldenberg <228832143+squaredg@users.noreply.github.com> Date: Sun, 11 Oct 2026 17:46:30 -0700 Subject: [PATCH] feat(mcp): accept sourceId in clickstack_sql so $__sourceTable resolves 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. --- .changeset/mcp-sql-source-id.md | 8 ++ .../src/mcp/__tests__/queryTool.int.test.ts | 119 +++++++++++++++++- packages/api/src/mcp/tools/query/sql.ts | 51 +++++++- 3 files changed, 171 insertions(+), 7 deletions(-) create mode 100644 .changeset/mcp-sql-source-id.md diff --git a/.changeset/mcp-sql-source-id.md b/.changeset/mcp-sql-source-id.md new file mode 100644 index 0000000000..56fb54907a --- /dev/null +++ b/.changeset/mcp-sql-source-id.md @@ -0,0 +1,8 @@ +--- +'@hyperdx/api': patch +--- + +feat(mcp): `clickstack_sql` accepts an optional `sourceId`, so `$__sourceTable` +expands to that source's table. Unknown sources, other teams' sources, and a +source on a different connection than `connectionId` are rejected, as is +`$__sourceTable` without a `sourceId`. diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index c6543a23c3..c4926279e3 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -1,6 +1,7 @@ import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node'; import { MetricsDataType, SourceKind } from '@hyperdx/common-utils/dist/types'; import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { ObjectId } from 'mongodb'; import * as config from '@/config'; import { @@ -20,6 +21,7 @@ import { import { McpContext } from '@/mcp/tools/types'; import Connection from '@/models/connection'; import { Source, type SourceDocument } from '@/models/source'; +import Team from '@/models/team'; import { callTool, createTestClient, getFirstText } from './mcpTestUtils'; @@ -163,6 +165,16 @@ describe('MCP Query Tools', () => { expect(tool!.inputSchema.required).toContain('connectionId'); expect(tool!.inputSchema.required).toContain('sql'); }); + + it('exposes an optional sourceId on clickstack_sql', async () => { + const { tools } = await client.listTools(); + const tool = tools.find(t => t.name === 'clickstack_sql')!; + + expect(Object.keys(tool.inputSchema.properties ?? {})).toContain( + 'sourceId', + ); + expect(tool.inputSchema.required).not.toContain('sourceId'); + }); }); // ─── clickstack_timeseries ───────────────────────────────────────────────────── @@ -848,12 +860,19 @@ describe('MCP Query Tools', () => { expect(examples).toHaveLength(2); for (const sql of examples) { - expect(sql).toContain('FROM '); + expect(sql).toMatch(/FROM (
|\$__sourceTable) /); expect(sql).toContain(''); expect(sql).not.toMatch(/otel_|TimestampTime/); } }); + it('show $__sourceTable for a source and
for any other table', async () => { + const [timeSeries, table] = await getExamples(); + + expect(timeSeries).toContain('FROM $__sourceTable '); + expect(table).toContain('FROM
'); + }); + it('run once the placeholders are filled from a source', async () => { const examples = await getExamples(); @@ -864,6 +883,7 @@ describe('MCP Query Tools', () => { .replaceAll('', 'Timestamp'); const result = await callTool(client, 'clickstack_sql', { connectionId: connection._id.toString(), + sourceId: logSource._id.toString(), sql, startTime: new Date(Date.now() - 60 * 60 * 1000).toISOString(), endTime: new Date().toISOString(), @@ -876,6 +896,103 @@ describe('MCP Query Tools', () => { }); }); + describe('sourceId', () => { + const countSql = + 'SELECT count() AS n FROM $__sourceTable WHERE $__timeFilter(Timestamp)'; + + it('resolves $__sourceTable to the table of the given source', async () => { + const now = Date.now(); + await bulkInsertLogs( + [1, 2, 3].map(minutesAgo => ({ + Body: 'from source', + ServiceName: 'sql-source', + SeverityText: 'INFO', + Timestamp: new Date(now - minutesAgo * 60 * 1000), + })), + ); + + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sourceId: logSource._id.toString(), + sql: `${countSql} AND ServiceName = 'sql-source'`, + startTime: new Date(now - 60 * 60 * 1000).toISOString(), + endTime: new Date(now).toISOString(), + }); + + expect(result.isError).toBeFalsy(); + expect(JSON.parse(getFirstText(result)).result.data).toEqual([ + { n: '3' }, + ]); + }); + + it('rejects $__sourceTable without a sourceId, saying to pass one', async () => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sql: countSql, + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain( + '$__sourceTable needs a sourceId', + ); + }); + + it('rejects a sourceId that does not exist', async () => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sourceId: new ObjectId().toString(), + sql: countSql, + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain('Source not found'); + }); + + it("rejects another team's sourceId as not found", async () => { + const otherTeam = await Team.create({ name: 'Other Team' }); + const otherSource = await Source.create({ + kind: SourceKind.Log, + team: otherTeam._id, + from: { + databaseName: DEFAULT_DATABASE, + tableName: DEFAULT_LOGS_TABLE, + }, + timestampValueExpression: 'Timestamp', + connection: connection._id, + name: 'Other Logs', + }); + + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sourceId: otherSource._id.toString(), + sql: countSql, + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain('Source not found'); + }); + + // $__sourceTable would otherwise expand to a table on another server. + it('rejects a sourceId whose connection differs from connectionId', async () => { + const otherConnection = await Connection.create({ + team: team._id, + name: 'Other', + host: config.CLICKHOUSE_HOST, + username: config.CLICKHOUSE_USER, + password: config.CLICKHOUSE_PASSWORD, + }); + + const result = await callTool(client, 'clickstack_sql', { + connectionId: otherConnection._id.toString(), + sourceId: logSource._id.toString(), + sql: countSql, + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain('does not match the connection'); + }); + }); + it('returns plain query rows unchanged', async () => { const result = await callTool(client, 'clickstack_sql', { connectionId: connection._id.toString(), diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts index 14affcdc22..74e965e904 100644 --- a/packages/api/src/mcp/tools/query/sql.ts +++ b/packages/api/src/mcp/tools/query/sql.ts @@ -1,6 +1,8 @@ +import { hasMacro } from '@hyperdx/common-utils/dist/macros'; import { hasVariableMacro } from '@hyperdx/common-utils/dist/variables'; import { z } from 'zod'; +import { getSource } from '@/controllers/sources'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpUserError } from '@/mcp/utils/errors'; @@ -17,6 +19,14 @@ const sqlSchema = z.object({ 'Connection ID (required). This is the only split tool that needs a connectionId ' + 'instead of sourceId. Call clickstack_list_sources to find available connections.', ), + sourceId: z + .string() + .optional() + .describe( + 'Source ID. Optional. Set it when the query reads a table backed by a source, so ' + + "`$__sourceTable` expands to that source's database.table. The source's " + + 'connection must match connectionId. Call clickstack_list_sources to find source IDs.', + ), sql: z .string() .describe( @@ -38,15 +48,17 @@ const sqlSchema = z.object({ ' $__timeInterval_ms(column) — same with millisecond precision\n' + ' $__interval_s — raw interval in seconds\n' + ' $__filters — dashboard filter conditions (resolves to 1=1 when no filters)\n' + + " $__sourceTable — the source's database.table. Requires sourceId.\n" + ' {intervalSeconds:Int64} / {intervalMilliseconds:Int64} — bucket size parameters\n\n' + "In the examples, replace
with a source's `table` and " + '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' + + 'clickstack_list_sources, or pass that source as sourceId and use ' + + '$__sourceTable. 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, with sourceId):\n' + ' SELECT $__timeInterval() AS ts, ServiceName, count() ' + - 'FROM
WHERE $__timeFilter() GROUP BY ServiceName, ts ORDER BY ts\n\n' + + 'FROM $__sourceTable WHERE $__timeFilter() GROUP BY ServiceName, ts ORDER BY ts\n\n' + 'Example (table):\n' + ' SELECT ServiceName, count() AS n FROM
' + 'WHERE >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) ' + @@ -79,7 +91,8 @@ export function registerSql({ context, registerTool }: ToolRegistrar) { 'A single-table aggregation, top-N, time-series, or row browse is ALWAYS a ' + 'builder-tool job, never raw SQL. If you are unsure, try the builder tool first and only ' + 'fall back to SQL if it cannot express what you need.\n\n' + - 'Requires connectionId (not sourceId) — call clickstack_list_sources to find connections. ' + + 'Requires connectionId — call clickstack_list_sources to find connections. Pass sourceId ' + + 'too when querying a source, so $__sourceTable resolves to its table. ' + 'Call clickstack_describe_source to discover column names before writing SQL.\n\n' + 'Results are always returned as table rows — for time-series semantics, ' + 'include a time column and ORDER BY it in your SQL.', @@ -105,6 +118,31 @@ export function registerSql({ context, registerTool }: ToolRegistrar) { ); } + if (input.sourceId) { + const source = await getSource(teamId.toString(), input.sourceId); + if (!source) { + return mcpUserError( + `Source not found: ${input.sourceId}. Call clickstack_list_sources to discover available source IDs.`, + ); + } + // $__sourceTable expands to the source's table, so a mismatch would run + // the query against a table on another server. + const sourceConnectionId = source.connection.toString(); + if (sourceConnectionId !== input.connectionId) { + return mcpUserError( + `connectionId "${input.connectionId}" does not match the connection of source ` + + `"${input.sourceId}" ("${sourceConnectionId}"). Use the source's own ` + + 'connection or drop sourceId from the call.', + ); + } + } else if (hasMacro(input.sql, 'sourceTable')) { + return mcpUserError( + '$__sourceTable needs a sourceId to know which table to expand to. ' + + 'Pass the sourceId of a source from clickstack_list_sources, or write ' + + "the source's `table` in place of the macro.", + ); + } + // 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 @@ -113,6 +151,7 @@ export function registerSql({ context, registerTool }: ToolRegistrar) { configType: 'sql' as const, displayType: 'line' as const, connectionId: input.connectionId, + sourceId: input.sourceId, sqlTemplate: input.sql, });