diff --git a/packages/api/src/mcp/__tests__/clickhouseClient.test.ts b/packages/api/src/mcp/__tests__/clickhouseClient.test.ts new file mode 100644 index 0000000000..99419614a6 --- /dev/null +++ b/packages/api/src/mcp/__tests__/clickhouseClient.test.ts @@ -0,0 +1,76 @@ +const mockGetConnectionById = jest.fn(); +const mockClickhouseClient = jest.fn(); + +jest.mock('@/controllers/connection', () => ({ + getConnectionById: (...args: unknown[]) => mockGetConnectionById(...args), +})); +jest.mock('@/clickhouse', () => ({ ClickhouseClient: mockClickhouseClient })); + +import type { McpContext } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; + +const context: McpContext = { teamId: 'team-1', userId: 'user-1' }; +const connection = { + host: 'http://ch:8123', + username: 'default', + password: 'secret', +}; + +describe('getMcpClickhouseClient', () => { + beforeEach(() => { + jest.clearAllMocks(); + }); + + it('looks the connection up for the calling team, with its password', async () => { + mockGetConnectionById.mockResolvedValue(connection); + + const client = await getMcpClickhouseClient(context, 'conn-1'); + + expect(mockGetConnectionById).toHaveBeenCalledWith( + 'team-1', + 'conn-1', + true, + ); + expect(client).toBe(mockClickhouseClient.mock.instances[0]); + expect(mockClickhouseClient.mock.calls[0][0]).toStrictEqual({ + host: 'http://ch:8123', + username: 'default', + password: 'secret', + }); + }); + + it('passes requestTimeout through to the client', async () => { + mockGetConnectionById.mockResolvedValue(connection); + + await getMcpClickhouseClient(context, 'conn-1', { requestTimeout: 5000 }); + + expect(mockClickhouseClient.mock.calls[0][0]).toStrictEqual({ + host: 'http://ch:8123', + username: 'default', + password: 'secret', + requestTimeout: 5000, + }); + }); + + it('throws McpConnectionNotFoundError when the team has no such connection', async () => { + mockGetConnectionById.mockResolvedValue(null); + + const result = getMcpClickhouseClient(context, 'conn-1'); + + await expect(result).rejects.toBeInstanceOf(McpConnectionNotFoundError); + await expect(result).rejects.toMatchObject({ connectionId: 'conn-1' }); + expect(mockClickhouseClient).not.toHaveBeenCalled(); + }); + + it('propagates lookup failures unchanged', async () => { + const failure = new Error('db down'); + mockGetConnectionById.mockRejectedValue(failure); + + await expect(getMcpClickhouseClient(context, 'conn-1')).rejects.toBe( + failure, + ); + }); +}); diff --git a/packages/api/src/mcp/__tests__/dashboards/queryTilesHandler.test.ts b/packages/api/src/mcp/__tests__/dashboards/queryTilesHandler.test.ts index 597ef883cf..8834085252 100644 --- a/packages/api/src/mcp/__tests__/dashboards/queryTilesHandler.test.ts +++ b/packages/api/src/mcp/__tests__/dashboards/queryTilesHandler.test.ts @@ -214,7 +214,7 @@ describe('clickstack_query_tiles handler — dashboard variables', () => { }); expect(mockRunConfigTile).toHaveBeenCalledWith( - 'team-1', + expect.objectContaining({ teamId: 'team-1' }), expect.objectContaining({ id: 't1' }), expect.any(Date), expect.any(Date), @@ -239,7 +239,7 @@ describe('clickstack_query_tiles handler — dashboard variables', () => { }); expect(mockRunConfigTile).toHaveBeenCalledWith( - 'team-1', + expect.objectContaining({ teamId: 'team-1' }), expect.anything(), expect.any(Date), expect.any(Date), diff --git a/packages/api/src/mcp/tools/dashboards/queryTile.ts b/packages/api/src/mcp/tools/dashboards/queryTile.ts index 1e610b0cd3..1589353f98 100644 --- a/packages/api/src/mcp/tools/dashboards/queryTile.ts +++ b/packages/api/src/mcp/tools/dashboards/queryTile.ts @@ -111,13 +111,9 @@ export function registerQueryTile({ } const { tile } = resolvedTile; - const result = await runConfigTile( - teamId.toString(), - tile, - startDate, - endDate, - { variables: resolvedVariables.variables }, - ); + const result = await runConfigTile(context, tile, startDate, endDate, { + variables: resolvedVariables.variables, + }); // Surface non-blocking missing macro and variable warnings alongside // the successful result so the agent can spot a tile that runs but diff --git a/packages/api/src/mcp/tools/dashboards/queryTiles.ts b/packages/api/src/mcp/tools/dashboards/queryTiles.ts index a1716461f2..297932f981 100644 --- a/packages/api/src/mcp/tools/dashboards/queryTiles.ts +++ b/packages/api/src/mcp/tools/dashboards/queryTiles.ts @@ -282,7 +282,7 @@ export function registerQueryTiles({ const result = await withDeadline( signal => runConfigTile( - teamId.toString(), + context, resolvedTile.tile, startDate, endDate, diff --git a/packages/api/src/mcp/tools/query/denoise.ts b/packages/api/src/mcp/tools/query/denoise.ts index 2465ef766f..7c6aacf5b1 100644 --- a/packages/api/src/mcp/tools/query/denoise.ts +++ b/packages/api/src/mcp/tools/query/denoise.ts @@ -9,9 +9,13 @@ import { import type { ChartConfigWithDateRange } from '@hyperdx/common-utils/dist/types'; import { DisplayType } from '@hyperdx/common-utils/dist/types'; -import { ClickhouseClient } from '@/clickhouse'; -import { getConnectionById } from '@/controllers/connection'; +import type { ClickhouseClient } from '@/clickhouse'; import { getSource } from '@/controllers/sources'; +import type { McpContext } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { MCP_QUERY_MAX_EXECUTION_SEC } from '@/mcp/utils/timeout'; import { resolveBodyExpression } from './helpers'; @@ -46,7 +50,7 @@ export interface DenoiseResult { * the shared TypeScript Drain implementation. */ export async function denoiseSearchResults( - teamId: string, + context: McpContext, sourceId: string, startDate: Date, endDate: Date, @@ -61,7 +65,7 @@ export async function denoiseSearchResults( } // ── Resolve source & connection ── - const source = await getSource(teamId, sourceId); + const source = await getSource(context.teamId, sourceId); if (!source) { return { rows, removedPatterns: [], skipped: 'source_not_found' }; } @@ -71,20 +75,16 @@ export async function denoiseSearchResults( return { rows, removedPatterns: [], skipped: 'no_body_column' }; } - const connection = await getConnectionById( - teamId, - source.connection.toString(), - true, - ); - if (!connection) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + source.connection.toString(), + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return { rows, removedPatterns: [], skipped: 'connection_not_found' }; } - - const clickhouseClient = new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - }); const metadata = getMetadata(clickhouseClient); const tsExpr = getFirstTimestampValueExpression( diff --git a/packages/api/src/mcp/tools/query/emergingSignals.ts b/packages/api/src/mcp/tools/query/emergingSignals.ts index be00d96371..b6dbe559e3 100644 --- a/packages/api/src/mcp/tools/query/emergingSignals.ts +++ b/packages/api/src/mcp/tools/query/emergingSignals.ts @@ -139,8 +139,6 @@ export function registerEmergingSignals({ context, registerTool, }: ToolRegistrar) { - const { teamId } = context; - registerTool( 'clickstack_emerging_signals', { @@ -210,14 +208,14 @@ export function registerEmergingSignals({ const [curRes, baseRes] = await Promise.all([ mineWindowPatterns( - teamId.toString(), + context, input.sourceId, cur.startDate, cur.endDate, opts, ), mineWindowPatterns( - teamId.toString(), + context, input.sourceId, base.startDate, base.endDate, diff --git a/packages/api/src/mcp/tools/query/eventDeltas.ts b/packages/api/src/mcp/tools/query/eventDeltas.ts index 603267551c..94ac4d32ef 100644 --- a/packages/api/src/mcp/tools/query/eventDeltas.ts +++ b/packages/api/src/mcp/tools/query/eventDeltas.ts @@ -11,11 +11,14 @@ import { } from '@hyperdx/common-utils/dist/types'; import { z } from 'zod'; -import { ClickhouseClient } from '@/clickhouse'; -import { getConnectionById } from '@/controllers/connection'; +import type { ClickhouseClient } from '@/clickhouse'; import { getSource } from '@/controllers/sources'; import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import type { ToolRegistrar } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { mcpUserError } from '@/mcp/utils/errors'; import { MCP_QUERY_MAX_EXECUTION_SEC } from '@/mcp/utils/timeout'; import { trimToolResponse } from '@/utils/trimToolResponse'; @@ -251,22 +254,18 @@ export function registerEventDeltas({ context, registerTool }: ToolRegistrar) { ); } - const connection = await getConnectionById( - teamId.toString(), - source.connection.toString(), - true, - ); - if (!connection) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + source.connection.toString(), + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError( `Connection not found for source: ${input.sourceId}`, ); } - - const clickhouseClient = new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - }); const metadata = getMetadata(clickhouseClient); // Build a stable per-source ORDER BY for sampling (matches what the diff --git a/packages/api/src/mcp/tools/query/eventPatterns.ts b/packages/api/src/mcp/tools/query/eventPatterns.ts index 6e09c127c5..4681c6b34a 100644 --- a/packages/api/src/mcp/tools/query/eventPatterns.ts +++ b/packages/api/src/mcp/tools/query/eventPatterns.ts @@ -76,8 +76,6 @@ export function registerEventPatterns({ context, registerTool, }: ToolRegistrar) { - const { teamId } = context; - registerTool( 'clickstack_event_patterns', { @@ -115,20 +113,14 @@ export function registerEventPatterns({ } const { startDate, endDate } = timeRange; - return runEventPatterns( - teamId.toString(), - input.sourceId, - startDate, - endDate, - { - where: input.where, - whereLanguage: input.whereLanguage, - bodyExpression: input.bodyExpression, - sampleSize: input.sampleSize, - topN: input.topN, - trendBuckets: input.trendBuckets, - }, - ); + return runEventPatterns(context, input.sourceId, startDate, endDate, { + where: input.where, + whereLanguage: input.whereLanguage, + bodyExpression: input.bodyExpression, + sampleSize: input.sampleSize, + topN: input.topN, + trendBuckets: input.trendBuckets, + }); }, ); } diff --git a/packages/api/src/mcp/tools/query/helpers.ts b/packages/api/src/mcp/tools/query/helpers.ts index 748eb062fd..526c6e32ed 100644 --- a/packages/api/src/mcp/tools/query/helpers.ts +++ b/packages/api/src/mcp/tools/query/helpers.ts @@ -26,10 +26,14 @@ import { import { ObjectId } from 'mongodb'; import ms from 'ms'; -import { ClickhouseClient } from '@/clickhouse'; -import { getConnectionById } from '@/controllers/connection'; +import type { ClickhouseClient } from '@/clickhouse'; import { PromQLQueryError } from '@/controllers/promql'; import { getSource } from '@/controllers/sources'; +import type { McpContext } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import type { McpErrorResult } from '@/mcp/utils/errors'; import { mcpServerError, mcpUserError } from '@/mcp/utils/errors'; import { @@ -489,7 +493,7 @@ function toPlainMetricTables( } export async function runConfigTile( - teamId: string, + context: McpContext, tile: ExternalDashboardTileWithId, startDate: Date, endDate: Date, @@ -514,6 +518,7 @@ export async function runConfigTile( partialSearchResults?: boolean; }, ) { + const { teamId } = context; if (!isConfigTile(tile)) { return mcpUserError('Invalid tile: config field missing'); } @@ -545,7 +550,7 @@ export async function runConfigTile( const selectStr = typeof builderConfig.select === 'string' ? builderConfig.select : ''; return runEventPatterns( - teamId, + context, builderConfig.source, startDate, endDate, @@ -579,24 +584,20 @@ export async function runConfigTile( ); if (kindMismatch) return kindMismatch; - const connection = await getConnectionById( - teamId, - source.connection.toString(), - true, - ); - if (!connection) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + source.connection.toString(), + { requestTimeout: MCP_REQUEST_TIMEOUT }, + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError( `Connection not found for source: ${builderConfig.source}`, ); } - const clickhouseClient = new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - requestTimeout: MCP_REQUEST_TIMEOUT, - }); - const isSearch = builderConfig.displayType === DisplayType.Search; const isMetricSource = source.kind === SourceKind.Metric; const defaultTableSelect = @@ -802,24 +803,20 @@ export async function runConfigTile( } } - const connection = await getConnectionById( - teamId, - savedConfig.connection, - true, - ); - if (!connection) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + savedConfig.connection, + { requestTimeout: MCP_REQUEST_TIMEOUT }, + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError( `Connection not found: ${savedConfig.connection}. Call clickstack_list_sources to discover available connection IDs.`, ); } - const clickhouseClient = new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - requestTimeout: MCP_REQUEST_TIMEOUT, - }); - const chartConfig = { ...savedConfig, ...sourceFields, diff --git a/packages/api/src/mcp/tools/query/promql.ts b/packages/api/src/mcp/tools/query/promql.ts index d704a67f6a..a5142f9d0c 100644 --- a/packages/api/src/mcp/tools/query/promql.ts +++ b/packages/api/src/mcp/tools/query/promql.ts @@ -49,8 +49,6 @@ const promqlSchema = z.object({ // ─── Tool registration ─────────────────────────────────────────────────────── export function registerPromql({ context, registerTool }: ToolRegistrar) { - const { teamId } = context; - registerTool( 'clickstack_promql', { @@ -107,7 +105,7 @@ export function registerPromql({ context, registerTool }: ToolRegistrar) { granularity: input.granularity, }); - return runConfigTile(teamId.toString(), tile, startDate, endDate); + return runConfigTile(context, tile, startDate, endDate); }, ); } diff --git a/packages/api/src/mcp/tools/query/runEventPatterns.ts b/packages/api/src/mcp/tools/query/runEventPatterns.ts index a6d6fbb507..7791ffd76b 100644 --- a/packages/api/src/mcp/tools/query/runEventPatterns.ts +++ b/packages/api/src/mcp/tools/query/runEventPatterns.ts @@ -19,9 +19,13 @@ import type { import { DisplayType, SourceKind } from '@hyperdx/common-utils/dist/types'; import { trace } from '@opentelemetry/api'; -import { ClickhouseClient } from '@/clickhouse'; -import { getConnectionById } from '@/controllers/connection'; +import type { ClickhouseClient } from '@/clickhouse'; import { getSource } from '@/controllers/sources'; +import type { McpContext } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { type McpErrorResult, mcpServerError, @@ -61,7 +65,7 @@ const drilldownWhereFailedCounter = getCounter( * Returns either an error result (MCP shape) or the mined patterns. */ export async function mineWindowPatterns( - teamId: string, + context: McpContext, sourceId: string, startDate: Date, endDate: Date, @@ -96,6 +100,7 @@ export async function mineWindowPatterns( drilldown?: { where: string; includesUserFilter: boolean }; } > { + const { teamId } = context; const sampleSize = options?.sampleSize ?? 10_000; const trendBuckets = options?.trendBuckets ?? 0; @@ -107,12 +112,14 @@ export async function mineWindowPatterns( ), }; } - const connection = await getConnectionById( - teamId, - source.connection.toString(), - true, - ); - if (!connection) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + source.connection.toString(), + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return { error: mcpUserError( `Connection not found for source: ${sourceId}. Call clickstack_list_sources to discover available source IDs.`, @@ -158,11 +165,6 @@ export async function mineWindowPatterns( ...filters.map(f => ('condition' in f ? f.condition : undefined)), ); - const clickhouseClient = new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - }); const metadata = getMetadata(clickhouseClient); const tsExpr = getFirstTimestampValueExpression( source.timestampValueExpression, @@ -384,7 +386,7 @@ export const EVENT_PATTERNS_REDUCTIONS: Reduction[] = [ ]; export async function runEventPatterns( - teamId: string, + context: McpContext, sourceId: string, startDate: Date, endDate: Date, @@ -412,16 +414,22 @@ export async function runEventPatterns( // conversion, sampleMultiplier usage). The helper wraps minePatterns in // try/catch and returns an {error} union, so a thrown Drain error surfaces as // a clean MCP error here rather than escaping. - const mined = await mineWindowPatterns(teamId, sourceId, startDate, endDate, { - where: options?.where, - whereLanguage: options?.whereLanguage, - bodyExpression: options?.bodyExpression, - sampleSize: options?.sampleSize, - trendBuckets, - abortSignal: options?.abortSignal, - variables: options?.variables, - includeDrilldownWhere: true, - }); + const mined = await mineWindowPatterns( + context, + sourceId, + startDate, + endDate, + { + where: options?.where, + whereLanguage: options?.whereLanguage, + bodyExpression: options?.bodyExpression, + sampleSize: options?.sampleSize, + trendBuckets, + abortSignal: options?.abortSignal, + variables: options?.variables, + includeDrilldownWhere: true, + }, + ); if ('error' in mined) return mined.error; const { diff --git a/packages/api/src/mcp/tools/query/search.ts b/packages/api/src/mcp/tools/query/search.ts index 6b4002dba5..6c2cc2346a 100644 --- a/packages/api/src/mcp/tools/query/search.ts +++ b/packages/api/src/mcp/tools/query/search.ts @@ -58,8 +58,6 @@ const searchSchema = z.object({ // ─── Tool registration ─────────────────────────────────────────────────────── export function registerSearch({ context, registerTool }: ToolRegistrar) { - const { teamId } = context; - registerTool( 'clickstack_search', { @@ -98,16 +96,10 @@ export function registerSearch({ context, registerTool }: ToolRegistrar) { whereLanguage: input.whereLanguage, }); - const result = await runConfigTile( - teamId.toString(), - tile, - startDate, - endDate, - { - maxResults: input.maxResults, - partialSearchResults: true, - }, - ); + const result = await runConfigTile(context, tile, startDate, endDate, { + maxResults: input.maxResults, + partialSearchResults: true, + }); // ── Denoising post-processing ── if (!input.denoise || ('isError' in result && result.isError)) { @@ -159,7 +151,7 @@ export function registerSearch({ context, registerTool }: ToolRegistrar) { let denoised; try { denoised = await denoiseSearchResults( - teamId.toString(), + context, input.sourceId, denoiseStartDate, endDate, diff --git a/packages/api/src/mcp/tools/query/serviceHealth/index.ts b/packages/api/src/mcp/tools/query/serviceHealth/index.ts index 85cd563429..078aa79e63 100644 --- a/packages/api/src/mcp/tools/query/serviceHealth/index.ts +++ b/packages/api/src/mcp/tools/query/serviceHealth/index.ts @@ -2,15 +2,20 @@ import { getMetadata } from '@hyperdx/common-utils/dist/core/metadata'; import { splitAndTrimWithBracket } from '@hyperdx/common-utils/dist/core/utils'; import { trace } from '@opentelemetry/api'; +import type { ClickhouseClient } from '@/clickhouse'; import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import { PREFER_BUILDER_OVER_SQL_NUDGE } from '@/mcp/tools/query/builderCatalog'; import { clickHouseErrorResult, isQueryOutOfTime, + MCP_REQUEST_TIMEOUT, parseTimeRange, } from '@/mcp/tools/query/helpers'; -import { getMcpClickhouseClient } from '@/mcp/tools/trace/shared'; import type { ToolRegistrar } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { mcpUserError } from '@/mcp/utils/errors'; import { trimToolResponse } from '@/utils/trimToolResponse'; @@ -92,8 +97,13 @@ export function registerServiceHealth({ const source = await loadHealthSource(teamId, input.sourceId, TOOL_NAME); if ('isError' in source) return source; - const client = await getMcpClickhouseClient(teamId, source.connection); - if (!client) { + let client: ClickhouseClient; + try { + client = await getMcpClickhouseClient(context, source.connection, { + requestTimeout: MCP_REQUEST_TIMEOUT, + }); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError( `Connection not found for source: ${input.sourceId}`, ); diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts index 82a33f7a8a..ccf8d2c729 100644 --- a/packages/api/src/mcp/tools/query/sql.ts +++ b/packages/api/src/mcp/tools/query/sql.ts @@ -137,7 +137,7 @@ export function registerSql({ context, registerTool }: ToolRegistrar) { } trace.getActiveSpan()?.setAttribute('mcp.sql.mode', 'batch'); return runSqlBatch({ - teamId: teamId.toString(), + context, queries, defaults: { connectionId: input.connectionId, @@ -164,12 +164,7 @@ export function registerSql({ context, registerTool }: ToolRegistrar) { return prepared.error; } - return runConfigTile( - teamId.toString(), - prepared.tile, - startDate, - endDate, - ); + return runConfigTile(context, prepared.tile, startDate, endDate); }, ); } diff --git a/packages/api/src/mcp/tools/query/sqlBatch.ts b/packages/api/src/mcp/tools/query/sqlBatch.ts index 9c68c6966b..8ec5578dec 100644 --- a/packages/api/src/mcp/tools/query/sqlBatch.ts +++ b/packages/api/src/mcp/tools/query/sqlBatch.ts @@ -2,7 +2,7 @@ import PQueue from '@esm2cjs/p-queue'; import { trace } from '@opentelemetry/api'; import { z } from 'zod'; -import type { ToolResult } from '@/mcp/tools/types'; +import type { McpContext, ToolResult } from '@/mcp/tools/types'; import { mcpUserError } from '@/mcp/utils/errors'; import { DeadlineExceededError, withDeadline } from '@/mcp/utils/timeout'; import { getCounter } from '@/utils/instrumentation'; @@ -158,13 +158,13 @@ function fitToBudget( } export async function runSqlBatch({ - teamId, + context, queries, defaults, startDate, endDate, }: { - teamId: string; + context: McpContext; queries: SqlBatchQuery[]; defaults: { connectionId: string; sourceId?: string }; startDate: Date; @@ -185,7 +185,7 @@ export async function runSqlBatch({ SQL_SINGLE_RESPONSE_LIMIT, Math.floor(SQL_BATCH_RESPONSE_BUDGET / queries.length), ); - const lookupSource = createSourceLookup(teamId); + const lookupSource = createSourceLookup(context.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; @@ -222,7 +222,7 @@ export async function runSqlBatch({ const result: ToolResult = await queue.add(() => withDeadline( signal => - runConfigTile(teamId, prepared.tile, startDate, endDate, { + runConfigTile(context, prepared.tile, startDate, endDate, { abortSignal: signal, maxResponseChars, lookupSource, diff --git a/packages/api/src/mcp/tools/query/table.ts b/packages/api/src/mcp/tools/query/table.ts index 5c1a1f035f..f3fa79fe3a 100644 --- a/packages/api/src/mcp/tools/query/table.ts +++ b/packages/api/src/mcp/tools/query/table.ts @@ -256,8 +256,6 @@ export function defaultOrderBy( // ─── Tool registration ─────────────────────────────────────────────────────── export function registerTable({ context, registerTool }: ToolRegistrar) { - const { teamId } = context; - registerTool( 'clickstack_table', { @@ -338,13 +336,10 @@ export function registerTable({ context, registerTool }: ToolRegistrar) { defaultOrderBy(selectItems, groupBy, displayType), }); - const result = await runConfigTile( - teamId.toString(), - tile, - startDate, - endDate, - { having: input.having, limit: input.limit }, - ); + const result = await runConfigTile(context, tile, startDate, endDate, { + having: input.having, + limit: input.limit, + }); // Surface language-mismatch warnings so the agent knows the top-level // where was not applied to every select item. diff --git a/packages/api/src/mcp/tools/query/timeseries.ts b/packages/api/src/mcp/tools/query/timeseries.ts index 32e75268fb..fe8897f539 100644 --- a/packages/api/src/mcp/tools/query/timeseries.ts +++ b/packages/api/src/mcp/tools/query/timeseries.ts @@ -72,8 +72,6 @@ const timeseriesSchema = z.object({ // ─── Tool registration ─────────────────────────────────────────────────────── export function registerTimeseries({ context, registerTool }: ToolRegistrar) { - const { teamId } = context; - registerTool( 'clickstack_timeseries', { @@ -144,13 +142,9 @@ export function registerTimeseries({ context, registerTool }: ToolRegistrar) { ...(input.granularity ? { granularity: input.granularity } : {}), }); - const result = await runConfigTile( - teamId.toString(), - tile, - startDate, - endDate, - { granularity: input.granularity }, - ); + const result = await runConfigTile(context, tile, startDate, endDate, { + granularity: input.granularity, + }); // Surface language-mismatch warnings so the agent knows the top-level // where was not applied to every select item. diff --git a/packages/api/src/mcp/tools/sources/describeMetric.ts b/packages/api/src/mcp/tools/sources/describeMetric.ts index b4818f51af..cf4c83df63 100644 --- a/packages/api/src/mcp/tools/sources/describeMetric.ts +++ b/packages/api/src/mcp/tools/sources/describeMetric.ts @@ -10,15 +10,18 @@ import { getMetadata } from '@hyperdx/common-utils/dist/core/metadata'; import { SourceKind } from '@hyperdx/common-utils/dist/types'; import { z } from 'zod'; -import { ClickhouseClient } from '@/clickhouse'; -import { getConnectionById } from '@/controllers/connection'; +import type { ClickhouseClient } from '@/clickhouse'; import { getSource } from '@/controllers/sources'; import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import { clickHouseErrorResult, parseTimeRange, } from '@/mcp/tools/query/helpers'; -import type { ToolRegistrar } from '@/mcp/tools/types'; +import type { McpContext, ToolRegistrar } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { mcpServerError, mcpUserError, @@ -468,10 +471,11 @@ async function sampleAttributeValues({ } async function describeMetricImpl( - teamId: string, + context: McpContext, input: z.infer, signal: AbortSignal, ) { + const { teamId } = context; const source = await getSource(teamId, input.sourceId); if (!source) { return mcpUserError( @@ -494,20 +498,16 @@ async function describeMetricImpl( } const { startDate, endDate } = timeRange; - const connection = await getConnectionById( - teamId, - source.connection.toString(), - true, - ); - if (!connection) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + source.connection.toString(), + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError(`Connection not found for source "${input.sourceId}".`); } - - const clickhouseClient = new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - }); const metadata = getMetadata(clickhouseClient); const databaseName = source.from.databaseName; const connectionId = source.connection.toString(); @@ -746,7 +746,7 @@ export function registerDescribeMetric({ // the typed shape we need for downstream calls. const input = describeMetricSchema.parse(rawInput); const outcome = await runWithTimeout( - signal => describeMetricImpl(teamId.toString(), input, signal), + signal => describeMetricImpl(context, input, signal), { timeoutMs: DESCRIBE_TIMEOUT_MS }, ); if (!outcome.timedOut) { diff --git a/packages/api/src/mcp/tools/sources/describeSource.ts b/packages/api/src/mcp/tools/sources/describeSource.ts index c096429d32..b12caa23f5 100644 --- a/packages/api/src/mcp/tools/sources/describeSource.ts +++ b/packages/api/src/mcp/tools/sources/describeSource.ts @@ -12,11 +12,14 @@ import { trace } from '@opentelemetry/api'; import SqlString from 'sqlstring'; import { z } from 'zod'; -import { ClickhouseClient } from '@/clickhouse'; -import { getConnectionById } from '@/controllers/connection'; +import type { ClickhouseClient } from '@/clickhouse'; import { getSource } from '@/controllers/sources'; import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import type { McpContext, ToolRegistrar, ToolResult } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { mcpServerError, mcpUserError } from '@/mcp/utils/errors'; import { isHiddenSource } from '@/mcp/utils/promql'; import { @@ -203,20 +206,16 @@ async function describeSourceSchema( }; } - const connection = await getConnectionById( - teamId, - source.connection.toString(), - true, - ); - if (!connection) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + source.connection.toString(), + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError(`Connection not found for source "${sourceId}".`); } - - const clickhouseClient = new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - }); const metadata = getMetadata(clickhouseClient); const databaseName = source.from.databaseName; const tableName = discoveryTableName; diff --git a/packages/api/src/mcp/tools/sources/describeTable.ts b/packages/api/src/mcp/tools/sources/describeTable.ts index 63290a75f1..221d50c40f 100644 --- a/packages/api/src/mcp/tools/sources/describeTable.ts +++ b/packages/api/src/mcp/tools/sources/describeTable.ts @@ -2,8 +2,7 @@ import { quoteIdentifierIfNeeded } from '@hyperdx/common-utils/dist/core/metadat import { SourceKind } from '@hyperdx/common-utils/dist/types'; import { trace } from '@opentelemetry/api'; -import { ClickhouseClient } from '@/clickhouse'; -import { getConnectionById } from '@/controllers/connection'; +import type { ClickhouseClient } from '@/clickhouse'; import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import { clickHouseErrorResult, @@ -12,6 +11,10 @@ import { MCP_REQUEST_TIMEOUT, } from '@/mcp/tools/query/helpers'; import type { ToolRegistrar, ToolResult } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { mcpServerError, mcpUserError, @@ -335,24 +338,20 @@ export function registerDescribeTable({ ...(input.table && { 'mcp.describe_table.table': input.table }), }); - const connection = await getConnectionById( - teamId, - input.connectionId, - true, - ); - if (!connection) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + input.connectionId, + { requestTimeout: MCP_REQUEST_TIMEOUT }, + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError( `Connection "${input.connectionId}" not found. Call clickstack_list_sources to see available connections.`, ); } - const clickhouseClient = new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - requestTimeout: MCP_REQUEST_TIMEOUT, - }); - const outcome = await runWithTimeout( signal => { const ctx = { diff --git a/packages/api/src/mcp/tools/sources/listMetrics.ts b/packages/api/src/mcp/tools/sources/listMetrics.ts index 5c373197b2..0594c6673b 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -3,12 +3,15 @@ import { SourceKind } from '@hyperdx/common-utils/dist/types'; import { trace } from '@opentelemetry/api'; import { z } from 'zod'; -import { ClickhouseClient } from '@/clickhouse'; -import { getConnectionById } from '@/controllers/connection'; +import type { ClickhouseClient } from '@/clickhouse'; import { getSource } from '@/controllers/sources'; import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import { parseTimeRange } from '@/mcp/tools/query/helpers'; -import type { ToolRegistrar } from '@/mcp/tools/types'; +import type { McpContext, ToolRegistrar } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { mcpServerError, mcpUserError } from '@/mcp/utils/errors'; import { MCP_TOOL_TIMEOUT_MS, runWithTimeout } from '@/mcp/utils/timeout'; import logger from '@/utils/logger'; @@ -77,7 +80,7 @@ export function registerListMetrics({ const deadlineAt = Date.now() + LIST_TIMEOUT_MS; const outcome = await runWithTimeout( - signal => listMetricsImpl(teamId.toString(), input, deadlineAt, signal), + signal => listMetricsImpl(context, input, deadlineAt, signal), { timeoutMs: LIST_TIMEOUT_MS }, ); if (!outcome.timedOut) { @@ -96,11 +99,12 @@ export function registerListMetrics({ } async function listMetricsImpl( - teamId: string, + context: McpContext, input: z.infer, deadlineAt: number, signal: AbortSignal, ) { + const { teamId } = context; const source = await getSource(teamId, input.sourceId); if (!source) { return mcpUserError( @@ -147,20 +151,16 @@ async function listMetricsImpl( ); } - const connection = await getConnectionById( - teamId, - source.connection.toString(), - true, - ); - if (!connection) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + source.connection.toString(), + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError(`Connection not found for source "${input.sourceId}".`); } - - const clickhouseClient = new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - }); const metadata = getMetadata(clickhouseClient); const limit = input.limit ?? DEFAULT_LIMIT; diff --git a/packages/api/src/mcp/tools/trace/breakdown.ts b/packages/api/src/mcp/tools/trace/breakdown.ts index ea4e0c5a6f..f96c1fbad4 100644 --- a/packages/api/src/mcp/tools/trace/breakdown.ts +++ b/packages/api/src/mcp/tools/trace/breakdown.ts @@ -19,12 +19,14 @@ import type { ChSql } from '@hyperdx/common-utils/dist/clickhouse'; import { getMetadata } from '@hyperdx/common-utils/dist/core/metadata'; import { SourceKind } from '@hyperdx/common-utils/dist/types'; +import type { ClickhouseClient } from '@/clickhouse'; import { getSource } from '@/controllers/sources'; import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import { clickHouseErrorResult, isQueryOutOfTime, isServerError, + MCP_REQUEST_TIMEOUT, parseTimeRange, } from '@/mcp/tools/query/helpers'; import { @@ -34,11 +36,14 @@ import { } from '@/mcp/tools/trace/breakdownSchema'; import { durationDivisor, - getMcpClickhouseClient, inclusiveTimeFilter, mcpQuerySettings, } from '@/mcp/tools/trace/shared'; import type { ToolRegistrar } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { mcpUserError } from '@/mcp/utils/errors'; // The child stage looks spans up by TraceId, which is not in the sort key, so @@ -90,11 +95,15 @@ export function registerTraceBreakdown({ ); } - const clickhouseClient = await getMcpClickhouseClient( - teamId.toString(), - source.connection.toString(), - ); - if (!clickhouseClient) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + source.connection.toString(), + { requestTimeout: MCP_REQUEST_TIMEOUT }, + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError( `Connection not found for source: ${input.sourceId}`, ); diff --git a/packages/api/src/mcp/tools/trace/shared.ts b/packages/api/src/mcp/tools/trace/shared.ts index 499980c7cf..4c5929f297 100644 --- a/packages/api/src/mcp/tools/trace/shared.ts +++ b/packages/api/src/mcp/tools/trace/shared.ts @@ -3,12 +3,7 @@ import type { Metadata } from '@hyperdx/common-utils/dist/core/metadata'; import { timeFilterExpr } from '@hyperdx/common-utils/dist/core/renderChartConfig'; import type { QuerySettings } from '@hyperdx/common-utils/dist/types'; -import { ClickhouseClient } from '@/clickhouse'; -import { getConnectionById } from '@/controllers/connection'; -import { - MCP_CLICKHOUSE_SETTINGS, - MCP_REQUEST_TIMEOUT, -} from '@/mcp/tools/query/helpers'; +import { MCP_CLICKHOUSE_SETTINGS } from '@/mcp/tools/query/helpers'; export function durationDivisor(precision: number): number { // durationPrecision is the number of decimal digits in the stored value. @@ -17,20 +12,6 @@ export function durationDivisor(precision: number): number { return Math.pow(10, Math.max(0, precision - 3)); } -export async function getMcpClickhouseClient( - teamId: string, - connectionId: string, -): Promise { - const connection = await getConnectionById(teamId, connectionId, true); - if (!connection) return null; - return new ClickhouseClient({ - host: connection.host, - username: connection.username, - password: connection.password, - requestTimeout: MCP_REQUEST_TIMEOUT, - }); -} - // MCP settings win over source.querySettings so a source can't relax the // max_execution_time ceiling, or the readonly guard that blocks DDL/DML // injected through raw SQL filters. diff --git a/packages/api/src/mcp/tools/trace/waterfall.ts b/packages/api/src/mcp/tools/trace/waterfall.ts index e7760f6be2..b2113116f2 100644 --- a/packages/api/src/mcp/tools/trace/waterfall.ts +++ b/packages/api/src/mcp/tools/trace/waterfall.ts @@ -16,16 +16,20 @@ import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import { clickHouseErrorResult, MCP_CLICKHOUSE_SETTINGS, + MCP_REQUEST_TIMEOUT, parseTimeRange, } from '@/mcp/tools/query/helpers'; import { durationDivisor, - getMcpClickhouseClient, inclusiveTimeFilter, mcpQuerySettings, type TimeFilterParams, } from '@/mcp/tools/trace/shared'; import type { ToolRegistrar } from '@/mcp/tools/types'; +import { + getMcpClickhouseClient, + McpConnectionNotFoundError, +} from '@/mcp/utils/clickhouse'; import { mcpUserError } from '@/mcp/utils/errors'; import logger from '@/utils/logger'; @@ -355,11 +359,15 @@ export function registerTraceWaterfall({ ); } - const clickhouseClient = await getMcpClickhouseClient( - teamId.toString(), - source.connection.toString(), - ); - if (!clickhouseClient) { + let clickhouseClient: ClickhouseClient; + try { + clickhouseClient = await getMcpClickhouseClient( + context, + source.connection.toString(), + { requestTimeout: MCP_REQUEST_TIMEOUT }, + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; return mcpUserError( `Connection not found for source: ${input.sourceId}`, ); @@ -686,10 +694,16 @@ export function registerTraceWaterfall({ if ( logSource.connection.toString() !== source.connection.toString() ) { - logClient = await getMcpClickhouseClient( - teamId.toString(), - logSource.connection.toString(), - ); + try { + logClient = await getMcpClickhouseClient( + context, + logSource.connection.toString(), + { requestTimeout: MCP_REQUEST_TIMEOUT }, + ); + } catch (e) { + if (!(e instanceof McpConnectionNotFoundError)) throw e; + logClient = null; + } } if (!logClient) { logsNote = `connection for log source ${source.logSourceId} not found`; diff --git a/packages/api/src/mcp/utils/clickhouse.ts b/packages/api/src/mcp/utils/clickhouse.ts new file mode 100644 index 0000000000..997eaa5839 --- /dev/null +++ b/packages/api/src/mcp/utils/clickhouse.ts @@ -0,0 +1,39 @@ +import type { ClickhouseClientOptions } from '@hyperdx/common-utils/dist/clickhouse'; + +import { ClickhouseClient } from '@/clickhouse'; +import { getConnectionById } from '@/controllers/connection'; +import type { McpContext } from '@/mcp/tools/types'; + +export class McpConnectionNotFoundError extends Error { + constructor(readonly connectionId: string) { + super(`Connection not found: ${connectionId}`); + this.name = 'McpConnectionNotFoundError'; + } +} + +/** + * Builds the ClickHouse client for a connection owned by the calling team. + * All MCP tools must obtain ClickHouse clients through this function. + * + * @throws McpConnectionNotFoundError when the team has no such connection. + */ +export async function getMcpClickhouseClient( + context: McpContext, + connectionId: string, + options?: Pick, +): Promise { + const connection = await getConnectionById( + context.teamId, + connectionId, + true, + ); + if (!connection) { + throw new McpConnectionNotFoundError(connectionId); + } + return new ClickhouseClient({ + host: connection.host, + username: connection.username, + password: connection.password, + ...options, + }); +}