Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/mcp-sql-source-id.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
'@hyperdx/api': patch
---

feat(mcp): `clickstack_sql` accepts an optional `sourceId`, so `$__sourceTable`
expands to that source's table. Unknown sources, other teams' sources, and a
source on a different connection than `connectionId` are rejected, as is
`$__sourceTable` without a `sourceId`.
119 changes: 118 additions & 1 deletion packages/api/src/mcp/__tests__/queryTool.int.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
import { MetricsDataType, SourceKind } from '@hyperdx/common-utils/dist/types';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { ObjectId } from 'mongodb';

import * as config from '@/config';
import {
Expand All @@ -20,6 +21,7 @@ import {
import { McpContext } from '@/mcp/tools/types';
import Connection from '@/models/connection';
import { Source, type SourceDocument } from '@/models/source';
import Team from '@/models/team';

import { callTool, createTestClient, getFirstText } from './mcpTestUtils';

Expand Down Expand Up @@ -163,6 +165,16 @@ describe('MCP Query Tools', () => {
expect(tool!.inputSchema.required).toContain('connectionId');
expect(tool!.inputSchema.required).toContain('sql');
});

it('exposes an optional sourceId on clickstack_sql', async () => {
const { tools } = await client.listTools();
const tool = tools.find(t => t.name === 'clickstack_sql')!;

expect(Object.keys(tool.inputSchema.properties ?? {})).toContain(
'sourceId',
);
expect(tool.inputSchema.required).not.toContain('sourceId');
});
});

// ─── clickstack_timeseries ─────────────────────────────────────────────────────
Expand Down Expand Up @@ -848,12 +860,19 @@ describe('MCP Query Tools', () => {

expect(examples).toHaveLength(2);
for (const sql of examples) {
expect(sql).toContain('FROM <table>');
expect(sql).toMatch(/FROM (<table>|\$__sourceTable) /);
expect(sql).toContain('<timestampColumn>');
expect(sql).not.toMatch(/otel_|TimestampTime/);
}
});

it('show $__sourceTable for a source and <table> for any other table', async () => {
const [timeSeries, table] = await getExamples();

expect(timeSeries).toContain('FROM $__sourceTable ');
expect(table).toContain('FROM <table> ');
});

it('run once the placeholders are filled from a source', async () => {
const examples = await getExamples();

Expand All @@ -864,6 +883,7 @@ describe('MCP Query Tools', () => {
.replaceAll('<timestampColumn>', 'Timestamp');
const result = await callTool(client, 'clickstack_sql', {
connectionId: connection._id.toString(),
sourceId: logSource._id.toString(),
sql,
startTime: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
endTime: new Date().toISOString(),
Expand All @@ -876,6 +896,103 @@ describe('MCP Query Tools', () => {
});
});

describe('sourceId', () => {
const countSql =
'SELECT count() AS n FROM $__sourceTable WHERE $__timeFilter(Timestamp)';

it('resolves $__sourceTable to the table of the given source', async () => {
const now = Date.now();
await bulkInsertLogs(
[1, 2, 3].map(minutesAgo => ({
Body: 'from source',
ServiceName: 'sql-source',
SeverityText: 'INFO',
Timestamp: new Date(now - minutesAgo * 60 * 1000),
})),
);

const result = await callTool(client, 'clickstack_sql', {
connectionId: connection._id.toString(),
sourceId: logSource._id.toString(),
sql: `${countSql} AND ServiceName = 'sql-source'`,
startTime: new Date(now - 60 * 60 * 1000).toISOString(),
endTime: new Date(now).toISOString(),
});

expect(result.isError).toBeFalsy();
expect(JSON.parse(getFirstText(result)).result.data).toEqual([
{ n: '3' },
]);
});

it('rejects $__sourceTable without a sourceId, saying to pass one', async () => {
const result = await callTool(client, 'clickstack_sql', {
connectionId: connection._id.toString(),
sql: countSql,
});

expect(result.isError).toBe(true);
expect(getFirstText(result)).toContain(
'$__sourceTable needs a sourceId',
);
});

it('rejects a sourceId that does not exist', async () => {
const result = await callTool(client, 'clickstack_sql', {
connectionId: connection._id.toString(),
sourceId: new ObjectId().toString(),
sql: countSql,
});

expect(result.isError).toBe(true);
expect(getFirstText(result)).toContain('Source not found');
});

it("rejects another team's sourceId as not found", async () => {
const otherTeam = await Team.create({ name: 'Other Team' });
const otherSource = await Source.create({
kind: SourceKind.Log,
team: otherTeam._id,
from: {
databaseName: DEFAULT_DATABASE,
tableName: DEFAULT_LOGS_TABLE,
},
timestampValueExpression: 'Timestamp',
connection: connection._id,
name: 'Other Logs',
});

const result = await callTool(client, 'clickstack_sql', {
connectionId: connection._id.toString(),
sourceId: otherSource._id.toString(),
sql: countSql,
});

expect(result.isError).toBe(true);
expect(getFirstText(result)).toContain('Source not found');
});

// $__sourceTable would otherwise expand to a table on another server.
it('rejects a sourceId whose connection differs from connectionId', async () => {
const otherConnection = await Connection.create({
team: team._id,
name: 'Other',
host: config.CLICKHOUSE_HOST,
username: config.CLICKHOUSE_USER,
password: config.CLICKHOUSE_PASSWORD,
});

const result = await callTool(client, 'clickstack_sql', {
connectionId: otherConnection._id.toString(),
sourceId: logSource._id.toString(),
sql: countSql,
});

expect(result.isError).toBe(true);
expect(getFirstText(result)).toContain('does not match the connection');
});
});

it('returns plain query rows unchanged', async () => {
const result = await callTool(client, 'clickstack_sql', {
connectionId: connection._id.toString(),
Expand Down
51 changes: 45 additions & 6 deletions packages/api/src/mcp/tools/query/sql.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
import { hasMacro } from '@hyperdx/common-utils/dist/macros';
import { hasVariableMacro } from '@hyperdx/common-utils/dist/variables';
import { z } from 'zod';

import { getSource } from '@/controllers/sources';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';

Expand All @@ -17,6 +19,14 @@ const sqlSchema = z.object({
'Connection ID (required). This is the only split tool that needs a connectionId ' +
'instead of sourceId. Call clickstack_list_sources to find available connections.',
),
sourceId: z
.string()
.optional()
.describe(
'Source ID. Optional. Set it when the query reads a table backed by a source, so ' +
"`$__sourceTable` expands to that source's database.table. The source's " +
'connection must match connectionId. Call clickstack_list_sources to find source IDs.',
),
sql: z
.string()
.describe(
Expand All @@ -38,15 +48,17 @@ const sqlSchema = z.object({
' $__timeInterval_ms(column) — same with millisecond precision\n' +
' $__interval_s — raw interval in seconds\n' +
' $__filters — dashboard filter conditions (resolves to 1=1 when no filters)\n' +
" $__sourceTable — the source's database.table. Requires sourceId.\n" +
' {intervalSeconds:Int64} / {intervalMilliseconds:Int64} — bucket size parameters\n\n' +
"In the examples, replace <table> with a source's `table` and <timestampColumn> " +
'with the first expression in its `timestampColumn`, both from ' +
'clickstack_list_sources. For a metric source, use a table from its ' +
'metricTables qualified with its `database`. Table and column names differ ' +
'between sources, so do not guess them.\n\n' +
'Example (time-series):\n' +
'clickstack_list_sources, or pass that source as sourceId and use ' +
'$__sourceTable. For a metric source, use a table from its metricTables ' +
'qualified with its `database`. Table and column names differ between ' +
'sources, so do not guess them.\n\n' +
'Example (time-series, with sourceId):\n' +
' SELECT $__timeInterval(<timestampColumn>) AS ts, ServiceName, count() ' +
'FROM <table> WHERE $__timeFilter(<timestampColumn>) GROUP BY ServiceName, ts ORDER BY ts\n\n' +
'FROM $__sourceTable WHERE $__timeFilter(<timestampColumn>) GROUP BY ServiceName, ts ORDER BY ts\n\n' +
'Example (table):\n' +
' SELECT ServiceName, count() AS n FROM <table> ' +
'WHERE <timestampColumn> >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) ' +
Expand Down Expand Up @@ -79,7 +91,8 @@ export function registerSql({ context, registerTool }: ToolRegistrar) {
'A single-table aggregation, top-N, time-series, or row browse is ALWAYS a ' +
'builder-tool job, never raw SQL. If you are unsure, try the builder tool first and only ' +
'fall back to SQL if it cannot express what you need.\n\n' +
'Requires connectionId (not sourceId) — call clickstack_list_sources to find connections. ' +
'Requires connectionId — call clickstack_list_sources to find connections. Pass sourceId ' +
'too when querying a source, so $__sourceTable resolves to its table. ' +
'Call clickstack_describe_source to discover column names before writing SQL.\n\n' +
'Results are always returned as table rows — for time-series semantics, ' +
'include a time column and ORDER BY it in your SQL.',
Expand All @@ -105,6 +118,31 @@ export function registerSql({ context, registerTool }: ToolRegistrar) {
);
}

if (input.sourceId) {
const source = await getSource(teamId.toString(), input.sourceId);
if (!source) {
return mcpUserError(
`Source not found: ${input.sourceId}. Call clickstack_list_sources to discover available source IDs.`,
);
}
// $__sourceTable expands to the source's table, so a mismatch would run
// the query against a table on another server.
const sourceConnectionId = source.connection.toString();
if (sourceConnectionId !== input.connectionId) {
return mcpUserError(
`connectionId "${input.connectionId}" does not match the connection of source ` +
`"${input.sourceId}" ("${sourceConnectionId}"). Use the source's own ` +
'connection or drop sourceId from the call.',
);
}
} else if (hasMacro(input.sql, 'sourceTable')) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 SQL comments block valid queries

hasMacro also matches $__sourceTable inside SQL comments. Without sourceId, a query such as SELECT 1 /* previously FROM $__sourceTable */ now returns an error even though the renderer skips that comment. Use the renderer's comment-aware scan for this check and add a test for a commented-out macro.

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex

return mcpUserError(
'$__sourceTable needs a sourceId to know which table to expand to. ' +
'Pass the sourceId of a source from clickstack_list_sources, or write ' +
"the source's `table` in place of the macro.",
);
}

// Raw SQL only uses displayType to pick which query params to bind, and
// only time-series types bind the interval params this tool advertises
// ({intervalSeconds}, $__interval_s, $__timeInterval). Rows come back
Expand All @@ -113,6 +151,7 @@ export function registerSql({ context, registerTool }: ToolRegistrar) {
configType: 'sql' as const,
displayType: 'line' as const,
connectionId: input.connectionId,
sourceId: input.sourceId,
sqlTemplate: input.sql,
});

Expand Down
Loading