You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by "Croway (via GitHub)" <gi...@apache.org> on 2026/10/14 09:00:48 UTC
[PR] CAMEL-25646: camel-jbang-mcp - the initialize response carries server instructions: the rules an agent needs before its first call [camel]
Croway opened a new pull request, #27816:
URL: https://github.com/apache/camel/pull/27816
Fixes https://issues.apache.org/jira/browse/CAMEL-25646
camel-jbang-mcp returned no `instructions` in its MCP `initialize` response. Agent hosts read that field before the first tool call, and on the hosts that defer tool schemas (Claude Code, Codex, Pi) it is the only text of the server the model sees at session start. In an evaluation of coding agents on migration tasks, the waste that remained came from questions no tool answers and the agents went hunting for: `camel.server.port` under `camel run` needs `camel.server.enabled=true`, extra jars go in `--dep`, the mail Subject header is ignored unless `useHeaderSubject=true`, onException is a top-level entry and `handled` an expression, `smtp` not `mail`.
- `McpServerInstructions`, an `InitialResponseInfo` bean: one summary line with the Camel version first (Pi shows only the first line, Codex weights the first 512 characters), then the rules in the order of what they cost in the evaluation, then a question-to-tool-name map. 2,138 characters, under Claude Code's 4,096 limit.
- `quarkus.mcp.server.server-info.instructions` still overrides it: the bean steps aside when the property is set.
- Test: size and first line, rule order, every `camel_*` name in the text is an `@Tool` method of this module and the mapped set is exactly the names in the text (a renamed tool fails the test), the override.
- A "Server instructions" section in camel-jbang-mcp.adoc.
Checked over stdio against the built runner jar: the initialize response carries the text, and the property replaces it.
_Claude Code on behalf of Croway_
--
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: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] CAMEL-25646: camel-jbang-mcp - the initialize response carries server instructions: the rules an agent needs before its first call [camel]
Posted by "Croway (via GitHub)" <gi...@apache.org>.
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: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] CAMEL-25646: camel-jbang-mcp - the initialize response carries server instructions: the rules an agent needs before its first call [camel]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #27816:
URL: https://github.com/apache/camel/pull/27816#issuecomment-6164810426
:star2: Thank you for your contribution to the Apache Camel project! :star2:
:robot: CI automation will test this PR automatically.
:camel: Apache Camel Committers, please review the following items:
* First-time contributors **require MANUAL approval** for the GitHub Actions to run
* You can use the command `/component-test (camel-)component-name1 (camel-)component-name2..` to request a test from the test bot although they are normally detected and executed by CI.
* You can label PRs using `skip-tests` and `test-dependents` to fine-tune the checks executed by this PR.
* Build and test logs are available in the summary page. **Only** [Apache Camel committers](https://camel.apache.org/community/team/#committers) have access to the summary.
:warning: Be careful when sharing logs. Review their contents before sharing them publicly.
--
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: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] CAMEL-25646: camel-jbang-mcp - the initialize response carries server instructions: the rules an agent needs before its first call [camel]
Posted by "Croway (via GitHub)" <gi...@apache.org>.
Croway merged PR #27816:
URL: https://github.com/apache/camel/pull/27816
--
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: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] CAMEL-25646: camel-jbang-mcp - the initialize response carries server instructions: the rules an agent needs before its first call [camel]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #27816:
URL: https://github.com/apache/camel/pull/27816#issuecomment-6167765609
<!-- ci-tested-modules -->
:test_tube: **CI tested the following changed modules:**
- `docs`
- `dsl/camel-jbang/camel-jbang-mcp`
---
<details><summary>:microscope: Scalpel shadow comparison — Scalpel: 1 of 703 tested, 0 compile-only — current: 1 all tested</summary>
[Maveniverse Scalpel](https://github.com/maveniverse/scalpel) detected **1 affected modules** (current approach: 1).
**Skip-tests mode would test 1 modules** (2 direct + 0 downstream), **skip tests for 0** (generated code, meta-modules)
<details><summary>Modules Scalpel would test (1)</summary>
- `camel-jbang-mcp` ← dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpServerInstructions.java, dsl/camel-jbang/camel-jbang-mcp/src/test/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpServerInstructionsTest.java
</details>
> :information_source: Shadow mode — Scalpel observes but does not affect test execution. [Learn more](https://github.com/maveniverse/scalpel)
</details>
:warning: **Some tests are disabled on GitHub Actions** (`@DisabledIfSystemProperty(named = "ci.env.name")`) and require manual verification:
- `dsl/camel-jbang/camel-jbang-mcp`: 1 test(s) disabled on GitHub Actions
<details><summary>All tested modules (2 modules, 59.7s total)</summary>
**Total reactor time:** 59.7s
| Module | Duration | Status |
| --- | --- | --- |
| Camel :: JBang :: MCP | 38.0s | SUCCESS |
| Camel :: Docs | 21.6s | SUCCESS |
**Top 20 slowest modules:**
- `Camel :: JBang :: MCP` (38.0s)
- `Camel :: Docs` (21.6s)
</details>
---
:gear: [View full build and test results](https://github.com/apache/camel/actions/runs/38545795912)
--
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: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] CAMEL-25646: camel-jbang-mcp - the initialize response carries server instructions: the rules an agent needs before its first call [camel]
Posted by "davsclaus (via GitHub)" <gi...@apache.org>.
davsclaus commented on code in PR #27816:
URL: https://github.com/apache/camel/pull/27816#discussion_r4269069369
##########
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:
On `main` this is no longer true. CAMEL-25528 (#27655) made `camel run` read `camel.jbang.dependencies` (and the runtime-specific variants) from the properties files given on the command line, in `Run.addDependenciesFromPropertiesFiles`. This text ships with 4.24.0, so the clause should go.
##########
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:
These docs repeat the two `camel run` rules that are out of date on `main` (CAMEL-25528, CAMEL-25533). They need the same change as the Java text.
##########
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:
Since CAMEL-25533 (#27667), `MainHttpServerFactory.configureHttpServer` applies `camel.server.port` and the other `camel.server.*` settings to the server started for platform-http, and it ignores `enabled` there. So `enabled=true` is no longer needed. A shorter rule would be more accurate, for example "camel.server.port (or camel run --port) sets the HTTP port".
##########
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:
With `camel.mcp.security.access-level=read-only`, `McpAccessFilter` hides `camel_run` (`readOnlyHint=false`), but the text still points the agent at it, here and in the "run the app (camel_run)" rule. Should the bean inject `McpSecurityConfig` and leave these lines out when the run tools are hidden? This could be a follow-up, together with CAMEL-25537.
##########
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:
This paragraph documents the limits of other products, which will change between Camel releases. I would keep it in the class javadoc (it is already there) and leave it out of the user guide, or reduce it to one sentence: "keep the first line self-contained, as some hosts show only that".
--
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: commits-unsubscribe@camel.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org