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. Mirrors the number-tile color MCP work in #2480 and the v2 REST parity in #2509.

Part of #1360. Replaces #2510 (closed; that branch began as a stacked PR and the commit history got noisy once the base merged). Same code, single clean commit against main.

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)

CI re-runs lint, typecheck, and the test suite against the current main on this branch.

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

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

[changeset-bot]

🦋 Changeset detected

Latest commit: bc17781

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	Patch
@hyperdx/app	Patch
@hyperdx/otel-collector	Patch

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:35pm
hyperdx-storybook	Ready	Preview, Comment	Jul 2, 2026 9:35pm

[github-actions]

🔵 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: 2
• Production lines changed: 30 (+ 139 in test files, excluded from tier calculation)
• Branch: alex/HDX-1360-mcp-number-tile-bg-chart
• 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.

[greptile-apps]

Greptile Summary

This PR adds backgroundChart support to number tiles in the MCP dashboard tools (clickstack_save_dashboard and clickstack_patch_dashboard), enabling an AI agent to author a background trend sparkline behind a number tile's value. It reuses BackgroundChartSchema from common-utils and leverages the already-existing external-API conversion path, so the addition is schema, prompt, and tests only.

• Schema (schemas.ts): imports and attaches BackgroundChartSchema.optional() to mcpNumberTileSchema.config; mcpPatchTileSchema inherits it automatically via .shape.config. Raw SQL tiles (mcpSqlTileSchema) deliberately omit the field, causing Zod to strip it on parse.
• Prompt (content.ts): adds a "NUMBER TILE BACKGROUND CHART" section with field semantics and a worked availability-tile example, matching the conventions of adjacent NUMBER TILE COLOR and colorRules sections.
• Tests (saveDashboard.test.ts, patchDashboard.test.ts): four integration tests covering save round-trip, patch round-trip, schema rejection of an invalid type, and silent drop on raw SQL tiles.

Confidence Score: 5/5

Safe to merge; changes are additive and confined to MCP schema, prompt text, and integration tests.

The diff is a clean, self-contained addition of an optional field. BackgroundChartSchema is imported from common-utils (shared with the REST API), so the type definition cannot drift. The external-API conversion layer already passes backgroundChart through, meaning no new conversion logic was needed. Raw SQL tiles correctly drop the field via Zod's default strip behavior, confirmed by a dedicated integration test. Four integration tests cover the key scenarios—round-trip save, round-trip patch, invalid-type rejection, and raw-SQL stripping—providing good confidence that the path is correct end-to-end.

No files require special attention.

Important Files Changed

Filename	Overview
packages/api/src/mcp/tools/dashboards/schemas.ts	Imports BackgroundChartSchema from common-utils and adds it as optional to mcpNumberTileSchema.config; mcpPatchTileSchema inherits it correctly via .shape.config. Raw SQL tiles omit the field by design.
packages/api/src/mcp/prompts/dashboards/content.ts	Adds NUMBER TILE BACKGROUND CHART section with field semantics and a worked example; placement and conventions match the adjacent color/colorRules sections.
packages/api/src/mcp/tests/dashboards/saveDashboard.test.ts	Adds three integration tests: save round-trip with backgroundChart, rejection of an invalid type ('bar'), and silent drop on a raw SQL number tile.
packages/api/src/mcp/tests/dashboards/patchDashboard.test.ts	Adds patch round-trip test: creates a line tile, patches to a number tile with backgroundChart, then confirms the field is persisted via get_dashboard_tile.
.changeset/mcp-number-tile-background-chart.md	Patch-level changeset for @hyperdx/api; description accurately reflects scope of the change.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Agent as MCP Agent
    participant Tool as MCP Tool (save/patch)
    participant Schema as mcpNumberTileSchema
    participant Conversion as externalAPI conversion
    participant DB as Dashboard Store

    Agent->>Tool: clickstack_save_dashboard / clickstack_patch_dashboard
    Tool->>Schema: Zod parse (mcpTileSchema union)
    Note over Schema: Builder number tile → mcpNumberTileSchema<br/>backgroundChart accepted (BackgroundChartSchema)<br/>Raw SQL tile → mcpSqlTileSchema<br/>backgroundChart stripped (not in schema)
    Schema-->>Tool: Validated tile config
    Tool->>Conversion: toInternalConfig / toExternalConfig
    Note over Conversion: backgroundChart passed through as-is
    Conversion->>DB: Persist BuilderSavedChartConfig with backgroundChart
    DB-->>Agent: Saved dashboard with backgroundChart in response

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"}}}%%
sequenceDiagram
    participant Agent as MCP Agent
    participant Tool as MCP Tool (save/patch)
    participant Schema as mcpNumberTileSchema
    participant Conversion as externalAPI conversion
    participant DB as Dashboard Store

    Agent->>Tool: clickstack_save_dashboard / clickstack_patch_dashboard
    Tool->>Schema: Zod parse (mcpTileSchema union)
    Note over Schema: Builder number tile → mcpNumberTileSchema<br/>backgroundChart accepted (BackgroundChartSchema)<br/>Raw SQL tile → mcpSqlTileSchema<br/>backgroundChart stripped (not in schema)
    Schema-->>Tool: Validated tile config
    Tool->>Conversion: toInternalConfig / toExternalConfig
    Note over Conversion: backgroundChart passed through as-is
    Conversion->>DB: Persist BuilderSavedChartConfig with backgroundChart
    DB-->>Agent: Saved dashboard with backgroundChart in response

Loading

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

[github-actions]

Deep Review

✅ No critical issues found.

This is a tightly-scoped, additive change: it adds backgroundChart (BackgroundChartSchema from common-utils) to the builder number-tile config in the MCP save/patch tools, plus a prompt section and tests. The external-api conversion (convertToInternalTileConfig) already passes backgroundChart through for builder number tiles and omits it for raw SQL number tiles, so no conversion edits were required. The schema reuses the shared BackgroundChartSchema rather than duplicating it, and the new field mirrors the existing color / colorRules additions in the same object. Round-trip (save/get and patch/get), invalid-type rejection, and raw-SQL-strip cases are all covered.

🔵 P3 nitpicks (1)

• packages/api/src/mcp/__tests__/dashboards/saveDashboard.test.ts:830 — the MCP-layer tests always send backgroundChart with an explicit color, so the "inherit tile color when color is unset" path (a type-only backgroundChart) is not exercised through the MCP save/get round-trip.
  • Fix: Add a case that round-trips a backgroundChart with only type set and asserts color stays absent on the returned config.

---

Reviewers (6): correctness, testing, maintainability, kieran-typescript, api-contract, project-standards.

Testing gaps: type-only backgroundChart (omitted color) is validated by BackgroundChartSchema's own unit tests in common-utils but not through the MCP save/get round-trip.

[github-actions]

E2E Test Results

✅ All tests passed • 224 passed • 3 skipped • 1519s

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

Tests ran across 4 shards in parallel.

View full report →