[
https://issues.apache.org/jira/browse/CAMEL-25542?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18126978#comment-18126978
]
Federico Mariani commented on CAMEL-25542:
------------------------------------------
Merged into CAMEL-25541: its description now carries the fix items of this
issue, so one PR covers both.
_Claude Code on behalf of Croway_
> 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-jbang-mcp, camel-platform-http
> Affects Versions: 4.22.1
> Reporter: Federico Mariani
> Priority: Major
>
> 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)
