Skip to content

feat(mcp): support ad hoc dashboard filters in the MCP dashboard tools - #3660

Open
knudtty wants to merge 8 commits into
aaron/adhoc-external-apifrom
aaron/adhoc-mcp
Open

knudtty wants to merge 8 commits into
aaron/adhoc-external-apifrom
aaron/adhoc-mcp

Conversation

@knudtty

@knudtty knudtty commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Stacked on #3659.

Summary

The MCP dashboard tools now create, read, and update dashboards with ADHOC filters. The previous PR left MCP hiding them. A side effect was that a clickstack_save_dashboard update that sent filters silently deleted any ad hoc filters already on the dashboard. This PR fixes that.

  • Input schemas: clickstack_save_dashboard accepts ADHOC filters, and clickstack_save_dashboard / clickstack_patch_dashboard accept adhoc entries in savedFilterValues. Validation reuses the external API schemas, so MCP and REST stay in sync; only the descriptions are MCP-specific. sourceType: "promql" is offered only while PromQL is enabled.
  • Reads: convertToExternalDashboard no longer has the temporary hideAdhoc option. hidePromql now hides PromQL ad hoc filters as well as PROMETHEUS_LABEL filters, through a shared isPromqlFilter helper.
  • Updates with PromQL off: hidden PromQL ad hoc filters are kept on update, like hidden PROMETHEUS_LABEL filters. The existing variable-name clash check also covers them.
  • Warnings: a saved adhoc entry produces a warning when its name matches no ad hoc filter, or when it uses an operator its filter's source type can't apply. The UI would silently ignore both.
  • Prompt docs: the create-dashboard prompt gets a rule 9h and two gotchas. The query guide documents the ad hoc filter shape. The PromQL dashboard section covers PromQL ad hoc filters.

How to reproduce

Starting point: yarn dev, with an MCP client connected to the local MCP server.

On main:

  1. Create a dashboard with an ad hoc filter in the UI, then call clickstack_get_dashboard. The filter is missing from filters.
  2. Call clickstack_save_dashboard with that dashboard's id and any filters array. The ad hoc filter is deleted.

On this branch:

  1. clickstack_get_dashboard returns the ad hoc filter and its adhoc saved conditions.
  2. clickstack_save_dashboard with filters: [{ "type": "ADHOC", "name": "Conditions", "sourceType": "sql", "sources": ["<trace-source-id>"] }] and savedFilterValues: [{ "type": "adhoc", "name": "Conditions", "conditions": [{ "key": "ServiceName", "operator": "IN", "value": "api" }] }] creates it. Opening the dashboard shows the condition applied.
  3. With ENABLE_PROMQL off, a PromQL ad hoc filter is absent from clickstack_get_dashboard and survives a save that leaves it out.

How to test on Vercel preview

N/A. API-only change.

Testing

  • make dev-int FILE=src/mcp/__tests__/dashboards passes. New cases cover a SQL round trip through save, get and save, a PromQL round trip, source-kind rejections, hiding and keeping PromQL ad hoc filters with PromQL off, and the warnings.
  • make dev-int FILE=src/routers/external-api/__tests__/dashboards.int.test.ts passes.

References

Save, get, and patch now handle ADHOC filters and their adhoc saved
conditions. PromQL ad hoc filters are offered only while PromQL is enabled;
otherwise reads hide them and updates keep them, as for PROMETHEUS_LABEL
filters. Saved conditions naming no ad hoc filter, or using an operator their
filter can't apply, warn. Drops the temporary hideAdhoc option.
@knudtty
knudtty requested a review from a team as a code owner November 13, 2026 21:36
@vercel

vercel Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Nov 16, 2026 3:31pm UTC
hyperdx-storybook Ready Ready Preview Nov 16, 2026 3:31pm UTC

Request Review

@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5c9d83b

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

@knudtty
knudtty added this pull request to stack #3661 November 13, 2026 21:37
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

3 finding(s): 🔴 0 critical · 🟠 1 major · 🔵 2 minor

None could be anchored to changed lines; they are listed below.

Findings outside the changed lines

  • 🟠 packages/api/src/mcp/tools/dashboards/saveDashboard.ts:344 — With PromQL off, a save that round-trips savedFilterValues gets a false warning to delete a hidden PromQL ad hoc filter's conditions → convertToExternalDashboard (routers/external-api/v2/utils/dashboards.ts:955) hides the PromQL ad hoc filter but still returns its adhoc entry in savedFilterValues. On update, effectiveFilters is just the request filters, which never contain the hidden filter, so getAdhocValueWarnings tells the agent that no ADHOC filter matches and to "fix the name or remove the entry". If the agent follows that advice, it deletes conditions it was never shown. Fix: run getSavedFilterValueWarnings against the filters actually persisted ([...requestFilters, ...hiddenFilters], or the existing filters when filters is omitted), or include the hidden PromQL filters in effectiveFilters. Add a PromQL-off test that saves read.savedFilterValues back and expects no warnings.
2 minor
  • 🔵 packages/api/src/mcp/tools/dashboards/validation.ts:806 — Ad hoc warning trims the saved name, but the UI matches it exactly → useDashboardFilters (packages/app/src/hooks/useDashboardFilters.tsx:224) looks the entry up with parsed.byVariable.get(getFilterVariableName(filter)), and parseDashboardFilterValues keys it by the raw entry.name. VariableFilterValueSchema.name allows whitespace, so name: " conditions" gets no MCP warning but is ignored when the dashboard loads. Fix: look up value.name without .trim(), or reject or normalise surrounding whitespace in the schema.
  • 🔵 packages/api/src/mcp/__tests__/dashboards/saveDashboard.int.test.ts:272 — Deleted-source test only checks that the save didn't fail → The test asserts only saved.isError is falsy. It would still pass if the save silently dropped the deleted source ID from sources, or dropped the filter entirely. Fix: also load the stored dashboard and assert its filters still match the original, including '65f5e4a3b9e77c001a999999'.

Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@github-actions

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 108 in total (1.18%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@github-actions github-actions Bot added the review/tier-4 Critical — deep review + domain expert sign-off label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

🔴 Tier 4 — Critical

Touches authentication, tenancy data models, the public API or shipped database config — or substantially changes the query rendering engine, background tasks, the OTel pipeline, image build, or release CI.

Why this tier:

  • Critical-path files (1) — tenancy, public API, or shipped database config:
    • packages/api/src/routers/external-api/v2/utils/dashboards.ts

Review process: Deep review from a domain expert. Synchronous walkthrough may be required.
SLA: Schedule synchronous review within 2 business days.

Stats
  • Production files changed: 13
  • Production lines changed: 297 (+ 273 in test files, excluded from tier calculation)
  • Critical-path lines changed: 29
  • Branch: aaron/adhoc-mcp
  • Author: knudtty

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

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 465 passed • 1 skipped • 1128s

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

Tests ran across 4 shards in parallel.

View full report →

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

Scope: PR #3660 — ad hoc dashboard filters in the MCP dashboard tools (17 files, ~296 production + ~240 test lines) against base 6953c12.
Intent: Let the MCP dashboard tools create/read/update ADHOC filters (incl. PromQL ad hoc), remove the temporary hideAdhoc read option, hide PromQL ad hoc filters via a shared isPromqlFilter helper when PromQL is off, and warn on unusable saved adhoc entries.

🟡 P2 — recommended

  • packages/api/src/mcp/tools/dashboards/saveDashboard.ts:346 — With PromQL disabled, convertToExternalDashboard returns savedFilterValues unfiltered while still hiding the matching PromQL ADHOC filter, so a read surfaces an adhoc saved entry whose filter is invisible; on the documented get→save round trip the warning check runs against effectiveFilters (visible filters only), emitting a false "no ADHOC filter's variableName matches … fix the name or remove the entry" for a filter that still exists and whose conditions are preserved — advice that, if followed, drops valid seeded conditions.
    • Fix: Run getSavedFilterValueWarnings against the full stored filter set including the re-added hidden PromQL ad hoc filters (as patchDashboard.ts:283 already does with existingDashboard.filters), or hide the saved values of hidden PromQL ad hoc filters in convertToExternalDashboard so reads and warnings stay consistent.
    • correctness, orchestrator-verification
  • packages/api/src/mcp/__tests__/dashboards/promqlTiles.int.test.ts:507 — The "keeps hidden PromQL ad hoc filters" test stores filters with no savedFilterValues and the update sends none, so the PromQL-off savedFilterValues round trip — the exact path that produces the spurious warning above — is untested.
    • Fix: Add a case where a stored PromQL ad hoc filter has an adhoc saved value, then read and save back the visible filters plus echoed savedFilterValues while PromQL is off, asserting the conditions survive and no false warning fires.
    • correctness, testing-gap
🔵 P3 nitpicks (1)
  • packages/api/src/mcp/tools/dashboards/schemas.ts:1859 — mcpPromqlAdhocFilterSchema reuses the base where via mcpAdhocFilterSchema.shape.where but rebuilds sources as a fresh z.array(objectIdSchema).min(1), duplicating the .min(1) rule so the variants can silently drift.
    • Fix: Reuse mcpAdhocFilterSchema.shape.sources.describe(...) for the PromQL variant's sources.

Reviewers (4 reported): correctness, maintainability, project-standards, learnings-researcher. Dead-code/dangling-ref removal (getMcpCompatibleFilters/getMcpCompatibleFilterValues, hideAdhoc) verified clean across packages/; changeset format and minor bump verified correct; isAdhocFilter/isPrometheusLabelFilter imports confirmed still live. The adversarial, api-contract, testing, kieran-typescript, and agent-native reviewers were dispatched but had not returned at synthesis time — their primary concerns (round-trip data loss, REST-path/schema-sync regressions, trim-key consistency in getAdhocValueWarnings) were covered by direct inspection and found sound; the REST default (hideAdhoc was false) is unchanged, and getFilterVariableName trims consistently on both map insert and lookup.

Testing gaps:

  • No coverage of the PromQL-off savedFilterValues round trip for a hidden PromQL ad hoc filter (see P2 above).
  • Variable-name clash is tested for a hidden PROMETHEUS_LABEL filter but not for a hidden PromQL ADHOC filter, which can also be variable-enabled (isFilterVariableEnabled returns true for it) and flow through the same saveDashboard.ts:404 check.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 5c9d83be Deployed Nov 16, 2026 by vercel[bot]
Preview – hyperdx-storybook — 5c9d83be Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review/tier-4 Critical — deep review + domain expert sign-off

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant