From 6341524e6477903e64ad44eb199b66fc721154bd Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Tue, 20 Oct 2026 12:55:55 -0600 Subject: [PATCH 1/3] feat(mcp): run multiple clickstack_sql queries in parallel via a queries array --- .changeset/mcp-sql-batch-queries.md | 8 + MCP.md | 2 +- .../queryTilesSummarizeRows.test.ts | 64 +--- .../src/mcp/__tests__/queryTool.int.test.ts | 107 +++++- .../src/mcp/__tests__/sqlToolBatch.test.ts | 355 ++++++++++++++++++ .../api/src/mcp/__tests__/timeout.test.ts | 64 +++- .../api/src/mcp/prompts/dashboards/content.ts | 5 + .../src/mcp/tools/dashboards/queryTiles.ts | 45 +-- packages/api/src/mcp/tools/query/helpers.ts | 13 +- .../api/src/mcp/tools/query/prepareSql.ts | 95 +++++ packages/api/src/mcp/tools/query/sql.ts | 144 ++++--- packages/api/src/mcp/tools/query/sqlBatch.ts | 173 +++++++++ packages/api/src/mcp/utils/timeout.ts | 37 ++ 13 files changed, 945 insertions(+), 167 deletions(-) create mode 100644 .changeset/mcp-sql-batch-queries.md create mode 100644 packages/api/src/mcp/__tests__/sqlToolBatch.test.ts create mode 100644 packages/api/src/mcp/tools/query/prepareSql.ts create mode 100644 packages/api/src/mcp/tools/query/sqlBatch.ts diff --git a/.changeset/mcp-sql-batch-queries.md b/.changeset/mcp-sql-batch-queries.md new file mode 100644 index 0000000000..266c576978 --- /dev/null +++ b/.changeset/mcp-sql-batch-queries.md @@ -0,0 +1,8 @@ +--- +'@hyperdx/api': patch +--- + +feat(mcp): `clickstack_sql` accepts a `queries` array to run up to 10 +independent queries in parallel under a shared 60s deadline. Each query reports +its own `ok`/`error`/`timeout` status, so one failing query does not fail the +others. Single-query calls with `sql` behave as before. diff --git a/MCP.md b/MCP.md index 132a7a9d79..4a11e752bf 100644 --- a/MCP.md +++ b/MCP.md @@ -132,7 +132,7 @@ with: | `clickstack_event_patterns` | Discover the most common log messages and event patterns using Drain clustering | | `clickstack_event_deltas` | Compare two row groups and rank properties by how their value distributions differ | | `clickstack_emerging_signals` | Detect NEW or GONE log/event patterns between a baseline and a current window (two-window Drain novelty diff) | -| `clickstack_sql` | Execute raw ClickHouse SQL for advanced queries (JOINs, CTEs, sub-queries) | +| `clickstack_sql` | Execute raw ClickHouse SQL for advanced queries (JOINs, CTEs, sub-queries); pass `queries` to run up to 10 in parallel | | `clickstack_get_dashboard` | List all dashboards or get full detail for a specific dashboard | | `clickstack_save_dashboard` | Create or update a dashboard with tiles (charts, tables, numbers, search, markdown) | | `clickstack_delete_dashboard` | Permanently delete a dashboard and its attached alerts | diff --git a/packages/api/src/mcp/__tests__/dashboards/queryTilesSummarizeRows.test.ts b/packages/api/src/mcp/__tests__/dashboards/queryTilesSummarizeRows.test.ts index 5708f699f9..8a01a97ad4 100644 --- a/packages/api/src/mcp/__tests__/dashboards/queryTilesSummarizeRows.test.ts +++ b/packages/api/src/mcp/__tests__/dashboards/queryTilesSummarizeRows.test.ts @@ -1,8 +1,4 @@ -import { - summarizeRows, - TileDeadlineError, - withDeadline, -} from '@/mcp/tools/dashboards/queryTiles'; +import { summarizeRows } from '@/mcp/tools/dashboards/queryTiles'; describe('summarizeRows', () => { it('reads a top-level array result as rows', () => { @@ -46,61 +42,3 @@ describe('summarizeRows', () => { expect(summarizeRows('123')).toEqual({}); }); }); - -describe('withDeadline', () => { - it('resolves work that finishes before the deadline', async () => { - await expect( - withDeadline(() => Promise.resolve('done'), Date.now() + 1000), - ).resolves.toBe('done'); - }); - - it('rejects with TileDeadlineError when work exceeds the deadline', async () => { - const slow = () => - new Promise(resolve => setTimeout(() => resolve('too late'), 50)); - await expect(withDeadline(slow, Date.now() + 5)).rejects.toBeInstanceOf( - TileDeadlineError, - ); - }); - - it('does not start the work when the shared deadline is already in the past', async () => { - // A tile scheduled after the batch budget is spent must fail fast WITHOUT - // invoking the thunk — this is what keeps the post-deadline drain from - // issuing any (un-cancellable) ClickHouse queries. - const start = jest.fn(() => Promise.resolve('too late')); - await expect(withDeadline(start, Date.now() - 1)).rejects.toBeInstanceOf( - TileDeadlineError, - ); - expect(start).not.toHaveBeenCalled(); - }); - - it('propagates a rejection from the underlying work', async () => { - const boom = () => Promise.reject(new Error('boom')); - await expect(withDeadline(boom, Date.now() + 1000)).rejects.toThrow('boom'); - }); - - it('aborts the signal handed to the work when the deadline fires', async () => { - // The signal must fire so the in-flight ClickHouse query is cancelled - // server-side rather than left running after the batch gives up on it. - let captured: AbortSignal | undefined; - const slow = (signal: AbortSignal) => { - captured = signal; - return new Promise(resolve => - setTimeout(() => resolve('too late'), 50), - ); - }; - await expect(withDeadline(slow, Date.now() + 5)).rejects.toBeInstanceOf( - TileDeadlineError, - ); - expect(captured?.aborted).toBe(true); - }); - - it('aborts the signal once work resolves so no query outlives the call', async () => { - let captured: AbortSignal | undefined; - const work = (signal: AbortSignal) => { - captured = signal; - return Promise.resolve('done'); - }; - await expect(withDeadline(work, Date.now() + 1000)).resolves.toBe('done'); - expect(captured?.aborted).toBe(true); - }); -}); diff --git a/packages/api/src/mcp/__tests__/queryTool.int.test.ts b/packages/api/src/mcp/__tests__/queryTool.int.test.ts index c4926279e3..c481324a44 100644 --- a/packages/api/src/mcp/__tests__/queryTool.int.test.ts +++ b/packages/api/src/mcp/__tests__/queryTool.int.test.ts @@ -162,8 +162,11 @@ describe('MCP Query Tools', () => { expect(props).toContain('sql'); expect(props).toContain('startTime'); expect(props).toContain('endTime'); + expect(props).toContain('queries'); expect(tool!.inputSchema.required).toContain('connectionId'); - expect(tool!.inputSchema.required).toContain('sql'); + // sql and queries are alternatives, so neither is required by the schema. + expect(tool!.inputSchema.required).not.toContain('sql'); + expect(tool!.inputSchema.required).not.toContain('queries'); }); it('exposes an optional sourceId on clickstack_sql', async () => { @@ -1004,6 +1007,108 @@ describe('MCP Query Tools', () => { { value: 1, label: 'a' }, ]); }); + + describe('queries (batch mode)', () => { + it('runs each query and reports its own status', async () => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + queries: [ + { id: 'one', sql: 'SELECT 1 AS value' }, + { id: 'bad', sql: 'SELECTT 1' }, + { id: 'two', sql: 'SELECT 2 AS value' }, + ], + }); + + expect(result.isError).toBeFalsy(); + const parsed = JSON.parse(getFirstText(result)); + expect(parsed.summary).toEqual({ + total: 3, + ok: 2, + error: 1, + timeout: 0, + }); + const [one, bad, two] = parsed.results; + expect(one).toMatchObject({ index: 0, id: 'one', status: 'ok' }); + expect(one.result.data).toEqual([{ value: 1 }]); + expect(bad).toMatchObject({ index: 1, id: 'bad', status: 'error' }); + expect(bad.error).toMatch(/syntax/i); + expect(two.result.data).toEqual([{ value: 2 }]); + }); + + it("expands $__sourceTable per query from that query's sourceId", async () => { + const now = Date.now(); + await bulkInsertLogs( + [1, 2].map(minutesAgo => ({ + Body: 'batch source', + ServiceName: 'sql-batch-source', + SeverityText: 'INFO', + Timestamp: new Date(now - minutesAgo * 60 * 1000), + })), + ); + + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + queries: [ + { + id: 'logs', + sourceId: logSource._id.toString(), + sql: + 'SELECT count() AS n FROM $__sourceTable ' + + "WHERE $__timeFilter(Timestamp) AND ServiceName = 'sql-batch-source'", + }, + { id: 'noSource', sql: 'SELECT count() FROM $__sourceTable' }, + ], + startTime: new Date(now - 60 * 60 * 1000).toISOString(), + endTime: new Date(now).toISOString(), + }); + + const parsed = JSON.parse(getFirstText(result)); + expect(parsed.results[0].result.data).toEqual([{ n: '2' }]); + expect(parsed.results[1].status).toBe('error'); + expect(parsed.results[1].error).toContain( + '$__sourceTable needs a sourceId', + ); + }); + + it('keeps readonly enforcement for every query', async () => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + queries: [ + { + sql: `INSERT INTO ${DEFAULT_DATABASE}.${DEFAULT_LOGS_TABLE} (Body) VALUES ('x')`, + }, + ], + }); + + expect(result.isError).toBe(true); + const parsed = JSON.parse(getFirstText(result)); + expect(parsed.results[0].status).toBe('error'); + expect(parsed.results[0].error).toMatch(/readonly/i); + }); + + it('rejects passing both sql and queries', async () => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + sql: 'SELECT 1', + queries: [{ sql: 'SELECT 2' }], + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain('exactly one of sql'); + }); + + it('rejects more than 10 queries at the schema', async () => { + const result = await callTool(client, 'clickstack_sql', { + connectionId: connection._id.toString(), + queries: Array.from({ length: 11 }, (_, i) => ({ + sql: `SELECT ${i}`, + })), + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain('Input validation error'); + }); + }); }); // ─── ClickHouse query errors ────────────────────────────────────────────────── diff --git a/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts b/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts new file mode 100644 index 0000000000..ca33d1f814 --- /dev/null +++ b/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts @@ -0,0 +1,355 @@ +// Unit tests for clickstack_sql batch mode (the `queries` argument). Mocks +// runConfigTile and getSource so the batch runner can be driven without +// ClickHouse or Mongo. + +const mockRunConfigTile = jest.fn(); +const mockGetSource = jest.fn(); + +jest.mock('@/mcp/tools/query/helpers', () => { + const actual = jest.requireActual('@/mcp/tools/query/helpers'); + return { + ...actual, + runConfigTile: (...args: unknown[]) => mockRunConfigTile(...args), + }; +}); + +jest.mock('@/models/source', () => ({})); +jest.mock('@/controllers/sources', () => ({ + getSource: (...args: unknown[]) => mockGetSource(...args), +})); +jest.mock('@/controllers/connection', () => ({})); + +import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; +import mongoose from 'mongoose'; + +import { registerSql } from '@/mcp/tools/query/sql'; +import { SQL_BATCH_CONCURRENCY } from '@/mcp/tools/query/sqlBatch'; +import type { McpContext, RegisterToolFn, ToolResult } from '@/mcp/tools/types'; +import { mcpUserError } from '@/mcp/utils/errors'; + +type Handler = Parameters[2]; + +const connectionId = new mongoose.Types.ObjectId().toString(); +const otherConnectionId = new mongoose.Types.ObjectId().toString(); +const sourceId = new mongoose.Types.ObjectId().toString(); + +function buildHandler(): Handler { + let captured: Handler | undefined; + const registerTool: RegisterToolFn = (_name, _config, handler) => { + captured = handler; + }; + const context: McpContext = { teamId: 'team-1', userId: 'user-1' }; + const server = new McpServer({ name: 'test', version: '0.0.0' }); + registerSql({ server, context, registerTool }); + if (!captured) throw new Error('handler was not registered'); + return captured; +} + +function textOf(result: ToolResult): string { + const item = result.content[0]; + if (!item || item.type !== 'text') throw new Error('expected text content'); + return item.text; +} + +function rowsResult(rows: unknown[]) { + return { + content: [ + { type: 'text' as const, text: JSON.stringify({ result: rows }) }, + ], + }; +} + +type TileArg = { + config: { sqlTemplate: string; connectionId: string; sourceId?: string }; +}; + +function tileArgs(): TileArg['config'][] { + return mockRunConfigTile.mock.calls.map( + ([, tile]: [unknown, TileArg]) => tile.config, + ); +} + +beforeEach(() => { + jest.clearAllMocks(); + mockRunConfigTile.mockImplementation((_team, tile: TileArg) => + Promise.resolve(rowsResult([{ sql: tile.config.sqlTemplate }])), + ); + mockGetSource.mockResolvedValue({ connection: connectionId }); +}); + +describe('clickstack_sql batch mode', () => { + it('rejects a call that passes both sql and queries', async () => { + const result = await buildHandler()({ + connectionId, + sql: 'SELECT 1', + queries: [{ sql: 'SELECT 2' }], + }); + + expect(result.isError).toBe(true); + expect(textOf(result)).toContain('exactly one of sql'); + expect(mockRunConfigTile).not.toHaveBeenCalled(); + }); + + it('rejects a call that passes neither sql nor queries', async () => { + const result = await buildHandler()({ connectionId }); + + expect(result.isError).toBe(true); + expect(textOf(result)).toContain('exactly one of sql'); + }); + + it('rejects duplicate query ids before running anything', async () => { + const result = await buildHandler()({ + connectionId, + queries: [ + { id: 'a', sql: 'SELECT 1' }, + { id: 'a', sql: 'SELECT 2' }, + ], + }); + + expect(result.isError).toBe(true); + expect(textOf(result)).toContain('Duplicate query id "a"'); + expect(mockRunConfigTile).not.toHaveBeenCalled(); + }); + + it('returns results in input order with index and id', async () => { + mockRunConfigTile.mockImplementation( + (_team, tile: TileArg) => + new Promise(resolve => + // Finish in reverse order to prove ordering is by input, not completion. + setTimeout( + () => resolve(rowsResult([{ sql: tile.config.sqlTemplate }])), + tile.config.sqlTemplate === 'SELECT 1' ? 20 : 1, + ), + ), + ); + + const result = await buildHandler()({ + connectionId, + queries: [{ id: 'first', sql: 'SELECT 1' }, { sql: 'SELECT 2' }], + }); + + expect(result.isError).toBeFalsy(); + const parsed = JSON.parse(textOf(result)); + expect(parsed.summary).toEqual({ total: 2, ok: 2, error: 0, timeout: 0 }); + expect(parsed.results).toEqual([ + { + index: 0, + id: 'first', + status: 'ok', + result: [{ sql: 'SELECT 1' }], + }, + { index: 1, status: 'ok', result: [{ sql: 'SELECT 2' }] }, + ]); + }); + + it('reports a query that fails validation without blocking the others', async () => { + const result = await buildHandler()({ + connectionId, + queries: [ + { id: 'macro', sql: 'SELECT 1 WHERE $__filter(ServiceName, $svc)' }, + { id: 'noSource', sql: 'SELECT count() FROM $__sourceTable' }, + { id: 'good', sql: 'SELECT 3' }, + ], + }); + + expect(result.isError).toBeFalsy(); + const parsed = JSON.parse(textOf(result)); + expect(parsed.summary).toMatchObject({ ok: 1, error: 2 }); + expect(parsed.results[0].error).toContain('only resolve for a tile'); + expect(parsed.results[1].error).toContain( + '$__sourceTable needs a sourceId', + ); + expect(parsed.results[2].status).toBe('ok'); + expect(tileArgs().map(c => c.sqlTemplate)).toEqual(['SELECT 3']); + }); + + it('reports ClickHouse errors and thrown errors per query', async () => { + mockRunConfigTile.mockImplementation((_team, tile: TileArg) => { + if (tile.config.sqlTemplate === 'BAD') { + return Promise.resolve(mcpUserError('Syntax error near BAD')); + } + if (tile.config.sqlTemplate === 'THROW') { + return Promise.reject(new Error('connection reset')); + } + return Promise.resolve(rowsResult([])); + }); + + const result = await buildHandler()({ + connectionId, + queries: [{ sql: 'BAD' }, { sql: 'THROW' }, { sql: 'SELECT 1' }], + }); + + expect(result.isError).toBeFalsy(); + const parsed = JSON.parse(textOf(result)); + expect(parsed.results.map((r: { status: string }) => r.status)).toEqual([ + 'error', + 'error', + 'ok', + ]); + expect(parsed.results[0].error).toContain('Syntax error near BAD'); + expect(parsed.results[1].error).toContain('connection reset'); + }); + + it('returns isError when every query fails, keeping per-query errors', async () => { + mockRunConfigTile.mockResolvedValue(mcpUserError('Unknown table')); + + const result = await buildHandler()({ + connectionId, + queries: [{ sql: 'SELECT 1' }, { sql: 'SELECT 2' }], + }); + + expect(result.isError).toBe(true); + const parsed = JSON.parse(textOf(result)); + expect(parsed.summary).toMatchObject({ ok: 0, error: 2 }); + expect(parsed.results[0].error).toContain('Unknown table'); + }); + + it('inherits top-level connectionId and sourceId unless a query overrides them', async () => { + const otherSourceId = new mongoose.Types.ObjectId().toString(); + mockGetSource.mockImplementation((_team, id: string) => + Promise.resolve({ + connection: id === otherSourceId ? otherConnectionId : connectionId, + }), + ); + + const result = await buildHandler()({ + connectionId, + sourceId, + queries: [ + { sql: 'SELECT 1' }, + { + sql: 'SELECT 2', + connectionId: otherConnectionId, + sourceId: otherSourceId, + }, + ], + }); + + expect(result.isError).toBeFalsy(); + expect(tileArgs()).toEqual([ + expect.objectContaining({ + sqlTemplate: 'SELECT 1', + connectionId, + sourceId, + }), + expect.objectContaining({ + sqlTemplate: 'SELECT 2', + connectionId: otherConnectionId, + sourceId: otherSourceId, + }), + ]); + }); + + it('flags a connection override that conflicts with the inherited source', async () => { + const result = await buildHandler()({ + connectionId, + sourceId, + queries: [ + { sql: 'SELECT 1' }, + { sql: 'SELECT 2', connectionId: otherConnectionId }, + ], + }); + + const parsed = JSON.parse(textOf(result)); + expect(parsed.results[0].status).toBe('ok'); + expect(parsed.results[1].status).toBe('error'); + expect(parsed.results[1].error).toContain('does not match the connection'); + }); + + it('looks each source up once per call', async () => { + await buildHandler()({ + connectionId, + sourceId, + queries: [{ sql: 'SELECT 1' }, { sql: 'SELECT 2' }, { sql: 'SELECT 3' }], + }); + + expect(mockGetSource).toHaveBeenCalledTimes(1); + }); + + it(`runs at most ${SQL_BATCH_CONCURRENCY} queries at once`, async () => { + let inFlight = 0; + let peak = 0; + mockRunConfigTile.mockImplementation(async () => { + inFlight += 1; + peak = Math.max(peak, inFlight); + await new Promise(resolve => setTimeout(resolve, 5)); + inFlight -= 1; + return rowsResult([]); + }); + + const result = await buildHandler()({ + connectionId, + queries: Array.from({ length: 10 }, (_, i) => ({ sql: `SELECT ${i}` })), + }); + + expect(JSON.parse(textOf(result)).summary.ok).toBe(10); + expect(peak).toBe(SQL_BATCH_CONCURRENCY); + }); + + it('times out queries past the shared deadline without starting queued ones', async () => { + const base = 1_000_000_000_000; + let now = base; + const nowSpy = jest.spyOn(Date, 'now').mockImplementation(() => now); + + try { + mockRunConfigTile.mockImplementation( + (_team, tile: TileArg) => + new Promise(resolve => + setImmediate(() => { + // Once every slot has started, the first query to finish moves + // the clock past the budget, so the query still waiting for a + // slot must fail without being issued. + if (tile.config.sqlTemplate === 'SELECT 0') { + now = base + 10 * 60_000; + } + resolve(rowsResult([])); + }), + ), + ); + + const queries = Array.from( + { length: SQL_BATCH_CONCURRENCY + 1 }, + (_, i) => ({ sql: `SELECT ${i}` }), + ); + const result = await buildHandler()({ + connectionId, + queries, + startTime: new Date(base - 60_000).toISOString(), + endTime: new Date(base).toISOString(), + }); + + const parsed = JSON.parse(textOf(result)); + const last = parsed.results.at(-1); + expect(last.status).toBe('timeout'); + expect(last.error).toContain('deadline'); + expect(parsed.summary.timeout).toBe(1); + expect(tileArgs().map(c => c.sqlTemplate)).not.toContain( + `SELECT ${SQL_BATCH_CONCURRENCY}`, + ); + } finally { + nowSpy.mockRestore(); + } + }); + + it('splits the response budget across the batch', async () => { + await buildHandler()({ + connectionId, + queries: Array.from({ length: 4 }, (_, i) => ({ sql: `SELECT ${i}` })), + }); + + for (const call of mockRunConfigTile.mock.calls) { + expect(call[4]).toMatchObject({ maxResponseChars: 25_000 }); + } + }); + + it('caps a single query at the single-query response limit', async () => { + await buildHandler()({ + connectionId, + queries: [{ sql: 'SELECT 1' }], + }); + + expect(mockRunConfigTile.mock.calls[0][4]).toMatchObject({ + maxResponseChars: 50_000, + }); + }); +}); diff --git a/packages/api/src/mcp/__tests__/timeout.test.ts b/packages/api/src/mcp/__tests__/timeout.test.ts index a97d2258e9..b816ca21c1 100644 --- a/packages/api/src/mcp/__tests__/timeout.test.ts +++ b/packages/api/src/mcp/__tests__/timeout.test.ts @@ -1,4 +1,8 @@ -import { runWithTimeout } from '@/mcp/utils/timeout'; +import { + DeadlineExceededError, + runWithTimeout, + withDeadline, +} from '@/mcp/utils/timeout'; const never = () => new Promise(() => {}); @@ -117,3 +121,61 @@ describe('runWithTimeout', () => { expect(jest.getTimerCount()).toBe(0); }); }); + +describe('withDeadline', () => { + it('resolves work that finishes before the deadline', async () => { + await expect( + withDeadline(() => Promise.resolve('done'), Date.now() + 1000), + ).resolves.toBe('done'); + }); + + it('rejects with DeadlineExceededError when work exceeds the deadline', async () => { + const slow = () => + new Promise(resolve => setTimeout(() => resolve('too late'), 50)); + await expect(withDeadline(slow, Date.now() + 5)).rejects.toBeInstanceOf( + DeadlineExceededError, + ); + }); + + it('does not start the work when the shared deadline is already in the past', async () => { + // Work scheduled after the batch budget is spent must fail fast WITHOUT + // invoking the thunk — this is what keeps the post-deadline drain from + // issuing any (un-cancellable) ClickHouse queries. + const start = jest.fn(() => Promise.resolve('too late')); + await expect(withDeadline(start, Date.now() - 1)).rejects.toBeInstanceOf( + DeadlineExceededError, + ); + expect(start).not.toHaveBeenCalled(); + }); + + it('propagates a rejection from the underlying work', async () => { + const boom = () => Promise.reject(new Error('boom')); + await expect(withDeadline(boom, Date.now() + 1000)).rejects.toThrow('boom'); + }); + + it('aborts the signal handed to the work when the deadline fires', async () => { + // The signal must fire so the in-flight ClickHouse query is cancelled + // server-side rather than left running after the batch gives up on it. + let captured: AbortSignal | undefined; + const slow = (signal: AbortSignal) => { + captured = signal; + return new Promise(resolve => + setTimeout(() => resolve('too late'), 50), + ); + }; + await expect(withDeadline(slow, Date.now() + 5)).rejects.toBeInstanceOf( + DeadlineExceededError, + ); + expect(captured?.aborted).toBe(true); + }); + + it('aborts the signal once work resolves so no query outlives the call', async () => { + let captured: AbortSignal | undefined; + const work = (signal: AbortSignal) => { + captured = signal; + return Promise.resolve('done'); + }; + await expect(withDeadline(work, Date.now() + 1000)).resolves.toBe('done'); + expect(captured?.aborted).toBe(true); + }); +}); diff --git a/packages/api/src/mcp/prompts/dashboards/content.ts b/packages/api/src/mcp/prompts/dashboards/content.ts index 69c8f4eb17..4a623db7c1 100644 --- a/packages/api/src/mcp/prompts/dashboards/content.ts +++ b/packages/api/src/mcp/prompts/dashboards/content.ts @@ -985,6 +985,11 @@ For configType: "sql" tiles, write ClickHouse SQL with template macros: IMPORTANT: Always include a LIMIT clause in table / number / pie / bar SQL queries. + BATCHING WITH clickstack_sql: to run several independent queries at once, pass + queries: [{ id, sql, sourceId?, connectionId? }, ...] (max 10) instead of sql. They run + in parallel over one shared time range, and each result reports status ok, error, or + timeout. Re-run a timed-out query on its own. + == PER-TILE TYPE CONSTRAINTS == number Exactly 1 select item. No groupBy. diff --git a/packages/api/src/mcp/tools/dashboards/queryTiles.ts b/packages/api/src/mcp/tools/dashboards/queryTiles.ts index 35b71c66f5..6afbfa8dd7 100644 --- a/packages/api/src/mcp/tools/dashboards/queryTiles.ts +++ b/packages/api/src/mcp/tools/dashboards/queryTiles.ts @@ -4,7 +4,7 @@ import { z } from 'zod'; import { parseTimeRange, runConfigTile } from '@/mcp/tools/query/helpers'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpUserError } from '@/mcp/utils/errors'; -import { runWithTimeout } from '@/mcp/utils/timeout'; +import { withDeadline } from '@/mcp/utils/timeout'; import Dashboard from '@/models/dashboard'; import { convertToExternalDashboard, @@ -64,49 +64,6 @@ function isMarkdownTile(tile: ExternalDashboardTileWithId): boolean { return tile.config.displayType === 'markdown'; } -/** - * Marker error so the per-tile catch can render a clear timeout message. - * Raised both when a started query overruns the deadline and when a queued - * tile's deadline has already passed before it could start. - * - * @internal Exported for testing only. - */ -export class TileDeadlineError extends Error { - constructor() { - super('Tile query exceeded the batch wall-clock deadline'); - this.name = 'TileDeadlineError'; - } -} - -/** - * Run `startWork` under a SHARED absolute deadline (epoch millis) — every tile - * in a batch passes the same `deadlineAt`, making the budget whole-call. - * - * `startWork` is a thunk, not an already-started promise, so the deadline is - * checked BEFORE the query is issued: once the budget is spent, tiles PQueue - * schedules during the drain fail fast without touching ClickHouse. - * - * A tile that did start runs under `runWithTimeout`: at the deadline its - * query is cancelled and the tile rejects with `TileDeadlineError`. - * - * @internal Exported for testing only. - */ -export async function withDeadline( - startWork: (signal: AbortSignal) => Promise, - deadlineAt: number, -): Promise { - const remaining = deadlineAt - Date.now(); - // Budget already spent — fail fast without starting the work at all. - if (remaining <= 0) { - throw new TileDeadlineError(); - } - const outcome = await runWithTimeout(startWork, { timeoutMs: remaining }); - if (outcome.timedOut) { - throw new TileDeadlineError(); - } - return outcome.value; -} - /** * Derive a compact data summary from a successful tile query payload. The * payload shape is `{ result: , ... }` where `` is either an array diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 028164edbe..51222cc166 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -296,8 +296,11 @@ function isEmptyResult(result: unknown): boolean { return false; } -function formatQueryResult(result: unknown) { - const { data: trimmedResult, isTrimmed } = trimToolResponse(result); +function formatQueryResult(result: unknown, maxResponseChars?: number) { + const { data: trimmedResult, isTrimmed } = trimToolResponse( + result, + maxResponseChars, + ); const empty = isEmptyResult(result); return { content: [ @@ -418,6 +421,8 @@ export async function runConfigTile( abortSignal?: AbortSignal; /** Dashboard variables and their selected values. Omitted when not in a dashboard context. */ variables?: ChartVariable[]; + /** Serialized size the result is trimmed to. Defaults to trimToolResponse's limit. */ + maxResponseChars?: number; }, ) { if (!isConfigTile(tile)) { @@ -615,7 +620,7 @@ export async function runConfigTile( abort_signal: options?.abortSignal, }, }); - return formatQueryResult(result); + return formatQueryResult(result, options?.maxResponseChars); } catch (e) { return clickHouseErrorResult(e); } @@ -690,7 +695,7 @@ export async function runConfigTile( abort_signal: options?.abortSignal, }, }); - return formatQueryResult(result); + return formatQueryResult(result, options?.maxResponseChars); } catch (e) { return clickHouseErrorResult(e, { rawSql: true }); } diff --git a/packages/api/src/mcp/tools/query/prepareSql.ts b/packages/api/src/mcp/tools/query/prepareSql.ts new file mode 100644 index 0000000000..1ead7c0db2 --- /dev/null +++ b/packages/api/src/mcp/tools/query/prepareSql.ts @@ -0,0 +1,95 @@ +import { hasMacro } from '@hyperdx/common-utils/dist/macros'; +import { hasVariableMacro } from '@hyperdx/common-utils/dist/variables'; + +import { getSource } from '@/controllers/sources'; +import type { McpErrorResult } from '@/mcp/utils/errors'; +import { mcpUserError } from '@/mcp/utils/errors'; +import type { ExternalDashboardTileWithId } from '@/utils/zod'; + +import { buildTile } from './helpers'; + +export type SourceLookup = (sourceId: string) => ReturnType; + +/** + * Source lookup memoized for one tool call, so a batch of queries against the + * same source reads it from Mongo once. + */ +export function createSourceLookup(teamId: string): SourceLookup { + const cache = new Map>(); + return sourceId => { + let pending = cache.get(sourceId); + if (!pending) { + pending = getSource(teamId, sourceId); + cache.set(sourceId, pending); + } + return pending; + }; +} + +/** + * Validate one raw SQL query and build the tile that runs it. Returns an error + * result instead of a tile when the query can never run as written. + */ +export async function prepareSqlQuery( + query: { sql: string; connectionId: string; sourceId?: string }, + lookupSource: SourceLookup, +): Promise<{ tile: ExternalDashboardTileWithId } | { error: McpErrorResult }> { + // $__filter / $__conditionalAll read the variables a dashboard's filters + // declare, and this tool has no dashboard behind it. + if (hasVariableMacro(query.sql)) { + return { + error: mcpUserError( + 'The $__filter and $__conditionalAll macros only resolve for a tile ' + + 'on a dashboard, because they read the dashboard variables its ' + + 'filters declare. This tool has no dashboard, so they would be ' + + 'sent to ClickHouse as literal text. Inline the condition here, ' + + 'or save the query as a dashboard tile and validate it with ' + + 'clickstack_query_tile.', + ), + }; + } + + if (query.sourceId) { + const source = await lookupSource(query.sourceId); + if (!source) { + return { + error: mcpUserError( + `Source not found: ${query.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 !== query.connectionId) { + return { + error: mcpUserError( + `connectionId "${query.connectionId}" does not match the connection of source ` + + `"${query.sourceId}" ("${sourceConnectionId}"). Use the source's own ` + + 'connection or drop sourceId from the call.', + ), + }; + } + } else if (hasMacro(query.sql, 'sourceTable')) { + return { + error: 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 + // the same either way, and ClickHouse ignores params a query never uses. + const tile = buildTile('MCP SQL', 24, 6, { + configType: 'sql' as const, + displayType: 'line' as const, + connectionId: query.connectionId, + sourceId: query.sourceId, + sqlTemplate: query.sql, + }); + return { tile }; +} diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts index 1ddcc32d68..28ba753e78 100644 --- a/packages/api/src/mcp/tools/query/sql.ts +++ b/packages/api/src/mcp/tools/query/sql.ts @@ -1,14 +1,18 @@ -import { hasMacro } from '@hyperdx/common-utils/dist/macros'; -import { hasVariableMacro } from '@hyperdx/common-utils/dist/variables'; +import { trace } from '@opentelemetry/api'; import { z } from 'zod'; -import { getSource } from '@/controllers/sources'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpUserError } from '@/mcp/utils/errors'; import { BUILDER_TOOLS_LIST, SQL_FALLBACK_CRITERIA } from './builderCatalog'; -import { buildTile, parseTimeRange, runConfigTile } from './helpers'; +import { parseTimeRange, runConfigTile } from './helpers'; +import { createSourceLookup, prepareSqlQuery } from './prepareSql'; import { endTimeSchema, startTimeSchema } from './schemas'; +import { + MAX_SQL_BATCH_QUERIES, + runSqlBatch, + SQL_BATCH_DEADLINE_MS, +} from './sqlBatch'; // ─── Schema ────────────────────────────────────────────────────────────────── @@ -29,8 +33,9 @@ const sqlSchema = z.object({ ), sql: z .string() + .optional() .describe( - 'Raw ClickHouse SQL query. Always include a LIMIT clause to avoid excessive data.\n\n' + + 'Raw ClickHouse SQL query. Use this or queries, not both. Always include a LIMIT clause to avoid excessive data.\n\n' + 'TIME FILTERING (preferred path):\n' + ' $__timeFilter(column) — column >= AND column <= (DateTime precision)\n' + ' $__timeFilter_ms(column) — same with DateTime64 millisecond precision\n' + @@ -65,10 +70,49 @@ const sqlSchema = z.object({ 'AND < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) ' + 'GROUP BY ServiceName ORDER BY n DESC LIMIT 20', ), + queries: z + .array( + z.object({ + id: z + .string() + .min(1) + .max(64) + .optional() + .describe( + "Label echoed back on this query's result. Results also carry their array index.", + ), + sql: z + .string() + .describe( + 'Raw ClickHouse SQL, with the same macros as the sql field.', + ), + connectionId: z + .string() + .optional() + .describe('Overrides the top-level connectionId for this query.'), + sourceId: z + .string() + .optional() + .describe( + 'Overrides the top-level sourceId for this query, so $__sourceTable expands to it.', + ), + }), + ) + .min(1) + .max(MAX_SQL_BATCH_QUERIES) + .optional() + .describe( + `Up to ${MAX_SQL_BATCH_QUERIES} independent queries to run in parallel instead of sql. ` + + 'They share startTime/endTime and default to the top-level connectionId and sourceId.', + ), startTime: startTimeSchema, endTime: endTimeSchema, }); +const SQL_OR_QUERIES_ERROR = + 'Pass exactly one of sql (a single query) or queries (several independent ' + + 'queries run in parallel).'; + // ─── Tool registration ─────────────────────────────────────────────────────── export function registerSql({ context, registerTool }: ToolRegistrar) { @@ -95,7 +139,12 @@ export function registerSql({ context, registerTool }: ToolRegistrar) { '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.', + 'include a time column and ORDER BY it in your SQL.\n\n' + + 'To run several independent queries at once (e.g. comparing sources, or several ' + + 'breakdowns for one investigation), pass queries instead of sql. They run in ' + + `parallel under a shared ${SQL_BATCH_DEADLINE_MS / 1000}s budget, and each result ` + + 'reports its own status (ok, error, or timeout), so one failing query does not ' + + 'fail the others.', inputSchema: sqlSchema, }, async input => { @@ -105,57 +154,46 @@ export function registerSql({ context, registerTool }: ToolRegistrar) { } const { startDate, endDate } = timeRange; - // $__filter / $__conditionalAll read the variables a dashboard's filters - // declare, and this tool has no dashboard behind it. - if (hasVariableMacro(input.sql)) { - return mcpUserError( - 'The $__filter and $__conditionalAll macros only resolve for a tile ' + - 'on a dashboard, because they read the dashboard variables its ' + - 'filters declare. This tool has no dashboard, so they would be ' + - 'sent to ClickHouse as literal text. Inline the condition here, ' + - 'or save the query as a dashboard tile and validate it with ' + - 'clickstack_query_tile.', - ); - } - - 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.', - ); + const { sql, queries } = input; + if (queries !== undefined) { + if (sql !== undefined) { + return mcpUserError(SQL_OR_QUERIES_ERROR); } - } 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.", - ); + trace.getActiveSpan()?.setAttribute('mcp.sql.mode', 'batch'); + return runSqlBatch({ + teamId: teamId.toString(), + queries, + defaults: { + connectionId: input.connectionId, + sourceId: input.sourceId, + }, + startDate, + endDate, + }); } - // 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: 'line' as const, - connectionId: input.connectionId, - sourceId: input.sourceId, - sqlTemplate: input.sql, - }); + if (sql === undefined) { + return mcpUserError(SQL_OR_QUERIES_ERROR); + } + trace.getActiveSpan()?.setAttribute('mcp.sql.mode', 'single'); + const prepared = await prepareSqlQuery( + { + sql, + connectionId: input.connectionId, + sourceId: input.sourceId, + }, + createSourceLookup(teamId.toString()), + ); + if ('error' in prepared) { + return prepared.error; + } - return runConfigTile(teamId.toString(), tile, startDate, endDate); + return runConfigTile( + teamId.toString(), + prepared.tile, + startDate, + endDate, + ); }, ); } diff --git a/packages/api/src/mcp/tools/query/sqlBatch.ts b/packages/api/src/mcp/tools/query/sqlBatch.ts new file mode 100644 index 0000000000..b279161f0e --- /dev/null +++ b/packages/api/src/mcp/tools/query/sqlBatch.ts @@ -0,0 +1,173 @@ +import PQueue from '@esm2cjs/p-queue'; +import { trace } from '@opentelemetry/api'; + +import type { ToolResult } from '@/mcp/tools/types'; +import { mcpUserError } from '@/mcp/utils/errors'; +import { DeadlineExceededError, withDeadline } from '@/mcp/utils/timeout'; +import { getCounter } from '@/utils/instrumentation'; + +import { runConfigTile } from './helpers'; +import { createSourceLookup, prepareSqlQuery } from './prepareSql'; + +export const MAX_SQL_BATCH_QUERIES = 10; + +/** @internal Exported for testing only. */ +export const SQL_BATCH_CONCURRENCY = 5; + +/** + * Whole-call budget shared by every query in the batch. Each query still has + * ClickHouse's own max_execution_time; this bounds the call as a whole so a + * queue of slow queries cannot run past the client's patience. + */ +export const SQL_BATCH_DEADLINE_MS = 60_000; + +/** Total serialized size budget split evenly across the batch's results. */ +const SQL_BATCH_RESPONSE_BUDGET = 100_000; +const SQL_SINGLE_RESPONSE_LIMIT = 50_000; + +const batchQueryCounter = getCounter('hyperdx.mcp.sql.batch.queries', { + description: 'Queries run by clickstack_sql in batch mode, by outcome.', +}); + +export type SqlBatchQuery = { + id?: string; + sql: string; + connectionId?: string; + sourceId?: string; +}; + +type SqlBatchStatus = 'ok' | 'error' | 'timeout'; + +type SqlBatchEntry = { + index: number; + id?: string; + status: SqlBatchStatus; + error?: string; + [key: string]: unknown; +}; + +function textOf(result: ToolResult): string { + const block = result.content?.[0]; + return block?.type === 'text' ? block.text : ''; +} + +/** + * Lift the `{ result, note?, hints? }` payload runConfigTile serialized back + * into an object so it nests in the batch response instead of as a string. + */ +function parsePayload(text: string): Record { + try { + const parsed: unknown = JSON.parse(text); + if ( + parsed != null && + typeof parsed === 'object' && + !Array.isArray(parsed) + ) { + return { ...parsed }; + } + } catch { + // Fall through to the raw text. + } + return { raw: text }; +} + +export async function runSqlBatch({ + teamId, + queries, + defaults, + startDate, + endDate, +}: { + teamId: string; + queries: SqlBatchQuery[]; + defaults: { connectionId: string; sourceId?: string }; + startDate: Date; + endDate: Date; +}): Promise { + const seenIds = new Set(); + for (const { id } of queries) { + if (id === undefined) continue; + if (seenIds.has(id)) { + return mcpUserError( + `Duplicate query id "${id}". Give each query in queries a unique id, or omit it.`, + ); + } + seenIds.add(id); + } + + const maxResponseChars = Math.min( + SQL_SINGLE_RESPONSE_LIMIT, + Math.floor(SQL_BATCH_RESPONSE_BUDGET / queries.length), + ); + const lookupSource = createSourceLookup(teamId); + const queue = new PQueue({ concurrency: SQL_BATCH_CONCURRENCY }); + // Fixed before anything is queued so every query races the same budget. + const deadlineAt = Date.now() + SQL_BATCH_DEADLINE_MS; + + const results = await Promise.all( + queries.map(async (query, index): Promise => { + const base = { + index, + ...(query.id !== undefined ? { id: query.id } : {}), + }; + try { + const prepared = await prepareSqlQuery( + { + sql: query.sql, + connectionId: query.connectionId ?? defaults.connectionId, + sourceId: query.sourceId ?? defaults.sourceId, + }, + lookupSource, + ); + if ('error' in prepared) { + return { ...base, status: 'error', error: textOf(prepared.error) }; + } + + const result: ToolResult = await queue.add(() => + withDeadline( + signal => + runConfigTile(teamId, prepared.tile, startDate, endDate, { + abortSignal: signal, + maxResponseChars, + }), + deadlineAt, + ), + ); + if (result.isError) { + return { ...base, status: 'error', error: textOf(result) }; + } + return { ...base, status: 'ok', ...parsePayload(textOf(result)) }; + } catch (err) { + if (err instanceof DeadlineExceededError) { + return { ...base, status: 'timeout', error: err.message }; + } + return { + ...base, + status: 'error', + error: err instanceof Error ? err.message : String(err), + }; + } + }), + ); + + const summary = { total: results.length, ok: 0, error: 0, timeout: 0 }; + let trimmed = 0; + for (const entry of results) { + summary[entry.status] += 1; + if (entry.note !== undefined) trimmed += 1; + batchQueryCounter.add(1, { status: entry.status }); + } + trace.getActiveSpan()?.setAttributes({ + 'mcp.sql.batch.size': summary.total, + 'mcp.sql.batch.ok': summary.ok, + 'mcp.sql.batch.error': summary.error, + 'mcp.sql.batch.timeout': summary.timeout, + 'mcp.sql.batch.trimmed': trimmed, + }); + + const text = JSON.stringify({ summary, results }, null, 2); + if (summary.ok === 0) { + return mcpUserError(text); + } + return { content: [{ type: 'text', text }] }; +} diff --git a/packages/api/src/mcp/utils/timeout.ts b/packages/api/src/mcp/utils/timeout.ts index 4152435bad..28118c5ef7 100644 --- a/packages/api/src/mcp/utils/timeout.ts +++ b/packages/api/src/mcp/utils/timeout.ts @@ -57,3 +57,40 @@ export async function runWithTimeout( controller.abort(); } } + +/** + * Raised by `withDeadline` both when started work overruns the deadline and + * when the deadline has already passed before the work could start. + */ +export class DeadlineExceededError extends Error { + constructor() { + super('Query exceeded the batch wall-clock deadline'); + this.name = 'DeadlineExceededError'; + } +} + +/** + * Run `startWork` under a SHARED absolute deadline (epoch millis) — every item + * in a batch passes the same `deadlineAt`, making the budget whole-call. + * + * `startWork` is a thunk, not an already-started promise, so the deadline is + * checked BEFORE the query is issued: once the budget is spent, items a queue + * schedules during the drain fail fast without touching ClickHouse. + * + * Work that did start runs under `runWithTimeout`: at the deadline its query + * is cancelled and the call rejects with `DeadlineExceededError`. + */ +export async function withDeadline( + startWork: (signal: AbortSignal) => Promise, + deadlineAt: number, +): Promise { + const remaining = deadlineAt - Date.now(); + if (remaining <= 0) { + throw new DeadlineExceededError(); + } + const outcome = await runWithTimeout(startWork, { timeoutMs: remaining }); + if (outcome.timedOut) { + throw new DeadlineExceededError(); + } + return outcome.value; +} From 1c7c7d79c7719a6699134b5718db05cff41b679d Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Tue, 20 Oct 2026 13:06:41 -0600 Subject: [PATCH 2/3] fix(mcp): enforce batch deadline and response budget in clickstack_sql (greptile P1s) --- .../src/mcp/__tests__/sqlToolBatch.test.ts | 76 ++++++++++- packages/api/src/mcp/tools/query/helpers.ts | 6 +- packages/api/src/mcp/tools/query/sql.ts | 29 +---- packages/api/src/mcp/tools/query/sqlBatch.ts | 120 +++++++++++++++--- 4 files changed, 183 insertions(+), 48 deletions(-) diff --git a/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts b/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts index ca33d1f814..9b98b69d78 100644 --- a/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts +++ b/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts @@ -23,7 +23,11 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import mongoose from 'mongoose'; import { registerSql } from '@/mcp/tools/query/sql'; -import { SQL_BATCH_CONCURRENCY } from '@/mcp/tools/query/sqlBatch'; +import { + SQL_BATCH_CONCURRENCY, + SQL_BATCH_DEADLINE_MS, + SQL_BATCH_RESPONSE_BUDGET, +} from '@/mcp/tools/query/sqlBatch'; import type { McpContext, RegisterToolFn, ToolResult } from '@/mcp/tools/types'; import { mcpUserError } from '@/mcp/utils/errors'; @@ -256,16 +260,84 @@ describe('clickstack_sql batch mode', () => { expect(parsed.results[1].error).toContain('does not match the connection'); }); - it('looks each source up once per call', async () => { + it('looks each source up once per call, including during execution', async () => { await buildHandler()({ connectionId, sourceId, queries: [{ sql: 'SELECT 1' }, { sql: 'SELECT 2' }, { sql: 'SELECT 3' }], }); + // runConfigTile is mocked, so call the lookup it was handed the way the + // real raw SQL path does and check it reuses the cached read. + for (const call of mockRunConfigTile.mock.calls) { + await call[4].lookupSource(sourceId); + } expect(mockGetSource).toHaveBeenCalledTimes(1); }); + it('times out a query whose source lookup outlives the deadline', async () => { + jest.useFakeTimers(); + try { + mockGetSource.mockReturnValue(new Promise(() => {})); + + const pending = buildHandler()({ + connectionId, + queries: [ + { id: 'stuck', sql: 'SELECT 1', sourceId }, + { id: 'free', sql: 'SELECT 2' }, + ], + }); + await jest.advanceTimersByTimeAsync(SQL_BATCH_DEADLINE_MS); + const parsed = JSON.parse(textOf(await pending)); + + expect(parsed.results[0]).toMatchObject({ + id: 'stuck', + status: 'timeout', + }); + expect(parsed.results[1]).toMatchObject({ id: 'free', status: 'ok' }); + } finally { + jest.useRealTimers(); + } + }); + + it('drops rows until the whole response fits the budget', async () => { + // trimToolResponse keeps ten rows per result however large they are, so + // ten such results would blow far past the batch budget on their own. + const bigRow = { body: 'x'.repeat(2_000) }; + mockRunConfigTile.mockResolvedValue({ + content: [ + { + type: 'text' as const, + text: JSON.stringify({ result: { data: Array(10).fill(bigRow) } }), + }, + ], + }); + + const result = await buildHandler()({ + connectionId, + queries: Array.from({ length: 10 }, (_, i) => ({ sql: `SELECT ${i}` })), + }); + + const text = textOf(result); + expect(text.length).toBeLessThanOrEqual(SQL_BATCH_RESPONSE_BUDGET); + const parsed = JSON.parse(text); + expect(parsed.summary.ok).toBe(10); + for (const entry of parsed.results) { + expect(entry.result.data.length).toBeGreaterThan(0); + expect(entry.result.data.length).toBeLessThan(10); + expect(entry.note).toContain('batch response size budget'); + } + }); + + it('leaves results under the budget untouched', async () => { + const result = await buildHandler()({ + connectionId, + queries: [{ sql: 'SELECT 1' }], + }); + + expect(JSON.parse(textOf(result)).results[0].note).toBeUndefined(); + }); + it(`runs at most ${SQL_BATCH_CONCURRENCY} queries at once`, async () => { let inFlight = 0; let peak = 0; diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 51222cc166..dd3dde0d4e 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -423,6 +423,8 @@ export async function runConfigTile( variables?: ChartVariable[]; /** Serialized size the result is trimmed to. Defaults to trimToolResponse's limit. */ maxResponseChars?: number; + /** Source lookup for raw SQL tiles, so a batch can share one per-call cache. */ + lookupSource?: (sourceId: string) => ReturnType; }, ) { if (!isConfigTile(tile)) { @@ -639,7 +641,9 @@ export async function runConfigTile( metricTables?: MetricTable; } = {}; if (savedConfig.source) { - const source = await getSource(teamId, savedConfig.source); + const source = await (options?.lookupSource + ? options.lookupSource(savedConfig.source) + : getSource(teamId, savedConfig.source)); if (source) { sourceFields = { from: source.from, diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts index 28ba753e78..3fb04cbb43 100644 --- a/packages/api/src/mcp/tools/query/sql.ts +++ b/packages/api/src/mcp/tools/query/sql.ts @@ -12,6 +12,7 @@ import { MAX_SQL_BATCH_QUERIES, runSqlBatch, SQL_BATCH_DEADLINE_MS, + sqlBatchQuerySchema, } from './sqlBatch'; // ─── Schema ────────────────────────────────────────────────────────────────── @@ -71,33 +72,7 @@ const sqlSchema = z.object({ 'GROUP BY ServiceName ORDER BY n DESC LIMIT 20', ), queries: z - .array( - z.object({ - id: z - .string() - .min(1) - .max(64) - .optional() - .describe( - "Label echoed back on this query's result. Results also carry their array index.", - ), - sql: z - .string() - .describe( - 'Raw ClickHouse SQL, with the same macros as the sql field.', - ), - connectionId: z - .string() - .optional() - .describe('Overrides the top-level connectionId for this query.'), - sourceId: z - .string() - .optional() - .describe( - 'Overrides the top-level sourceId for this query, so $__sourceTable expands to it.', - ), - }), - ) + .array(sqlBatchQuerySchema) .min(1) .max(MAX_SQL_BATCH_QUERIES) .optional() diff --git a/packages/api/src/mcp/tools/query/sqlBatch.ts b/packages/api/src/mcp/tools/query/sqlBatch.ts index b279161f0e..342cd33367 100644 --- a/packages/api/src/mcp/tools/query/sqlBatch.ts +++ b/packages/api/src/mcp/tools/query/sqlBatch.ts @@ -1,5 +1,6 @@ import PQueue from '@esm2cjs/p-queue'; import { trace } from '@opentelemetry/api'; +import { z } from 'zod'; import type { ToolResult } from '@/mcp/tools/types'; import { mcpUserError } from '@/mcp/utils/errors'; @@ -21,20 +22,47 @@ export const SQL_BATCH_CONCURRENCY = 5; */ export const SQL_BATCH_DEADLINE_MS = 60_000; -/** Total serialized size budget split evenly across the batch's results. */ -const SQL_BATCH_RESPONSE_BUDGET = 100_000; +/** + * Serialized size budget for the whole batch response. It is split evenly + * across queries up front, then enforced on the final payload, because + * trimToolResponse keeps at least ten rows per result whatever their size. + */ +export const SQL_BATCH_RESPONSE_BUDGET = 100_000; const SQL_SINGLE_RESPONSE_LIMIT = 50_000; const batchQueryCounter = getCounter('hyperdx.mcp.sql.batch.queries', { description: 'Queries run by clickstack_sql in batch mode, by outcome.', }); -export type SqlBatchQuery = { - id?: string; - sql: string; - connectionId?: string; - sourceId?: string; -}; +const BATCH_TRIM_NOTE = + 'Rows were dropped to fit the batch response size budget. Narrow the time ' + + 'range, add filters, or run fewer queries per call.'; + +export const sqlBatchQuerySchema = z.object({ + id: z + .string() + .min(1) + .max(64) + .optional() + .describe( + "Label echoed back on this query's result. Results also carry their array index.", + ), + sql: z + .string() + .describe('Raw ClickHouse SQL, with the same macros as the sql field.'), + connectionId: z + .string() + .optional() + .describe('Overrides the top-level connectionId for this query.'), + sourceId: z + .string() + .optional() + .describe( + 'Overrides the top-level sourceId for this query, so $__sourceTable expands to it.', + ), +}); + +export type SqlBatchQuery = z.infer; type SqlBatchStatus = 'ok' | 'error' | 'timeout'; @@ -71,6 +99,56 @@ function parsePayload(text: string): Record { return { raw: text }; } +/** The row array of an ok entry: `result` itself, or ClickHouse's `result.data`. */ +function rowsOf(entry: SqlBatchEntry): unknown[] | undefined { + const { result } = entry; + if (Array.isArray(result)) return result; + if ( + result != null && + typeof result === 'object' && + 'data' in result && + Array.isArray(result.data) + ) { + return result.data; + } + return undefined; +} + +function setRows(entry: SqlBatchEntry, rows: unknown[]) { + const { result } = entry; + entry.result = + result != null && typeof result === 'object' && !Array.isArray(result) + ? { ...result, data: rows } + : rows; + entry.note = BATCH_TRIM_NOTE; +} + +/** + * Halve the rows of the largest result until the serialized payload fits the + * budget, or no rows are left to drop. + */ +function fitToBudget( + payload: { results: SqlBatchEntry[] }, + budget: number, +): void { + const sizeOf = (value: unknown) => JSON.stringify(value, null, 2).length; + while (sizeOf(payload) > budget) { + let target: SqlBatchEntry | undefined; + let targetSize = 0; + for (const entry of payload.results) { + if (!rowsOf(entry)?.length) continue; + const size = sizeOf(entry); + if (size > targetSize) { + target = entry; + targetSize = size; + } + } + if (!target) return; + const rows = rowsOf(target) ?? []; + setRows(target, rows.slice(0, Math.floor(rows.length / 2))); + } +} + export async function runSqlBatch({ teamId, queries, @@ -111,13 +189,17 @@ export async function runSqlBatch({ ...(query.id !== undefined ? { id: query.id } : {}), }; try { - const prepared = await prepareSqlQuery( - { - sql: query.sql, - connectionId: query.connectionId ?? defaults.connectionId, - sourceId: query.sourceId ?? defaults.sourceId, - }, - lookupSource, + const prepared = await withDeadline( + () => + prepareSqlQuery( + { + sql: query.sql, + connectionId: query.connectionId ?? defaults.connectionId, + sourceId: query.sourceId ?? defaults.sourceId, + }, + lookupSource, + ), + deadlineAt, ); if ('error' in prepared) { return { ...base, status: 'error', error: textOf(prepared.error) }; @@ -129,6 +211,7 @@ export async function runSqlBatch({ runConfigTile(teamId, prepared.tile, startDate, endDate, { abortSignal: signal, maxResponseChars, + lookupSource, }), deadlineAt, ), @@ -151,12 +234,13 @@ export async function runSqlBatch({ ); const summary = { total: results.length, ok: 0, error: 0, timeout: 0 }; - let trimmed = 0; for (const entry of results) { summary[entry.status] += 1; - if (entry.note !== undefined) trimmed += 1; batchQueryCounter.add(1, { status: entry.status }); } + const payload = { summary, results }; + fitToBudget(payload, SQL_BATCH_RESPONSE_BUDGET); + const trimmed = results.filter(entry => entry.note !== undefined).length; trace.getActiveSpan()?.setAttributes({ 'mcp.sql.batch.size': summary.total, 'mcp.sql.batch.ok': summary.ok, @@ -165,7 +249,7 @@ export async function runSqlBatch({ 'mcp.sql.batch.trimmed': trimmed, }); - const text = JSON.stringify({ summary, results }, null, 2); + const text = JSON.stringify(payload, null, 2); if (summary.ok === 0) { return mcpUserError(text); } From e9f6c78616b77f3d82fae7ca628d10c42724e73c Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Tue, 20 Oct 2026 13:16:49 -0600 Subject: [PATCH 3/3] fix(mcp): don't inherit the top-level sourceId across a connectionId override --- .../src/mcp/__tests__/sqlToolBatch.test.ts | 20 +++++++++++++++---- packages/api/src/mcp/tools/query/sqlBatch.ts | 13 ++++++++++-- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts b/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts index 9b98b69d78..0b3be1b1e7 100644 --- a/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts +++ b/packages/api/src/mcp/__tests__/sqlToolBatch.test.ts @@ -244,7 +244,7 @@ describe('clickstack_sql batch mode', () => { ]); }); - it('flags a connection override that conflicts with the inherited source', async () => { + it('does not inherit the top-level sourceId when a query overrides connectionId', async () => { const result = await buildHandler()({ connectionId, sourceId, @@ -255,9 +255,21 @@ describe('clickstack_sql batch mode', () => { }); const parsed = JSON.parse(textOf(result)); - expect(parsed.results[0].status).toBe('ok'); - expect(parsed.results[1].status).toBe('error'); - expect(parsed.results[1].error).toContain('does not match the connection'); + expect(parsed.summary.ok).toBe(2); + const overridden = tileArgs().find(c => c.sqlTemplate === 'SELECT 2'); + expect(overridden?.connectionId).toBe(otherConnectionId); + expect(overridden?.sourceId).toBeUndefined(); + }); + + it('flags an explicit source on a different connection', async () => { + const result = await buildHandler()({ + connectionId, + queries: [{ sql: 'SELECT 1', connectionId: otherConnectionId, sourceId }], + }); + + const parsed = JSON.parse(textOf(result)); + expect(parsed.results[0].status).toBe('error'); + expect(parsed.results[0].error).toContain('does not match the connection'); }); it('looks each source up once per call, including during execution', async () => { diff --git a/packages/api/src/mcp/tools/query/sqlBatch.ts b/packages/api/src/mcp/tools/query/sqlBatch.ts index 342cd33367..83c449d5fe 100644 --- a/packages/api/src/mcp/tools/query/sqlBatch.ts +++ b/packages/api/src/mcp/tools/query/sqlBatch.ts @@ -53,7 +53,10 @@ export const sqlBatchQuerySchema = z.object({ connectionId: z .string() .optional() - .describe('Overrides the top-level connectionId for this query.'), + .describe( + 'Overrides the top-level connectionId for this query. A query that sets it ' + + 'does not inherit the top-level sourceId.', + ), sourceId: z .string() .optional() @@ -195,7 +198,13 @@ export async function runSqlBatch({ { sql: query.sql, connectionId: query.connectionId ?? defaults.connectionId, - sourceId: query.sourceId ?? defaults.sourceId, + // The top-level source belongs to the top-level connection, so a + // query on another connection must not inherit it. + sourceId: + query.sourceId ?? + (query.connectionId === undefined + ? defaults.sourceId + : undefined), }, lookupSource, ),