Skip to content

feat(mcp): accept note and numConsecutiveWindows in clickstack_save_alert - #3694

Merged
kodiakhq[bot] merged 3 commits into
ClickHouse:mainfrom
igor-kupczynski:feat/mcp-save-alert-note-windows
Nov 17, 2026
Merged

kodiakhq[bot] merged 3 commits into
ClickHouse:mainfrom
igor-kupczynski:feat/mcp-save-alert-note-windows

Conversation

@igor-kupczynski

@igor-kupczynski igor-kupczynski commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

clickstack_save_alert can't set an alert's note or numConsecutiveWindows, although the alert model, the UI and the external API support both and clickstack_get_alert returns them. So an alert created through MCP always fires on its first window, and any update through MCP clears a note or window count that someone set in the UI.

This PR adds both fields to the tool's input schema and passes them through on create and update. Validation reuses alertNoteSchema, and a new shared alertNumConsecutiveWindowsSchema (integer ≥ 1) in common-utils replaces the rule's inline copies in the external API, the MCP tool and the alert forms.

One design decision to review. On update, an omitted note or numConsecutiveWindows keeps the stored value, and null clears it. This is the tool's existing scheduleStartAt rule, not the replace rule that name and message keep. Callers written before these fields existed don't send them, so replace semantics would keep wiping values set in the UI. To do this, the update path loads the existing alert first, so an unknown id now returns "Alert not found" before the referenced entities are validated. The tool description is updated to match.

Tests. New integration tests in packages/api/src/mcp/__tests__/alerts.int.test.ts cover create with both fields and with neither (stored as null), rejecting numConsecutiveWindows: 0 and an empty or over-long note, and an update that omits (keeps), sets (replaces) and nulls (clears) them. The file passes locally; tsc --noEmit passes for common-utils, api and app, and eslint reports no errors on the touched files.

How to reproduce

Starting point: yarn dev (the change needs the API), with one saved search, one webhook, and an MCP client connected to /api/mcp.

On main:

  1. In the UI, edit an alert on the saved search: add a note and set Advanced settings → consecutive windows to 3.
  2. Call clickstack_save_alert with that alert's id and its current threshold, interval, source and channel.
  3. clickstack_get_alert returns note: null and numConsecutiveWindows: null. Passing either field in step 2 changes nothing.

On this branch:

  1. Repeat steps 1–3: the note and the window count are kept.
  2. Pass note or numConsecutiveWindows to clickstack_save_alert on create or update: the value is stored. Pass null on update: it is cleared.

How to test on Vercel preview

N/A — non-UI change (MCP tool in packages/api).

References

  • Linear Issue: N/A. I found no existing GitHub issue for this.
  • Related PRs: none

…lert

Updates that omit either field keep the stored value instead of clearing
it; null clears.
@igor-kupczynski
igor-kupczynski requested a review from a team as a code owner November 17, 2026 15:06
@vercel

vercel Bot commented Nov 17, 2026

Copy link
Copy Markdown

@igor-kupczynski is attempting to deploy a commit to the HyperDX Team on Vercel.

A member of the Team first needs to authorize it.

@changeset-bot

changeset-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: fdec519

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

This PR includes changesets to release 4 packages
Name Type
@hyperdx/common-utils Patch
@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

@github-actions github-actions Bot added external needs-vouch Author needs a maintainer to vouch for them labels Nov 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Hi @igor-kupczynski, thanks for the pull request!

Before we review code from a first-time contributor, a maintainer vouches for them, and you're not on our list yet. There's nothing else to file and this PR stays open — a maintainer will look at it, usually within a day or two, and vouch for you right here if it's a genuine attempt at the problem.

To make that quick, check the PR description has:

  • The issue it addresses (ideally one labelled Accepting PR) and why the change is needed
  • Steps to reproduce the problem and verify the fix, starting from https://play.hyperdx.io or yarn app:dev:local connected to the demo server
  • Before/after screenshots if anything in the UI changed

More detail in our contributing guide.

// Unlike name and message, an omitted note or window count keeps the
// stored value: callers written before this tool accepted them would
// otherwise wipe what was set in the UI. null still clears.
note: input.note === undefined ? existing?.note : input.note,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Keep-on-omit uses read-then-write, so a concurrent UI edit to note or numConsecutiveWindows can be reverted

existing is read at line 82, but the write happens at line 163, after validateAlertInput has made several awaited DB queries. If someone saves a new note or window count in the UI in that gap, the update writes the stale existing values back over it. Do this the way makeAlert already handles scheduleStartAt (packages/api/src/controllers/alerts.ts:259-294): leave note/numConsecutiveWindows out of $set when they are undefined, behind an opt-in flag so the external and internal APIs keep clearing omitted fields. Then the update is atomic, and the extra getAlertById lookup can go (the updateAlert null check at line 170 already returns 'Alert not found').

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Answered in #3694 (comment)

'stored value or send null to clear it.',
),

numConsecutiveWindows: z

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The numConsecutiveWindows validator is now written out a fifth time instead of shared like alertNoteSchema

z.number().int().min(1).nullish() is already written out separately in packages/common-utils/src/types.ts:1131 and :3154, packages/api/src/utils/zod.ts:1242, and the app forms. Export an alertNumConsecutiveWindowsSchema next to alertNoteSchema in packages/common-utils/src/types.ts and import it here, so the MCP rule can't drift from the external API's.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sharing it means adding an export to packages/common-utils/src/types.ts, which this PR does not touch, so I am leaving it out of scope here; the rule is the same as the external API's (integer ≥ 1, nullable).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did it after all, in fdec519. alertNumConsecutiveWindowsSchema sits next to alertNoteSchema and replaces all six copies, the two in the app forms included.

@github-actions

github-actions Bot commented Nov 17, 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 · 🟠 0 major · 🔵 1 minor

1 posted as inline comment(s) on the changed lines.


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 17, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found. The change is tightly scoped and behavior-preserving: the two new fields reach the controller through the existing AlertInput shape, the string | null | undefined / number | null | undefined field types on the mongoose document satisfy the ternary expressions and AlertInput without any cast, the update path is team-scoped via getAlertById, and the extracted alertNumConsecutiveWindowsSchema is byte-equivalent to the six inline copies it replaces. The keep-on-omit / clear-on-null semantics correctly mirror the existing scheduleStartAt convention and are reflected in the updated tool description.

🔵 P3 nitpicks (1)
  • packages/api/src/mcp/__tests__/alerts.int.test.ts:1381 — The update tests exercise note and numConsecutiveWindows only together (both kept, both replaced, both nulled), so the per-field independence of the keep-on-omit logic is never asserted.
    • Fix: Add an update test that provides one field while omitting the other and asserts the omitted field is preserved while the provided one changes.

Reviewers (6): correctness, testing, maintainability, api-contract, kieran-typescript, previous-comments.

Testing gaps:

  • No update test covers a mixed payload (one of note / numConsecutiveWindows provided, the other omitted) to confirm each field is preserved or replaced independently.

Prior feedback: The earlier testing-gap request (empty / 4097-char note rejection and a create-path null-persistence assertion) and the request to share the numConsecutiveWindows validation rule are both addressed in the current diff.

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

@igor-kupczynski

Copy link
Copy Markdown
Contributor Author

The testing gap from the review is covered in 1ffbfe2: rejection cases for an empty and a 4097-character note, and a create-path test asserting that an omitted note and numConsecutiveWindows persist as null.

// Unlike name and message, an omitted note or window count keeps the
// stored value: callers written before this tool accepted them would
// otherwise wipe what was set in the UI. null still clears.
note: input.note === undefined ? existing?.note : input.note,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Keeping the stored note/window count by reading first and writing later can overwrite a concurrent UI edit

getAlertById (line 81) reads the alert, then updateAlert writes existing.note and existing.numConsecutiveWindows back into $set several awaits later, after validateAlertInput has made its DB lookups. If someone edits the note in the UI during that gap, an MCP update that left the fields out silently puts back the old values. Instead, keep omitted fields out of $set entirely, the way makeAlert already handles scheduleStartAt (hasScheduleStartAt spread in packages/api/src/controllers/alerts.ts:259-294). Add an opt-in flag on makeAlert/updateAlert so the external API's replace semantics stay as they are. That also removes the extra full-document fetch.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe the tool already works this way for every other field: an update replaces the alert with whatever the caller read from clickstack_get_alert earlier, so a UI edit made in between is lost for the threshold, channels, name and so on. These two fields get the same gap, only a few ms wide instead of a whole agent turn.

'stored value or send null to clear it.',
),

numConsecutiveWindows: z

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The numConsecutiveWindows rule is written out a second time instead of shared

The external API already defines this rule inline as numConsecutiveWindows: z.number().int().min(1).nullish() (packages/api/src/utils/zod.ts:1242). Move it into a shared schema next to alertNoteSchema in common-utils (e.g. alertNumConsecutiveWindowsSchema) and import it in both places, so the MCP and REST validation can't drift. This is the REQUIRED DRY convention.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

@igor-kupczynski igor-kupczynski Nov 17, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in fdec519: the rule is now a shared alertNumConsecutiveWindowsSchema in common-utils, used by all its former inline copies.

(this increased the scope slightly, as it replaced the other cases by the shared rule as well)

Export alertNumConsecutiveWindowsSchema from common-utils next to
alertNoteSchema and use it in the alert schemas, the external API schema,
the MCP tool and the two alert forms, which each wrote the same rule out.
// Unlike name and message, an omitted note or window count keeps the
// stored value: callers written before this tool accepted them would
// otherwise wipe what was set in the UI. null still clears.
note: input.note === undefined ? existing?.note : input.note,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Keeping the stored note/window count by reading and re-writing it can undo a concurrent UI edit

The tool reads the alert, then runs validateAlertInput's DB lookups, then writes existing.note / existing.numConsecutiveWindows back in a full $set (via makeAlert, which turns undefined into null). If someone edits the note or window count in the UI during that gap, the MCP update puts back the old value. The fix is to leave the omitted fields out of the $set, the same way makeAlert already handles an omitted scheduleStartAt (packages/api/src/controllers/alerts.ts:259-294). One option is a flag on makeAlert/updateAlert that skips note/numConsecutiveWindows when they are undefined. That also removes the extra getAlertById round-trip from the update path.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Answered in #3694 (comment)

@brandon-pereira brandon-pereira left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM - thanks for the contribution

@brandon-pereira

Copy link
Copy Markdown
Member

/vouch @igor-kupczynski

@brandon-pereira brandon-pereira added automerge and removed needs-vouch Author needs a maintainer to vouch for them labels Nov 17, 2026
@kodiakhq
kodiakhq Bot merged commit 02a4092 into ClickHouse:main Nov 17, 2026
32 of 35 checks passed
@github-actions github-actions Bot mentioned this pull request Nov 17, 2026
kodiakhq Bot pushed a commit that referenced this pull request Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants