Federico Mariani created CAMEL-25542:
----------------------------------------
Summary: camel-jbang-mcp - the component doc answer leaves out the
page sections that decide correctness (xslt header parameters, mail
useHeader*), and platform-http does not point at platform-http-main
Key: CAMEL-25542
URL: https://issues.apache.org/jira/browse/CAMEL-25542
Project: Camel
Issue Type: Improvement
Components: camel-platform-http, camel-jbang-mcp
Affects Versions: 4.22.1
Reporter: Federico Mariani
In an evaluation of coding agents (Claude Code and IBM Bob) on migration tasks
with camel-jbang-mcp 4.22.1, three component behaviours that decide whether a
route is correct were never in the answer to the component documentation tool,
because they live in the component's AsciiDoc page and not in its catalog JSON:
* *xslt*: "By default, all headers and variables are added as parameters"
(section "Getting Usable Parameters into the XSLT").
* *mail*: the Subject/From/To headers are ignored unless
{{useHeaderSubject}}/{{useHeaderFrom}}/{{useHeaderRecipients}} is true (section
"Opting out of header overrides", 4.21+).
* *platform-http* under Camel Main / {{camel run}}: {{camel.server.port}} needs
{{camel.server.enabled=true}}. Only the {{platform-http-main}} page says so;
the {{platform-http}} page neither says it nor links to that page.
h3. Reproduction
{noformat}
camel_catalog_component_doc {component: xslt, includeOptions: all,
optionsFilter: param}
-> {"name":"xslt",...,"componentOptions":[],"endpointOptions":[],"headers":[]}
camel_catalog_component_doc {component: xslt, includeHeaders: true}
-> headers: CamelXsltResourceUri, CamelXsltStylesheet, CamelXsltFileName
(nothing about parameters)
{noformat}
Agents read the empty result as "xslt cannot take parameters": one session
rewrote the transformation in FreeMarker, another pushed the values through the
body. For mail, 11 sessions (plus 2 on a second task) set the {{subject}}
header and sent an email with an empty subject; nothing in the component doc
answer says the header is ignored by default. For the HTTP port, 5 of 10 Bob
sessions on one task listened on 8080 instead of the configured port, after
15-47 calls each looking for the setting ({{component_properties
platform-http}} is 15 KB of endpoint options and never names
{{camel.server.*}}). The one session that called {{camel_catalog_doc
name=platform-http-main}}, by guessing the name, added
{{camel.server.enabled=true}} in its next command.
h3. Cause
4.22.1: {{CatalogTools.camel_catalog_component_doc}} returns
{{ComponentDetailResult}} (name, title, description, label, syntax, options,
headers): the catalog JSON only, no prose.
main: CAMEL-25040 added a {{documentation}} excerpt to {{camel_catalog_doc}}
({{CatalogDocs.docExcerpt}}, {{DOC_EXCERPT_BUDGET = 1400}}) taken from the
first {{==}} section, and CAMEL-25283 added {{docPages}} from
{{xref:others:<scheme>-<page>.adoc}} links. That does not reach any of the
three facts: for xslt the excerpt is the "URI format" section and stops inside
"Using XSLT endpoints" (the parameter section starts at line 129 of 442); for
mail it stops in "Default ports" (the useHeader table is at line ~300); for
platform-http it is the Quarkus / Spring Boot provider dependencies.
{{platform-http-component.adoc}} has no link to {{platform-http-main.adoc}}, so
{{docPages}} is empty.
h3. Fix
# {{platform-http-component.adoc}}: add a Camel Main / {{camel run}} entry to
"Platform HTTP Provider" (the first section, so it lands in the excerpt) with
{{camel.server.enabled=true}} + {{camel.server.port}}, and link
{{xref:others:platform-http-main.adoc[...]}}, which {{componentDocPages}}
already turns into {{docPage=main}}.
# Make the rest of the page discoverable: return the page's section titles
({{"sections": ["Getting Usable Parameters into the XSLT", ...]}}) with a way
to fetch one ({{docPage=<section>}}), so a model that sees an empty option
filter can still find the section that answers it.
# Optionally a short curated {{notes}} list per component for defaults that
silently change behaviour (mail useHeader*, xslt header parameters), returned
on every call for that component regardless of {{optionsFilter}}.
Related: CAMEL-25534 (mail {{subject}} option description), CAMEL-25533
({{camel run}} applying {{camel.server.port}}). Note the mail page itself still
has "Headers take precedence over pre-configured recipients" above the
useHeader table.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
