luigidemasi opened a new issue, #108: URL: https://github.com/apache/camel-kit/issues/108
> Imported from [luigidemasi/camel-kit#248](https://github.com/luigidemasi/camel-kit/issues/248), opened by [Croway](https://github.com/Croway) on 2026-10-10. --- ## Problem `skills/shared/mcp-setup.md` and `skills/shared/iron-laws.md` are the two files that tell agents how to use MCP, and they only describe the Camel catalog server. The generated `.mcp.json` starts three servers (`camel`, `camel-knowledge`, `citrus`), but neither file says when to use the knowledge server. `mcp-setup.md` mentions it only as a row in the runner table (line 37). Iron Law 1 step 2 lists `camel_catalog_component_doc`, `camel_catalog_eip_doc`, `camel_catalog_dataformat_doc` and `camel_catalog_language_doc`. The knowledge tools are described only in `skills/camel-knowledge/SKILL.md`, which agents do not load during normal work. Both files also require a version probe that agents skip, and that fails as written on the pinned server. `mcp-setup.md` Rule 3 says: > Before consuming catalog detail or list fields, call `camel_catalog_components` with `limit=0` and the same `runtime` and full `platformBom` GAV. [...] Record that probe and the exact call arguments as the version binding for subsequent catalog calls Iron Law 1 step 3 makes this mandatory ("ESTABLISH the version binding with the `camel_catalog_components` probe"). The same probe is repeated in `catalog-researcher.md`, `integration-architect.md`, `camel-brainstorm`, `component-selection.md`, `design-assembly.md`, three `camel-migrate` phase-2 guides and `quality-checks.md`. ## Evidence This comes from an evaluation of coding agents (Claude Code with Haiku/Sonnet 5.5, and IBM Bob) on legacy-to-Camel migration tasks, using camel-kit 0.4.1 and camel-jbang-mcp 4.22.1: - Sonnet 5.5 called a knowledge tool in 2 of 72 kit/MCP sessions. Haiku with camel-kit called none in the 4 sessions of a Mule process-API task. When agents did use the knowledge server, it was a fallback after the catalog had no answer, never the first call. The questions were behaviour questions the catalog cannot answer, such as how `camel run` binds the platform-http port, mail STARTTLS, `onException` in YAML, or registering a DataSource bean. - Bob called a non-existent `mcp__camel__camel_docs_search` in 7 sessions. It moved the knowledge tool name onto the camel server. In one session this came after 7 failed catalog calls about DataSource registration. The real `camel_docs_search` then answered on the first try. - No session in 163 camel-kit sessions ran the `limit=0` probe. `camel_catalog_components` was called 14 times in total, always with a filter. - As written, the probe fails in 4.22.1. Every `@ToolArg` of `camel_catalog_components` is required there (`filter`, `label`, `limit`, `runtime`, `camelVersion`, `platformBom`). A real call that omitted `label` returned: ``` camel_catalog_components {"runtime":"main","camelVersion":"4.22.1","platformBom":"org.apache.camel:camel-bom:4.22.1","filter":"activemq"} -> error: Missing required argument: label ``` The same call with `"label": ""` succeeds. - The probe also adds nothing. `.camel-kit/config.properties` already has `project.camelVersion=4.22.1` and `project.platformBomVersion=4.22.1`, and `distribution.properties` pins `camel.mcp.version=4.22.1`. - On Apache Camel `main` (4.23, CAMEL-24712), `camel_catalog_components` and the `camel_catalog_*_doc` tools named in Iron Law 1 are removed. They are replaced by `camel_catalog_find` / `camel_catalog_doc`, and `runtime`/`platformBom` have no equivalent. So the probe and the gate both need rewriting when camel-kit moves past 4.22. `origin/main` of camel-kit has the same text in both files. ## Proposal 1. Add one rule to `mcp-setup.md`, and refer to it from Iron Law 1: *for behaviour questions (which headers propagate, what changed in version X, how an EIP is written in YAML, how `camel run` is configured) use `camel-knowledge` `camel_docs_search` with `max_results` 3. For option names and existence use the catalog with `optionsFilter`. The knowledge tools are on the `camel-knowledge` server, not `camel`.* 2. Remove the `limit=0` probe from Rule 3, Iron Law 1 step 3, and the files listed above. Bind the version from `.camel-kit/config.properties` (the `runtime` and `platformBom` that were passed are the binding). If a probe is kept, give the full argument list that 4.22.1 requires (`filter: ""`, `label: ""`, `limit: 1`). 3. When moving to Camel 4.23+, rename the tools in Iron Law 1 step 2 to `camel_catalog_find` / `camel_catalog_doc`. Related: luigidemasi/camel-kit#246 (rules block in AGENTS.md) and luigidemasi/camel-kit#243 (skill discoverability) cover other parts of the same evaluation. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
