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"))