[
https://issues.apache.org/jira/browse/CAMEL-25646?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Work on CAMEL-25646 started by Federico Mariani.
------------------------------------------------
> 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
>
> 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)
