feat(api/mcp): add heatmap tile schema for hyperdx_save_dashboard by alex-fedotyev · Pull Request #2199 · hyperdxio/hyperdx

alex-fedotyev · 2026-05-05T19:35:50Z

Summary

Adds a heatmap display type to the MCP mcpTilesParam schema so AI agents
can author heatmap tiles via hyperdx_save_dashboard.

The new mcpHeatmapSelectItemSchema mirrors the heatmap fields persisted in
DerivedColumnSchema (common-utils):

aggFn: literal "heatmap" (not part of AggregateFunctionSchema)
valueExpression: required column to bucket on the Y axis
countExpression: optional normalization expression
alias: optional display label
heatmapScaleType: optional "log" | "linear"

The new mcpHeatmapTileSchema adds numberFormat so AI agents can format
durations/bytes on the value axis. groupBy is intentionally omitted because
heatmap tiles don't group, and per-select where/whereLanguage is omitted
because heatmap doesn't filter per-item (filtering happens at the chart level).

Stacked on #2200

This PR is stacked on #2200 ([HDX-4120] external dashboards API heatmap support).
Without #2200, calls to hyperdx_save_dashboard with a heatmap tile would
return a cryptic Zod validation error from the external-API discriminated
union. #2200 should merge first, then this PR rebases on main and an
integration round-trip test can be added in dashboards.test.ts (extending
the existing "create a dashboard with multiple tile types" pattern).

Marking this PR draft until #2200 lands.

What's in this PR

mcpHeatmapSelectItemSchema and mcpHeatmapTileSchema in mcp/tools/dashboards/schemas.ts
Heatmap added to the mcpTileSchema z.union(...)
One few-shot example for heatmap added to the mcpTilesParam.describe(...) block
Schema-validation unit tests at mcp/tools/dashboards/__tests__/schemas.test.ts covering accept and reject cases
Minor changeset

What's NOT in this PR

Raw-SQL heatmap. Heatmap is builder-only across the codebase, so the
mcpSqlTileSchema.config.displayType enum is intentionally untouched.
Integration round-trip test in dashboards.test.ts. Will be added once
[HDX-4120] feat(api): support heatmap tiles in external dashboards API #2200 merges and this branch rebases on main.

Drive-by

The pre-existing en-dashes (used as em-dashes) in seven describe() strings
on this file were replaced with regular punctuation to match the team's
writing style. No semantic change.

Deep-review carryover from #2200 (2026-05-07)

The deep-review that fired on #2200 also flagged two MCP-side items that belong here:

Resolved in this PR: buildCreateDashboardPrompt and buildQueryGuidePrompt now enumerate heatmap in the TILE TYPE GUIDE, COMMON MISTAKES, and PER-TILE TYPE CONSTRAINTS sections (commit e583fc6).
Pending until [HDX-4120] feat(api): support heatmap tiles in external dashboards API #2200 merges: MCP createDashboard/updateDashboard does not yet call getHeatmapTilesWithIncompatibleSources, so an MCP-saved heatmap can persist against a non-Trace source while the REST routes reject it with HTTP 400. The helper is added in [HDX-4120] feat(api): support heatmap tiles in external dashboards API #2200 and is not importable from this branch yet. Will land in the post-[HDX-4120] feat(api): support heatmap tiles in external dashboards API #2200 rebase commit alongside the round-trip integration test.

Test plan

yarn lint clean
yarn tsc --noEmit clean
jest src/mcp/tools/dashboards/__tests__/schemas.test.ts (5/5 passing)
prose-lint --staged clean
Tier predictor reports Tier 2
After [HDX-4120] feat(api): support heatmap tiles in external dashboards API #2200 merges: rebase, add round-trip integration test, mark ready for review

Adds a heatmap display type to the MCP mcpTilesParam schema so AI agents can author heatmap tiles via hyperdx_save_dashboard. New mcpHeatmapSelectItemSchema carries valueExpression, countExpression, alias, and heatmapScaleType, mirroring the heatmap fields persisted in DerivedColumnSchema. Adds a unit test file covering accept/reject cases for the heatmap schema and a few-shot example in the tiles description block. Drive-by cleanup: replaced en-dashes used as em-dashes in pre-existing describe() strings with regular punctuation to match the team's writing style. Follow-up to #2107 (heatmap chart type wired into editor and renderer). This PR adds the MCP-side schema only. End-to-end save/get of heatmap tiles also requires the external API conversion layer to land in a sister PR before AI agents can persist heatmap tiles via hyperdx_save_dashboard. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

vercel · 2026-05-05T19:35:56Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	May 7, 2026 6:06pm

changeset-bot · 2026-05-05T19:35:57Z

🦋 Changeset detected

Latest commit: e583fc6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Minor
@hyperdx/app	Minor
@hyperdx/otel-collector	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-05-05T19:36:22Z

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats

Production files changed: 1
Production lines changed: 98 (+ 124 in test files, excluded from tier calculation)
Branch: alex/HDX-mcp-heatmap-schema
Author: alex-fedotyev

To override this classification, remove the review/tier-2 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

github-actions · 2026-05-05T19:38:34Z

PR Review

⚠️ Heatmap tiles silently fail on save — externalDashboardBuilderTileConfigSchema (in packages/api/src/utils/zod.ts) does not include a 'heatmap' discriminant, so any agent call to hyperdx_save_dashboard with a heatmap tile will return a Validation error to the agent with no useful message. PR description acknowledges this is intentional pending a sister PR, but there's no guard or clear error message surfaced to the caller. → Consider adding a descriptive error or returning a not yet supported message in the MCP save path until the sister PR lands.
⚠️ schemas.ts exceeds the 300-line guideline — file grows to ~401 lines (was ~330 pre-PR). AGENTS.md calls this out explicitly. → Consider splitting heatmap schemas into a separate file and re-exporting.

✅ No critical bugs or security issues. Schema fields (valueExpression, countExpression, heatmapScaleType, alias) correctly mirror DerivedColumnSchema. select: z.array(...).length(1) constraint is properly tested with both valid and rejection cases. Changeset targets the correct package at minor.

github-actions · 2026-05-05T19:46:58Z

E2E Test Results

✅ All tests passed • 163 passed • 3 skipped • 1218s

Status	Count
✅ Passed	163
❌ Failed	0
⚠️ Flaky	6
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

The external API surface in PR #2200 exposes where/whereLanguage at the chart-config level for heatmaps (UI HeatmapSeriesEditor doesn't render per-series filters; the persisted shape stores them once via SelectSQLStatementSchema). The MCP heatmap schema was dropping them, so once #2200 lands a save through hyperdx_save_dashboard would silently discard the filter on read-back. Add `where` and `whereLanguage` to mcpHeatmapTileSchema.config with the same defaults the search tile uses (where: '', whereLanguage: 'lucene'). Extend the round-trip test with a Lucene filter, add an explicit whereLanguage="sql" round-trip, and a negative test for an invalid whereLanguage. Update the example string and changeset to document the new fields.

Deep-review on #2200 flagged that buildCreateDashboardPrompt and buildQueryGuidePrompt enumerate every supported displayType but omit heatmap, hiding the new capability from agents reading the prompt. Adds heatmap to: - TILE TYPE GUIDE (buildCreateDashboardPrompt): one-line description plus the Trace-source-only and aggFn:"heatmap" + valueExpression requirements. - COMMON MISTAKES TO AVOID: a single bullet covering the source-kind and select-item rules. - PER-TILE TYPE CONSTRAINTS (buildQueryGuidePrompt): 1 select item, no groupBy, Trace sources only. Not in this commit: the MCP source-kind runtime gate (getHeatmapTilesWithIncompatibleSources) flagged as P0/P1 #2 in the same deep-review. The helper is added in #2200 and is not yet importable from this branch; the gate will land in the rebase commit after #2200 merges.

github-actions Bot added the review/tier-2 Low risk — AI review + quick human skim label May 5, 2026

vercel Bot deployed to Preview May 5, 2026 19:39 View deployment

alex-fedotyev marked this pull request as draft May 5, 2026 19:44

vercel Bot deployed to Preview May 6, 2026 17:03 View deployment

vercel Bot deployed to Preview May 7, 2026 18:06 View deployment

This was referenced May 7, 2026

External dashboards API: deferred follow-ups from #2200 + #2201 deep-reviews #2236

Open

[HDX-4120] feat(api): support heatmap tiles in external dashboards API #2200

Open

alex-fedotyev requested a review from brandon-pereira May 9, 2026 01:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(api/mcp): add heatmap tile schema for hyperdx_save_dashboard#2199

feat(api/mcp): add heatmap tile schema for hyperdx_save_dashboard#2199
alex-fedotyev wants to merge 3 commits intomainfrom
alex/HDX-mcp-heatmap-schema

alex-fedotyev commented May 5, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 5, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 5, 2026

Uh oh!

github-actions Bot commented May 5, 2026

Uh oh!

github-actions Bot commented May 5, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

alex-fedotyev commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Stacked on #2200

What's in this PR

What's NOT in this PR

Drive-by

Deep-review carryover from #2200 (2026-05-07)

Test plan

Uh oh!

vercel Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented May 5, 2026

🔵 Tier 2 — Low Risk

Uh oh!

github-actions Bot commented May 5, 2026

PR Review

Uh oh!

github-actions Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Test Results

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

alex-fedotyev commented May 5, 2026 •

edited

Loading

vercel Bot commented May 5, 2026 •

edited

Loading

changeset-bot Bot commented May 5, 2026 •

edited

Loading

github-actions Bot commented May 5, 2026 •

edited

Loading