This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git


The following commit(s) were added to refs/heads/main by this push:
     new 38f0d51a96c9 CAMEL-26932: camel-jbang-mcp - a runtime tool acts on the 
integration the call names (#29911)
38f0d51a96c9 is described below

commit 38f0d51a96c961b79f84c68814289c604cd80c54
Author: Claus Ibsen <[email protected]>
AuthorDate: Sun Nov 15 10:59:52 2026 +0100

    CAMEL-26932: camel-jbang-mcp - a runtime tool acts on the integration the 
call names (#29911)
    
    Item 1 of [CAMEL-26932](https://issues.apache.org/jira/browse/CAMEL-26932).
    
    ## Problem
    
    The `camel_runtime_*` tools of the MCP server pick their integration by 
`nameOrPid`. `camel_run`, `camel_get_log`, `camel_get_errors`, `camel_control` 
and `camel_eval_expression` take `name` instead, so agents carry `name` over to 
the runtime tools. Such a call had `name` ignored and acted on the only 
integration that runs:
    
    ```
    camel_runtime_routes {"name":"nosuch"}
    {"argumentNote":"ignored: name; camel_runtime_routes takes 
nameOrPid","routes":[{"routeId":"route1",...
    ```
    
    The same path serves route control, send, receive, SQL, HTTP requests and 
chaos. So an agent could change another app than the one it meant, including 
the user's own. In `camel_runtime_heap_dump`, `name` was the file name of the 
dump.
    
    ## Change
    
    - **Aliases.** A tool that takes `nameOrPid` also takes the integration as 
`name`, `pid` or `integration`. `camel_get_log`, `camel_get_errors`, 
`camel_control` and `camel_eval_expression` also take it as `nameOrPid`, `pid` 
or `integration`. This uses the existing alias mechanism 
(`ToolArgumentAliases`), so the answer notes the declared name, and `camel ask` 
resolves the same way. The declared argument always wins, and tools where 
`name` means something else (`camel_catalog_doc`, `came [...]
    - **Refusal.** Some calls name the integration with an argument the tool 
ignores (`process`, `app`, `application`, `context`, `integrationName`, ...) 
and do not give the tool's own argument. These are now refused with a message 
saying which argument to use, instead of running against the one integration 
that runs.
    - **Heap dump.** `camel_runtime_heap_dump`'s file-name argument is renamed 
from `name` to `file`, so `name` names the integration as on every other 
runtime tool. This is in the 4.24 upgrade guide.
    - **Docs.** `camel-jbang-mcp.adoc` describes the accepted names.
    
    ## Tests
    
    - `ToolArgumentAliasesTest`: the aliases, and the ignored-selector check.
    - `McpArgumentGuardrailTest`: against the real tool definitions. Without 
the fix, both new tests fail.
    - End to end, over stdio, against the runner jar, with one integration 
`orders` running in an isolated home:
    
    | call | main | this PR |
    |---|---|---|
    | `camel_runtime_routes {"name":"nosuch"}` | routes of `orders` | error: no 
Camel process matches `nosuch` |
    | `camel_runtime_routes {"name":"orders"}` | routes of `orders` (by luck) | 
routes of `orders`, note "nameOrPid is the argument name (got name)" |
    | `camel_runtime_routes {"process":"nosuch"}` | routes of `orders` | error: 
process is not an argument ..., give the name or pid as nameOrPid |
    
    - camel-jbang-mcp: all 547 tests pass, built in a reactor with this core.
    - camel-jbang-core: all pass, except two groups on this machine:
      - 9 tests of `ExportTest` and `RunExportGoldenTest` failed with "Address 
already in use" on 8080, because another `camel run` on the machine held that 
port at the time.
      - `DependencyUpdateTest` failed once and passes on its own.
    
      The suites of the two earlier PRs passed all of these, and CI runs them 
on a clean machine.
    
    Co-Authored-By: Claude Opus 5.5 <[email protected]>
---
 .../ROOT/pages/camel-4x-upgrade-guide-4_24.adoc    | 12 +++++
 .../modules/ROOT/pages/camel-jbang-mcp.adoc        |  8 +++-
 .../core/commands/ai/ToolArgumentAliases.java      | 54 +++++++++++++++++++++-
 .../core/commands/ai/ToolArgumentAliasesTest.java  | 40 ++++++++++++++++
 .../core/commands/mcp/McpArgumentGuardrail.java    | 10 ++++
 .../dsl/jbang/core/commands/mcp/RuntimeTools.java  |  4 +-
 .../commands/mcp/McpArgumentGuardrailTest.java     | 37 +++++++++++++++
 7 files changed, 160 insertions(+), 5 deletions(-)

diff --git 
a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc 
b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc
index b3ed7a493bc6..6acc26ae0b92 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_24.adoc
@@ -1495,6 +1495,18 @@ configuration file now fails a command with a message 
that names the file, the k
 command of the CLI has is still stored, with a warning. `camel config unset` 
of a key that is not set now exits with
 code `3` (not found) and says so, as `camel config get` does; it exited with 
`0`.
 
+=== camel-jbang-mcp - the runtime tools act on the integration a call names
+
+A runtime tool of the MCP server (`camel_runtime_*`) picks its integration by 
`nameOrPid`. A call that gave the
+integration as `name` (as `camel_run`, `camel_get_log` and `camel_control` 
take it) had that argument ignored, and the
+tool acted on the only integration that runs, which could be another one. Now 
`name`, `pid` and `integration` are taken
+for `nameOrPid` (and `nameOrPid` for the `name` of `camel_get_log`, 
`camel_get_errors`, `camel_control` and
+`camel_eval_expression`), and a call that names the integration with another 
argument the tool does not take, such as
+`process` or `app`, is refused.
+
+The argument of `camel_runtime_heap_dump` for the file name of the dump is 
renamed from `name` to `file`: `name` now
+names the integration, like on the other runtime tools.
+
 === camel-jbang - camel run exits with 1 when the integration fails to start
 
 When `camel run` cannot start the integration, such as for a route that cannot 
be created or started, it now exits
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc 
b/docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc
index bfeefa47faee..2dc4656f2571 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-mcp.adoc
@@ -844,7 +844,10 @@ NOTE: Runtime tools require a running Camel application 
started via `camel run`.
 application through the file-based IPC protocol in `~/.camel/`. All tools 
accept an optional `nameOrPid`
 parameter; when omitted, the server auto-discovers the running Camel process 
(this works when exactly one
 process is running). The MCP server itself is never one of them: it is not 
listed, not selected when no name is
-given, and a call that names its pid is refused.
+given, and a call that names its pid is refused. A call may also give the 
integration as `name`, `pid` or
+`integration` (and `camel_get_log`, `camel_get_errors`, `camel_control` and 
`camel_eval_expression`, which take `name`,
+accept `nameOrPid`). A call that names the integration with another argument 
the tool does not take, such as
+`process` or `app`, is refused rather than run against the one integration 
that runs.
 
 ==== Process Discovery
 
@@ -936,7 +939,8 @@ given, and a call that names its pid is refused.
 
 | `camel_runtime_heap_dump`
 | Write a heap dump (`.hprof`) from a running integration for deep memory 
analysis with tools such as Eclipse MAT,
-  VisualVM or jhat. The dump is written to the process working directory; a 
`name` with a directory is refused.
+  VisualVM or jhat. The dump is written to the process working directory, 
named by `file`; a `file` with a
+  directory is refused.
 
 | `camel_runtime_memory_leak`
 | Diagnose memory leaks in a running Camel integration using Java Flight 
Recorder (JFR).
diff --git 
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/ai/ToolArgumentAliases.java
 
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/ai/ToolArgumentAliases.java
index ef1904c4e3b4..9ff71f18ce7e 100644
--- 
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/ai/ToolArgumentAliases.java
+++ 
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/ai/ToolArgumentAliases.java
@@ -19,7 +19,9 @@ package org.apache.camel.dsl.jbang.core.commands.ai;
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
+import java.util.Set;
 
 import org.apache.camel.util.json.DeserializationException;
 import org.apache.camel.util.json.JsonObject;
@@ -51,6 +53,25 @@ public final class ToolArgumentAliases {
             // a path says more than a file name, so it wins when a call gives 
both
             "camel_validate_source", pairs("path", "file", "filename", "file", 
"name", "file", "source", "content"));
 
+    /**
+     * The names a call may give the integration a tool acts on by. The 
runtime tools of the MCP server take
+     * {@code nameOrPid}; camel_run, camel_get_log, camel_get_errors, 
camel_control and camel_eval_expression take
+     * {@code name}. A model that carries one over to the other kind of tool 
must not act on another integration
+     * (CAMEL-26932).
+     */
+    private static final Map<String, String> TO_NAME_OR_PID
+            = pairs("name", "nameOrPid", "pid", "nameOrPid", "integration", 
"nameOrPid");
+    private static final Map<String, String> TO_NAME = pairs("nameOrPid", 
"name", "pid", "name", "integration", "name");
+    private static final Set<String> NAME_TOOLS
+            = Set.of("camel_get_log", "camel_get_errors", "camel_control", 
"camel_eval_expression");
+
+    /**
+     * Arguments that name an integration, in lower case: a call that gives 
one the tool ignores must not act on the
+     * only integration that runs.
+     */
+    private static final Set<String> SELECTORS = Set.of("name", "nameorpid", 
"pid", "integration", "integrationname",
+            "process", "processname", "app", "appname", "application", 
"context", "contextname");
+
     private ToolArgumentAliases() {
     }
 
@@ -114,6 +135,37 @@ public final class ToolArgumentAliases {
         return ALIASES.getOrDefault(tool, Map.of());
     }
 
+    /**
+     * The aliases of a tool with the given arguments, alias to declared name: 
those of {@link #aliases(String)}, and
+     * the other names of the argument that picks the integration the tool 
acts on.
+     */
+    public static Map<String, String> aliases(String tool, List<String> names) 
{
+        Map<String, String> answer = new LinkedHashMap<>(aliases(tool));
+        if (names.contains("nameOrPid")) {
+            TO_NAME_OR_PID.forEach(answer::putIfAbsent);
+        } else if (NAME_TOOLS.contains(tool) && names.contains("name")) {
+            TO_NAME.forEach(answer::putIfAbsent);
+        }
+        return answer;
+    }
+
+    /**
+     * The argument a call gave to name an integration that the tool ignored, 
while it did not give the argument the
+     * tool picks its integration by: the tool would act on the only 
integration that runs, which may be another one.
+     * Null when there is none.
+     */
+    public static String ignoredSelector(Resolved<?> resolved) {
+        String selector = resolved.declared().stream().map(Argument::name)
+                .filter(n -> n.equals("nameOrPid") || (n.equals("name") && 
NAME_TOOLS.contains(resolved.tool())))
+                .findFirst().orElse(null);
+        if (selector == null || resolved.arguments().get(selector) != null) {
+            return null;
+        }
+        return resolved.ignored().stream()
+                .filter(n -> SELECTORS.contains(n.toLowerCase(Locale.ROOT)))
+                .findFirst().orElse(null);
+    }
+
     /** The arguments a registry tool declares, for {@link #resolve(String, 
List, Map)}. */
     public static List<Argument> arguments(ToolDescriptor tool) {
         return tool.params().stream().map(p -> new Argument(p.name(), 
p.required())).toList();
@@ -132,7 +184,7 @@ public final class ToolArgumentAliases {
         // alias to declared name, for the aliases taken
         Map<String, String> taken = new LinkedHashMap<>();
         Map<String, String> renamed = new LinkedHashMap<>();
-        for (Map.Entry<String, String> alias : aliases(tool).entrySet()) {
+        for (Map.Entry<String, String> alias : aliases(tool, 
names).entrySet()) {
             String name = alias.getValue();
             if (names.contains(name) && !names.contains(alias.getKey()) && 
!renamed.containsKey(name)
                     && arguments.get(name) == null && 
arguments.get(alias.getKey()) != null) {
diff --git 
a/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/ai/ToolArgumentAliasesTest.java
 
b/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/ai/ToolArgumentAliasesTest.java
index 3f1c45635188..e55748892687 100644
--- 
a/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/ai/ToolArgumentAliasesTest.java
+++ 
b/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/ai/ToolArgumentAliasesTest.java
@@ -182,6 +182,46 @@ class ToolArgumentAliasesTest {
         }
     }
 
+    @Test
+    void theIntegrationOfARuntimeToolMayBeGivenAsNameOrPid() {
+        List<ToolArgumentAliases.Argument> runtime = List.of(new 
ToolArgumentAliases.Argument("nameOrPid", false),
+                new ToolArgumentAliases.Argument("filter", false));
+
+        ToolArgumentAliases.Resolved<String> resolved
+                = ToolArgumentAliases.resolve("camel_runtime_routes", runtime, 
Map.of("name", "orders"));
+        
assertThat(resolved.arguments()).containsExactly(Map.entry("nameOrPid", 
"orders"));
+        assertThat(ToolArgumentAliases.ignoredSelector(resolved)).isNull();
+
+        assertThat(ToolArgumentAliases.resolve("camel_runtime_routes", 
runtime, Map.of("integration", "orders"))
+                .arguments()).containsExactly(Map.entry("nameOrPid", 
"orders"));
+
+        // the tools that take name: only those that act on a running 
integration
+        List<ToolArgumentAliases.Argument> named = List.of(new 
ToolArgumentAliases.Argument("name", false));
+        assertThat(ToolArgumentAliases.resolve("camel_get_log", named, 
Map.of("nameOrPid", "orders")).arguments())
+                .containsExactly(Map.entry("name", "orders"));
+        assertThat(ToolArgumentAliases.resolve("camel_catalog_doc", named, 
Map.of("nameOrPid", "kafka")).ignored())
+                .containsExactly("nameOrPid");
+    }
+
+    @Test
+    void anIgnoredArgumentThatNamesTheIntegrationIsTheSelector() {
+        List<ToolArgumentAliases.Argument> runtime = List.of(new 
ToolArgumentAliases.Argument("nameOrPid", false));
+
+        assertThat(ToolArgumentAliases.ignoredSelector(
+                ToolArgumentAliases.resolve("camel_runtime_routes", runtime, 
Map.of("Process", "orders"))))
+                .isEqualTo("Process");
+        assertThat(ToolArgumentAliases.ignoredSelector(
+                ToolArgumentAliases.resolve("camel_runtime_routes", runtime, 
Map.of("application", "orders"))))
+                .isEqualTo("application");
+        assertThat(ToolArgumentAliases.ignoredSelector(
+                ToolArgumentAliases.resolve("camel_runtime_routes", runtime, 
Map.of("bogus", "x")))).isNull();
+        
assertThat(ToolArgumentAliases.ignoredSelector(ToolArgumentAliases.resolve("camel_runtime_routes",
 runtime,
+                Map.of("nameOrPid", "orders", "app", "orders")))).isNull();
+        // a tool that does not act on an integration has no selector
+        
assertThat(ToolArgumentAliases.ignoredSelector(ToolArgumentAliases.resolve("camel_catalog_find",
+                List.of(new ToolArgumentAliases.Argument("term", true)), 
Map.of("term", "x", "app", "y")))).isNull();
+    }
+
     @Test
     void theNoteIsTheFirstFieldOfAJsonObjectAnswer() throws Exception {
         String answer = 
ToolArgumentAliases.withNote("{\"term\":\"mqtt\",\"matches\":[]}", "term is the 
argument name");
diff --git 
a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpArgumentGuardrail.java
 
b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpArgumentGuardrail.java
index 515c43e1bbdd..37fce4d32922 100644
--- 
a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpArgumentGuardrail.java
+++ 
b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpArgumentGuardrail.java
@@ -62,6 +62,16 @@ public class McpArgumentGuardrail implements 
ToolInputGuardrail, ToolOutputGuard
         if (!resolved.missing().isEmpty()) {
             throw new ToolCallException(resolved.missingMessage());
         }
+        String selector = ToolArgumentAliases.ignoredSelector(resolved);
+        if (selector != null) {
+            // without it the tool would act on the only integration that 
runs, which may be another one
+            throw new ToolCallException(
+                    selector + " is not an argument of " + tool.name() + ", so 
it cannot pick the"
+                                        + " integration: give the name or pid 
of the integration as "
+                                        + 
resolved.declared().stream().map(ToolArgumentAliases.Argument::name)
+                                                .filter(n -> 
n.equals("nameOrPid")).findFirst().orElse("name")
+                                        + ", or leave " + selector + " out to 
use the only integration that runs");
+        }
         if (!resolved.renamed().isEmpty()) {
             context.setArguments(new JsonObject(resolved.arguments()));
         }
diff --git 
a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/RuntimeTools.java
 
b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/RuntimeTools.java
index a4a02ee25e52..aeaf8f809a7c 100644
--- 
a/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/RuntimeTools.java
+++ 
b/dsl/camel-jbang/camel-jbang-mcp/src/main/java/org/apache/camel/dsl/jbang/core/commands/mcp/RuntimeTools.java
@@ -680,11 +680,11 @@ public class RuntimeTools {
             @ToolArg(description = NAME_OR_PID_DESC, required = false) String 
nameOrPid,
             @ToolArg(description = "File name for the heap dump, without a 
directory and without the .hprof extension. "
                                    + "Defaults to heap-dump-<timestamp>",
-                     required = false) String name,
+                     required = false) String file,
             @ToolArg(description = "Whether to dump only live objects (default 
true). Live dumps trigger a GC first",
                      required = false) String live) {
         Map<String, String> args = new HashMap<>();
-        putIfNotBlank(args, "name", name);
+        putIfNotBlank(args, "name", file);
         putIfNotBlank(args, "live", live);
         return delegateToRegistry("write_heap_dump", nameOrPid, args);
     }
diff --git 
a/dsl/camel-jbang/camel-jbang-mcp/src/test/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpArgumentGuardrailTest.java
 
b/dsl/camel-jbang/camel-jbang-mcp/src/test/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpArgumentGuardrailTest.java
index adb3985df530..a0e7ad79e92b 100644
--- 
a/dsl/camel-jbang/camel-jbang-mcp/src/test/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpArgumentGuardrailTest.java
+++ 
b/dsl/camel-jbang/camel-jbang-mcp/src/test/java/org/apache/camel/dsl/jbang/core/commands/mcp/McpArgumentGuardrailTest.java
@@ -129,6 +129,43 @@ class McpArgumentGuardrailTest {
         assertThat(guardrail.callNote.take()).isNull();
     }
 
+    @Test
+    void aRuntimeToolGivenTheIntegrationAsNameActsOnThatIntegration() throws 
Exception {
+        // camel_get_log and camel_control take name, the runtime tools 
nameOrPid: a model carries one over to the
+        // other, and before, the runtime tool ignored name and acted on the 
only integration that runs (CAMEL-26932)
+        assertThat(input("camel_runtime_routes", "name", 
"orders").getArguments().getMap())
+                .containsExactly(Map.entry("nameOrPid", "orders"));
+        assertThat(guardrail.callNote.take()).isEqualTo("nameOrPid is the 
argument name (got name)");
+        assertThat(input("camel_runtime_route_control", "pid", "4711", 
"routeId", "route1",
+                "command", "stop").getArguments().getMap())
+                .containsEntry("nameOrPid", "4711");
+        assertThat(input("camel_get_log", "nameOrPid", 
"orders").getArguments().getMap())
+                .containsEntry("name", "orders");
+        // the file of the heap dump is no longer called name
+        assertThat(input("camel_runtime_heap_dump", "name", "orders", "file", 
"before-fix").getArguments().getMap())
+                .containsEntry("nameOrPid", "orders").containsEntry("file", 
"before-fix");
+        // the declared argument wins
+        assertThat(input("camel_runtime_routes", "nameOrPid", "billing", 
"name", "orders").getArguments().getMap())
+                .containsEntry("nameOrPid", "billing");
+    }
+
+    @Test
+    void aRuntimeToolGivenTheIntegrationByAnotherArgumentIsRefused() throws 
Exception {
+        assertThatThrownBy(() -> input("camel_runtime_routes", "process", 
"orders"))
+                .isInstanceOf(ToolCallException.class)
+                .hasMessage("process is not an argument of 
camel_runtime_routes, so it cannot pick the integration:"
+                            + " give the name or pid of the integration as 
nameOrPid, or leave process out to use the"
+                            + " only integration that runs");
+        assertThatThrownBy(() -> input("camel_get_errors", "app", "orders"))
+                .hasMessageStartingWith("app is not an argument of 
camel_get_errors, so it cannot pick the integration:"
+                                        + " give the name or pid of the 
integration as name,");
+        // with the integration given, another argument is only noted
+        assertThat(input("camel_runtime_routes", "nameOrPid", "orders", "app", 
"orders").getArguments().getMap())
+                .containsEntry("nameOrPid", "orders");
+        // an argument that does not name an integration is only noted
+        assertThat(input("camel_runtime_routes", "bogus", 
"x").getArguments().getMap()).containsKey("bogus");
+    }
+
     @Test
     void aMissingArgumentIsAnsweredWithTheArgumentsOfTheTool() {
         assertThatThrownBy(() -> input("camel_catalog_find", "q", "mqtt"))

Reply via email to