From 7b65eeff796c4edacc1d0deccf297fe723de62e6 Mon Sep 17 00:00:00 2001 From: Karl Power Date: Tue, 20 Oct 2026 11:38:04 +0200 Subject: [PATCH 1/2] fix: Validate PromQL tile sources and keep PromQL tiles on MCP saves Reject external API PromQL tiles whose sourceId is not a PromQL source, sharing the check with PROMETHEUS_LABEL filters. MCP save_dashboard updates now keep the PromQL tiles MCP hides from agents instead of deleting them, until HDX-5302. Add integration tests for PromQL tile create, read and save back, source validation, PromQL heatmaps, and MCP hide and keep. --- .../external-api-promql-tile-validation.md | 7 ++ .../dashboards/promqlTiles.int.test.ts | 89 +++++++++++++++ .../src/mcp/tools/dashboards/saveDashboard.ts | 14 ++- .../__tests__/dashboards.int.test.ts | 103 ++++++++++++++++++ .../external-api/v2/utils/dashboards.ts | 27 ++++- 5 files changed, 233 insertions(+), 7 deletions(-) create mode 100644 .changeset/external-api-promql-tile-validation.md create mode 100644 packages/api/src/mcp/__tests__/dashboards/promqlTiles.int.test.ts diff --git a/.changeset/external-api-promql-tile-validation.md b/.changeset/external-api-promql-tile-validation.md new file mode 100644 index 0000000000..031570105c --- /dev/null +++ b/.changeset/external-api-promql-tile-validation.md @@ -0,0 +1,7 @@ +--- +'@hyperdx/api': patch +--- + +fix: Reject external API PromQL tiles that reference a non-PromQL source, and keep PromQL tiles when an MCP agent updates a dashboard + +`/api/v2/dashboards` now returns a 400 when a PromQL tile's `sourceId` is not a PromQL source. MCP `clickstack_save_dashboard` updates no longer delete the PromQL tiles that MCP hides from agents. diff --git a/packages/api/src/mcp/__tests__/dashboards/promqlTiles.int.test.ts b/packages/api/src/mcp/__tests__/dashboards/promqlTiles.int.test.ts new file mode 100644 index 0000000000..d315631232 --- /dev/null +++ b/packages/api/src/mcp/__tests__/dashboards/promqlTiles.int.test.ts @@ -0,0 +1,89 @@ +import { DisplayType } from '@hyperdx/common-utils/dist/types'; +import mongoose from 'mongoose'; + +import { callTool, getFirstText } from '@/mcp/__tests__/mcpTestUtils'; +import Dashboard from '@/models/dashboard'; + +import { setupDashboardTests } from './setup'; + +// MCP cannot edit PromQL tiles until HDX-5302, so it hides them on read and +// keeps them on save. Remove with that work. +describe('MCP Dashboard Tools - PromQL tiles', () => { + const ctx = setupDashboardTests(); + + const promqlTile = { + id: 'promql-tile', + x: 0, + y: 0, + w: 6, + h: 3, + config: { + configType: 'promql', + name: 'PromQL', + displayType: DisplayType.Line, + source: new mongoose.Types.ObjectId().toString(), + promqlExpression: [{ expression: 'up' }], + }, + }; + + const markdownTile = { + id: 'markdown-tile', + x: 6, + y: 0, + w: 6, + h: 3, + config: { + name: 'Notes', + displayType: DisplayType.Markdown, + markdown: 'Notes', + source: '', + where: '', + select: [], + }, + }; + + const createDashboard = () => + new Dashboard({ + name: 'PromQL dashboard', + tiles: [promqlTile, markdownTile], + team: ctx.team._id, + }).save(); + + it('hides PromQL tiles from clickstack_get_dashboard', async () => { + const dashboard = await createDashboard(); + + const result = await callTool(ctx.client!, 'clickstack_get_dashboard', { + id: dashboard._id.toString(), + }); + + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + expect(output.tiles.map((t: { id: string }) => t.id)).toEqual([ + 'markdown-tile', + ]); + }); + + it('keeps PromQL tiles when clickstack_save_dashboard updates the dashboard', async () => { + const dashboard = await createDashboard(); + + const result = await callTool(ctx.client!, 'clickstack_save_dashboard', { + id: dashboard._id.toString(), + name: 'PromQL dashboard', + tiles: [ + { + id: 'markdown-tile', + name: 'Updated notes', + config: { displayType: 'markdown', markdown: 'Updated' }, + }, + ], + }); + + expect(result.isError).toBeFalsy(); + const stored = await Dashboard.findById(dashboard._id).lean(); + expect(stored?.tiles.map(t => t.id)).toEqual([ + 'markdown-tile', + 'promql-tile', + ]); + expect(stored?.tiles[1].config).toEqual(promqlTile.config); + }); +}); diff --git a/packages/api/src/mcp/tools/dashboards/saveDashboard.ts b/packages/api/src/mcp/tools/dashboards/saveDashboard.ts index 827f56f66a..3ac9dc7169 100644 --- a/packages/api/src/mcp/tools/dashboards/saveDashboard.ts +++ b/packages/api/src/mcp/tools/dashboards/saveDashboard.ts @@ -1,3 +1,4 @@ +import { isPromqlSavedChartConfig } from '@hyperdx/common-utils/dist/guards'; import type { DashboardContainer } from '@hyperdx/common-utils/dist/types'; import { uniq } from 'lodash'; import mongoose from 'mongoose'; @@ -318,10 +319,21 @@ async function updateDashboard({ (existingDashboard.filters ?? []).map((f: { id: string }) => f.id), ); - const internalTiles = convertExternalTilesToInternal( + const requestTiles = convertExternalTilesToInternal( tilesWithId, existingTileIds, ); + // MCP reads hide PromQL tiles, so the agent's tile list never contains them. + // Keep them rather than delete tiles it could not see. A request tile that + // reuses a hidden tile's id replaces it. Remove with HDX-5302. + const requestTileIds = new Set(requestTiles.map(tile => tile.id)); + const internalTiles = [ + ...requestTiles, + ...(existingDashboard.tiles ?? []).filter( + tile => + isPromqlSavedChartConfig(tile.config) && !requestTileIds.has(tile.id), + ), + ]; // Typed as `Partial` (the canonical Mongo doc shape) so // misnamed or wrong-shape fields fail at compile time, mirroring the diff --git a/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts b/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts index d579706d49..86e5546a0f 100644 --- a/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts +++ b/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts @@ -7138,6 +7138,109 @@ describe('External API v2 Dashboards - new format', () => { }); }); + describe('PromQL tiles', () => { + const promqlTile = (config: Record = {}) => ({ + name: 'PromQL', + x: 0, + y: 0, + w: 6, + h: 3, + config: { + configType: 'promql', + displayType: 'line', + sourceId: promqlSource._id.toString(), + expressions: [{ expression: 'up', alias: 'Up' }], + legendTemplate: '{{job}}', + ...config, + }, + }); + + const postTile = (config: Record = {}) => + authRequest('post', BASE_URL).send({ + name: 'PromQL dashboard', + tiles: [promqlTile(config)], + tags: [], + }); + + it('round-trips a PromQL tile through POST and GET', async () => { + const create = await postTile().expect(200); + const expected = { ...promqlTile().config, fillNulls: true }; + expect(create.body.data.tiles[0].config).toEqual(expected); + + const get = await authRequest( + 'get', + `${BASE_URL}/${create.body.data.id}`, + ).expect(200); + expect(get.body.data.tiles[0].config).toEqual(expected); + }); + + it('keeps PromQL tiles when a dashboard is read and saved back', async () => { + const promqlConfig = { + configType: 'promql', + name: 'Saved in the app', + displayType: DisplayType.Number, + source: promqlSource._id.toString(), + promqlExpression: [{ expression: 'up', reducer: 'max' }], + }; + const dashboard = await createTestDashboard({ + tiles: [ + { id: 'promql-tile', x: 0, y: 0, w: 6, h: 3, config: promqlConfig }, + { + id: 'markdown-tile', + x: 6, + y: 0, + w: 6, + h: 3, + config: { + name: 'Notes', + displayType: DisplayType.Markdown, + markdown: 'Notes', + source: '', + where: '', + select: [], + }, + }, + ], + }); + + const get = await authRequest( + 'get', + `${BASE_URL}/${dashboard._id}`, + ).expect(200); + const { name, tiles, tags } = get.body.data; + await authRequest('put', `${BASE_URL}/${dashboard._id}`) + .send({ name, tiles, tags }) + .expect(200); + + const stored = await Dashboard.findById(dashboard._id).lean(); + expect(stored?.tiles.find(t => t.id === 'promql-tile')?.config).toEqual( + promqlConfig, + ); + }); + + it('rejects a PromQL tile whose source is not a PromQL source', async () => { + const res = await postTile({ + sourceId: traceSource._id.toString(), + }).expect(400); + expect(JSON.stringify(res.body)).toContain( + `PromQL tiles require a PromQL source. The following source IDs are not PromQL sources: ${traceSource._id.toString()}`, + ); + }); + + // The builder heatmap check requires a Trace source; it must not apply. + it('accepts a PromQL heatmap on a PromQL source', async () => { + const create = await postTile({ + displayType: 'heatmap', + heatmapMode: 'histogram', + expressions: [{ expression: 'sum by (le) (rate(x_bucket[5m]))' }], + }).expect(200); + expect(create.body.data.tiles[0].config).toMatchObject({ + displayType: 'heatmap', + heatmapMode: 'histogram', + }); + }); + }); + describe('Chart formulas', () => { // Two metric operand series (A, B) — the shape the formula grammar // references by position. Payloads go through `.send()` (untyped) so diff --git a/packages/api/src/routers/external-api/v2/utils/dashboards.ts b/packages/api/src/routers/external-api/v2/utils/dashboards.ts index 5f26c518c3..39a15090cf 100644 --- a/packages/api/src/routers/external-api/v2/utils/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/utils/dashboards.ts @@ -1359,11 +1359,13 @@ function getHeatmapTilesWithIncompatibleSources( /** * Returns an error message string if any of the referenced source IDs is not - * a valid PromQL source, or null if all of them are. + * a valid PromQL source, or null if all of them are. `subject` names what + * referenced them, e.g. "PromQL tiles". */ -function getPromqlLabelFilterSourceError( +function getNonPromqlSourceError( sources: SourceForValidation[], referencedSourceIds: string[], + subject: string, ): string | null { const sourceById = new Map(sources.map(s => [s._id.toString(), s])); const invalid = [...new Set(referencedSourceIds)].filter(id => { @@ -1371,7 +1373,7 @@ function getPromqlLabelFilterSourceError( return source === undefined || !isPromqlSource(source); }); if (invalid.length === 0) return null; - return `PROMETHEUS_LABEL filters require a PromQL source. The following source IDs are not PromQL sources: ${invalid.join(', ')}`; + return `${subject} require a PromQL source. The following source IDs are not PromQL sources: ${invalid.join(', ')}`; } /** @@ -1711,7 +1713,7 @@ export type TileValidationContext = { /** * Run the full suite of tile validation checks (sources, connections, - * heatmap source-kind, onClick targets, container/tab refs). Returns + * heatmap and PromQL source-kind, onClick targets, container/tab refs). Returns * `null` when all checks pass, or an error message string on failure. * * Consolidates the ~95-line validation block that was previously @@ -1789,11 +1791,24 @@ export async function validateDashboardTiles( return `Tiles with formulas require a Metric, Log, or Trace source. The following source IDs are not formula-capable: ${formulaIncompatibleSources.join(', ')}`; } - // Validate that PROMETHEUS_LABEL filters reference PromQL sources + // PromQL tiles and PROMETHEUS_LABEL filters query through their source's + // connection and TimeSeries table, which only a PromQL source carries. + const promqlTileError = getNonPromqlSourceError( + sources, + tiles.flatMap(tile => + isConfigTile(tile) && isPromqlExternalTileConfig(tile.config) + ? [tile.config.sourceId] + : [], + ), + 'PromQL tiles', + ); + if (promqlTileError != null) return promqlTileError; + const promqlLabelFilters = (filters ?? []).filter(isPrometheusLabelFilter); - const promqlLabelFilterError = getPromqlLabelFilterSourceError( + const promqlLabelFilterError = getNonPromqlSourceError( sources, promqlLabelFilters.map(f => f.sourceId), + 'PROMETHEUS_LABEL filters', ); if (promqlLabelFilterError != null) return promqlLabelFilterError; From 3e9d310b5ae81502fed1791a5b5ebeab76afa926 Mon Sep 17 00:00:00 2001 From: Karl Power Date: Wed, 21 Oct 2026 09:04:22 +0200 Subject: [PATCH 2/2] fix: Only check PromQL tile sources that are new or changed on update A source whose kind changes after a PromQL tile is saved no longer blocks unrelated dashboard edits, matching the heatmap and formula checks. --- .../__tests__/dashboards.int.test.ts | 43 +++++++++++++++++++ .../external-api/v2/utils/dashboards.ts | 33 +++++++++++--- 2 files changed, 71 insertions(+), 5 deletions(-) diff --git a/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts b/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts index 86e5546a0f..25d3f0b9c7 100644 --- a/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts +++ b/packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts @@ -7227,6 +7227,49 @@ describe('External API v2 Dashboards - new format', () => { ); }); + describe('when the source kind changes after the tile is saved', () => { + const createAndRetypeSource = async () => { + const create = await postTile().expect(200); + await Source.updateOne( + { _id: promqlSource._id }, + { $set: { kind: SourceKind.Log } }, + ); + return create.body.data; + }; + + it('still lets unrelated edits through', async () => { + const { id, tiles, tags } = await createAndRetypeSource(); + + await authRequest('put', `${BASE_URL}/${id}`) + .send({ name: 'Renamed', tiles, tags }) + .expect(200); + }); + + it('rejects pointing the tile at a non-PromQL source', async () => { + const { id, tiles, tags } = await createAndRetypeSource(); + const [tile] = tiles; + + const res = await authRequest('put', `${BASE_URL}/${id}`) + .send({ + name: 'Renamed', + tiles: [ + { + ...tile, + config: { + ...tile.config, + sourceId: traceSource._id.toString(), + }, + }, + ], + tags, + }) + .expect(400); + expect(JSON.stringify(res.body)).toContain( + 'PromQL tiles require a PromQL source', + ); + }); + }); + // The builder heatmap check requires a Trace source; it must not apply. it('accepts a PromQL heatmap on a PromQL source', async () => { const create = await postTile({ diff --git a/packages/api/src/routers/external-api/v2/utils/dashboards.ts b/packages/api/src/routers/external-api/v2/utils/dashboards.ts index 39a15090cf..8ffa9564b3 100644 --- a/packages/api/src/routers/external-api/v2/utils/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/utils/dashboards.ts @@ -1506,6 +1506,33 @@ function filterChangedHeatmapTiles( }); } +/** + * Returns the source IDs of PromQL tiles to check against the PromQL + * source-kind gate. With `existingTiles` (update paths), a tile that was already + * a PromQL tile on the same source is skipped, mirroring + * `filterChangedHeatmapTiles`: a source whose kind changed after the tile was + * saved must not block unrelated dashboard edits. + */ +function getChangedPromqlTileSourceIds( + tiles: ExternalDashboardTileWithId[], + existingTiles: DashboardDocument['tiles'] | undefined, +): string[] { + const existingPromqlSources = new Map( + (existingTiles ?? []).flatMap(tile => + isPromqlSavedChartConfig(tile.config) + ? [[tile.id, tile.config.source]] + : [], + ), + ); + return tiles.flatMap(tile => + isConfigTile(tile) && + isPromqlExternalTileConfig(tile.config) && + existingPromqlSources.get(tile.id) !== tile.config.sourceId + ? [tile.config.sourceId] + : [], + ); +} + /** * Returns source IDs referenced by onClick search link-outs (mode=id, * type=search) whose source kind is not log or trace. The /search destination @@ -1795,11 +1822,7 @@ export async function validateDashboardTiles( // connection and TimeSeries table, which only a PromQL source carries. const promqlTileError = getNonPromqlSourceError( sources, - tiles.flatMap(tile => - isConfigTile(tile) && isPromqlExternalTileConfig(tile.config) - ? [tile.config.sourceId] - : [], - ), + getChangedPromqlTileSourceIds(tiles, existingTiles), 'PromQL tiles', ); if (promqlTileError != null) return promqlTileError;