Shared ToolRegistry, DevConsole tools, analysis tools, and diagnostic prompts

[gnodet]

Summary

Claude Code on behalf of Guillaume Nodet

Introduce a shared ToolRegistry to eliminate tool duplication between the MCP server and Agent REPL, surface DevConsole data as AI-accessible tools, add higher-level analysis capabilities, and create guided diagnostic/optimization prompts. The MCP server's RuntimeTools now delegates to ToolRegistry, making it the single source of truth.

Changes by commit

Commit 1: Introduce shared ToolRegistry (camel-jbang-core)

• Central registry of 49+ shared tool descriptors with ToolDescriptor, ToolContext, ToolExecutor
• AskTools (Agent REPL) refactored to delegate to ToolRegistry for shared tools
• CLI-only and file-system tools remain in AskTools (depend on CamelJBangMain)
• New catalog tools added to registry: catalog_dataformats, catalog_dataformat_doc, catalog_languages, catalog_language_doc, catalog_eip_doc
• 16 unit tests covering tool registration, execution, and edge cases

Commit 2: Surface DevConsole data as AI tools (camel-jbang-core)

• Circuit breaker status (get_circuit_breakers) — aggregates Resilience4j + Fault Tolerance sections
• Startup recorder steps (get_startup_steps)
• Datasource pool status (get_datasources)
• SQL query execution (sql_query) — marked as destructive since arbitrary SQL can include DDL/DML
• OpenTelemetry spans (get_spans)
• Micrometer metrics (get_metrics)

Commit 3: Add analysis and diagnostic tools (camel-jbang-core)

• get_route_analysis — route structure analysis with anti-pattern hints
• get_eip_stats — EIP usage statistics across routes
• detect_config_drift — compare running routes vs source files

Commit 4: Add MCP prompts for diagnosis and optimization (camel-jbang-mcp)

• camel_diagnose_route — guided 7-step workflow for root cause analysis
• camel_optimize_route — guided 6-step workflow for performance optimization

Commit 5: Address review feedback

• sql_query marked as destructive (arbitrary SQL can include DDL/DML)
• ToolContext.catalog() made thread-safe with volatile + double-checked locking
• Removed planning document (design/tui-mcp-agent-gaps.adoc)

Commit 6: Refactor RuntimeTools to delegate to ToolRegistry

• All @Tool methods in RuntimeTools now delegate to ToolRegistry via a helper that resolves nameOrPid, creates ToolContext, and translates exceptions
• Only MCP-specific tools (camel_runtime_processes, camel_runtime_receive) keep their own implementations
• ToolRegistry aligned with MCP behavior: get_memory combines memory+gc+threads sections, get_route_topology accepts metric/external params, trace_control throws on unknown actions
• This makes ToolRegistry the actual single source of truth — changes to tool logic only need to happen in one place

Architecture

ToolRegistry (camel-jbang-core)
  └── 49+ shared tool descriptors (ToolDescriptor + ToolExecutor)
       ├── AskTools (Agent REPL) — delegates to ToolRegistry for shared tools
       └── RuntimeTools (MCP server) — delegates to ToolRegistry for runtime tools
  
CatalogTools (camel-jbang-mcp) — stays separate (versioned catalog, typed records)
ExampleTools (camel-jbang-mcp) — stays separate (typed records, Docker info)

Test plan

• ToolRegistryTest — 16 tests covering registration, execution, edge cases
• MCP module — 280 tests passing
• Both modules compile and pass formatting checks
• Verified delegateToRegistry() correctly bridges ToolExecutionException → ToolCallException

🤖 Generated with Claude Code

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[github-actions]

🧪 CI tested the following changed modules:

• dsl/camel-jbang/camel-jbang-core
• dsl/camel-jbang/camel-jbang-mcp

⚠️ Some tests are disabled on GitHub Actions (@DisabledIfSystemProperty(named = "ci.env.name")) and require manual verification:

• dsl/camel-jbang/camel-jbang-core: 1 test(s) disabled on GitHub Actions
• dsl/camel-jbang/camel-jbang-mcp: 1 test(s) disabled on GitHub Actions

💡 Manual integration tests recommended:

You modified dsl/camel-jbang/camel-jbang-core. The related integration tests in dsl/camel-jbang/camel-jbang-it are excluded from CI. Consider running them manually:

mvn verify -f dsl/camel-jbang/camel-jbang-it -Djbang-it-test

All tested modules (7 modules)

• Camel :: JBang :: Core
• Camel :: JBang :: MCP
• Camel :: JBang :: Plugin :: MCP
• Camel :: JBang :: Plugin :: Route Parser
• Camel :: JBang :: Plugin :: TUI
• Camel :: JBang :: Plugin :: Validate
• Camel :: Launcher :: Container

---

⚙️ View full build and test results

[davsclaus]

Review: Shared ToolRegistry, DevConsole tools, analysis tools, and diagnostic prompts

This review evaluates the PR against project rules and conventions. It does not replace specialized AI review tools (CodeRabbit, Sourcery) or static analysis (SonarCloud).

Overall

Well-structured refactoring. The ToolRegistry pattern is clean, the registerStatusTool/registerRouteControlTool helpers eliminate boilerplate nicely, and backward compatibility is preserved (existing AskCliToolsTest tests pass, AskTools public API unchanged). The MCP prompts (camel_diagnose_route, camel_optimize_route) provide clear step-by-step workflows.

Findings

1. PR description overstates scope — MCP deduplication is not achieved yet (Medium)

The description claims this PR will "eliminate tool duplication between the MCP server and Agent REPL" and create a "single source of truth." However, the MCP server tools (RuntimeTools.java, CatalogTools.java, etc. in camel-jbang-mcp) are not refactored to use the new ToolRegistry — they retain their own Quarkus @Tool-annotated implementations backed by RuntimeService. Currently, ToolRegistry is consumed by AskTools only. This isn't a code defect, but the PR description should accurately reflect what was done vs. what's planned as follow-up.

2. Missing JIRA reference in commits (Low)

Per project conventions, commit format should be CAMEL-XXXX: Brief description. All 5 commits lack a JIRA reference.

3. sql_query tool should be marked destructive (Medium) — see inline comment

4. ToolContext.catalog() lazy init is not thread-safe (Low) — see inline comment

Questions

1. Is refactoring the MCP server (RuntimeTools, CatalogTools, etc.) to consume ToolRegistry planned as a follow-up?
2. The 5th commit says "Remove planning document now that implementation is complete" but no file removal appears in the diff. Was this a file added and removed within this branch?
3. The DevConsole tools (get_startup_steps, get_datasources, get_spans, get_metrics) call actions/status sections that may not exist in all Camel applications. Has the behavior been verified for absent sections — does the IPC protocol return a clean "not available" response vs. an error?
4. The PR body has unchecked manual test items ("Manual verification with a running Camel application" and "MCP server smoke test"). These should ideally be verified before merge.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

[davsclaus]

This lazy initialization is not thread-safe. If ToolContext instances can be shared across threads (e.g., concurrent MCP server requests), two threads could create separate DefaultCamelCatalog instances. If single-threaded use is the intent, a brief comment would clarify that assumption. Otherwise, synchronized or a holder pattern would be safer.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

[davsclaus]

Updated Review — PR #24337

Following up on my earlier review. The two new commits address all prior findings.

Prior findings — all addressed

1. sql_query destructive flag — Now .readOnly(false).destructive(true). ✅
2. ToolContext.catalog() thread safety — Proper double-checked locking with volatile fields. ✅
3. MCP deduplication — RuntimeTools now delegates to ToolRegistry via delegateToRegistry(), with only camel_runtime_processes and camel_runtime_receive remaining as MCP-specific. The "single source of truth" claim is now accurate. ✅

New changes look good

• get_memory enriched in ToolRegistry to combine memory/gc/threads sections — matches prior MCP behavior.
• get_route_topology now has configurable metric/external params instead of hardcoded values.
• trace_control throws on unknown action instead of silently passing through.
• toJsonObject helper handles the String→JsonObject conversion cleanly with a reasonable fallback.
• camel_runtime_receive properly documented as MCP-only.

Remaining (low severity, already flagged)

• Commit messages lack JIRA references per project conventions (CAMEL-XXXX: ... format).

No blocking issues. The PR delivers on its stated goals — nice work consolidating the tool definitions.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.