Federico Mariani created CAMEL-25539:
----------------------------------------
Summary: camel-jbang-mcp - camel_catalog_doc for an EIP or
language does not say where the element goes nor the YAML shape of expression
and namespace options
Key: CAMEL-25539
URL: https://issues.apache.org/jira/browse/CAMEL-25539
Project: Camel
Issue Type: Improvement
Components: camel-jbang-mcp
Affects Versions: 4.22.1
Reporter: Federico Mariani
In camel-jbang-mcp 4.22.1, {{camel_catalog_eip_doc}} and
{{camel_catalog_language_doc}} return the model options and nothing about how
the element is written in YAML or where it goes. On main both are replaced by
{{camel_catalog_doc}} (CAMEL-24712), which has the same gap for EIPs and for
options whose type is not a scalar. {{camel_catalog_sample}} (CAMEL-24693,
CAMEL-25370) now answers the placement question, but only when an agent thinks
of calling it after reading the doc.
In an evaluation of coding agents (Claude Code and IBM Bob) on migration tasks
with camel-jbang-mcp 4.22.1, the doc answers were read and then not enough to
write valid YAML:
* 4 of 20 sessions that asked for the onException doc then wrote
{{onException}} as a step inside {{from.steps}} and got {{property
'onException' is not defined in the schema}}.
* 34 sessions wrote {{handled: true}} / {{handled: false}} and got {{boolean
found, object expected}}. The doc lists {{handled}} as {{"type":"object"}},
with nothing that says it is an expression.
* About 20 sessions wrote the XPath namespaces as {{namespaces:}}, as a string,
or as a list of {{\{prefix: uri\}}} maps. The doc lists {{namespace}} as
{{"type":"array"}} with the description "Injects the XML Namespaces of prefix
to uri mappings."; the {{[\{key, value\}]}} shape appears nowhere in the answer.
h3. Reproduction
{noformat}
camel_catalog_doc name=onException kind=eip
-> kind, name, title, description, label, input, output, options
no placement; handled:
{"name":"handled","type":"object","required":false,"group":"common",...}
camel_catalog_doc name=xpath kind=language
-> namespace: {"name":"namespace","type":"array","description":"Injects the
XML Namespaces of prefix to uri mappings."}
{noformat}
What the YAML DSL expects:
{code:yaml}
- onException: # a top-level entry, not a step
exception: [java.net.ConnectException]
handled:
constant:
expression: "true"
- route:
from:
uri: direct:start
steps:
- setHeader:
name: price
expression:
xpath:
expression: /c:order/c:price/text()
namespace:
- key: c
value: http://acme.com/cheese
{code}
h3. Cause
{{dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/ai/CatalogDocs.java}}:
* {{eipDoc(EipModel, ...)}} puts the options only. The placement is already
computed by {{CatalogSamples.placement(String)}} (TOP_LEVEL, ERROR_HANDLERS),
but only {{camel_catalog_sample}} returns it.
* {{optionToJson}} adds a YAML hint only for an element written as one of its
kinds ({{isWrittenAsKind}}, CAMEL-25370). An option of kind {{expression}}
({{handled}}, {{continued}}, {{retryWhile}}, {{completionPredicate}}, ...) and
an element list of {{PropertyDefinition}} ({{namespace}} of xpath, xquery,
xtokenize) are shown as {{object}} / {{array}} with no shape.
h3. Fix
* In the EIP answer of {{camel_catalog_doc}}, add the {{placement}} from
{{CatalogSamples.placement}} ("top-level entry: a list item at the same level
as route or from, not a step inside a route" for onException,
routeConfiguration, onCompletion, intercept...) and a hint that
{{camel_catalog_sample}} returns a validated YAML example.
* In {{optionToJson}}, add a {{yaml}} hint for an option of kind {{expression}}
(e.g. {{handled: \{constant: \{expression: "true"\}\}}}, as the validator hint
of CAMEL-24702 says), and for a list of {{PropertyDefinition}} ({{namespace:
[\{key: c, value: http://...\}]}}).
Related: CAMEL-25370 (placement in camel_catalog_sample), CAMEL-24915 (accept a
plain value for handled). Not included: the jq functions {{header()}} /
{{property()}} are already in the doc excerpt on main (CAMEL-25235), and the
simple functions are listed (CAMEL-24804).
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
