Repository navigation
feat(mcp): declare all four behavior hints on every tool - #3395
Conversation
🦋 Changeset detectedLatest commit: dc4bc54 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Duplicate code analysisNo new duplicate code introduced by this PR. jscpd compared this branch against |
[Low impact] The PR appears safe to merge with the documented downstream EE updates. SummaryAdds shared presets declaring all four MCP behavior hints, requires them in
Reviews (4) · Last reviewed commit: "Merge branch 'main' into agent/mcp-tool-..." · Reviewed by Greptile |
E2E Test Results✅ All tests passed • 436 passed • 1 skipped • 1455s
Tests ran across 4 shards in parallel. |
🔵 Tier 2 — Low RiskSmall, isolated change with no API route or data model modifications. Why this tier:
Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns. Stats
|
PR Review
1 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 1 minor None could be anchored to changed lines; they are listed below. Findings outside the changed lines1 minor
Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides. |
Deep Review✅ No critical issues found. This PR is a mechanical, low-risk change: it introduces three shared annotation presets ( 🟡 P2 -- recommended
🔵 P3 nitpicks (1)
Reviewers (7): correctness, testing, maintainability, kieran-typescript, api-contract, security, previous-comments. Testing gaps:
No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond |
jordan-simonovski
left a comment
There was a problem hiding this comment.
Approved with one possible improvement we could make
| * 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 = { |
There was a problem hiding this comment.
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,
};There was a problem hiding this comment.
Good point, will handle this in EE for now
Summary
MCP compatibility checks fail any tool that does not declare
readOnlyHint,destructiveHint,idempotentHint, andopenWorldHintas booleans. Each tool set only one hint before this change.packages/api/src/mcp/tools/annotations.ts:READ_ONLY_TOOLfor get/list/query tools.UPSERT_TOOLfor create-or-update tools. They are not idempotent: omittingidcreates a new object on every call.IDEMPOTENT_DESTRUCTIVE_TOOLfordelete_*andpatch_dashboard.openWorldHintisfalseon every tool, because tools only touch the team's own Mongo metadata and ClickHouse data.RegisterToolFnnow requires all four hints, so a new tool without them fails to compile.packages/api/src/mcp/__tests__/toolAnnotations.test.ts.Downstream (EE) impact: the EE-only tools
clickstack_get_source_filter_values,clickstack_backtest_anomaly_alert, andclickstack_list_teamswill fail typecheck on the upstream merge until they get annotations.How to reproduce
Starting point: local full stack (
yarn dev) withnpx @modelcontextprotocol/inspectorconnected to the local MCP endpoint (seeMCP.md).On
main:initialize, thentools/list.annotationshas only one hint set.On this branch:
initialize, thentools/list.annotationshas all four hints set as booleans.How to test on Vercel preview
N/A — non-UI change.
References
agent/mcp-tool-descriptions(independent; touches neighboring lines, but the two 3-way merge cleanly)