Federico Mariani created CAMEL-25540:
----------------------------------------
Summary: camel-jbang-mcp - catalog lookups that find nothing
answer with an empty list or a bare not-found, which agents read as unsupported
Key: CAMEL-25540
URL: https://issues.apache.org/jira/browse/CAMEL-25540
Project: Camel
Issue Type: Improvement
Components: camel-jbang-mcp
Affects Versions: 4.22.1
Reporter: Federico Mariani
When a catalog lookup finds nothing, the MCP tools return an empty list or a
bare "not found", and agents read that as "Camel does not support this". The
not-found side is mostly fixed on main (CAMEL-24712 unified
{{camel_catalog_doc}} with suggestions, CAMEL-24898 resolves json/json-jackson,
CAMEL-25370 answers for the error handler). This issue is about what is still
missing on main.
In an evaluation of coding agents (Claude Code and IBM Bob) on migration tasks,
with camel-jbang-mcp 4.22.1, 25 of 81 {{camel_catalog_component_doc}} calls
with {{optionsFilter}} (22 of 53 sessions) came back with no option at all. The
agents concluded the feature does not exist: on smtp with {{optionsFilter:
tls}} (15 sessions) several decided "no TLS support" and two switched to
{{useJavaMailSessionPropertiesFromHeaders=true}} with {{mail.smtp.*}} headers;
on xslt with {{optionsFilter: param}} the agents concluded XSLT takes no
parameters and one moved to FreeMarker; on activemq {{optionsFilter:
redeliver}} found nothing (redelivery is configured elsewhere).
h3. Reproduction
{noformat}
camel_catalog_component_doc component: smtp optionsFilter: tls
includeOptions: all
-> {"name":"smtp", ..., "componentOptions":[], "endpointOptions":[],
"headers":[]}
camel_catalog_component_doc component: xslt optionsFilter: param
includeOptions: all
-> {"name":"xslt", ..., "componentOptions":[], "endpointOptions":[],
"headers":[]}
{noformat}
On main the filter also searches descriptions, groups and labels, which helps
but does not close it:
* smtp + {{tls}} now returns exactly one option,
{{useJavaMailSessionPropertiesFromHeaders}}, the one its own description warns
against for this purpose. The supported way, {{mail.smtp.starttls.enable=true}}
as a URI parameter, is not shown:
{{MailComponent.configureAdditionalJavaMailProperties}} passes every {{mail.*}}
parameter through, and the catalog knows it ({{additionalJavaMailProperties}}
has {{"prefix": "mail.", "multiValue": true}}), but the answer does not say so.
* xslt + {{param}} still matches no option. The answer is in the component
page, section "Getting Usable Parameters into the XSLT" (headers and variables
are passed as stylesheet parameters).
* An empty match carries {{"matchedOptions": 0}} and nothing else.
Not-found names that main still does not resolve (reading
{{CatalogDocs.catalogDoc}}):
* Page names from {{camel_catalog_docs}} ({{wireTap-eip}}, {{onException-eip}},
{{jackson-dataformat}}): {{camel_catalog_docs}} lists them and points at
{{camel_catalog_doc}}, but {{camel_catalog_doc name: wireTap-eip}} ends in
"Artifact not found" with no suggestion, since the
{{-eip}}/{{-component}}/{{-dataformat}}/{{-language}} suffix is not stripped.
* {{retry}}: {{suggestEipNames("retry", 1)}} matches the title word of
{{optimisticLockRetryPolicy}}, so {{eipByTerm}} answers with the aggregate's
optimistic-lock policy instead of pointing at {{errorHandler}} /
{{onException}} / {{redeliveryPolicy}}.
* {{camel_catalog_example_file}} with an unknown example: "Example not found:
X" without the example names (separate from CAMEL-25535).
h3. Cause
* 4.22.1: {{CatalogTools.nameFilter}} (substring on option name only) and
{{toComponentDetailResult}} return the empty lists as is.
* main: {{dsl/camel-jbang/camel-jbang-core/.../commands/ai/CatalogDocs.java}},
{{componentDoc}} / {{putOptions}} / {{matchesOptionFilter}}: no handling for
zero matches; {{catalogDoc}} does not normalise page names; {{eipByTerm}}
accepts a title-word match as the answer.
{{ExampleTools.camel_catalog_example_file}}: bare "Example not found".
h3. Fix
# When {{optionsFilter}} matches no option, say so ({{"note": "no option
matches 'tls'"}}) and add: the closest option names by edit distance (the
catalog has the suggester since CAMEL-24666), with their group; the multi-value
prefix options of the component ({{additionalJavaMailProperties}}: "any mail.*
URI parameter is passed to JavaMail"), also when the filter did match
something; and the headings of the doc sections whose text contains the term,
so the caller can ask for the page.
# In {{camel_catalog_doc}}, strip a {{-component}}, {{-dataformat}},
{{-language}} or {{-eip}} suffix and look up again (case-insensitive), so the
names {{camel_catalog_docs}} returns work.
# Do not resolve a bare word such as {{retry}} to an EIP by a title word alone;
return it as a suggestion together with the error handler entries, or add
{{retry}}/{{redelivery}} as aliases of the error handler.
# {{camel_catalog_example_file}}: list the closest example names on "Example
not found".
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
