Skip to content

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

Merged
knudtty merged 3 commits into
aaron/adhoc-external-apifrom
aaron/adhoc-mcp
Nov 17, 2026
Merged

knudtty merged 3 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

@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 17, 2026 5:05pm UTC
hyperdx-storybook Ready Ready Preview Nov 17, 2026 5:05pm UTC

Request Review

@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 51b9dcf

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.

1 finding(s): 🔴 0 critical · 🟠 1 major · 🔵 0 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, saving back what clickstack_get_dashboard returned warns the agent to delete the hidden PromQL ad hoc filter's saved conditions → convertToExternalDashboard (routers/external-api/v2/utils/dashboards.ts) hides PromQL ad hoc filters but still returns their adhoc entries in savedFilterValues. On update, getSavedFilterValueWarnings checks against effectiveFilters, which here is just the request filters. The hidden filters are only added back later, as hiddenFilters. So when an agent sends back the filters and savedFilterValues it read, it gets a "no ADHOC filter's variableName matches … fix the name or remove the entry" warning for conditions that do apply. That steers it into deleting them. Fix: compute the hidden filters before the warnings and check against [...filters, ...hiddenFilters]. Alternatively, hide those savedFilterValues entries too and keep them on update, the same way the filters are kept. Then add a promqlTiles test that round-trips savedFilterValues with PromQL off.

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

@github-actions

github-actions Bot commented Nov 13, 2026 •

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.17%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@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: 294 (+ 288 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 • 466 passed • 1 skipped • 1376s

Status Count
✅ Passed 466
❌ Failed 0
⚠️ Flaky 2
⏭️ 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

✅ No critical issues found in the reviewer results and verification available at synthesis time.

This change brings the MCP dashboard tools to parity with the REST v2 API for ADHOC filters and fixes a real data-loss bug (a clickstack_save_dashboard update that sent filters previously deleted existing ad hoc filters). Independent verification confirmed three of the highest-risk areas are sound:

  • getSavedFilterValueWarnings name matching is correct. The adhocSourceTypeByName map is keyed on getFilterVariableName(filter) (which trims / derives the name) and looked up with value.name.trim(), so both sides normalize consistently — no false "matches no filter" warnings from whitespace or a derived default name. (validation.ts:270, common-utils/filters.ts:1263)
  • PromQL where-rejection and all REST superRefines run on the MCP path. createDashboard/updateDashboard re-parse through createDashboardBodySchema / updateDashboardBodySchema, so validateDashboardFilterFieldGating (which rejects where/whereLanguage on a promql ad hoc filter) is enforced for MCP exactly as for REST — the MCP input schema is only the tool's declared shape, not the validation boundary. (saveDashboard.ts:179, common-utils/dashboardValidation.ts:245)
  • Tenant scoping is preserved. Every read (getDashboard, getDashboardTile, queryTile, queryTiles) keeps Dashboard.findOne({ _id, team: teamId }), and save/update/patch keep team: teamId in their query filters. The patchDashboard response now returns updatedDashboard.savedFilterValues ?? [] directly, but reads from the just-written, team-scoped document, so no cross-tenant data becomes reachable.

🟡 P2 -- recommended

  • packages/api/src/mcp/tools/dashboards/validation.ts:289 -- The new adhoc write path (where/condition value now round-tripping through MCP) has no test asserting the shared query renderer safely handles adversarial where/value content, and the free-form where string remains unbounded (matching the pre-existing REST/QUERY_EXPRESSION surface rather than tightening it).
    • Fix: Add a test exercising adhoc conditions and where with SQL metacharacters through save → query to confirm they are parameterized/escaped at execution, and decide whether where should carry a max-length bound like the condition fields.
    • security

Reviewers (3 completed, 7 did not return before synthesis): project-standards, security, learnings-researcher completed. correctness, adversarial, api-contract, kieran-typescript, testing, and maintainability were dispatched but had not returned results at the time output was required, and agent-native did not return — their lenses (logic/edge-case bugs, adversarial data-mutation scenarios, contract/dangling-import checks, test-coverage of the data-loss fix) are therefore not reflected below. Treat this as a partial review.

Testing gaps:

  • No test confirming the core regression fix — that a save sending filters no longer deletes existing ad hoc filters — was verifiable from the completed reviewer set; confirm saveDashboard.int.test.ts asserts ad hoc filter persistence across such an update.
  • No negative test for cross-tenant isolation of adhoc filters/savedFilterValues (relies on existing team scoping).

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

karl-power
karl-power previously approved these changes Nov 17, 2026
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.
…romQL where note

IN is now the only stored ad hoc OR operator. Also restores the note that
where is rejected on PromQL ad hoc filters, which the stack rebase dropped
along with the merge commit it lived in.
@knudtty
knudtty merged commit b681cec into main Nov 17, 2026
29 of 53 checks passed

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 51b9dcf9 Deployed Nov 17, 2026 by vercel[bot]
Preview – hyperdx-storybook — 51b9dcf9 Deployed Nov 17, 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.

3 participants