Skip to content

Commit fe2e38e

Browse files
steipetesteipete
committed
feat: add MCP code-mode namespace
1 parent 2e25400 commit fe2e38e

8 files changed

Lines changed: 602 additions & 28 deletions

File tree

‎docs/reference/code-mode.md‎

Lines changed: 41 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,8 @@ When code mode is active:
4444
guest program through `ALL_TOOLS` and `tools`.
4545
- Guest code can search the hidden catalog, describe a tool, and call a tool
4646
through the same OpenClaw execution path used by normal agent turns.
47+
- MCP tools are grouped under the `MCP` namespace. In code mode, this namespace
48+
is the only supported way to call MCP tools.
4749
- `wait` resumes a suspended code-mode run when nested tool calls are still
4850
pending.
4951

@@ -381,6 +383,7 @@ The guest runtime exposes a small global API:
381383
```typescript
382384
declare const ALL_TOOLS: ToolCatalogEntry[];
383385
declare const tools: ToolCatalog;
386+
declare const MCP: Record<string, unknown>;
384387
declare const namespaces: Record<string, unknown>;
385388

386389
declare function text(value: unknown): void;
@@ -432,6 +435,21 @@ const content = await tools.call(fileRead.id, { path: "README.md" });
432435
const hits = await tools.web_search({ query: "OpenClaw code mode" });
433436
```
434437

438+
MCP catalog entries are not callable through `tools.call(...)` or convenience
439+
functions in code mode. Use the generated `MCP` namespace instead:
440+
441+
```typescript
442+
const issue = await MCP.github.createIssue({
443+
owner: "openclaw",
444+
repo: "openclaw",
445+
title: "Investigate gateway logs",
446+
});
447+
448+
const snapshot = await MCP.chromeDevtools.takeSnapshot({ output: "markdown" });
449+
const resource = await MCP.docs.resources.read("memo://one");
450+
const prompt = await MCP.docs.prompts.get("brief", { topic: "release" });
451+
```
452+
435453
The guest runtime must not expose host objects directly. Inputs and outputs cross
436454
the bridge as JSON-compatible values with explicit size caps.
437455

@@ -613,10 +631,10 @@ Namespace changes should cover the security boundary and the guest behavior:
613631
- suspended namespace calls resume through `wait`
614632
- plugin rollback clears the owning namespace registrations
615633

616-
Namespaces complement the generic `tools.search` / `tools.call` catalog. Use
617-
the catalog for arbitrary enabled tools; use namespaces for plugin-owned,
618-
documented domain APIs where concise code is more reliable than repeated schema
619-
lookups.
634+
Namespaces complement the generic `tools.search` / `tools.call` catalog. Use the
635+
catalog for arbitrary enabled OpenClaw, plugin, and client tools; use `MCP` for
636+
MCP tools; use other namespaces for plugin-owned, documented domain APIs where
637+
concise code is more reliable than repeated schema lookups.
620638

621639
## Output API
622640

@@ -681,6 +699,12 @@ The catalog omits code-mode control tools:
681699

682700
This prevents recursion and keeps the model-facing contract narrow.
683701

702+
MCP entries stay in the run-scoped catalog so policy, approvals, hooks,
703+
telemetry, transcript projection, and exact tool ids remain shared with normal
704+
tool execution. The guest-facing `tools.call(...)` bridge rejects MCP entries;
705+
the generated `MCP.<server>.<tool>(...)` namespace resolves back to the exact
706+
catalog id and then dispatches through the same executor path.
707+
684708
## Tool Search interaction
685709

686710
Code mode supersedes the OpenClaw Tool Search model surface for runs where it is
@@ -693,6 +717,7 @@ When `tools.codeMode.enabled` is true and code mode activates:
693717
- The same cataloging idea moves inside the guest runtime.
694718
- The guest runtime receives compact `ALL_TOOLS` metadata and search, describe,
695719
and call helpers.
720+
- MCP calls use the generated `MCP` namespace instead of `tools.call(...)`.
696721
- Nested calls dispatch through the same OpenClaw executor path that Tool Search
697722
uses.
698723

@@ -912,6 +937,8 @@ Code mode coverage should prove:
912937
- all effective tools appear in `ALL_TOOLS`
913938
- denied tools do not appear in `ALL_TOOLS`
914939
- `tools.search`, `tools.describe`, and `tools.call` work for OpenClaw tools
940+
- MCP namespace calls work for visible MCP tools and direct MCP `tools.call`
941+
attempts fail closed
915942
- Tool Search control tools are hidden from both the model surface and the hidden
916943
catalog
917944
- nested calls preserve approval and hook behavior
@@ -939,13 +966,16 @@ Run these as integration or end-to-end tests when changing the runtime:
939966
5. Send an agent turn with OpenClaw, plugin, MCP, and client test tools.
940967
6. Assert the model-visible tool list is exactly `exec`, `wait`.
941968
7. In `exec`, read `ALL_TOOLS` and assert the effective test tools are present.
942-
8. In `exec`, call `tools.search`, `tools.describe`, and `tools.call`.
943-
9. Assert denied tools are absent and cannot be called by guessed id.
944-
10. Start a nested tool call that resolves after `exec` returns `waiting`.
945-
11. Call `wait` and assert the restored VM receives the tool result.
946-
12. Assert the final answer contains output produced after restore.
947-
13. Assert timeout, abort, and snapshot expiry clean up runtime state.
948-
14. Export trajectory and assert nested calls are visible under the parent
969+
8. In `exec`, call OpenClaw/plugin/client tools through `tools.search`,
970+
`tools.describe`, and `tools.call`.
971+
9. In `exec`, call MCP tools through `MCP.<server>.<tool>(...)` and assert direct
972+
MCP `tools.call(...)` attempts fail.
973+
10. Assert denied tools are absent and cannot be called by guessed id.
974+
11. Start a nested tool call that resolves after `exec` returns `waiting`.
975+
12. Call `wait` and assert the restored VM receives the tool result.
976+
13. Assert the final answer contains output produced after restore.
977+
14. Assert timeout, abort, and snapshot expiry clean up runtime state.
978+
15. Export trajectory and assert nested calls are visible under the parent
949979
code-mode call.
950980

951981
Docs-only changes to this page should still run `pnpm check:docs`.

‎src/agents/agent-bundle-mcp-materialize.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
33
import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
44
import type { OpenClawConfig } from "../config/types.openclaw.js";
55
import { logWarn } from "../logger.js";
6-
import { setPluginToolMeta } from "../plugins/tools.js";
6+
import { setPluginToolMeta, type PluginToolMcpMeta } from "../plugins/tools.js";
77
import {
88
buildSafeToolName,
99
normalizeReservedToolNames,
@@ -150,7 +150,7 @@ function addMcpUtilityTool(params: {
150150
serverName: string;
151151
safeServerName: string;
152152
executionMode: AnyAgentTool["executionMode"];
153-
operation: string;
153+
operation: Exclude<PluginToolMcpMeta["operation"], "tool">;
154154
label: string;
155155
description: string;
156156
parameters: Record<string, unknown>;
@@ -177,6 +177,12 @@ function addMcpUtilityTool(params: {
177177
setPluginToolMeta(agentTool, {
178178
pluginId: "bundle-mcp",
179179
optional: false,
180+
mcp: {
181+
serverName: params.serverName,
182+
safeServerName: params.safeServerName,
183+
toolName: params.operation,
184+
operation: params.operation,
185+
},
180186
});
181187
params.tools.push(agentTool);
182188
}
@@ -242,6 +248,12 @@ export function buildBundleMcpToolsFromCatalog(params: {
242248
setPluginToolMeta(agentTool, {
243249
pluginId: "bundle-mcp",
244250
optional: false,
251+
mcp: {
252+
serverName: tool.serverName,
253+
safeServerName: tool.safeServerName,
254+
toolName: tool.toolName,
255+
operation: "tool",
256+
},
245257
});
246258
tools.push(agentTool);
247259
}

‎src/agents/agent-bundle-mcp-tools.materialize.test.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,15 @@ describe("createBundleMcpToolRuntime", () => {
9090

9191
expect(runtime.tools.map((tool) => tool.name)).toEqual(["bundleProbe__bundle_probe"]);
9292
expect(runtime.tools[0].executionMode).toBe("sequential");
93-
expect(getPluginToolMeta(runtime.tools[0])?.pluginId).toBe("bundle-mcp");
93+
expect(getPluginToolMeta(runtime.tools[0])).toMatchObject({
94+
pluginId: "bundle-mcp",
95+
mcp: {
96+
serverName: "bundleProbe",
97+
safeServerName: "bundleProbe",
98+
toolName: "bundle_probe",
99+
operation: "tool",
100+
},
101+
});
94102
const result = await runtime.tools[0].execute("call-bundle-probe", {}, undefined, undefined);
95103
expectTextContentBlock(result.content[0], "FROM-BUNDLE");
96104
expect(result.details).toEqual({

0 commit comments

Comments
 (0)