You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@camel.apache.org by "Federico Mariani (Jira)" <ji...@apache.org> on 2026/10/14 14:04:00 UTC
[jira] [Updated] (CAMEL-25646) camel-jbang-mcp - ship MCP server instructions: the rules an agent needs before its first call, front-loaded, version-aware
[ https://issues.apache.org/jira/browse/CAMEL-25646?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Federico Mariani updated CAMEL-25646:
-------------------------------------
Fix Version/s: 4.24.0
> camel-jbang-mcp - ship MCP server instructions: the rules an agent needs before its first call, front-loaded, version-aware
> ---------------------------------------------------------------------------------------------------------------------------
>
> Key: CAMEL-25646
> URL: https://issues.apache.org/jira/browse/CAMEL-25646
> Project: Camel
> Issue Type: Improvement
> Components: camel-jbang-mcp
> Reporter: Federico Mariani
> Assignee: Federico Mariani
> Priority: Major
> Fix For: 4.24.0
>
>
> camel-jbang-mcp returns no {{instructions}} in its MCP {{initialize}} response: {{quarkus.mcp.server.server-info.instructions}} is unset and no {{io.quarkiverse.mcp.server.InitialResponseInfo}} bean exists (quarkus-mcp-server 2.0.2 supports both; {{McpMessageHandler.buildInstructions}} asks the beans first, then the property).
> Agent hosts read that field before the first tool call, and on the hosts that defer tool schemas it is the only text of the server the model sees at session start:
> || Host || Tool schemas at session start || How the model reaches a tool || Server {{instructions}} ||
> | Claude Code 2.1.29x | deferred: tool names only ({{ENABLE_TOOL_SEARCH}} unset = always defer; {{auto}} = defer above 10% of the context) | ToolSearch {{select:<name>}}: 113 such calls in the evaluation, every one by name | loaded at session start, up to 4096 characters |
> | Codex CLI (main, 2026-10-14) | deferred: tool search is on by default ({{core/tests/suite/search_tool.rs}}, {{mcp_tool_exposure.rs:84}}) | tool_search | read from {{initialize}}, used as server-wide guidance; the first 512 characters matter most; {{enabled_tools}}/{{disabled_tools}} per server on the client side |
> | OpenCode (main, 2026-10-14) | code mode by default: tools are not declared, the prompt carries one catalog line per tool | an {{execute}} script calling {{tools["<server>"]}} | full text in an {{<mcp_instructions>}} block, re-sent when it changes |
> | Pi (main, 2026-10-14) | {{codemode}} by default (scripts use {{searchTools()}}), {{deferred}} via tool_search, {{direct}} per tool | scripts or tool_search | only the FIRST LINE reaches the system prompt; the full text through {{describeNamespace()}} in scripts |
> | Bob Shell 2.0.5 | all schemas up front (995 evaluation calls, no search step) | direct | not documented |
> h3. Why it matters: the evaluation
> In an evaluation of coding agents (Claude Code with Haiku 5.5 and Sonnet 5.5, IBM Bob) on ten legacy-to-Camel migration tasks with camel-jbang-mcp 4.22.1 (419 trials), the measured gain of the camel-kit arm came from its generated AGENTS.md rules and the .mcp.json, not from its skills, and the task prompt had to carry a note on how to call the server (components by scheme, the three version arguments, validate before finishing). 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}}: 30 knowledge searches, 12 {{camel_component_properties platform-http}} calls and jar archaeology ({{Run.class}} disassembled in 35 plain-arm trials), 5 of 10 Bob trials on one task bound 8080 after 15-47 calls each.
> * extra jars: {{camel.jbang.dependencies}} in a properties file passed on the command line is ignored; agents grepped camel-jbang-core and camel-main jars for it in both plain and MCP arms (Sonnet in the MCP arm included, which made 0-2 MCP calls per trial).
> * mail: the Subject/From/To headers are ignored unless {{useHeader*=true}}; 11 sessions sent a mail with an empty subject; plain arms disassembled {{MailConfiguration}} (31), {{MailBinding}} (15), {{MailConstants}} (11).
> * onException/errorHandler/routeConfiguration are top-level entries and {{handled}} is an expression: 44 of 53 {{camel_validate_yaml_dsl}} calls were invalid, placement 10 and the handled shape 3 of them.
> * {{smtp}} not {{mail}}, {{platform-http}} for the HTTP server: "Component not found: mail" and {{optionsFilter: tls}} hunts.
> None of this needs a tool call. Instructions reach every host above with zero calls, which is the one change that helps a small model (fewer unanswerable hunts) and a large one (Sonnet digs jars instead of calling tools) alike.
> h3. Proposal
> An {{InitialResponseInfo}} bean in camel-jbang-mcp (programmatic, so the text can carry the CLI's own Camel version and, later, the active profile of CAMEL-25537), under 4096 characters, front-loaded:
> # One summary line first: Pi shows only that line, Codex weights the first 512 characters. Something like: "Apache Camel <version> catalog, validation and run tools. Look components up by URI scheme (smtp, platform-http); validate with camel_validate_source before finishing."
> # The rules, in order of what they cost in the evaluation: components by scheme; onException/errorHandler/routeConfiguration/intercept/onCompletion are top-level entries beside {{route}}, never steps, and {{handled}}/{{continued}} are expressions ({{handled: {constant: "true"}}}); under {{camel run}}: {{camel.server.enabled=true}} + {{camel.server.port}}, extra jars with {{--dep}} or a {{//DEPS}} line, not in a properties file passed on the command line; mail: Subject/From/To headers ignored unless {{useHeaderSubject}}/{{useHeaderFrom}}/{{useHeaderRecipients}}; strip {{Camel*}} headers ({{removeHeaders}}) before an http or mail producer; xslt gets headers and variables as parameters; a YAML schema pass is not a runtime pass, run the app and read the log.
> # A question-to-tool map by tool name, since the deferred hosts pick a tool by its name before reading any description: options and URI rules of a component ({{camel_catalog_doc}}), which component for a protocol ({{camel_catalog_find}}), a validated YAML sample and where it goes ({{camel_catalog_sample}}), the Maven/{{--dep}} coordinates of a class ({{camel_dependency_for_class}}), validate ({{camel_validate_source}}), run and read the log ({{camel_run}}, {{camel_get_log}}, {{camel_get_errors}}).
> # Keep it versioned with the release: the mail defaults changed in 4.21, the YAML shape rules with the DSL.
> # Document the text in camel-jbang-mcp.adoc, and a test that the initialize response carries it and that it stays under 4096 characters.
> Not part of this issue: the same rules for the TUI ({{camel tui --mcp}} shares the registry but not the Quarkus server), and the eval-side probe of whether Bob shows the text to its model.
> Related: CAMEL-25537 (profiles; the instructions should name the tools of the active profile), CAMEL-25639 (consolidation; tool names chosen for name-level discovery), CAMEL-25541, CAMEL-25539, CAMEL-25534, CAMEL-25533.
> _Claude Code on behalf of Croway_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)