feat(api): support number-tile backgroundChart in the MCP dashboard tools

[alex-fedotyev]

Add backgroundChart to number tiles in the MCP dashboard tools, so an agent can author the background trend sparkline through clickstack_save_dashboard and clickstack_patch_dashboard.

Stacked on #2509 (the v2 REST parity), which makes the shared conversion backgroundChart-aware. Mirrors the number-tile color MCP work in #2480.

Part of #1360.

Summary

Add backgroundChart (a required type of line or area, plus an optional palette-token color) to the builder number-tile config in the MCP save and patch tools, reusing BackgroundChartSchema from common-utils. The MCP tools already share the external-api conversion, so this is schema, prompt, and tests only, no conversion edits. Raw SQL number tiles do not expose it (no time dimension to bucket), matching the editor and the REST API.

What

• Add backgroundChart to mcpNumberTileSchema.config with a tool description; the patch tool inherits it via mcpPatchTileSchema.
• Add a "NUMBER TILE BACKGROUND CHART" section to the dashboard authoring prompt with a worked builder example.
• Tests: round-trip through save/get and through patch/get; reject a type outside line/area; drop the field on a raw SQL number tile.

Test plan

• yarn workspace @hyperdx/api lint
• yarn workspace @hyperdx/api tsc --noEmit
• integration: mcp/__tests__/dashboards/{saveDashboard,patchDashboard}.test.ts (75 passed)

What's NOT in this PR (follow-up)

• Customer docs for the sparkline option (tracked separately).

Note: this is stacked on #2509; review that first. GitHub retargets this to main once #2509 merges.

[changeset-bot]

🦋 Changeset detected

Latest commit: c871684

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

This PR includes changesets to release 4 packages

Name	Type
@hyperdx/api	Minor
@hyperdx/otel-collector	Minor
@hyperdx/hdx-eval	Patch
@hyperdx/app	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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Jul 2, 2026 9:28pm
hyperdx-storybook	Ready	Preview, Comment	Jul 2, 2026 9:28pm

[greptile-apps]

Greptile Summary

This PR adds backgroundChart (a line or area sparkline with an optional palette color) to builder number tiles in the MCP clickstack_save_dashboard and clickstack_patch_dashboard tools by re-using the existing BackgroundChartSchema from common-utils. Raw SQL number tiles intentionally omit the field, matching the dashboard editor and v2 REST API.

• Schema: BackgroundChartSchema.optional() added to mcpNumberTileSchema.shape.config; mcpPatchTileSchema inherits it automatically; mcpSqlTileSchema is unchanged.
• Prompt: New "NUMBER TILE BACKGROUND CHART" section with a worked availability-tile example added to the dashboard authoring content.
• Tests: Round-trip through save/get, round-trip through patch/get, rejection of an invalid type, and silent strip of the field on a raw SQL tile — all four cases covered.

Confidence Score: 5/5

Clean additive schema change with no conversion logic touched and four integration tests covering the new field end-to-end.

The change is schema, prompt copy, and tests only — no conversion code was modified. The new field is optional, backward-compatible, and gated to builder number tiles exactly as intended. All four test scenarios (round-trip save, round-trip patch, invalid-type rejection, raw-SQL strip) pass. No regressions are expected.

No files require special attention.

Important Files Changed

Filename	Overview
packages/api/src/mcp/tools/dashboards/schemas.ts	Adds optional backgroundChart: BackgroundChartSchema to mcpNumberTileSchema.shape.config; raw SQL tile schema (mcpSqlTileSchema) correctly omits the field; patch union inherits the shape via mcpNumberTileSchema.shape.config.
packages/api/src/mcp/prompts/dashboards/content.ts	Adds a "NUMBER TILE BACKGROUND CHART" section with description and a worked example; placement and prose are consistent with surrounding prompt sections.
packages/api/src/mcp/tests/dashboards/saveDashboard.test.ts	Adds three tests: round-trip save/get with backgroundChart, rejection of an invalid type value, and silent strip of backgroundChart on a raw SQL tile — good coverage of the happy path and both guard cases.
packages/api/src/mcp/tests/dashboards/patchDashboard.test.ts	Adds a patch round-trip test that converts a line tile to a number tile with backgroundChart and verifies the field persists through clickstack_get_dashboard_tile.
.changeset/mcp-number-tile-background-chart.md	Changeset for @hyperdx/api at patch bump; description accurately reflects scope of the change.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[MCP Tool Call] --> B{configType?}
    B -->|builder| C[mcpNumberTileSchema]
    B -->|sql| D[mcpSqlTileSchema]
    C --> E[backgroundChart optional\ntype: line or area\ncolor: optional palette token]
    D --> F[backgroundChart not in schema\nZod strips unknown fields silently]
    E --> G{backgroundChart provided?}
    G -->|yes| H{type valid?}
    G -->|no| I[Saved without sparkline]
    H -->|line or area| J[Tile saved with sparkline]
    H -->|other e.g. bar| K[Validation error returned]
    F --> L[backgroundChart dropped\ncolor field preserved]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[MCP Tool Call] --> B{configType?}
    B -->|builder| C[mcpNumberTileSchema]
    B -->|sql| D[mcpSqlTileSchema]
    C --> E[backgroundChart optional\ntype: line or area\ncolor: optional palette token]
    D --> F[backgroundChart not in schema\nZod strips unknown fields silently]
    E --> G{backgroundChart provided?}
    G -->|yes| H{type valid?}
    G -->|no| I[Saved without sparkline]
    H -->|line or area| J[Tile saved with sparkline]
    H -->|other e.g. bar| K[Validation error returned]
    F --> L[backgroundChart dropped\ncolor field preserved]

Loading

_{Reviews (1): Last reviewed commit: "feat(api): support number-tile backgroun..." | Re-trigger Greptile}

[greptile-apps]

Too many files changed for review. (316 files found, 100 file limit)

Bypass the limit by tagging @greptile-apps to review.

[github-actions]

Deep Review

✅ No critical issues found. Six reviewers (correctness, maintainability, project-standards, api-contract, TypeScript, agent-native) returned clean. The change is cleanly additive: backgroundChart reuses the canonical BackgroundChartSchema from common-utils, the save/get conversion round-trip was traced symmetric in both directions, the patch tool correctly inherits the field via mcpNumberTileSchema.shape.config, and raw SQL number tiles genuinely lack the field so a sent value is stripped. The only findings are test-coverage gaps for documented edge cases.

🟡 P2 — recommended

• packages/api/src/mcp/__tests__/dashboards/saveDashboard.test.ts:836 — The color-less builder path (backgroundChart omitting color, which the schema and prompt document as inheriting the tile color) has no positive round-trip coverage; every builder test sets color, and the only color-less case asserts it is dropped on a raw SQL tile.
  • Fix: Add a builder save+get round-trip with backgroundChart: { type: 'line' } and assert it persists as { type: 'line' } with color undefined.
  • _{testing, correctness}

🔵 P3 nitpicks (4)

• packages/api/src/mcp/__tests__/dashboards/saveDashboard.test.ts:880 — The required type field's absence is untested; only an invalid enum value ('bar') is rejected, not a missing type.

  • Fix: Add a save test with backgroundChart: { color: 'chart-blue' } (no type) asserting result.isError === true.

• packages/api/src/mcp/__tests__/dashboards/saveDashboard.test.ts:880 — An invalid color palette token in backgroundChart is never exercised, so bad-token rejection is unverified.

  • Fix: Add a save test with backgroundChart: { type: 'line', color: 'not-a-token' } asserting result.isError === true.
  • _{testing, api-contract}

• packages/api/src/mcp/__tests__/dashboards/patchDashboard.test.ts:653 — Full-config-replace clear semantics are untested; no test confirms that patching a number tile with a config omitting backgroundChart clears a previously-set value.

  • Fix: Add a patch test that sets backgroundChart, then patches with a config omitting it, and asserts the field is cleared.
  • _{correctness, api-contract}

• packages/api/src/mcp/__tests__/dashboards/saveDashboard.test.ts:896 — The negative type test asserts only isError === true without pinning the cause, so it would still pass if the tile were rejected for an unrelated reason.

  • Fix: Assert the error text references backgroundChart/type so the test fails for the right reason.

---

Reviewers (8): correctness, testing, maintainability, project-standards, api-contract, kieran-typescript, agent-native, learnings-researcher.

Testing gaps:

• No positive builder round-trip for a color-less backgroundChart (the documented tile-color-inheritance path).
• No coverage for the missing-required-type or invalid-palette-color rejection branches of BackgroundChartSchema.
• No test documents the patch full-replace clear semantics for backgroundChart.

[alex-fedotyev]

Replaced by #2584, which ships the same MCP backgroundChart support as a single clean commit against main. This branch started life as a stacked PR and the history got noisy once the base (#2509) merged, so a fresh PR reads more cleanly. All good here, closing in favor of #2584.