Croway commented on code in PR #27816: URL: https://github.com/apache/camel/pull/27816#discussion_r4269304517
########## dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpServerInstructions.java: ########## @@ -0,0 +1,117 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.camel.dsl.jbang.core.commands.mcp; + +import java.util.List; +import java.util.Optional; + +import jakarta.enterprise.context.ApplicationScoped; + +import io.quarkiverse.mcp.server.InitialResponseInfo; +import org.apache.camel.catalog.DefaultCamelCatalog; +import org.eclipse.microprofile.config.inject.ConfigProperty; + +/** + * The {@code instructions} of the MCP {@code initialize} response: the rules an agent needs before its first tool call, + * and which tool answers which question. + * <p> + * Hosts that defer tool schemas (Claude Code, Codex, OpenCode, Pi) give the model this text at session start, before + * any tool description. Pi shows only the first line and Codex weighs the first 512 characters most, so the first line + * is a one-sentence summary with the Camel version. The whole text stays under 4096 characters (what Claude Code + * loads). + * <p> + * A value set in {@code quarkus.mcp.server.server-info.instructions} replaces this text: Quarkus asks the + * {@link InitialResponseInfo} beans before it reads the property, so this bean steps aside when the property is set. + */ +@ApplicationScoped +public class McpServerInstructions implements InitialResponseInfo { + + /** The length the hosts take in full (Claude Code loads up to this many characters). */ + static final int MAX_LENGTH = 4096; + + /** The tool names the text maps questions to; a test checks that each one is an {@code @Tool} method. */ + static final List<String> MAPPED_TOOLS = List.of( + "camel_catalog_doc", "camel_catalog_find", "camel_catalog_sample", "camel_catalog_examples", + "camel_dependency_for_class", "camel_validate_source", "camel_run", "camel_get_log", "camel_get_errors", + "camel_project_overview"); + + /** The text, with the Camel version as its only parameter. Kept here so the whole text reviews in one place. */ + private static final String TEMPLATE = """ + Apache Camel %s catalog, validation and run tools: look components up by URI scheme (smtp, \ + platform-http) and validate with camel_validate_source before finishing. + + Rules: + - Components are named by URI scheme: smtp/smtps/imap/pop3 (not mail), platform-http for an HTTP server, \ + http/https for an HTTP client. camel_catalog_find maps a protocol or product to the scheme. + - YAML DSL: onException, errorHandler, routeConfiguration, intercept and onCompletion are top-level \ + entries beside route (or inside routeConfiguration), never steps. handled and continued are \ + expressions: handled: {constant: "true"}. + - camel run: the HTTP server needs camel.server.enabled=true plus camel.server.port. Extra jars go in \ + --dep groupId:artifactId:version or a //DEPS line in a source file; camel.jbang.dependencies in a \ + properties file passed on the command line is ignored. Review Comment: Dropped the "is ignored" clause: the rule now lists `camel.jbang.dependencies=group:artifact:version` in `application.properties` as one of the three ways to add a jar, matching CAMEL-25528 (b6f8a0f8cd43). ########## dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpServerInstructions.java: ########## @@ -0,0 +1,117 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.camel.dsl.jbang.core.commands.mcp; + +import java.util.List; +import java.util.Optional; + +import jakarta.enterprise.context.ApplicationScoped; + +import io.quarkiverse.mcp.server.InitialResponseInfo; +import org.apache.camel.catalog.DefaultCamelCatalog; +import org.eclipse.microprofile.config.inject.ConfigProperty; + +/** + * The {@code instructions} of the MCP {@code initialize} response: the rules an agent needs before its first tool call, + * and which tool answers which question. + * <p> + * Hosts that defer tool schemas (Claude Code, Codex, OpenCode, Pi) give the model this text at session start, before + * any tool description. Pi shows only the first line and Codex weighs the first 512 characters most, so the first line + * is a one-sentence summary with the Camel version. The whole text stays under 4096 characters (what Claude Code + * loads). + * <p> + * A value set in {@code quarkus.mcp.server.server-info.instructions} replaces this text: Quarkus asks the + * {@link InitialResponseInfo} beans before it reads the property, so this bean steps aside when the property is set. + */ +@ApplicationScoped +public class McpServerInstructions implements InitialResponseInfo { + + /** The length the hosts take in full (Claude Code loads up to this many characters). */ + static final int MAX_LENGTH = 4096; + + /** The tool names the text maps questions to; a test checks that each one is an {@code @Tool} method. */ + static final List<String> MAPPED_TOOLS = List.of( + "camel_catalog_doc", "camel_catalog_find", "camel_catalog_sample", "camel_catalog_examples", + "camel_dependency_for_class", "camel_validate_source", "camel_run", "camel_get_log", "camel_get_errors", + "camel_project_overview"); + + /** The text, with the Camel version as its only parameter. Kept here so the whole text reviews in one place. */ + private static final String TEMPLATE = """ + Apache Camel %s catalog, validation and run tools: look components up by URI scheme (smtp, \ + platform-http) and validate with camel_validate_source before finishing. + + Rules: + - Components are named by URI scheme: smtp/smtps/imap/pop3 (not mail), platform-http for an HTTP server, \ + http/https for an HTTP client. camel_catalog_find maps a protocol or product to the scheme. + - YAML DSL: onException, errorHandler, routeConfiguration, intercept and onCompletion are top-level \ + entries beside route (or inside routeConfiguration), never steps. handled and continued are \ + expressions: handled: {constant: "true"}. + - camel run: the HTTP server needs camel.server.enabled=true plus camel.server.port. Extra jars go in \ Review Comment: Rewritten as "camel.server.port (or camel run --port) sets the HTTP port", without `enabled=true`, matching CAMEL-25533 (b6f8a0f8cd43). ########## dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpServerInstructions.java: ########## @@ -0,0 +1,117 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.camel.dsl.jbang.core.commands.mcp; + +import java.util.List; +import java.util.Optional; + +import jakarta.enterprise.context.ApplicationScoped; + +import io.quarkiverse.mcp.server.InitialResponseInfo; +import org.apache.camel.catalog.DefaultCamelCatalog; +import org.eclipse.microprofile.config.inject.ConfigProperty; + +/** + * The {@code instructions} of the MCP {@code initialize} response: the rules an agent needs before its first tool call, + * and which tool answers which question. + * <p> + * Hosts that defer tool schemas (Claude Code, Codex, OpenCode, Pi) give the model this text at session start, before + * any tool description. Pi shows only the first line and Codex weighs the first 512 characters most, so the first line + * is a one-sentence summary with the Camel version. The whole text stays under 4096 characters (what Claude Code + * loads). + * <p> + * A value set in {@code quarkus.mcp.server.server-info.instructions} replaces this text: Quarkus asks the + * {@link InitialResponseInfo} beans before it reads the property, so this bean steps aside when the property is set. + */ +@ApplicationScoped +public class McpServerInstructions implements InitialResponseInfo { + + /** The length the hosts take in full (Claude Code loads up to this many characters). */ + static final int MAX_LENGTH = 4096; + + /** The tool names the text maps questions to; a test checks that each one is an {@code @Tool} method. */ + static final List<String> MAPPED_TOOLS = List.of( + "camel_catalog_doc", "camel_catalog_find", "camel_catalog_sample", "camel_catalog_examples", + "camel_dependency_for_class", "camel_validate_source", "camel_run", "camel_get_log", "camel_get_errors", + "camel_project_overview"); + + /** The text, with the Camel version as its only parameter. Kept here so the whole text reviews in one place. */ + private static final String TEMPLATE = """ + Apache Camel %s catalog, validation and run tools: look components up by URI scheme (smtp, \ + platform-http) and validate with camel_validate_source before finishing. + + Rules: + - Components are named by URI scheme: smtp/smtps/imap/pop3 (not mail), platform-http for an HTTP server, \ + http/https for an HTTP client. camel_catalog_find maps a protocol or product to the scheme. + - YAML DSL: onException, errorHandler, routeConfiguration, intercept and onCompletion are top-level \ + entries beside route (or inside routeConfiguration), never steps. handled and continued are \ + expressions: handled: {constant: "true"}. + - camel run: the HTTP server needs camel.server.enabled=true plus camel.server.port. Extra jars go in \ + --dep groupId:artifactId:version or a //DEPS line in a source file; camel.jbang.dependencies in a \ + properties file passed on the command line is ignored. + - mail producer: the Subject, From and To headers are ignored unless useHeaderSubject=true, \ + useHeaderFrom=true and useHeaderRecipients=true; otherwise use the subject, from and to options. + - Before an http or mail producer, remove the Camel* headers you did not set yourself \ + (removeHeaders: {pattern: "Camel*"} when none are yours), so inbound CamelHttpPath, CamelHttpQuery or \ + CamelHttpUri do not redirect the call and no header leaks into the mail. + - xslt receives the message headers and variables as stylesheet parameters (xsl:param). + - Passing the YAML schema is not passing at runtime: run the app (camel_run) and read its log before \ + calling it done. + + Which tool: + - options, URI syntax, headers of a component, EIP, data format or language: camel_catalog_doc + - which component for a protocol or product: camel_catalog_find + - a validated YAML sample and where it goes: camel_catalog_sample + - complete example projects: camel_catalog_examples + - Maven coordinates (the --dep value) of a Java class: camel_dependency_for_class + - validate YAML/Java/XML/properties before writing: camel_validate_source + - run an integration: camel_run; its log: camel_get_log; its errors: camel_get_errors Review Comment: Agreed, left as a follow-up together with CAMEL-25537: the bean will take `McpSecurityConfig` and the active profile into account and leave the `camel_run` lines out when those tools are hidden. ########## docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc: ########## @@ -87,6 +87,35 @@ java -Dquarkus.http.host-enabled=true -Dquarkus.http.port=8080 -jar camel-jbang- IMPORTANT: The MCP server does **not** expose REST endpoints — all communication uses JSON-RPC over the MCP protocol. +== Server instructions + +The `initialize` response carries `instructions`: a short plain-text guide (under 4096 characters) that the agent +host gives the model at session start, before any tool call and before any tool description is loaded. It answers the +questions that no tool answers and that agents otherwise go hunting for: + +* The first line is a one-sentence summary with the Camel version of the server: look components up by URI scheme + and validate with `camel_validate_source` before finishing. +* The rules: components by URI scheme (`smtp`, not `mail`; `platform-http` for an HTTP server); `onException`, + `errorHandler`, `routeConfiguration`, `intercept` and `onCompletion` are top-level entries, not steps, and + `handled`/`continued` are expressions; under `camel run` the HTTP server needs `camel.server.enabled=true` plus Review Comment: The doc's rules bullet carries the same camel run rules as the Java text now, and the long line is re-wrapped. ########## docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc: ########## @@ -87,6 +87,35 @@ java -Dquarkus.http.host-enabled=true -Dquarkus.http.port=8080 -jar camel-jbang- IMPORTANT: The MCP server does **not** expose REST endpoints — all communication uses JSON-RPC over the MCP protocol. +== Server instructions + +The `initialize` response carries `instructions`: a short plain-text guide (under 4096 characters) that the agent +host gives the model at session start, before any tool call and before any tool description is loaded. It answers the +questions that no tool answers and that agents otherwise go hunting for: + +* The first line is a one-sentence summary with the Camel version of the server: look components up by URI scheme + and validate with `camel_validate_source` before finishing. +* The rules: components by URI scheme (`smtp`, not `mail`; `platform-http` for an HTTP server); `onException`, + `errorHandler`, `routeConfiguration`, `intercept` and `onCompletion` are top-level entries, not steps, and + `handled`/`continued` are expressions; under `camel run` the HTTP server needs `camel.server.enabled=true` plus + `camel.server.port`, and extra jars go in `--dep` or a `//DEPS` line, not in a properties file passed on the command + line; the mail Subject, From and To headers are ignored unless `useHeaderSubject`, `useHeaderFrom` and + `useHeaderRecipients` are `true`; remove the `Camel*` headers you did not set yourself before an http or mail producer; `xslt` gets the headers + and variables as stylesheet parameters; a source that passes the schema can still fail at runtime, so run it and + read the log. +* Which tool answers which question, by tool name: `camel_catalog_doc`, `camel_catalog_find`, + `camel_catalog_sample`, `camel_catalog_examples`, `camel_dependency_for_class`, `camel_validate_source`, + `camel_run`, `camel_get_log`, `camel_get_errors` and `camel_project_overview`. + +How hosts use it: Claude Code loads it at session start (up to 4096 characters), which matters most when it defers the Review Comment: Reduced to one sentence ("The first line is self-contained, as some hosts show only that line."); the per-host limits stay in the class javadoc only. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
