CAMEL-24332: MCP tool annotation hints on ai-tool endpoints - #25395
Conversation
Expose optional MCP ToolAnnotations metadata on ai-tool consumer endpoints (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Carry hints through AiToolSpec, McpServerTool SPI, and Vert.x MCP engine. Includes AssertJ tests for configuration parsing, registry lifecycle, bridge passthrough, and Vert.x listTools annotation mapping. Regenerated catalog and DSL metadata. Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Clarify that annotation hints are untrusted UX metadata per the MCP spec, document client default behavior when hints are omitted, and link from mcp-server.adoc to the ai-tool configuration section. Co-authored-by: Cursor <cursoragent@cursor.com>
- Convert AiToolAnnotations to a record (review suggestion) - Add title-only and partial-hint unit/integration tests - Document Tool.title mapping and catalog defaultValue caveat - Regenerate catalog docs Co-authored-by: Cursor <cursoragent@cursor.com>
|
AI-generated comment on behalf of atiaomar1978-hub via Cursor Cloud Agent. Reopened on branch |
davsclaus
left a comment
davsclaus
left a comment
There was a problem hiding this comment.
Review: CAMEL-24332 — MCP tool annotation hints on ai-tool endpoints
Well-structured feature PR. The implementation cleanly spans the appropriate layers (configuration → spec → bridge SPI → Vert.x engine) with good test coverage and documentation.
Highlights
- Clean separation of concerns:
AiToolAnnotationsrecord,AiToolConfigurationfields,AiToolSpecextension,McpServerBridgepassthrough,VertxMcpServerEnginemapping - Proper backward compatibility via
defaultmethod onMcpServerTool - Nullable handling throughout the chain (
null= no annotation = omit from published tool) - Good test coverage: unit tests (
AiToolAnnotationsTest), lifecycle tests, bridge tests, and Vert.x integration tests with a real MCP client - Documentation with Java and YAML examples in both
ai-tool-component.adocandmcp-server.adoc
Note
The catalog JSON shows "defaultValue": false for the boolean hint fields, but at runtime these are Boolean (boxed, initially null) — meaning "hint omitted from published MCP tool." The MCP spec distinguishes between "hint absent" and "hint = false." The documentation correctly explains this tension. This is a known characteristic of Camel's code generator for Boolean fields, not a PR-specific issue.
This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.
3 participants
AI-generated PR on behalf of atiaomar1978-hub via Cursor Cloud Agent.
Supersedes #25394 — same changeset on the correctly named branch
feature/CAMEL-24332-ai-tool-mcp-annotations(Apache convention).Summary
Implements CAMEL-24332: optional MCP
ToolAnnotationsmetadata onai-toolconsumer endpoints.Routes can now declare advisory hints for MCP clients:
Supported options:
title,readOnlyHint,destructiveHint,idempotentHint,openWorldHint.Changes
AiToolAnnotationsrecord + new@UriParamoptions onAiToolConfigurationAiToolSpeccarries annotations from consumer registrationMcpServerToolSPI extended withannotations()(defaultnull)McpServerBridgepasses spec annotations into published toolsVertxMcpServerEnginemaps hints to MCP Java SDKTool.title()/ToolAnnotationsai-tool-component.adocand cross-link frommcp-server.adoc; regenerated catalog docsHints are advisory only (per MCP spec) — documented as untrusted UX metadata, not authorization.
Review follow-ups addressed
feature/CAMEL-24332-ai-tool-mcp-annotationsAiToolAnnotationsconverted to a Java recordTool.titlemapping and catalogdefaultValue: falsevs runtime omit semanticsTests
AiToolAnnotationsTestAiToolEndpointLifecycleTestMcpServerBridgeTestVertxMcpServerToolAnnotationsTestAll tests pass locally.