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

feat(mcp): declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint on every MCP tool
26 changes: 26 additions & 0 deletions packages/api/src/mcp/__tests__/toolAnnotations.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
import { McpContext } from '@/mcp/tools/types';

import { createTestClient } from './mcpTestUtils';

describe('MCP tool annotations', () => {
const context: McpContext = { teamId: 'team-id', userId: 'user-id' };

it('declares every behavior hint as a boolean on every tool', async () => {
const client = await createTestClient(context);
const { tools } = await client.listTools();
expect(tools.length).toBeGreaterThan(0);

const missing = tools.flatMap(tool =>
Object.entries({
readOnlyHint: tool.annotations?.readOnlyHint,
destructiveHint: tool.annotations?.destructiveHint,
idempotentHint: tool.annotations?.idempotentHint,
openWorldHint: tool.annotations?.openWorldHint,
})
.filter(([, value]) => typeof value !== 'boolean')
.map(([hint]) => `${tool.name}.annotations.${hint}`),
);

expect(missing).toEqual([]);
});
});
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/alerts/deleteWebhook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import mongoose from 'mongoose';
import { z } from 'zod';

import { deleteWebhook } from '@/controllers/webhook';
import { IDEMPOTENT_DESTRUCTIVE_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
import { objectIdSchema } from '@/utils/zod';
Expand All @@ -16,7 +17,7 @@ export function registerDeleteWebhook({
'clickstack_delete_webhook',
{
title: 'Delete Webhook',
annotations: { destructiveHint: true },
annotations: IDEMPOTENT_DESTRUCTIVE_TOOL,
description:
'Permanently delete a webhook by ID. Blocked while any alert still ' +
'references it — reassign or delete those alerts first. Use ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/alerts/getAlert.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { z } from 'zod';
import * as config from '@/config';
import { getRecentAlertHistories } from '@/controllers/alertHistory';
import { getAlertById } from '@/controllers/alerts';
import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError, validateObjectId } from '@/mcp/utils/errors';
import Alert from '@/models/alert';
Expand All @@ -25,7 +26,7 @@ export function registerGetAlert({
'clickstack_get_alert',
{
title: 'Get Alert(s)',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Without an ID: list all alerts as a high-level summary ' +
'(id, name, displayName, tags, state, source, interval). Optionally ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/alerts/getWebhook.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import Webhook from '@/models/webhook';

Expand All @@ -13,7 +14,7 @@ export function registerGetWebhook({
'clickstack_get_webhook',
{
title: 'List Webhooks',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'List available webhook destinations (id, name, service type). ' +
'Use the returned id as the webhookId when creating alerts with ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/alerts/saveAlert.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import {
updateAlert,
validateAlertInput,
} from '@/controllers/alerts';
import { UPSERT_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import {
formatZodIssues,
Expand Down Expand Up @@ -42,7 +43,7 @@ export function registerSaveAlert({
'clickstack_save_alert',
{
title: 'Create or Update Alert',
annotations: { destructiveHint: true },
annotations: UPSERT_TOOL,
description:
'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 ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/alerts/saveWebhook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import mongoose from 'mongoose';
import { z } from 'zod';

import { createWebhook, updateWebhook } from '@/controllers/webhook';
import { UPSERT_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import {
mcpServerError,
Expand Down Expand Up @@ -97,7 +98,7 @@ export function registerSaveWebhook({
'clickstack_save_webhook',
{
title: 'Create or Update Webhook',
annotations: { destructiveHint: true },
annotations: UPSERT_TOOL,
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 ' +
Expand Down
44 changes: 44 additions & 0 deletions packages/api/src/mcp/tools/annotations.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';

/**
* The four behavior hints every tool must declare. Platform compatibility
* checks reject tools that leave any of them unset.
*/
export type ToolBehaviorAnnotations = Required<
Pick<
ToolAnnotations,
'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'
>
>;

// Every tool reads or writes only the calling team's own ClickStack metadata
// (MongoDB) and telemetry (ClickHouse), so none of them is open-world.

export const READ_ONLY_TOOL: ToolBehaviorAnnotations = {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
};

/**
* Create-or-update tools: omitting `id` creates a new object on every call
* (not idempotent), and providing `id` overwrites the stored object.
*/
export const UPSERT_TOOL: ToolBehaviorAnnotations = {

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.

OOC could we also add a preset for writes that aren't destructive?
Stuff like add_investigation_note only appends, so it isn't destructive or idempotent, and share_notebook is idempotent but not destructive. Without a matching preset, EE would either hand-write the objects or pick UPSERT_TOOL. Would something like this cover both?

export const APPEND_TOOL: ToolBehaviorAnnotations = {
  readOnlyHint: false,
  destructiveHint: false,
  idempotentHint: false,
  openWorldHint: false,
};

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Good point, will handle this in EE for now

readOnlyHint: false,
destructiveHint: true,
idempotentHint: false,
openWorldHint: false,
};

/**
* Updates or deletes an existing object by ID. Repeating the call with the
* same arguments leaves the same end state.
*/
export const IDEMPOTENT_DESTRUCTIVE_TOOL: ToolBehaviorAnnotations = {
readOnlyHint: false,
destructiveHint: true,
idempotentHint: true,
openWorldHint: false,
};
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/dashboards/deleteDashboard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import mongoose from 'mongoose';
import { z } from 'zod';

import { deleteDashboard } from '@/controllers/dashboard';
import { IDEMPOTENT_DESTRUCTIVE_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
import Dashboard from '@/models/dashboard';
Expand All @@ -17,7 +18,7 @@ export function registerDeleteDashboard({
'clickstack_delete_dashboard',
{
title: 'Delete Dashboard',
annotations: { destructiveHint: true },
annotations: IDEMPOTENT_DESTRUCTIVE_TOOL,
description:
'Permanently delete a dashboard by ID. Also removes any alerts attached to its tiles. ' +
'Use clickstack_get_dashboard (without an ID) to list available dashboard IDs.',
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/dashboards/getDashboard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { z } from 'zod';

import * as config from '@/config';
import { getDashboards } from '@/controllers/dashboard';
import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError, validateObjectId } from '@/mcp/utils/errors';
import Dashboard from '@/models/dashboard';
Expand All @@ -21,7 +22,7 @@ export function registerGetDashboard({
'clickstack_get_dashboard',
{
title: 'Get Dashboard(s)',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Without an ID: list all dashboards (returns IDs, names, tags). ' +
'With an ID: get full dashboard detail including all tiles and configuration.',
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/dashboards/getDashboardTile.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
import Dashboard from '@/models/dashboard';
Expand All @@ -16,7 +17,7 @@ export function registerGetDashboardTile({
'clickstack_get_dashboard_tile',
{
title: 'Get a Single Dashboard Tile',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Retrieve a single tile from a dashboard by tileId. ' +
'Useful for inspecting one tile without loading the full dashboard. ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/dashboards/patchDashboard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { uniq } from 'lodash';

import * as config from '@/config';
import { recordDashboardOnboardingIfHasTiles } from '@/controllers/dashboard';
import { IDEMPOTENT_DESTRUCTIVE_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
import Dashboard from '@/models/dashboard';
Expand Down Expand Up @@ -33,7 +34,7 @@ export function registerPatchDashboard({
'clickstack_patch_dashboard',
{
title: 'Patch Dashboard',
annotations: { destructiveHint: true },
annotations: IDEMPOTENT_DESTRUCTIVE_TOOL,
description:
'Make targeted updates to a dashboard without resubmitting the full object. ' +
'You can update dashboard-level fields (name, tags) and/or replace a single ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/dashboards/queryTile.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import { parseTimeRange, runConfigTile } from '@/mcp/tools/query/helpers';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
Expand All @@ -23,7 +24,7 @@ export function registerQueryTile({
'clickstack_query_tile',
{
title: 'Query a Dashboard Tile',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Execute the query for a specific tile on an existing dashboard. ' +
'Useful for validating that a tile returns data or for spot-checking results ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/dashboards/queryTiles.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import PQueue from '@esm2cjs/p-queue';
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import { parseTimeRange, runConfigTile } from '@/mcp/tools/query/helpers';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
Expand Down Expand Up @@ -166,7 +167,7 @@ export function registerQueryTiles({
'clickstack_query_tiles',
{
title: 'Query Multiple Dashboard Tiles',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Run the queries for many tiles of a dashboard in ONE call and return a ' +
'compact per-tile success/failure summary. This is the efficient way to ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/dashboards/saveDashboard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { z } from 'zod';

import * as config from '@/config';
import { recordDashboardOnboardingIfHasTiles } from '@/controllers/dashboard';
import { UPSERT_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { formatZodIssues, mcpUserError } from '@/mcp/utils/errors';
import Dashboard, { IDashboard } from '@/models/dashboard';
Expand Down Expand Up @@ -42,7 +43,7 @@ export function registerSaveDashboard({
'clickstack_save_dashboard',
{
title: 'Create or Update Dashboard',
annotations: { destructiveHint: true },
annotations: UPSERT_TOOL,
description:
'Create a new dashboard (omit id) or update an existing one (provide id). ' +
'Call clickstack_list_sources first to obtain sourceId and connectionId values. ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/dashboards/searchDashboards.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { escapeRegExp } from 'lodash';

import * as config from '@/config';
import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpServerError, mcpUserError } from '@/mcp/utils/errors';
import Dashboard from '@/models/dashboard';
Expand All @@ -21,7 +22,7 @@ export function registerSearchDashboards({
'clickstack_search_dashboards',
{
title: 'Search Dashboards',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Search dashboards by name and/or tags. Returns matching dashboards with ' +
'their IDs, names, and tags. More targeted than clickstack_get_dashboard (which ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/query/emergingSignals.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
import { trimToolResponse } from '@/utils/trimToolResponse';
Expand Down Expand Up @@ -139,7 +140,7 @@ export function registerEmergingSignals({
'clickstack_emerging_signals',
{
title: 'Emerging & Disappeared Signals',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Detect what is NEW or GONE between an earlier baseline window and a ' +
'current window — log/event patterns that emerged, ramped up, or ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/query/eventDeltas.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import { z } from 'zod';
import { ClickhouseClient } from '@/clickhouse';
import { getConnectionById } from '@/controllers/connection';
import { getSource } from '@/controllers/sources';
import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
import { MCP_QUERY_MAX_EXECUTION_SEC } from '@/mcp/utils/timeout';
Expand Down Expand Up @@ -163,7 +164,7 @@ export function registerEventDeltas({ context, registerTool }: ToolRegistrar) {
'clickstack_event_deltas',
{
title: 'Compare Events: Target vs Baseline',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Rank every attribute of two row groups (logs or trace spans) by how ' +
'much its value distribution differs between a target and a baseline ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/query/eventPatterns.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';

Expand Down Expand Up @@ -73,7 +74,7 @@ export function registerEventPatterns({
'clickstack_event_patterns',
{
title: 'Event Pattern Mining',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Discover the most common log messages and event patterns. ' +
'Samples random events, clusters them using the Drain algorithm, and returns ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/query/search.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';
import logger from '@/utils/logger';
Expand Down Expand Up @@ -62,7 +63,7 @@ export function registerSearch({ context, registerTool }: ToolRegistrar) {
'clickstack_search',
{
title: 'Search Events',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Browse individual log/event/trace rows. ' +
'Use this when you need to see raw events, investigate specific log lines, ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/query/sql.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { hasVariableMacro } from '@hyperdx/common-utils/dist/variables';
import { z } from 'zod';

import { getSource } from '@/controllers/sources';
import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';

Expand Down Expand Up @@ -79,7 +80,7 @@ export function registerSql({ context, registerTool }: ToolRegistrar) {
{
title: 'Raw SQL Query',
// Enforces ClickHouse readonly=2, so effectively read-only.
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
Comment thread
brandon-pereira marked this conversation as resolved.
Resolved
description:
'Execute raw ClickHouse SQL. LAST-RESORT TOOL — do NOT reach for this first.\n\n' +
'Default to the builder tools for querying; they are more reliable and produce ' +
Expand Down
3 changes: 2 additions & 1 deletion packages/api/src/mcp/tools/query/table.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { z } from 'zod';

import { READ_ONLY_TOOL } from '@/mcp/tools/annotations';
import type { ToolRegistrar } from '@/mcp/tools/types';
import { mcpUserError } from '@/mcp/utils/errors';

Expand Down Expand Up @@ -204,7 +205,7 @@ export function registerTable({ context, registerTool }: ToolRegistrar) {
'clickstack_table',
{
title: 'Aggregation Table',
annotations: { readOnlyHint: true },
annotations: READ_ONLY_TOOL,
description:
'Compute aggregated metrics as a table, single number, pie chart, or bar chart. ' +
'Use this for grouped aggregations, top-N queries, single-value KPIs, ' +
Expand Down
Loading
Loading