diff --git a/.changeset/mcp-tool-annotations.md b/.changeset/mcp-tool-annotations.md new file mode 100644 index 0000000000..0f5f65f677 --- /dev/null +++ b/.changeset/mcp-tool-annotations.md @@ -0,0 +1,5 @@ +--- +'@hyperdx/api': patch +--- + +feat(mcp): declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint on every MCP tool diff --git a/packages/api/src/mcp/__tests__/toolAnnotations.test.ts b/packages/api/src/mcp/__tests__/toolAnnotations.test.ts new file mode 100644 index 0000000000..66ea92464f --- /dev/null +++ b/packages/api/src/mcp/__tests__/toolAnnotations.test.ts @@ -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([]); + }); +}); diff --git a/packages/api/src/mcp/tools/alerts/deleteWebhook.ts b/packages/api/src/mcp/tools/alerts/deleteWebhook.ts index ff5265fcac..b2668c0e89 100644 --- a/packages/api/src/mcp/tools/alerts/deleteWebhook.ts +++ b/packages/api/src/mcp/tools/alerts/deleteWebhook.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/alerts/getAlert.ts b/packages/api/src/mcp/tools/alerts/getAlert.ts index d9e223a120..a15ded3708 100644 --- a/packages/api/src/mcp/tools/alerts/getAlert.ts +++ b/packages/api/src/mcp/tools/alerts/getAlert.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/alerts/getWebhook.ts b/packages/api/src/mcp/tools/alerts/getWebhook.ts index 7252276c59..33ce93cef9 100644 --- a/packages/api/src/mcp/tools/alerts/getWebhook.ts +++ b/packages/api/src/mcp/tools/alerts/getWebhook.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/alerts/saveAlert.ts b/packages/api/src/mcp/tools/alerts/saveAlert.ts index e687ed9be8..9c5962026d 100644 --- a/packages/api/src/mcp/tools/alerts/saveAlert.ts +++ b/packages/api/src/mcp/tools/alerts/saveAlert.ts @@ -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, @@ -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 ' + diff --git a/packages/api/src/mcp/tools/alerts/saveWebhook.ts b/packages/api/src/mcp/tools/alerts/saveWebhook.ts index 163d31e2ee..3d0e0f801f 100644 --- a/packages/api/src/mcp/tools/alerts/saveWebhook.ts +++ b/packages/api/src/mcp/tools/alerts/saveWebhook.ts @@ -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, @@ -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 ' + diff --git a/packages/api/src/mcp/tools/annotations.ts b/packages/api/src/mcp/tools/annotations.ts new file mode 100644 index 0000000000..ed8b31b8d7 --- /dev/null +++ b/packages/api/src/mcp/tools/annotations.ts @@ -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 = { + 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, +}; diff --git a/packages/api/src/mcp/tools/dashboards/deleteDashboard.ts b/packages/api/src/mcp/tools/dashboards/deleteDashboard.ts index 54499e0701..d5a1921c04 100644 --- a/packages/api/src/mcp/tools/dashboards/deleteDashboard.ts +++ b/packages/api/src/mcp/tools/dashboards/deleteDashboard.ts @@ -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'; @@ -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.', diff --git a/packages/api/src/mcp/tools/dashboards/getDashboard.ts b/packages/api/src/mcp/tools/dashboards/getDashboard.ts index d03bbb20ee..278e0f5339 100644 --- a/packages/api/src/mcp/tools/dashboards/getDashboard.ts +++ b/packages/api/src/mcp/tools/dashboards/getDashboard.ts @@ -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'; @@ -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.', diff --git a/packages/api/src/mcp/tools/dashboards/getDashboardTile.ts b/packages/api/src/mcp/tools/dashboards/getDashboardTile.ts index 6493406349..43230b4290 100644 --- a/packages/api/src/mcp/tools/dashboards/getDashboardTile.ts +++ b/packages/api/src/mcp/tools/dashboards/getDashboardTile.ts @@ -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'; @@ -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. ' + diff --git a/packages/api/src/mcp/tools/dashboards/patchDashboard.ts b/packages/api/src/mcp/tools/dashboards/patchDashboard.ts index 05689c80af..d966571acd 100644 --- a/packages/api/src/mcp/tools/dashboards/patchDashboard.ts +++ b/packages/api/src/mcp/tools/dashboards/patchDashboard.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/dashboards/queryTile.ts b/packages/api/src/mcp/tools/dashboards/queryTile.ts index 77024d98fb..c05153c190 100644 --- a/packages/api/src/mcp/tools/dashboards/queryTile.ts +++ b/packages/api/src/mcp/tools/dashboards/queryTile.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/dashboards/queryTiles.ts b/packages/api/src/mcp/tools/dashboards/queryTiles.ts index 35b71c66f5..443076db76 100644 --- a/packages/api/src/mcp/tools/dashboards/queryTiles.ts +++ b/packages/api/src/mcp/tools/dashboards/queryTiles.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/dashboards/saveDashboard.ts b/packages/api/src/mcp/tools/dashboards/saveDashboard.ts index f757ac576a..477f55d692 100644 --- a/packages/api/src/mcp/tools/dashboards/saveDashboard.ts +++ b/packages/api/src/mcp/tools/dashboards/saveDashboard.ts @@ -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'; @@ -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. ' + diff --git a/packages/api/src/mcp/tools/dashboards/searchDashboards.ts b/packages/api/src/mcp/tools/dashboards/searchDashboards.ts index 908c045ef0..c10977c85e 100644 --- a/packages/api/src/mcp/tools/dashboards/searchDashboards.ts +++ b/packages/api/src/mcp/tools/dashboards/searchDashboards.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/query/emergingSignals.ts b/packages/api/src/mcp/tools/query/emergingSignals.ts index ca776f7d24..a29decf503 100644 --- a/packages/api/src/mcp/tools/query/emergingSignals.ts +++ b/packages/api/src/mcp/tools/query/emergingSignals.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/query/eventDeltas.ts b/packages/api/src/mcp/tools/query/eventDeltas.ts index 5c4d51d7f0..95824415ef 100644 --- a/packages/api/src/mcp/tools/query/eventDeltas.ts +++ b/packages/api/src/mcp/tools/query/eventDeltas.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/query/eventPatterns.ts b/packages/api/src/mcp/tools/query/eventPatterns.ts index 43dea0a7a4..fc27683a1e 100644 --- a/packages/api/src/mcp/tools/query/eventPatterns.ts +++ b/packages/api/src/mcp/tools/query/eventPatterns.ts @@ -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'; @@ -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 ' + diff --git a/packages/api/src/mcp/tools/query/search.ts b/packages/api/src/mcp/tools/query/search.ts index 036c33b67e..ca78c83215 100644 --- a/packages/api/src/mcp/tools/query/search.ts +++ b/packages/api/src/mcp/tools/query/search.ts @@ -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'; @@ -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, ' + diff --git a/packages/api/src/mcp/tools/query/sql.ts b/packages/api/src/mcp/tools/query/sql.ts index 1ddcc32d68..28ac32a851 100644 --- a/packages/api/src/mcp/tools/query/sql.ts +++ b/packages/api/src/mcp/tools/query/sql.ts @@ -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'; @@ -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, 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 ' + diff --git a/packages/api/src/mcp/tools/query/table.ts b/packages/api/src/mcp/tools/query/table.ts index 687dd7370d..6c757bd33e 100644 --- a/packages/api/src/mcp/tools/query/table.ts +++ b/packages/api/src/mcp/tools/query/table.ts @@ -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'; @@ -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, ' + diff --git a/packages/api/src/mcp/tools/query/timeseries.ts b/packages/api/src/mcp/tools/query/timeseries.ts index a81cdfe1b4..32e75268fb 100644 --- a/packages/api/src/mcp/tools/query/timeseries.ts +++ b/packages/api/src/mcp/tools/query/timeseries.ts @@ -1,6 +1,7 @@ import { FIXED_TIME_BUCKET_EXPR_ALIAS } from '@hyperdx/common-utils/dist/core/renderChartConfig'; 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'; @@ -77,7 +78,7 @@ export function registerTimeseries({ context, registerTool }: ToolRegistrar) { 'clickstack_timeseries', { title: 'Time-Series Chart', - annotations: { readOnlyHint: true }, + annotations: READ_ONLY_TOOL, description: 'Plot metrics over time as a line or stacked bar chart. ' + 'Use this when you need to visualize trends, compare time-series, ' + diff --git a/packages/api/src/mcp/tools/savedSearches/getSavedSearch.ts b/packages/api/src/mcp/tools/savedSearches/getSavedSearch.ts index 4d18f316ec..0499780014 100644 --- a/packages/api/src/mcp/tools/savedSearches/getSavedSearch.ts +++ b/packages/api/src/mcp/tools/savedSearches/getSavedSearch.ts @@ -2,6 +2,7 @@ import { z } from 'zod'; import * as config from '@/config'; import { getSavedSearch } from '@/controllers/savedSearch'; +import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpUserError, validateObjectId } from '@/mcp/utils/errors'; import { SavedSearch } from '@/models/savedSearch'; @@ -17,7 +18,7 @@ export function registerGetSavedSearch({ 'clickstack_get_saved_search', { title: 'Get Saved Search(es)', - annotations: { readOnlyHint: true }, + annotations: READ_ONLY_TOOL, description: 'Without an ID: list all saved searches as a high-level summary ' + '(id, name, tags). ' + diff --git a/packages/api/src/mcp/tools/savedSearches/saveSavedSearch.ts b/packages/api/src/mcp/tools/savedSearches/saveSavedSearch.ts index 5522954597..3ed1421c81 100644 --- a/packages/api/src/mcp/tools/savedSearches/saveSavedSearch.ts +++ b/packages/api/src/mcp/tools/savedSearches/saveSavedSearch.ts @@ -5,6 +5,7 @@ import { updateSavedSearch, } from '@/controllers/savedSearch'; import { getSource } from '@/controllers/sources'; +import { UPSERT_TOOL } from '@/mcp/tools/annotations'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpServerError, @@ -25,7 +26,7 @@ export function registerSaveSavedSearch({ 'clickstack_save_saved_search', { title: 'Create or Update Saved Search', - annotations: { destructiveHint: true }, + annotations: UPSERT_TOOL, description: 'Create a new saved search (omit id) or update an existing one (provide id). ' + 'A saved search stores a reusable query (select, where, orderBy, filters) ' + diff --git a/packages/api/src/mcp/tools/sources/deleteSource.ts b/packages/api/src/mcp/tools/sources/deleteSource.ts index 3518a96912..be9850735a 100644 --- a/packages/api/src/mcp/tools/sources/deleteSource.ts +++ b/packages/api/src/mcp/tools/sources/deleteSource.ts @@ -1,6 +1,7 @@ import { z } from 'zod'; import { deleteSource } from '@/controllers/sources'; +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'; @@ -15,7 +16,7 @@ export function registerDeleteSource({ 'clickstack_delete_source', { title: 'Delete Source', - annotations: { destructiveHint: true }, + annotations: IDEMPOTENT_DESTRUCTIVE_TOOL, description: 'Permanently delete a data source by ID. Other sources may reference ' + 'it (e.g. a trace source linked to a log source) — those links are ' + diff --git a/packages/api/src/mcp/tools/sources/describeMetric.ts b/packages/api/src/mcp/tools/sources/describeMetric.ts index 8131235605..36ccec9ca8 100644 --- a/packages/api/src/mcp/tools/sources/describeMetric.ts +++ b/packages/api/src/mcp/tools/sources/describeMetric.ts @@ -13,6 +13,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 { clickHouseErrorResult, parseTimeRange, @@ -713,7 +714,7 @@ export function registerDescribeMetric({ 'clickstack_describe_metric', { title: 'Describe Metric', - annotations: { readOnlyHint: true }, + annotations: READ_ONLY_TOOL, description: 'DRILL-DOWN: Use after clickstack_list_metrics (or after a clickstack_describe_source ' + 'sample) to get attribute keys, sampled values, unit, and description for a ' + diff --git a/packages/api/src/mcp/tools/sources/describeSource.ts b/packages/api/src/mcp/tools/sources/describeSource.ts index 193a6f0a6d..4be29904da 100644 --- a/packages/api/src/mcp/tools/sources/describeSource.ts +++ b/packages/api/src/mcp/tools/sources/describeSource.ts @@ -12,6 +12,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, ToolResult } from '@/mcp/tools/types'; import { mcpServerError, mcpUserError } from '@/mcp/utils/errors'; import { @@ -555,7 +556,7 @@ export function registerDescribeSource({ 'clickstack_describe_source', { title: 'Describe Source Schema', - annotations: { readOnlyHint: true }, + annotations: READ_ONLY_TOOL, description: 'CALL THIS BEFORE WRITING QUERIES — prevents unknown-column errors.\n\n' + 'Returns the full column schema, map-attribute keys, and sampled low-cardinality ' + diff --git a/packages/api/src/mcp/tools/sources/listMetrics.ts b/packages/api/src/mcp/tools/sources/listMetrics.ts index a3fe42b9d7..5c373197b2 100644 --- a/packages/api/src/mcp/tools/sources/listMetrics.ts +++ b/packages/api/src/mcp/tools/sources/listMetrics.ts @@ -6,6 +6,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 { parseTimeRange } from '@/mcp/tools/query/helpers'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpServerError, mcpUserError } from '@/mcp/utils/errors'; @@ -51,7 +52,7 @@ export function registerListMetrics({ 'clickstack_list_metrics', { title: 'List Metric Names', - annotations: { readOnlyHint: true }, + annotations: READ_ONLY_TOOL, description: 'DISCOVERY: Use this after clickstack_describe_source when you need more metric ' + 'names than the per-kind sample shows, or when you want to narrow by ' + diff --git a/packages/api/src/mcp/tools/sources/listSources.ts b/packages/api/src/mcp/tools/sources/listSources.ts index 48cc7a3106..0cc36b9a5e 100644 --- a/packages/api/src/mcp/tools/sources/listSources.ts +++ b/packages/api/src/mcp/tools/sources/listSources.ts @@ -17,6 +17,7 @@ import { getConnectionsByTeam, } from '@/controllers/connection'; import { getSources } from '@/controllers/sources'; +import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { runWithTimeout } from '@/mcp/utils/timeout'; import logger from '@/utils/logger'; @@ -206,7 +207,7 @@ export function registerListSources({ 'clickstack_list_sources', { title: 'List Sources & Connections', - annotations: { readOnlyHint: true }, + annotations: READ_ONLY_TOOL, description: 'List all data sources (logs, metrics, traces) and database connections available to this team. ' + 'Returns source IDs, names, kinds, and connection IDs as a lightweight catalog. ' + diff --git a/packages/api/src/mcp/tools/sources/saveSource.ts b/packages/api/src/mcp/tools/sources/saveSource.ts index 93622651bb..f796c32ce3 100644 --- a/packages/api/src/mcp/tools/sources/saveSource.ts +++ b/packages/api/src/mcp/tools/sources/saveSource.ts @@ -4,6 +4,7 @@ import mongoose from 'mongoose'; import * as config from '@/config'; import { validateConnectionId } from '@/controllers/connection'; import { createSource, getSource, updateSource } from '@/controllers/sources'; +import { UPSERT_TOOL } from '@/mcp/tools/annotations'; import type { ToolRegistrar } from '@/mcp/tools/types'; import { mcpServerError, @@ -25,7 +26,7 @@ export function registerSaveSource({ 'clickstack_save_source', { title: 'Create or Update Source', - annotations: { destructiveHint: true }, + annotations: UPSERT_TOOL, description: 'Create a new data source (omit id) or update an existing one ' + '(provide id) so shipped telemetry becomes queryable. Update is a ' + diff --git a/packages/api/src/mcp/tools/trace/breakdown.ts b/packages/api/src/mcp/tools/trace/breakdown.ts index 9a7263097d..e480c2a566 100644 --- a/packages/api/src/mcp/tools/trace/breakdown.ts +++ b/packages/api/src/mcp/tools/trace/breakdown.ts @@ -20,6 +20,7 @@ import { getMetadata } from '@hyperdx/common-utils/dist/core/metadata'; import { SourceKind } from '@hyperdx/common-utils/dist/types'; import { getSource } from '@/controllers/sources'; +import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import { clickHouseErrorResult, isQueryOutOfTime, @@ -64,7 +65,7 @@ export function registerTraceBreakdown({ 'clickstack_trace_top_time_consuming_operations', { title: 'Top Time-Consuming Operations Across Matching Traces', - annotations: { readOnlyHint: true }, + annotations: READ_ONLY_TOOL, description: TRACE_BREAKDOWN_DESCRIPTION, inputSchema: traceBreakdownSchema, }, diff --git a/packages/api/src/mcp/tools/trace/waterfall.ts b/packages/api/src/mcp/tools/trace/waterfall.ts index 234e3bc3f6..46d9125a1c 100644 --- a/packages/api/src/mcp/tools/trace/waterfall.ts +++ b/packages/api/src/mcp/tools/trace/waterfall.ts @@ -12,6 +12,7 @@ import { z } from 'zod'; import type { ClickhouseClient } from '@/clickhouse'; import { getSource } from '@/controllers/sources'; +import { READ_ONLY_TOOL } from '@/mcp/tools/annotations'; import { clickHouseErrorResult, MCP_CLICKHOUSE_SETTINGS, @@ -310,7 +311,7 @@ export function registerTraceWaterfall({ 'clickstack_trace_waterfall', { title: 'Trace Waterfall (single trace)', - annotations: { readOnlyHint: true }, + annotations: READ_ONLY_TOOL, description: 'Fetch every span in ONE trace as a parent/child waterfall, pre-ordered for ' + 'reading. Use it for "show me an example trace" or "what happened in trace X" ' + diff --git a/packages/api/src/mcp/tools/types.ts b/packages/api/src/mcp/tools/types.ts index 8a055c20e0..920c6b94a6 100644 --- a/packages/api/src/mcp/tools/types.ts +++ b/packages/api/src/mcp/tools/types.ts @@ -5,6 +5,7 @@ import type { } from '@modelcontextprotocol/sdk/types.js'; import type { AnyZodObject } from 'zod'; +import type { ToolBehaviorAnnotations } from '@/mcp/tools/annotations'; import type { McpClientInfo } from '@/mcp/utils/mcpClient'; export type McpContext = { @@ -41,10 +42,11 @@ export type RegisterToolFn = ( description: string; inputSchema: TSchema; /** - * Advisory MCP tool annotations (readOnlyHint, destructiveHint, etc.). - * These are hints only — clients must not rely on them for safety. + * Advisory MCP tool annotations. All four behavior hints are required; + * use the presets in `./annotations`. These are hints only — clients + * must not rely on them for safety. */ - annotations?: ToolAnnotations; + annotations: ToolAnnotations & ToolBehaviorAnnotations; }, handler: (args: TSchema['_output']) => Promise, ) => void;