Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/mcp-save-alert-note-windows.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
'@hyperdx/common-utils': patch
'@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.
171 changes: 171 additions & 0 deletions packages/api/src/mcp/__tests__/alerts.int.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,97 @@ 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.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();
Expand Down Expand Up @@ -1297,6 +1388,86 @@ describe('MCP Alert Tools', () => {
expect(updatedAlert?.tileId).toBeNull();
});

describe('note and numConsecutiveWindows', () => {
async function saveExisting(
alertId: string,
savedSearchId: string,
webhookId: string,
extra: Record<string, unknown> = {},
) {
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();
Expand Down
24 changes: 20 additions & 4 deletions packages/api/src/mcp/tools/alerts/saveAlert.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import * as config from '@/config';
import {
type AlertInput,
createAlert,
getAlertById,
updateAlert,
validateAlertInput,
} from '@/controllers/alerts';
Expand Down Expand Up @@ -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.',
Expand All @@ -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,
Expand Down Expand Up @@ -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,

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)

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.

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)

numConsecutiveWindows:
input.numConsecutiveWindows === undefined
? existing?.numConsecutiveWindows
: input.numConsecutiveWindows,
displayName: input.displayName,
tags: input.tags,
groupBy: input.groupBy,
Expand All @@ -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);
Expand Down
13 changes: 13 additions & 0 deletions packages/api/src/mcp/tools/alerts/schemas.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ import {
ALERT_INTERVAL_TO_MINUTES,
alertDisplayNameSchema,
type AlertInterval,
alertNoteSchema,
alertNumConsecutiveWindowsSchema,
checkAlertChannelSelection,
isRangeThresholdType,
MAX_ALERT_CHANNELS,
Expand Down Expand Up @@ -244,6 +246,12 @@ export const mcpSaveAlertSchema = z.object({
'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(),
channels: z
Expand Down Expand Up @@ -273,6 +281,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.',
),
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/utils/zod.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import {
AlertChartConfigSchema,
alertDisplayNameSchema,
alertNoteSchema,
alertNumConsecutiveWindowsSchema,
alertTagsSchema,
AlertThresholdType,
BackgroundChartSchema,
Expand Down Expand Up @@ -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
Expand Down
5 changes: 2 additions & 3 deletions packages/app/src/DBSearchPageAlertModal.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import {
type Alert,
alertDisplayNameSchema,
AlertIntervalSchema,
alertNumConsecutiveWindowsSchema,
AlertSource,
alertTagsSchema,
AlertThresholdType,
Expand Down Expand Up @@ -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)
Expand Down
5 changes: 2 additions & 3 deletions packages/app/src/components/alerts/EditAlertModal.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import {
type Alert,
alertDisplayNameSchema,
AlertIntervalSchema,
alertNumConsecutiveWindowsSchema,
AlertSource,
alertTagsSchema,
AlertThresholdType,
Expand Down Expand Up @@ -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)
Expand Down
12 changes: 10 additions & 2 deletions packages/common-utils/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1090,6 +1090,14 @@ export type TagResourceType = z.infer<typeof TagResourceTypeSchema>;

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()
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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<typeof AlertsPageItemSchema>;
Expand Down
Loading