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
6 changes: 6 additions & 0 deletions .changeset/mcp-tool-descriptions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@hyperdx/api': patch
'@hyperdx/common-utils': patch
---

fix(mcp): describe every MCP tool input, drop descriptions that restate schema constraints, and keep tool descriptions under Claude Code's 2 KB limit
32 changes: 32 additions & 0 deletions packages/api/src/mcp/__tests__/toolDescriptions.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
import { McpContext } from '@/mcp/tools/types';

import { createTestClient } from './mcpTestUtils';

describe('MCP tool descriptions', () => {
Comment thread
brandon-pereira marked this conversation as resolved.
Resolved
const context: McpContext = { teamId: 'team-id', userId: 'user-id' };

// Claude Code truncates tool descriptions and server instructions past
// this many UTF-8 bytes.
const CLAUDE_CODE_METADATA_LIMIT = 2048;

it('keeps tool descriptions and server instructions within the Claude Code limit', async () => {
const client = await createTestClient(context);
const { tools } = await client.listTools();
expect(tools.length).toBeGreaterThan(0);

const texts = [
['instructions', client.getInstructions() ?? ''] as const,
...tools.map(tool => [tool.name, tool.description ?? ''] as const),
];

expect(
texts.filter(([, text]) => text.trim() === '').map(([name]) => name),
).toEqual([]);

const oversized = texts
.map(([name, text]) => [name, Buffer.byteLength(text, 'utf8')] as const)
.filter(([, bytes]) => bytes > CLAUDE_CODE_METADATA_LIMIT);

Comment thread
brandon-pereira marked this conversation as resolved.
Resolved
Comment thread
brandon-pereira marked this conversation as resolved.
Resolved
expect(oversized).toEqual([]);
});
});
57 changes: 49 additions & 8 deletions packages/api/src/mcp/__tests__/toolSchemas.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,10 +79,25 @@ describe('MCP tool input schemas', () => {

expect(tools.length).toBeGreaterThan(0);

const offenders = tools.flatMap(tool => walk(tool.inputSchema, tool.name));
const offenders = tools.flatMap(tool =>
walk(tool.inputSchema, tool.name, providerRejections),
);

expect(offenders).toEqual([]);
});

it('describe every input property', async () => {
const client = await createTestClient(context);
const { tools } = await client.listTools();

expect(tools.length).toBeGreaterThan(0);

const missing = tools.flatMap(tool =>
walk(tool.inputSchema, tool.name, undescribedProperties),
);

expect(missing).toEqual([]);
});
});

function isRecord(value: unknown): value is Record<string, unknown> {
Expand All @@ -93,13 +108,26 @@ function isUnknownArray(value: unknown): value is unknown[] {
return Array.isArray(value);
}

/** JSON pointer path -> problem, for every offending node under `node`. */
function walk(node: unknown, path: string): string[] {
type SchemaCheck = (node: Record<string, unknown>, path: string) => string[];

/** JSON pointer path -> problem, for every node under `node` that fails `check`. */
function walk(node: unknown, path: string, check: SchemaCheck): string[] {
if (isUnknownArray(node)) {
return node.flatMap((child, i) => walk(child, `${path}/${i}`));
return node.flatMap((child, i) => walk(child, `${path}/${i}`, check));
}
if (!isRecord(node)) return [];

const found = check(node, path);
for (const [key, value] of Object.entries(node)) {
found.push(...walk(value, `${path}/${key}`, check));
}
return found;
}

function providerRejections(
node: Record<string, unknown>,
path: string,
): string[] {
const found: string[] = [];

const enumValues = node.enum;
Expand All @@ -120,9 +148,22 @@ function walk(node: unknown, path: string): string[] {
);
}

for (const [key, value] of Object.entries(node)) {
found.push(...walk(value, `${path}/${key}`));
}

return found;
}

function undescribedProperties(
node: Record<string, unknown>,
path: string,
): string[] {
if (!isRecord(node.properties)) return [];
return Object.entries(node.properties).flatMap(([key, prop]) => {
if (!isRecord(prop)) return [];
// zod-to-json-schema dedupes a reused schema into a bare $ref pointer;
// the description lives on the referenced definition.
if (Object.keys(prop).length === 1 && '$ref' in prop) return [];
const { description } = prop;
return typeof description === 'string' && description.trim() !== ''
? []
: [`${path}/properties/${key}: missing description`];
});
}
4 changes: 3 additions & 1 deletion packages/api/src/mcp/tools/alerts/deleteWebhook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,9 @@ export function registerDeleteWebhook({
'references it — reassign or delete those alerts first. Use ' +
'clickstack_get_webhook to list available webhook IDs.',
inputSchema: z.object({
id: objectIdSchema.describe('Webhook ID to delete.'),
id: objectIdSchema.describe(
'ID of the webhook to delete, from clickstack_get_webhook.',
),
}),
},
async ({ id: webhookId }) => {
Expand Down
7 changes: 4 additions & 3 deletions packages/api/src/mcp/tools/alerts/getAlert.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,14 +38,15 @@ export function registerGetAlert({
.string()
.optional()
.describe(
'Alert ID. Omit to list all alerts, provide to get full detail.',
'Alert ID from a previous list call or clickstack_save_alert. ' +
'Omit to list all alerts, provide to get full detail.',
),
state: z
.enum(['ALERT', 'OK', 'DISABLED', 'INSUFFICIENT_DATA'])
.optional()
.describe(
'Filter list by alert state (only applies when id is omitted). ' +
'Use "ALERT" to find currently firing alerts.',
'List only alerts currently in this state; ignored when id is ' +
'provided. Use ALERT to find alerts that are firing now.',
),
}),
},
Expand Down
18 changes: 12 additions & 6 deletions packages/api/src/mcp/tools/alerts/saveAlert.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,18 @@ export function registerSaveAlert({
'Create a new alert (omit id) or update an existing one (provide id). ' +
'Alerts monitor a saved search, a dashboard tile, or an inline chart ' +
'config (source "inline" + chartConfig — no saved search or dashboard ' +
'needed) and fire when the metric crosses a threshold. At least one ' +
'webhook notification channel ' +
'is required: pass "channels" for 1-10 targets, or the legacy singular ' +
'"channel" for one. Updates replace the alert configuration rather than ' +
'merging it, so read the alert first and resend its full "channels" ' +
'array to avoid dropping channels you did not mean to remove.',
'needed) and fire when the metric crosses a threshold. Once saved, the ' +
'alert is evaluated every interval and notifies its webhook channels ' +
'when it fires and when it resolves. At least one webhook channel is ' +
'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 ' +
'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.',
inputSchema: mcpSaveAlertSchema,
},
async input => {
Expand Down
33 changes: 21 additions & 12 deletions packages/api/src/mcp/tools/alerts/saveWebhook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,16 @@ const mcpSaveWebhookSchema = z.object({
.string()
.optional()
.describe(
'Webhook ID. Omit to create a new webhook, provide to update an existing one.',
'Webhook ID from clickstack_get_webhook. Omit to create a new ' +
'webhook, provide to update an existing one.',
),
name: z
.string()
.min(1)
.describe(
"Display name for the webhook. Must be unique among the team's " +
'webhooks of the same service.',
),
name: z.string().min(1).describe('Human-friendly webhook name.'),
service: z
.enum(WEBHOOK_SERVICES)
.describe(
Expand All @@ -48,14 +55,14 @@ const mcpSaveWebhookSchema = z.object({
.string()
.optional()
.describe(
'Optional description shown in the UI. On update this is a full replace: ' +
'Description shown in the UI. On update this is a full replace: ' +
'omitting it clears the stored description.',
),
headers: z
.record(z.string(), z.string())
.optional()
.describe(
'Optional HTTP headers (key -> value). Not supported for the slack ' +
'HTTP headers sent with each request. Not supported for the slack ' +
'service. On update these are write-only: omitting them PRESERVES the ' +
'stored values; send an empty object ({}) to clear them. If the ' +
'destination (url or service) changes, omitted headers are cleared.',
Expand All @@ -64,14 +71,14 @@ const mcpSaveWebhookSchema = z.object({
.record(z.string(), z.string())
.optional()
.describe(
'Optional query parameters (key -> value). Not supported for the slack ' +
'Query parameters appended to the URL. Not supported for the slack ' +
'service. Same write-only update semantics as headers.',
),
body: z
.string()
.optional()
.describe(
'Optional Handlebars request body template. Not supported for the ' +
'Handlebars template for the request body. Not supported for the ' +
'slack service. Rejected if it does not compile or calls a helper ' +
'other than eq and the Handlebars built-ins. Write string ' +
'arguments inside {{ }} with plain or single quotes, e.g. ' +
Expand All @@ -94,12 +101,14 @@ export function registerSaveWebhook({
description:
'Create a new webhook (omit id) or update an existing one (provide ' +
'id). Use the returned id as the webhookId when creating alerts with ' +
'clickstack_save_alert. Required: name, service (slack, generic, or ' +
'incidentio), and url. For the slack service the url host must end in ' +
'slack.com and headers/queryParams/body are not supported. On update, ' +
'readable fields (description, body) are a full replace while ' +
'write-only headers/queryParams are preserved when omitted (send {} to ' +
'clear); changing the destination clears omitted write-only secrets.',
'clickstack_save_alert. For the slack service the url host must end ' +
'in slack.com and headers/queryParams/body are not supported. On ' +
'update, every alert using this webhook sends its next notifications ' +
'with the new settings, including a changed url. description and body ' +
'are a full replace (omitting them clears them), while write-only ' +
'headers/queryParams are preserved when omitted (send {} to clear); ' +
'changing url or service clears omitted headers/queryParams. ' +
'url, headers, and queryParams are never returned.',
inputSchema: mcpSaveWebhookSchema,
},
async input => {
Expand Down
Loading
Loading