From 00f2d1b78eb90a4d8627b45b61380c4e2c3ee70e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20Kupczy=C5=84ski?= Date: Tue, 17 Nov 2026 16:06:01 +0100 Subject: [PATCH 1/3] feat(mcp): accept note and numConsecutiveWindows in clickstack_save_alert Updates that omit either field keep the stored value instead of clearing it; null clears. --- .changeset/mcp-save-alert-note-windows.md | 8 ++ .../api/src/mcp/__tests__/alerts.int.test.ts | 127 ++++++++++++++++++ .../api/src/mcp/tools/alerts/saveAlert.ts | 24 +++- packages/api/src/mcp/tools/alerts/schemas.ts | 18 +++ 4 files changed, 173 insertions(+), 4 deletions(-) create mode 100644 .changeset/mcp-save-alert-note-windows.md diff --git a/.changeset/mcp-save-alert-note-windows.md b/.changeset/mcp-save-alert-note-windows.md new file mode 100644 index 000000000..6cc330fab --- /dev/null +++ b/.changeset/mcp-save-alert-note-windows.md @@ -0,0 +1,8 @@ +--- +'@hyperdx/api': patch +--- + +feat: `clickstack_save_alert` accepts `note` and `numConsecutiveWindows` + +Updates that omit either field now keep the stored value instead of clearing it; +send `null` to clear. diff --git a/packages/api/src/mcp/__tests__/alerts.int.test.ts b/packages/api/src/mcp/__tests__/alerts.int.test.ts index ac87f7222..659e6d84f 100644 --- a/packages/api/src/mcp/__tests__/alerts.int.test.ts +++ b/packages/api/src/mcp/__tests__/alerts.int.test.ts @@ -353,6 +353,53 @@ describe('MCP Alert Tools', () => { expect(output.state).toBe('OK'); }); + it('should create an alert with a note and consecutive-window count', async () => { + const savedSearch = await createTestSavedSearch(); + const webhook = await createTestWebhook(); + + const result = await callTool(client, 'clickstack_save_alert', { + source: 'saved_search', + savedSearchId: savedSearch._id.toString(), + threshold: 50, + thresholdType: 'above', + interval: '5m', + channel: { type: 'webhook', webhookId: webhook._id.toString() }, + note: 'See the [runbook](https://example.com/runbook).', + numConsecutiveWindows: 3, + }); + + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + expect(output.note).toBe( + 'See the [runbook](https://example.com/runbook).', + ); + expect(output.numConsecutiveWindows).toBe(3); + + const persisted = await Alert.findById(output.id); + expect(persisted?.note).toBe( + 'See the [runbook](https://example.com/runbook).', + ); + expect(persisted?.numConsecutiveWindows).toBe(3); + }); + + it('should reject a consecutive-window count below 1', async () => { + const savedSearch = await createTestSavedSearch(); + const webhook = await createTestWebhook(); + + const result = await callTool(client, 'clickstack_save_alert', { + source: 'saved_search', + savedSearchId: savedSearch._id.toString(), + threshold: 50, + thresholdType: 'above', + interval: '5m', + channel: { type: 'webhook', webhookId: webhook._id.toString() }, + numConsecutiveWindows: 0, + }); + + expect(result.isError).toBe(true); + expect(await Alert.countDocuments({ team: team._id })).toBe(0); + }); + it('should create an alert with an explicit displayName and tags', async () => { const savedSearch = await createTestSavedSearch(); const webhook = await createTestWebhook(); @@ -1297,6 +1344,86 @@ describe('MCP Alert Tools', () => { expect(updatedAlert?.tileId).toBeNull(); }); + describe('note and numConsecutiveWindows', () => { + async function saveExisting( + alertId: string, + savedSearchId: string, + webhookId: string, + extra: Record = {}, + ) { + return callTool(client, 'clickstack_save_alert', { + id: alertId, + source: 'saved_search', + savedSearchId, + threshold: 200, + thresholdType: 'above', + interval: '15m', + channel: { type: 'webhook', webhookId }, + ...extra, + }); + } + + it('keeps the stored values when omitted', async () => { + const webhook = await createTestWebhook(); + const alert = await createTestAlert({ + note: 'Set in the UI', + numConsecutiveWindows: 4, + }); + + const result = await saveExisting( + alert._id.toString(), + alert.savedSearch!.toString(), + webhook._id.toString(), + ); + + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + expect(output.threshold).toBe(200); + expect(output.note).toBe('Set in the UI'); + expect(output.numConsecutiveWindows).toBe(4); + }); + + it('replaces the stored values when provided', async () => { + const webhook = await createTestWebhook(); + const alert = await createTestAlert({ + note: 'Set in the UI', + numConsecutiveWindows: 4, + }); + + const result = await saveExisting( + alert._id.toString(), + alert.savedSearch!.toString(), + webhook._id.toString(), + { note: 'Updated note', numConsecutiveWindows: 2 }, + ); + + expect(result.isError).toBeFalsy(); + const persisted = await Alert.findById(alert._id); + expect(persisted?.note).toBe('Updated note'); + expect(persisted?.numConsecutiveWindows).toBe(2); + }); + + it('clears the stored values when sent as null', async () => { + const webhook = await createTestWebhook(); + const alert = await createTestAlert({ + note: 'Set in the UI', + numConsecutiveWindows: 4, + }); + + const result = await saveExisting( + alert._id.toString(), + alert.savedSearch!.toString(), + webhook._id.toString(), + { note: null, numConsecutiveWindows: null }, + ); + + expect(result.isError).toBeFalsy(); + const persisted = await Alert.findById(alert._id); + expect(persisted?.note).toBeNull(); + expect(persisted?.numConsecutiveWindows).toBeNull(); + }); + }); + it('should return not found for non-existent alert id', async () => { const savedSearch = await createTestSavedSearch(); const webhook = await createTestWebhook(); diff --git a/packages/api/src/mcp/tools/alerts/saveAlert.ts b/packages/api/src/mcp/tools/alerts/saveAlert.ts index b1149d1e6..24883dc01 100644 --- a/packages/api/src/mcp/tools/alerts/saveAlert.ts +++ b/packages/api/src/mcp/tools/alerts/saveAlert.ts @@ -5,6 +5,7 @@ import * as config from '@/config'; import { type AlertInput, createAlert, + getAlertById, updateAlert, validateAlertInput, } from '@/controllers/alerts'; @@ -54,9 +55,9 @@ export function registerSaveAlert({ 'required: pass "channels", or the legacy singular "channel" for one ' + '(webhook IDs come from clickstack_get_webhook). Updates replace the ' + 'alert configuration rather than merging it: channels you do not resend are ' + - 'removed, omitted name and message are cleared, omitted displayName and tags ' + - 'are re-derived from the source, and settings this tool cannot set ' + - '(note, consecutive-window count) are cleared. Omitting both ' + + 'removed, omitted name and message are cleared, and omitted displayName ' + + 'and tags are re-derived from the source. Omitted note and ' + + 'numConsecutiveWindows keep their stored values. Omitting both ' + 'scheduleStartAt and scheduleOffsetMinutes keeps the stored schedule; ' + 'clearing scheduleStartAt without an offset resets the offset to 0. Read the alert with ' + 'clickstack_get_alert first and resend every field you want to keep.', @@ -76,6 +77,14 @@ export function registerSaveAlert({ if (idError) return idError; } + const mongoTeamId = new mongoose.Types.ObjectId(teamId); + const existing = alertId + ? await getAlertById(alertId, mongoTeamId) + : null; + if (alertId && !existing) { + return mcpUserError('Alert not found'); + } + // Inline alerts: run the chart config through the shared external // schema (same one the v2 REST API parses) so formula validation and // the number single-select rule cannot drift between the surfaces, @@ -114,6 +123,14 @@ export function registerSaveAlert({ scheduleStartAt: input.scheduleStartAt, name: input.name, message: input.message, + // 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, + numConsecutiveWindows: + input.numConsecutiveWindows === undefined + ? existing?.numConsecutiveWindows + : input.numConsecutiveWindows, displayName: input.displayName, tags: input.tags, groupBy: input.groupBy, @@ -124,7 +141,6 @@ export function registerSaveAlert({ }; // ── Validate referenced entities exist ── - const mongoTeamId = new mongoose.Types.ObjectId(teamId); let refs; try { refs = await validateAlertInput(mongoTeamId, alertInput); diff --git a/packages/api/src/mcp/tools/alerts/schemas.ts b/packages/api/src/mcp/tools/alerts/schemas.ts index 65503aa07..b9968ff64 100644 --- a/packages/api/src/mcp/tools/alerts/schemas.ts +++ b/packages/api/src/mcp/tools/alerts/schemas.ts @@ -2,6 +2,7 @@ import { ALERT_INTERVAL_TO_MINUTES, alertDisplayNameSchema, type AlertInterval, + alertNoteSchema, checkAlertChannelSelection, isRangeThresholdType, MAX_ALERT_CHANNELS, @@ -244,6 +245,18 @@ export const mcpSaveAlertSchema = z.object({ 'stored value or send null to clear it.', ), + numConsecutiveWindows: z + .number() + .int() + .min(1) + .nullable() + .optional() + .describe( + 'Fire only after the threshold condition is met in this many ' + + 'consecutive evaluation windows; 1 fires on the first. On update, ' + + 'omit to keep the stored value or send null to clear it.', + ), + // Channel channel: mcpAlertChannelSchema.optional(), channels: z @@ -273,6 +286,11 @@ export const mcpSaveAlertSchema = z.object({ .max(4096) .optional() .describe('Handlebars template for the notification body.'), + note: alertNoteSchema.describe( + 'Markdown note shown with the alert, e.g. why it exists and links to ' + + 'runbooks. On update, omit to keep the stored value or send null to ' + + 'clear it.', + ), displayName: alertDisplayNameSchema.describe( 'Display name shown for the alert in the UI. Defaults to the saved search name, dashboard tile name, or inline chartConfig name when omitted. Overridden by the "name" field in alert notifications when provided.', ), From 1ffbfe277a202286e6086e3198152a16dc8350dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20Kupczy=C5=84ski?= Date: Tue, 17 Nov 2026 16:16:08 +0100 Subject: [PATCH 2/3] test(mcp): cover note bounds and create defaults --- .../api/src/mcp/__tests__/alerts.int.test.ts | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/packages/api/src/mcp/__tests__/alerts.int.test.ts b/packages/api/src/mcp/__tests__/alerts.int.test.ts index 659e6d84f..8350abd54 100644 --- a/packages/api/src/mcp/__tests__/alerts.int.test.ts +++ b/packages/api/src/mcp/__tests__/alerts.int.test.ts @@ -400,6 +400,50 @@ describe('MCP Alert Tools', () => { expect(await Alert.countDocuments({ team: team._id })).toBe(0); }); + it.each([ + ['empty', ''], + ['longer than 4096 characters', 'a'.repeat(4097)], + ])('should reject a note that is %s', async (_description, note) => { + const savedSearch = await createTestSavedSearch(); + const webhook = await createTestWebhook(); + + const result = await callTool(client, 'clickstack_save_alert', { + source: 'saved_search', + savedSearchId: savedSearch._id.toString(), + threshold: 50, + thresholdType: 'above', + interval: '5m', + channel: { type: 'webhook', webhookId: webhook._id.toString() }, + note, + }); + + expect(result.isError).toBe(true); + expect(await Alert.countDocuments({ team: team._id })).toBe(0); + }); + + it('should persist an omitted note and consecutive-window count as null', async () => { + const savedSearch = await createTestSavedSearch(); + const webhook = await createTestWebhook(); + + const result = await callTool(client, 'clickstack_save_alert', { + source: 'saved_search', + savedSearchId: savedSearch._id.toString(), + threshold: 50, + thresholdType: 'above', + interval: '5m', + channel: { type: 'webhook', webhookId: webhook._id.toString() }, + }); + + expect(result.isError).toBeFalsy(); + const output = JSON.parse(getFirstText(result)); + expect(output.note).toBeNull(); + expect(output.numConsecutiveWindows).toBeNull(); + + const persisted = await Alert.findById(output.id); + expect(persisted?.note).toBeNull(); + expect(persisted?.numConsecutiveWindows).toBeNull(); + }); + it('should create an alert with an explicit displayName and tags', async () => { const savedSearch = await createTestSavedSearch(); const webhook = await createTestWebhook(); From fdec51956f4052cbf45d45f5aa403f2c78fef76c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20Kupczy=C5=84ski?= Date: Tue, 17 Nov 2026 16:19:20 +0100 Subject: [PATCH 3/3] refactor: share the numConsecutiveWindows schema 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. --- .changeset/mcp-save-alert-note-windows.md | 1 + packages/api/src/mcp/tools/alerts/schemas.ts | 17 ++++++----------- packages/api/src/utils/zod.ts | 3 ++- packages/app/src/DBSearchPageAlertModal.tsx | 5 ++--- .../src/components/alerts/EditAlertModal.tsx | 5 ++--- packages/common-utils/src/types.ts | 12 ++++++++++-- 6 files changed, 23 insertions(+), 20 deletions(-) diff --git a/.changeset/mcp-save-alert-note-windows.md b/.changeset/mcp-save-alert-note-windows.md index 6cc330fab..0888a1fd7 100644 --- a/.changeset/mcp-save-alert-note-windows.md +++ b/.changeset/mcp-save-alert-note-windows.md @@ -1,4 +1,5 @@ --- +'@hyperdx/common-utils': patch '@hyperdx/api': patch --- diff --git a/packages/api/src/mcp/tools/alerts/schemas.ts b/packages/api/src/mcp/tools/alerts/schemas.ts index b9968ff64..af568f546 100644 --- a/packages/api/src/mcp/tools/alerts/schemas.ts +++ b/packages/api/src/mcp/tools/alerts/schemas.ts @@ -3,6 +3,7 @@ import { alertDisplayNameSchema, type AlertInterval, alertNoteSchema, + alertNumConsecutiveWindowsSchema, checkAlertChannelSelection, isRangeThresholdType, MAX_ALERT_CHANNELS, @@ -245,17 +246,11 @@ export const mcpSaveAlertSchema = z.object({ 'stored value or send null to clear it.', ), - numConsecutiveWindows: z - .number() - .int() - .min(1) - .nullable() - .optional() - .describe( - 'Fire only after the threshold condition is met in this many ' + - 'consecutive evaluation windows; 1 fires on the first. On update, ' + - 'omit to keep the stored value or send null to clear it.', - ), + numConsecutiveWindows: alertNumConsecutiveWindowsSchema.describe( + 'Fire only after the threshold condition is met in this many ' + + 'consecutive evaluation windows; 1 fires on the first. On update, ' + + 'omit to keep the stored value or send null to clear it.', + ), // Channel channel: mcpAlertChannelSchema.optional(), diff --git a/packages/api/src/utils/zod.ts b/packages/api/src/utils/zod.ts index 2542a9d4a..ff46115ee 100644 --- a/packages/api/src/utils/zod.ts +++ b/packages/api/src/utils/zod.ts @@ -5,6 +5,7 @@ import { AlertChartConfigSchema, alertDisplayNameSchema, alertNoteSchema, + alertNumConsecutiveWindowsSchema, alertTagsSchema, AlertThresholdType, BackgroundChartSchema, @@ -1239,7 +1240,7 @@ const alertBaseSchema = z.object({ note: alertNoteSchema, displayName: alertDisplayNameSchema, tags: alertTagsSchema, - numConsecutiveWindows: z.number().int().min(1).nullish(), + numConsecutiveWindows: alertNumConsecutiveWindowsSchema, }); // External v2 alert schema. Inline alerts carry their chart config in the diff --git a/packages/app/src/DBSearchPageAlertModal.tsx b/packages/app/src/DBSearchPageAlertModal.tsx index 2207e6ec6..5284b2db2 100644 --- a/packages/app/src/DBSearchPageAlertModal.tsx +++ b/packages/app/src/DBSearchPageAlertModal.tsx @@ -14,6 +14,7 @@ import { type Alert, alertDisplayNameSchema, AlertIntervalSchema, + alertNumConsecutiveWindowsSchema, AlertSource, alertTagsSchema, AlertThresholdType, @@ -91,9 +92,7 @@ const SavedSearchAlertFormSchema = z channels: zAlertChannels, displayName: alertDisplayNameSchema, tags: alertTagsSchema, - // nullish() (not optional()): persisted alerts store this as null, which - // optional() would reject. - numConsecutiveWindows: z.number().int().min(1).nullish(), + numConsecutiveWindows: alertNumConsecutiveWindowsSchema, }) .passthrough() .superRefine(validateAlertScheduleOffsetMinutes) diff --git a/packages/app/src/components/alerts/EditAlertModal.tsx b/packages/app/src/components/alerts/EditAlertModal.tsx index c0864bbe0..b044e7944 100644 --- a/packages/app/src/components/alerts/EditAlertModal.tsx +++ b/packages/app/src/components/alerts/EditAlertModal.tsx @@ -7,6 +7,7 @@ import { type Alert, alertDisplayNameSchema, AlertIntervalSchema, + alertNumConsecutiveWindowsSchema, AlertSource, alertTagsSchema, AlertThresholdType, @@ -74,9 +75,7 @@ const EditAlertFormSchema = z channels: zAlertChannels.optional(), displayName: alertDisplayNameSchema, tags: alertTagsSchema, - // nullish() (not optional()): persisted alerts store this as null, which - // optional() would reject. - numConsecutiveWindows: z.number().int().min(1).nullish(), + numConsecutiveWindows: alertNumConsecutiveWindowsSchema, }) .passthrough() .superRefine(validateAlertChannelSelection) diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index 75b4dda70..341fb0939 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -1090,6 +1090,14 @@ export type TagResourceType = z.infer; export const alertNoteSchema = z.string().min(1).max(4096).nullish(); +// nullish() (not optional()): persisted alerts store this as null, which +// optional() would reject. +export const alertNumConsecutiveWindowsSchema = z + .number() + .int() + .min(1) + .nullish(); + export const MAX_ALERT_DISPLAY_NAME_LENGTH = 512; export const alertDisplayNameSchema = z .string() @@ -1128,7 +1136,7 @@ export const AlertBaseObjectSchema = z.object({ until: z.string(), }) .optional(), - numConsecutiveWindows: z.number().int().min(1).nullish(), + numConsecutiveWindows: alertNumConsecutiveWindowsSchema, }); // Keep AlertBaseSchema as a ZodObject for backwards compatibility with @@ -3151,7 +3159,7 @@ export const AlertsPageItemSchema = z.object({ }) .optional(), executionErrors: z.array(AlertErrorSchema).optional(), - numConsecutiveWindows: z.number().int().min(1).nullish(), + numConsecutiveWindows: alertNumConsecutiveWindowsSchema, }); export type AlertsPageItem = z.infer;