CAMEL-23270: Camel-Jbang-MCP: Add MCP tool annotations (readOnlyHint, destructiveHint, openWorldHint) to all tools (#22341)

oscerd · web-flow · commit dba5a0f7194e · 2026-03-30T15:29:04.000+02:00
Add @Tool.Annotations(readOnlyHint=true, destructiveHint=false,
openWorldHint=false) to all 27 tool methods across 12 tool classes.
All tools in this module are read-only (query catalogs, validate input,
generate scaffolds) so this explicitly declares that to MCP clients,
enabling auto-approval and better tool selection decisions.

Quarkus MCP Server SDK 1.11.0 already supports these annotations.

Signed-off-by: Andrea Cosentino &lt;ancosen@gmail.com&gt;
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/CatalogTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/CatalogTools.java
@@ -44,7 +44,8 @@ public class CatalogTools {
     /**
      * Tool to list available Camel components.
      */
-    @Tool(description = "List available Camel components from the catalog. " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "List available Camel components from the catalog. " +
                         "Returns component name, description, and labels. " +
                         "Use filter to search by name, label to filter by category.")
     public ComponentListResult camel_catalog_components(
@@ -92,7 +93,8 @@ public ComponentListResult camel_catalog_components(
     /**
      * Tool to get detailed documentation for a specific component.
      */
-    @Tool(description = "Get detailed documentation for a Camel component including all options, " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get detailed documentation for a Camel component including all options, " +
                         "endpoint parameters, and usage examples.")
     public ComponentDetailResult camel_catalog_component_doc(
             @ToolArg(description = "Component name (e.g., kafka, http, file, timer)") String component,
@@ -154,7 +156,8 @@ public ComponentDetailResult camel_catalog_component_doc(
     /**
      * Tool to list data formats.
      */
-    @Tool(description = "List available Camel data formats for marshalling/unmarshalling " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "List available Camel data formats for marshalling/unmarshalling " +
                         "(e.g., json, xml, csv, avro, protobuf).")
     public DataFormatListResult camel_catalog_dataformats(
             @ToolArg(description = "Filter by name") String filter,
@@ -187,7 +190,8 @@ public DataFormatListResult camel_catalog_dataformats(
     /**
      * Tool to list expression languages.
      */
-    @Tool(description = "List available Camel expression languages " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "List available Camel expression languages " +
                         "(e.g., simple, jsonpath, xpath, groovy, jq).")
     public LanguageListResult camel_catalog_languages(
             @ToolArg(description = "Filter by name") String filter,
@@ -216,7 +220,8 @@ public LanguageListResult camel_catalog_languages(
     /**
      * Tool to get detailed documentation for a specific data format.
      */
-    @Tool(description = "Get detailed documentation for a Camel data format including all options, "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get detailed documentation for a Camel data format including all options, "
                         + "Maven coordinates, and configuration parameters.")
     public DataFormatDetailResult camel_catalog_dataformat_doc(
             @ToolArg(description = "Data format name (e.g., json-jackson, avro, csv, protobuf, jaxb)") String dataformat,
@@ -250,7 +255,8 @@ public DataFormatDetailResult camel_catalog_dataformat_doc(
     /**
      * Tool to get detailed documentation for a specific expression language.
      */
-    @Tool(description = "Get detailed documentation for a Camel expression language including all options, "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get detailed documentation for a Camel expression language including all options, "
                         + "Maven coordinates, and configuration parameters.")
     public LanguageDetailResult camel_catalog_language_doc(
             @ToolArg(description = "Language name (e.g., simple, jsonpath, xpath, jq, groovy)") String language,
@@ -283,7 +289,8 @@ public LanguageDetailResult camel_catalog_language_doc(
     /**
      * Tool to list EIPs (Enterprise Integration Patterns).
      */
-    @Tool(description = "List Camel Enterprise Integration Patterns (EIPs) like split, aggregate, " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "List Camel Enterprise Integration Patterns (EIPs) like split, aggregate, " +
                         "filter, choice, multicast, circuit-breaker, etc.")
     public EipListResult camel_catalog_eips(
             @ToolArg(description = "Filter by name") String filter,
@@ -314,7 +321,8 @@ public EipListResult camel_catalog_eips(
     /**
      * Tool to get detailed documentation for a specific EIP.
      */
-    @Tool(description = "Get detailed documentation for a Camel EIP (Enterprise Integration Pattern).")
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get detailed documentation for a Camel EIP (Enterprise Integration Pattern).")
     public EipDetailResult camel_catalog_eip_doc(
             @ToolArg(description = "EIP name (e.g., split, aggregate, choice, filter)") String eip,
             @ToolArg(description = "Runtime type: main, spring-boot, or quarkus (default: main)") String runtime,
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/DependencyCheckTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/DependencyCheckTools.java
@@ -47,7 +47,8 @@ public class DependencyCheckTools {
     /**
      * Tool to check Camel dependency hygiene for a project.
      */
-    @Tool(description = "Check Camel project dependency hygiene. Given a pom.xml (and optionally route definitions), "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Check Camel project dependency hygiene. Given a pom.xml (and optionally route definitions), "
                         + "detects outdated Camel dependencies compared to the latest catalog version, "
                         + "missing Maven dependencies for components used in routes, "
                         + "and version conflicts between the Camel BOM and explicit dependency overrides. "
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/DiagnoseTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/DiagnoseTools.java
@@ -72,7 +72,8 @@ public class DiagnoseTools {
     /**
      * Tool to diagnose Camel errors from stack traces or error messages.
      */
-    @Tool(description = "Diagnose a Camel error from a stack trace or error message. "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Diagnose a Camel error from a stack trace or error message. "
                         + "Returns the identified component/EIP involved, common causes for the error, "
                         + "links to relevant Camel documentation, and suggested fixes. "
                         + "Covers the most common Camel exceptions including NoSuchEndpointException, "
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/ExplainTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/ExplainTools.java
@@ -46,7 +46,8 @@ public class ExplainTools {
     /**
      * Tool to get enriched context for a Camel route.
      */
-    @Tool(description = "Get enriched context for a Camel route including documentation for all components and EIPs used. "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get enriched context for a Camel route including documentation for all components and EIPs used. "
                         +
                         "Returns structured data with component descriptions, EIP explanations, and route structure. " +
                         "Use this context to understand and explain the route.")
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/HardenTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/HardenTools.java
@@ -48,7 +48,8 @@ public class HardenTools {
     /**
      * Tool to get security hardening context for a Camel route.
      */
-    @Tool(description = "Get security hardening analysis context for a Camel route. " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get security hardening analysis context for a Camel route. " +
                         "Returns security-sensitive components, potential vulnerabilities, " +
                         "and security best practices. Use this context to provide security " +
                         "hardening recommendations for the route.")
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/KameletTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/KameletTools.java
@@ -40,7 +40,8 @@ public class KameletTools {
     /**
      * Tool to list available Kamelets.
      */
-    @Tool(description = "List available Camel Kamelets from the Kamelet Catalog. " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "List available Camel Kamelets from the Kamelet Catalog. " +
                         "Returns kamelet name, type (source, sink, action), support level, and description. " +
                         "Use filter to search by name or description, type to filter by category.")
     public KameletListResult camel_catalog_kamelets(
@@ -97,7 +98,8 @@ public KameletListResult camel_catalog_kamelets(
     /**
      * Tool to get detailed documentation for a specific Kamelet.
      */
-    @Tool(description = "Get detailed documentation for a specific Camel Kamelet including all properties/options, "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get detailed documentation for a specific Camel Kamelet including all properties/options, "
                         + "dependencies, and usage information.")
     public KameletDetailResult camel_catalog_kamelet_doc(
             @ToolArg(description = "Kamelet name (e.g., aws-s3-source, kafka-sink, log-action)") String kamelet,
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/MigrationTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/MigrationTools.java
@@ -47,7 +47,8 @@ public class MigrationTools {
     /**
      * Step 1: Analyze a project's pom.xml to detect runtime, Camel version, Java version, and components.
      */
-    @Tool(description = "Analyze a Camel project's pom.xml to detect the runtime type (main, spring-boot, quarkus, "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Analyze a Camel project's pom.xml to detect the runtime type (main, spring-boot, quarkus, "
                         + "wildfly, karaf), Camel version, Java version, and Camel component dependencies. "
                         + "This is the first step in a migration workflow.")
     public ProjectAnalysisResult camel_migration_analyze(
@@ -96,7 +97,8 @@ public ProjectAnalysisResult camel_migration_analyze(
     /**
      * Step 2: Check compatibility and provide relevant migration guide references.
      */
-    @Tool(description = "Check migration compatibility for Camel components by providing relevant migration guide "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Check migration compatibility for Camel components by providing relevant migration guide "
                         + "URLs and Java version requirements. The LLM should consult the migration guides for "
                         + "detailed component rename mappings and API changes.")
     public CompatibilityResult camel_migration_compatibility(
@@ -194,7 +196,8 @@ public CompatibilityResult camel_migration_compatibility(
     /**
      * Step 3: Get Maven commands to run OpenRewrite migration recipes.
      */
-    @Tool(description = "Get Maven commands to run Camel OpenRewrite migration recipes for upgrading between versions. "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get Maven commands to run Camel OpenRewrite migration recipes for upgrading between versions. "
                         + "Returns the exact Maven commands to execute on the project. "
                         + "PREREQUISITE: The project MUST compile successfully ('mvn clean compile' must pass) "
                         + "BEFORE running the OpenRewrite recipes. If the project does not compile, fix the build "
@@ -278,7 +281,8 @@ public MigrationRecipesResult camel_migration_recipes(
     /**
      * Search migration guides for a specific term.
      */
-    @Tool(description = "Search Camel migration and upgrade guides for a specific term or component name. "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Search Camel migration and upgrade guides for a specific term or component name. "
                         + "Returns matching snippets from the official guides with version info and URLs. "
                         + "Supports fuzzy matching for typo tolerance. "
                         + "Use this instead of web search when looking up migration-related changes, "
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/MigrationWildflyKarafTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/MigrationWildflyKarafTools.java
@@ -42,7 +42,8 @@ public class MigrationWildflyKarafTools {
     /**
      * WildFly/Karaf migration guidance with archetype-based project creation.
      */
-    @Tool(description = "Get migration guidance for Camel projects running on WildFly, Karaf, or WAR-based "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get migration guidance for Camel projects running on WildFly, Karaf, or WAR-based "
                         + "application servers. Returns the Maven archetype command to create a new target project, "
                         + "migration steps, and relevant migration guide URLs. "
                         + "IMPORTANT: When migrating to a different runtime (e.g., WildFly to Quarkus, Karaf to Spring Boot), "
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/OpenApiTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/OpenApiTools.java
@@ -48,7 +48,8 @@ public class OpenApiTools {
 
     private static final Set<String> VALID_MISSING_OPERATION_MODES = Set.of("fail", "ignore", "mock");
 
-    @Tool(description = "Validate an OpenAPI specification for use with Camel's contract-first REST support. "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Validate an OpenAPI specification for use with Camel's contract-first REST support. "
                         + "Checks for compatibility issues like missing operationIds, unsupported security schemes, "
                         + "and OpenAPI 3.1 features that Camel does not fully support.")
     public ValidateResult camel_openapi_validate(
@@ -127,7 +128,8 @@ public ValidateResult camel_openapi_validate(
         return new ValidateResult(valid, errors, warnings, info, operationCount);
     }
 
-    @Tool(description = "Generate Camel YAML scaffold for contract-first OpenAPI integration. "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Generate Camel YAML scaffold for contract-first OpenAPI integration. "
                         + "Produces a rest:openApi configuration block and route stubs for each operation "
                         + "defined in the spec. This is the recommended approach since Camel 4.6.")
     public ScaffoldResult camel_openapi_scaffold(
@@ -191,7 +193,8 @@ public ScaffoldResult camel_openapi_scaffold(
         return new ScaffoldResult(yaml.toString(), stubs.size(), filename, mode, apiTitle);
     }
 
-    @Tool(description = "Get guidance on configuring Camel's contract-first REST missingOperation modes "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Get guidance on configuring Camel's contract-first REST missingOperation modes "
                         + "(fail, ignore, mock). For 'mock' mode, provides directory structure, mock file paths, "
                         + "and example content derived from the OpenAPI spec.")
     public MockGuidanceResult camel_openapi_mock_guidance(
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/TestScaffoldTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/TestScaffoldTools.java
@@ -72,7 +72,8 @@ public class TestScaffoldTools {
     /**
      * Tool to generate a JUnit 5 test skeleton for a Camel route.
      */
-    @Tool(description = "Generate a JUnit 5 test skeleton for a Camel route. "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Generate a JUnit 5 test skeleton for a Camel route. "
                         + "Given a YAML or XML route definition, produces a test class with "
                         + "CamelTestSupport or @CamelSpringBootTest boilerplate, "
                         + "mock endpoints for producer endpoints, MockEndpoint assertions, "
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/TransformTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/TransformTools.java
@@ -58,7 +58,8 @@ public class TransformTools {
     /**
      * Tool to validate a Camel route or endpoint URI.
      */
-    @Tool(description = "Validate a Camel endpoint URI or route definition. " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Validate a Camel endpoint URI or route definition. " +
                         "Checks syntax, required options, and valid parameter names.")
     public ValidationResult camel_validate_route(
             @ToolArg(description = "Camel endpoint URI to validate (e.g., 'kafka:myTopic?brokers=localhost:9092')") String uri,
@@ -154,7 +155,8 @@ public ValidationResult camel_validate_route(
     /**
      * Tool to transform routes between DSL formats.
      */
-    @Tool(description = "Transform a Camel route between different DSL formats (YAML, XML). " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Transform a Camel route between different DSL formats (YAML, XML). " +
                         "Note: Java to YAML/XML transformation has limitations.")
     public TransformResult camel_transform_route(
             @ToolArg(description = "Route definition to transform") String route,
@@ -261,7 +263,8 @@ private String transformYamlToXml(String yaml) throws Exception {
     /**
      * Tool to validate a YAML DSL route definition against the Camel YAML DSL JSON schema.
      */
-    @Tool(description = "Validate a YAML DSL route definition against the Camel YAML DSL JSON schema. "
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "Validate a YAML DSL route definition against the Camel YAML DSL JSON schema. "
                         + "Checks for valid DSL elements, correct route structure, and returns detailed schema validation errors.")
     public YamlDslValidationResult camel_validate_yaml_dsl(
             @ToolArg(description = "YAML DSL route definition to validate") String route) {
diff --git a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/VersionTools.java b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/VersionTools.java
@@ -41,7 +41,8 @@ public class VersionTools {
     /**
      * Tool to list available Camel versions for a specific runtime.
      */
-    @Tool(description = "List available Camel versions for a specific runtime (main, spring-boot, quarkus). " +
+    @Tool(annotations = @Tool.Annotations(readOnlyHint = true, destructiveHint = false, openWorldHint = false),
+          description = "List available Camel versions for a specific runtime (main, spring-boot, quarkus). " +
                         "Returns version information including release date, JDK requirements, and LTS status.")
     public VersionListResult camel_version_list(
             @ToolArg(description = "Runtime type: main, spring-boot, or quarkus (default: main)") String runtime,
