[
https://issues.apache.org/jira/browse/CAMEL-25639?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Federico Mariani updated CAMEL-25639:
-------------------------------------
Attachment: camel-jbang-mcp-review-2026-10.md
> camel-jbang-mcp - consolidate the tool surface (86 to about 66 tools) and
> normalise arguments, hints and output bounds
> ----------------------------------------------------------------------------------------------------------------------
>
> Key: CAMEL-25639
> URL: https://issues.apache.org/jira/browse/CAMEL-25639
> Project: Camel
> Issue Type: Improvement
> Components: camel-jbang-mcp
> Reporter: Federico Mariani
> Priority: Major
> Attachments: camel-jbang-mcp-review-2026-10.md
>
>
> camel-jbang-mcp lists 86 tools on main. In an evaluation of coding agents
> (Claude Code and IBM Bob) on legacy-to-Camel migration tasks with 4.22.1, 647
> calls used 22 of the 73 tools then exposed; the catalog tools, the
> validators, {{camel_component_properties}} and
> {{camel_configuration_validate}} were 98% of the calls, and several of the
> tools that were called answered with something a model could not use
> ({{camel_component_properties}} 15-124 K for one option name,
> {{camel_properties_translate}} main-to-main no-ops,
> {{camel_catalog_languages}} unfiltered 12-14 K). A code review of all 86
> tools (October 2026) then found that about twenty are subsets, composites or
> copies of another tool, several with descriptions that promise more than the
> code does. Dropping and folding them removes wrong answers from the path the
> agents take, makes the surface easier for a model to pick from, and makes the
> profiles of CAMEL-25537 smaller to define.
> The first group is the one the evaluation exercised; the second was never
> called in any session and is a cleanup.
> h3. First: tools on the agents' path
> || Tool || Into || Why ||
> | {{camel_component_properties}} | {{configKey}} on the component options of
> {{camel_catalog_doc}} | Same {{ComponentModel}}; its endpoint-options claim
> is false (CAMEL-25541). |
> | {{camel_catalog_docs}} | drop, or a {{kind=page}} in {{find}} | A page
> index whose names {{camel_catalog_doc}} resolves only for the four artifact
> kinds ({{CatalogDocs.java:227, 246, 270, 444}}). |
> | {{camel_configuration_validate}} | {{camel_validate_source}} on a
> {{.properties}} file | {{validate_source}} already runs the same catalog
> validation per line ({{PropertiesChecks.java:137}}) plus nested-group hints,
> closest-name suggestions, line numbers and {{fixes}}; add
> {{runtime}}/{{platformBom}} there. CAMEL-25538 stays a catalog fix. |
> h3. Second: never called in any evaluation session
> || Tool || Into || Why ||
> | {{camel_runtime_receive}} | drop | Leaks a consumer (see the code-review
> umbrella issue). |
> | {{camel_catalog_kamelets}}, {{camel_catalog_kamelet_doc}} |
> {{camel_catalog_doc}} / {{camel_catalog_find}} {{kind=kamelet}} (CAMEL-25379)
> | Same catalog jar; {{catalog_doc}} already adds the YAML shape, suggestions
> and project Kamelets. Add {{type}}, {{supportLevel}}, {{dependencies}} to the
> kamelet answer and let {{find}} take an empty term with a {{type}} filter. |
> | {{camel_migration_compatibility}} | {{camel_migration_recipes}} with the
> Java check from {{camelReleases()}} | Static and wrong data, unused required
> argument (see the migration data issue). |
> | {{camel_migration_analyze}} | {{camel_dependency_check}} {{projectInfo}} |
> Subset ({{DependencyCheckTools.java:87-88}});
> {{camel_migration_wildfly_karaf}} takes {{sourceRuntime}} instead of a POM. |
> | {{camel_openapi_mock_guidance}} | {{camel_openapi_scaffold}} output when
> {{missingOperation=mock}} | Static text plus a duplicate per-operation walk. |
> | {{camel_runtime_route_analysis}}, {{camel_runtime_eip_stats}},
> {{camel_runtime_config_drift}} | drop | Composites of two unbounded dumps
> each with six static hint strings and no analysis, aggregation or comparison
> ({{ToolRegistry.java:681-774}}), despite descriptions promising all three. |
> | {{camel_runtime_ai_trace}} | {{filter=ai}} on {{camel_runtime_history}} /
> {{top}} | Only true composite; sees one exchange. |
> | {{camel_route_context}} | {{camel_project_overview}} with a {{content}}
> argument | Its EIP extraction is a substring match over all model names
> ({{ExplainTools.java:106-122}}): every YAML route "uses" to, from, step,
> route; {{kafka:topic}} matches {{to}}. Use {{RouteNodes}}/{{RouteModel}}. |
> | {{camel_route_harden_context}} | {{camel_security_scan}} behind
> {{includeContext}} | Same regexes, coarser ({{HardenTools.java:181-243}} vs
> {{SecurityScanTools.java:202-326}}); the prompts call only harden, never the
> line-level scanner. Keep the catalog component context and the CVE match. |
> | {{camel_runtime_heap_histogram}}, {{heap_dump}}, {{memory_leak}} | one
> {{camel_runtime_heap view=histogram|dump|jfr}} | |
> | {{camel_runtime_trace}} | split the read ({{dump}}) from
> {{enable}}/{{disable}} | Today the whole tool is {{readOnlyHint=false}}, so
> read-only clients cannot dump traces. |
> {{ExampleTools}} becomes a thin wrapper of the registry (as
> {{AuthoringTools}} is): duplicated code with divergent not-found behaviour,
> CAMEL-25535.
> h3. Arguments
> * Process selector: {{nameOrPid}} on the runtime tools, {{name}} on
> {{camel_control}}/{{get_log}}/{{get_errors}}/{{eval_expression}}; required on
> {{ai_trace}} only.
> * Booleans typed {{String}} in {{heap_dump}}, {{memory_leak}}, {{sql}};
> {{limit}} {{Integer}} in browse/get_log but {{String}} in spans ({{limit}})
> and sql ({{maxRows}}).
> * Route selector {{routeId}} vs {{routeFilter}}; {{headers}} as {{key=value}}
> lines in {{send}} but JSON or {{name: value}} in {{http_request}}.
> * Three camelVersion descriptions ({{VERSION_DESC}},
> {{ToolArgDocs.CAMEL_VERSION}}, {{ToolArgDocs.VERSION_QUERY}} which asks for a
> Quarkus platform version); {{kind}} vocabularies differ between doc, find and
> sample; {{limit <= 0}} throws in docs, defaults in examples, is used raw in
> kamelets.
> * Four tools take a POM as inline content; none takes a {{directory}} like
> {{camel_project_overview}} does.
> h3. Output bounds the consoles support and the registry never passes
> {{route_source}} ({{filter=*}} is every file in full),
> {{route_dump}}/{{route_structure}} ({{limit}}, {{brief}}), {{thread_dump}}
> (full stacks of every thread), {{trace}} dump ({{limit}}, {{bodyMaxChars}}),
> {{history}} ({{summary}} exists in the registry, {{ToolRegistry.java:220}},
> not in the MCP wrapper), {{browse}} ({{bodyMaxChars}}),
> {{properties}}/{{endpoints}}/{{services}} (no filter).
> h3. Hints
> {{send}} destructive in MCP, not in the registry; {{route_control}}
> destructive for start/resume; {{sql}} destructive blocks read-write clients
> from SELECT (a SELECT-only check would allow it); {{heap_dump}} name
> unvalidated; {{write_file}} overwrites whole files as non-destructive.
> h3. Also worth doing on the way
> Hand-written tables with dead schemes: {{SecurityData}} lists websocket,
> rabbitmq, redis, ldaps, aws2-secrets-manager, cassandraql (not in the
> catalog; a component with an option marked {{secret}} or {{security=}} is
> derivable); {{TestInfraData}} maps 16 of 76 test-infra modules and sends
> sftp/ftps to plain FTP; {{DependencyData}} core-transitive list is only right
> for the {{camel-core}} aggregate. Regex heuristics with concrete false
> positives: {{security_scan}} flags {{to:}} producers and YAML {{- rest:}}
> blocks as consumers without a header filter, any {{sql:}} without {{:#}}, a
> log line with {{file:}} and {{${}}; {{route_cost_estimate}} prices Bedrock as
> Claude Sonnet regardless of {{modelId}}; {{route_test_scaffold}} generates a
> new {{from(first)}} to mock route so nothing of the real route is tested;
> {{camel_render_route_diagram}} says "parsed without running it" but boots a
> transient {{Run}}. Doc rows to refresh: DOC:349 ("only a plain file name"),
> DOC:493 (example levels), DOC:601 ("17 exceptions", 19), {{camel_control}}
> omits {{reload}}, {{tool_groups}} omits http/semantic,
> {{camel_migrate_project}} says pomContent required.
> Blocks CAMEL-25537: define the profiles over the reduced surface.
> _Claude Code on behalf of Croway_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
