diff --git a/CHANGELOG.md b/CHANGELOG.md index 24335d41a91..4ff37ae11c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,7 @@ Docs: https://docs.openclaw.ai - secrets: harden read-only SecretRef command paths and diagnostics. (#47794) Thanks @joshavant. - Browser/existing-session: support `browser.profiles..userDataDir` so Chrome DevTools MCP can attach to Brave, Edge, and other Chromium-based browsers through their own user data directories. (#48170) Thanks @velvet-shark. - Skills/prompt budget: preserve all registered skills via a compact catalog fallback before dropping entries when the full prompt format exceeds `maxSkillsPromptChars`. (#47553) Thanks @snese. +- Plugins/bundles: make enabled bundle MCP servers expose runnable tools in embedded Pi, and default relative bundle MCP launches to the bundle root so marketplace bundles like Context7 work through Pi instead of stopping at config import. ### Breaking diff --git a/docs/plugins/bundles.md b/docs/plugins/bundles.md index 2fad626ccfe..bc6bc49e5a0 100644 --- a/docs/plugins/bundles.md +++ b/docs/plugins/bundles.md @@ -104,11 +104,15 @@ loader. Cursor command markdown works through the same path. - `HOOK.md` - `handler.ts` or `handler.js` -#### MCP for CLI backends +#### MCP for Pi - enabled bundles can contribute MCP server config -- current runtime wiring is used by the `claude-cli` backend -- OpenClaw merges bundle MCP config into the backend `--mcp-config` file +- OpenClaw merges bundle MCP config into the effective embedded Pi settings as + `mcpServers` +- OpenClaw also exposes supported bundle MCP tools during embedded Pi agent + turns by launching supported stdio MCP servers as subprocesses +- project-local Pi settings still apply after bundle defaults, so workspace + settings can override bundle MCP entries when needed #### Embedded Pi settings @@ -133,7 +137,6 @@ diagnostics/info output, but OpenClaw does not run them yet: - Cursor `.cursor/agents` - Cursor `.cursor/hooks.json` - Cursor `.cursor/rules` -- Cursor `mcpServers` outside the current mapped runtime paths - Codex inline/app metadata beyond capability reporting ## Capability reporting @@ -153,7 +156,8 @@ Current exceptions: - Claude `commands` is considered supported because it maps to skills - Claude `settings` is considered supported because it maps to embedded Pi settings - Cursor `commands` is considered supported because it maps to skills -- bundle MCP is considered supported where OpenClaw actually imports it +- bundle MCP is considered supported because it maps into embedded Pi settings + and exposes supported stdio tools to embedded Pi - Codex `hooks` is considered supported only for OpenClaw hook-pack layouts ## Format differences @@ -195,6 +199,8 @@ Claude-specific notes: - `commands/` is treated like skill content - `settings.json` is imported into embedded Pi settings +- `.mcp.json` and manifest `mcpServers` can expose supported stdio tools to + embedded Pi - `hooks/hooks.json` is detected, but not executed as Claude automation ### Cursor @@ -246,7 +252,9 @@ Current behavior: - bundle discovery reads files inside the plugin root with boundary checks - skills and hook-pack paths must stay inside the plugin root - bundle settings files are read with the same boundary checks -- OpenClaw does not execute arbitrary bundle runtime code in-process +- supported stdio bundle MCP servers may be launched as subprocesses for + embedded Pi tool calls +- OpenClaw does not load arbitrary bundle runtime modules in-process This makes bundle support safer by default than native plugin modules, but you should still treat third-party bundles as trusted content for the features they diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 8ab2ba87e1f..48acd41e202 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -214,18 +214,23 @@ plugins: OpenClaw skill loader - supported now: Claude bundle `settings.json` defaults for embedded Pi agent settings (with shell override keys sanitized) +- supported now: bundle MCP config, merged into embedded Pi agent settings as + `mcpServers`, with supported stdio bundle MCP tools exposed during embedded + Pi agent turns - supported now: Cursor `.cursor/commands/*.md` roots, mapped into the normal OpenClaw skill loader - supported now: Codex bundle hook directories that use the OpenClaw hook-pack layout (`HOOK.md` + `handler.ts`/`handler.js`) - detected but not wired yet: other declared bundle capabilities such as - agents, Claude hook automation, Cursor rules/hooks/MCP metadata, MCP/app/LSP + agents, Claude hook automation, Cursor rules/hooks metadata, app/LSP metadata, output styles That means bundle install/discovery/list/info/enablement all work, and bundle skills, Claude command-skills, Claude bundle settings defaults, and compatible -Codex hook directories load when the bundle is enabled, but bundle runtime code -is not executed in-process. +Codex hook directories load when the bundle is enabled. Supported bundle MCP +servers may also run as subprocesses for embedded Pi tool calls when they use +supported stdio transport, but bundle runtime modules are not loaded +in-process. Bundle hook support is limited to the normal OpenClaw hook directory format (`HOOK.md` plus `handler.ts`/`handler.js` under the declared hook roots). diff --git a/src/agents/embedded-pi-mcp.ts b/src/agents/embedded-pi-mcp.ts new file mode 100644 index 00000000000..82d4d0e486c --- /dev/null +++ b/src/agents/embedded-pi-mcp.ts @@ -0,0 +1,29 @@ +import type { OpenClawConfig } from "../config/config.js"; +import { normalizeConfiguredMcpServers } from "../config/mcp-config.js"; +import type { BundleMcpDiagnostic, BundleMcpServerConfig } from "../plugins/bundle-mcp.js"; +import { loadEnabledBundleMcpConfig } from "../plugins/bundle-mcp.js"; + +export type EmbeddedPiMcpConfig = { + mcpServers: Record; + diagnostics: BundleMcpDiagnostic[]; +}; + +export function loadEmbeddedPiMcpConfig(params: { + workspaceDir: string; + cfg?: OpenClawConfig; +}): EmbeddedPiMcpConfig { + const bundleMcp = loadEnabledBundleMcpConfig({ + workspaceDir: params.workspaceDir, + cfg: params.cfg, + }); + const configuredMcp = normalizeConfiguredMcpServers(params.cfg?.mcp?.servers); + + return { + // OpenClaw config is the owner-managed layer, so it overrides bundle defaults. + mcpServers: { + ...bundleMcp.config.mcpServers, + ...configuredMcp, + }, + diagnostics: bundleMcp.diagnostics, + }; +} diff --git a/src/agents/mcp-stdio.ts b/src/agents/mcp-stdio.ts new file mode 100644 index 00000000000..77ab6171ca7 --- /dev/null +++ b/src/agents/mcp-stdio.ts @@ -0,0 +1,79 @@ +type StdioMcpServerLaunchConfig = { + command: string; + args?: string[]; + env?: Record; + cwd?: string; +}; + +type StdioMcpServerLaunchResult = + | { ok: true; config: StdioMcpServerLaunchConfig } + | { ok: false; reason: string }; + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === "object" && !Array.isArray(value); +} + +function toStringRecord(value: unknown): Record | undefined { + if (!isRecord(value)) { + return undefined; + } + const entries = Object.entries(value) + .map(([key, entry]) => { + if (typeof entry === "string") { + return [key, entry] as const; + } + if (typeof entry === "number" || typeof entry === "boolean") { + return [key, String(entry)] as const; + } + return null; + }) + .filter((entry): entry is readonly [string, string] => entry !== null); + return entries.length > 0 ? Object.fromEntries(entries) : undefined; +} + +function toStringArray(value: unknown): string[] | undefined { + if (!Array.isArray(value)) { + return undefined; + } + const entries = value.filter((entry): entry is string => typeof entry === "string"); + return entries.length > 0 ? entries : []; +} + +export function resolveStdioMcpServerLaunchConfig(raw: unknown): StdioMcpServerLaunchResult { + if (!isRecord(raw)) { + return { ok: false, reason: "server config must be an object" }; + } + if (typeof raw.command !== "string" || raw.command.trim().length === 0) { + if (typeof raw.url === "string" && raw.url.trim().length > 0) { + return { + ok: false, + reason: "only stdio MCP servers are supported right now", + }; + } + return { ok: false, reason: "its command is missing" }; + } + const cwd = + typeof raw.cwd === "string" && raw.cwd.trim().length > 0 + ? raw.cwd + : typeof raw.workingDirectory === "string" && raw.workingDirectory.trim().length > 0 + ? raw.workingDirectory + : undefined; + return { + ok: true, + config: { + command: raw.command, + args: toStringArray(raw.args), + env: toStringRecord(raw.env), + cwd, + }, + }; +} + +export function describeStdioMcpServerLaunchConfig(config: StdioMcpServerLaunchConfig): string { + const args = + Array.isArray(config.args) && config.args.length > 0 ? ` ${config.args.join(" ")}` : ""; + const cwd = config.cwd ? ` (cwd=${config.cwd})` : ""; + return `${config.command}${args}${cwd}`; +} + +export type { StdioMcpServerLaunchConfig, StdioMcpServerLaunchResult }; diff --git a/src/agents/pi-bundle-mcp-tools.test.ts b/src/agents/pi-bundle-mcp-tools.test.ts new file mode 100644 index 00000000000..69b2839eb94 --- /dev/null +++ b/src/agents/pi-bundle-mcp-tools.test.ts @@ -0,0 +1,184 @@ +import fs from "node:fs/promises"; +import { createRequire } from "node:module"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import { createBundleMcpToolRuntime } from "./pi-bundle-mcp-tools.js"; + +const require = createRequire(import.meta.url); +const SDK_SERVER_MCP_PATH = require.resolve("@modelcontextprotocol/sdk/server/mcp.js"); +const SDK_SERVER_STDIO_PATH = require.resolve("@modelcontextprotocol/sdk/server/stdio.js"); + +const tempDirs: string[] = []; + +async function makeTempDir(prefix: string): Promise { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix)); + tempDirs.push(dir); + return dir; +} + +async function writeExecutable(filePath: string, content: string): Promise { + await fs.mkdir(path.dirname(filePath), { recursive: true }); + await fs.writeFile(filePath, content, { encoding: "utf-8", mode: 0o755 }); +} + +async function writeBundleProbeMcpServer(filePath: string): Promise { + await writeExecutable( + filePath, + `#!/usr/bin/env node +import { McpServer } from ${JSON.stringify(SDK_SERVER_MCP_PATH)}; +import { StdioServerTransport } from ${JSON.stringify(SDK_SERVER_STDIO_PATH)}; + +const server = new McpServer({ name: "bundle-probe", version: "1.0.0" }); +server.tool("bundle_probe", "Bundle MCP probe", async () => { + return { + content: [{ type: "text", text: process.env.BUNDLE_PROBE_TEXT ?? "missing-probe-text" }], + }; +}); + +await server.connect(new StdioServerTransport()); +`, + ); +} + +async function writeClaudeBundle(params: { + pluginRoot: string; + serverScriptPath: string; +}): Promise { + await fs.mkdir(path.join(params.pluginRoot, ".claude-plugin"), { recursive: true }); + await fs.writeFile( + path.join(params.pluginRoot, ".claude-plugin", "plugin.json"), + `${JSON.stringify({ name: "bundle-probe" }, null, 2)}\n`, + "utf-8", + ); + await fs.writeFile( + path.join(params.pluginRoot, ".mcp.json"), + `${JSON.stringify( + { + mcpServers: { + bundleProbe: { + command: "node", + args: [path.relative(params.pluginRoot, params.serverScriptPath)], + env: { + BUNDLE_PROBE_TEXT: "FROM-BUNDLE", + }, + }, + }, + }, + null, + 2, + )}\n`, + "utf-8", + ); +} + +afterEach(async () => { + await Promise.all( + tempDirs.splice(0, tempDirs.length).map((dir) => fs.rm(dir, { recursive: true, force: true })), + ); +}); + +describe("createBundleMcpToolRuntime", () => { + it("loads bundle MCP tools and executes them", async () => { + const workspaceDir = await makeTempDir("openclaw-bundle-mcp-tools-"); + const pluginRoot = path.join(workspaceDir, ".openclaw", "extensions", "bundle-probe"); + const serverScriptPath = path.join(pluginRoot, "servers", "bundle-probe.mjs"); + await writeBundleProbeMcpServer(serverScriptPath); + await writeClaudeBundle({ pluginRoot, serverScriptPath }); + + const runtime = await createBundleMcpToolRuntime({ + workspaceDir, + cfg: { + plugins: { + entries: { + "bundle-probe": { enabled: true }, + }, + }, + }, + }); + + try { + expect(runtime.tools.map((tool) => tool.name)).toEqual(["bundle_probe"]); + const result = await runtime.tools[0].execute("call-bundle-probe", {}, undefined, undefined); + expect(result.content[0]).toMatchObject({ + type: "text", + text: "FROM-BUNDLE", + }); + expect(result.details).toEqual({ + mcpServer: "bundleProbe", + mcpTool: "bundle_probe", + }); + } finally { + await runtime.dispose(); + } + }); + + it("skips bundle MCP tools that collide with existing tool names", async () => { + const workspaceDir = await makeTempDir("openclaw-bundle-mcp-tools-"); + const pluginRoot = path.join(workspaceDir, ".openclaw", "extensions", "bundle-probe"); + const serverScriptPath = path.join(pluginRoot, "servers", "bundle-probe.mjs"); + await writeBundleProbeMcpServer(serverScriptPath); + await writeClaudeBundle({ pluginRoot, serverScriptPath }); + + const runtime = await createBundleMcpToolRuntime({ + workspaceDir, + cfg: { + plugins: { + entries: { + "bundle-probe": { enabled: true }, + }, + }, + }, + reservedToolNames: ["bundle_probe"], + }); + + try { + expect(runtime.tools).toEqual([]); + } finally { + await runtime.dispose(); + } + }); + + it("loads configured stdio MCP tools without a bundle", async () => { + const workspaceDir = await makeTempDir("openclaw-bundle-mcp-tools-"); + const serverScriptPath = path.join(workspaceDir, "servers", "configured-probe.mjs"); + await writeBundleProbeMcpServer(serverScriptPath); + + const runtime = await createBundleMcpToolRuntime({ + workspaceDir, + cfg: { + mcp: { + servers: { + configuredProbe: { + command: "node", + args: [serverScriptPath], + env: { + BUNDLE_PROBE_TEXT: "FROM-CONFIG", + }, + }, + }, + }, + }, + }); + + try { + expect(runtime.tools.map((tool) => tool.name)).toEqual(["bundle_probe"]); + const result = await runtime.tools[0].execute( + "call-configured-probe", + {}, + undefined, + undefined, + ); + expect(result.content[0]).toMatchObject({ + type: "text", + text: "FROM-CONFIG", + }); + expect(result.details).toEqual({ + mcpServer: "configuredProbe", + mcpTool: "bundle_probe", + }); + } finally { + await runtime.dispose(); + } + }); +}); diff --git a/src/agents/pi-bundle-mcp-tools.ts b/src/agents/pi-bundle-mcp-tools.ts new file mode 100644 index 00000000000..159cd8bfe12 --- /dev/null +++ b/src/agents/pi-bundle-mcp-tools.ts @@ -0,0 +1,225 @@ +import type { AgentToolResult } from "@mariozechner/pi-agent-core"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; +import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import type { OpenClawConfig } from "../config/config.js"; +import { logDebug, logWarn } from "../logger.js"; +import { loadEmbeddedPiMcpConfig } from "./embedded-pi-mcp.js"; +import { + describeStdioMcpServerLaunchConfig, + resolveStdioMcpServerLaunchConfig, +} from "./mcp-stdio.js"; +import type { AnyAgentTool } from "./tools/common.js"; + +type BundleMcpToolRuntime = { + tools: AnyAgentTool[]; + dispose: () => Promise; +}; + +type BundleMcpSession = { + serverName: string; + client: Client; + transport: StdioClientTransport; + detachStderr?: () => void; +}; + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === "object" && !Array.isArray(value); +} + +async function listAllTools(client: Client) { + const tools: Awaited>["tools"] = []; + let cursor: string | undefined; + do { + const page = await client.listTools(cursor ? { cursor } : undefined); + tools.push(...page.tools); + cursor = page.nextCursor; + } while (cursor); + return tools; +} + +function toAgentToolResult(params: { + serverName: string; + toolName: string; + result: CallToolResult; +}): AgentToolResult { + const content = Array.isArray(params.result.content) + ? (params.result.content as AgentToolResult["content"]) + : []; + const normalizedContent: AgentToolResult["content"] = + content.length > 0 + ? content + : params.result.structuredContent !== undefined + ? [ + { + type: "text", + text: JSON.stringify(params.result.structuredContent, null, 2), + }, + ] + : ([ + { + type: "text", + text: JSON.stringify( + { + status: params.result.isError === true ? "error" : "ok", + server: params.serverName, + tool: params.toolName, + }, + null, + 2, + ), + }, + ] as AgentToolResult["content"]); + const details: Record = { + mcpServer: params.serverName, + mcpTool: params.toolName, + }; + if (params.result.structuredContent !== undefined) { + details.structuredContent = params.result.structuredContent; + } + if (params.result.isError === true) { + details.status = "error"; + } + return { + content: normalizedContent, + details, + }; +} + +function attachStderrLogging(serverName: string, transport: StdioClientTransport) { + const stderr = transport.stderr; + if (!stderr || typeof stderr.on !== "function") { + return undefined; + } + const onData = (chunk: Buffer | string) => { + const message = String(chunk).trim(); + if (!message) { + return; + } + for (const line of message.split(/\r?\n/)) { + const trimmed = line.trim(); + if (trimmed) { + logDebug(`bundle-mcp:${serverName}: ${trimmed}`); + } + } + }; + stderr.on("data", onData); + return () => { + if (typeof stderr.off === "function") { + stderr.off("data", onData); + } else if (typeof stderr.removeListener === "function") { + stderr.removeListener("data", onData); + } + }; +} + +async function disposeSession(session: BundleMcpSession) { + session.detachStderr?.(); + await session.client.close().catch(() => {}); + await session.transport.close().catch(() => {}); +} + +export async function createBundleMcpToolRuntime(params: { + workspaceDir: string; + cfg?: OpenClawConfig; + reservedToolNames?: Iterable; +}): Promise { + const loaded = loadEmbeddedPiMcpConfig({ + workspaceDir: params.workspaceDir, + cfg: params.cfg, + }); + for (const diagnostic of loaded.diagnostics) { + logWarn(`bundle-mcp: ${diagnostic.pluginId}: ${diagnostic.message}`); + } + + const reservedNames = new Set( + Array.from(params.reservedToolNames ?? [], (name) => name.trim().toLowerCase()).filter(Boolean), + ); + const sessions: BundleMcpSession[] = []; + const tools: AnyAgentTool[] = []; + + try { + for (const [serverName, rawServer] of Object.entries(loaded.mcpServers)) { + const launch = resolveStdioMcpServerLaunchConfig(rawServer); + if (!launch.ok) { + logWarn(`bundle-mcp: skipped server "${serverName}" because ${launch.reason}.`); + continue; + } + const launchConfig = launch.config; + + const transport = new StdioClientTransport({ + command: launchConfig.command, + args: launchConfig.args, + env: launchConfig.env, + cwd: launchConfig.cwd, + stderr: "pipe", + }); + const client = new Client( + { + name: "openclaw-bundle-mcp", + version: "0.0.0", + }, + {}, + ); + const session: BundleMcpSession = { + serverName, + client, + transport, + detachStderr: attachStderrLogging(serverName, transport), + }; + + try { + await client.connect(transport); + const listedTools = await listAllTools(client); + sessions.push(session); + for (const tool of listedTools) { + const normalizedName = tool.name.trim().toLowerCase(); + if (!normalizedName) { + continue; + } + if (reservedNames.has(normalizedName)) { + logWarn( + `bundle-mcp: skipped tool "${tool.name}" from server "${serverName}" because the name already exists.`, + ); + continue; + } + reservedNames.add(normalizedName); + tools.push({ + name: tool.name, + label: tool.title ?? tool.name, + description: + tool.description?.trim() || + `Provided by bundle MCP server "${serverName}" (${describeStdioMcpServerLaunchConfig(launchConfig)}).`, + parameters: tool.inputSchema, + execute: async (_toolCallId, input) => { + const result = (await client.callTool({ + name: tool.name, + arguments: isRecord(input) ? input : {}, + })) as CallToolResult; + return toAgentToolResult({ + serverName, + toolName: tool.name, + result, + }); + }, + }); + } + } catch (error) { + logWarn( + `bundle-mcp: failed to start server "${serverName}" (${describeStdioMcpServerLaunchConfig(launchConfig)}): ${String(error)}`, + ); + await disposeSession(session); + } + } + + return { + tools, + dispose: async () => { + await Promise.allSettled(sessions.map((session) => disposeSession(session))); + }, + }; + } catch (error) { + await Promise.allSettled(sessions.map((session) => disposeSession(session))); + throw error; + } +} diff --git a/src/agents/pi-embedded-runner.bundle-mcp.e2e.test.ts b/src/agents/pi-embedded-runner.bundle-mcp.e2e.test.ts new file mode 100644 index 00000000000..2eac44e922b --- /dev/null +++ b/src/agents/pi-embedded-runner.bundle-mcp.e2e.test.ts @@ -0,0 +1,302 @@ +import fs from "node:fs/promises"; +import { createRequire } from "node:module"; +import path from "node:path"; +import "./test-helpers/fast-coding-tools.js"; +import { afterAll, beforeAll, describe, expect, it, vi } from "vitest"; +import { + cleanupEmbeddedPiRunnerTestWorkspace, + createEmbeddedPiRunnerOpenAiConfig, + createEmbeddedPiRunnerTestWorkspace, + type EmbeddedPiRunnerTestWorkspace, + immediateEnqueue, +} from "./test-helpers/pi-embedded-runner-e2e-fixtures.js"; + +const E2E_TIMEOUT_MS = 20_000; +const require = createRequire(import.meta.url); +const SDK_SERVER_MCP_PATH = require.resolve("@modelcontextprotocol/sdk/server/mcp.js"); +const SDK_SERVER_STDIO_PATH = require.resolve("@modelcontextprotocol/sdk/server/stdio.js"); + +function createMockUsage(input: number, output: number) { + return { + input, + output, + cacheRead: 0, + cacheWrite: 0, + totalTokens: input + output, + cost: { + input: 0, + output: 0, + cacheRead: 0, + cacheWrite: 0, + total: 0, + }, + }; +} + +let streamCallCount = 0; +let observedContexts: Array> = []; + +async function writeExecutable(filePath: string, content: string): Promise { + await fs.mkdir(path.dirname(filePath), { recursive: true }); + await fs.writeFile(filePath, content, { encoding: "utf-8", mode: 0o755 }); +} + +async function writeBundleProbeMcpServer(filePath: string): Promise { + await writeExecutable( + filePath, + `#!/usr/bin/env node +import { McpServer } from ${JSON.stringify(SDK_SERVER_MCP_PATH)}; +import { StdioServerTransport } from ${JSON.stringify(SDK_SERVER_STDIO_PATH)}; + +const server = new McpServer({ name: "bundle-probe", version: "1.0.0" }); +server.tool("bundle_probe", "Bundle MCP probe", async () => { + return { + content: [{ type: "text", text: process.env.BUNDLE_PROBE_TEXT ?? "missing-probe-text" }], + }; +}); + +await server.connect(new StdioServerTransport()); +`, + ); +} + +async function writeClaudeBundle(params: { + pluginRoot: string; + serverScriptPath: string; +}): Promise { + await fs.mkdir(path.join(params.pluginRoot, ".claude-plugin"), { recursive: true }); + await fs.writeFile( + path.join(params.pluginRoot, ".claude-plugin", "plugin.json"), + `${JSON.stringify({ name: "bundle-probe" }, null, 2)}\n`, + "utf-8", + ); + await fs.writeFile( + path.join(params.pluginRoot, ".mcp.json"), + `${JSON.stringify( + { + mcpServers: { + bundleProbe: { + command: "node", + args: [path.relative(params.pluginRoot, params.serverScriptPath)], + env: { + BUNDLE_PROBE_TEXT: "FROM-BUNDLE", + }, + }, + }, + }, + null, + 2, + )}\n`, + "utf-8", + ); +} + +vi.mock("@mariozechner/pi-coding-agent", async () => { + return await vi.importActual( + "@mariozechner/pi-coding-agent", + ); +}); + +vi.mock("@mariozechner/pi-ai", async () => { + const actual = await vi.importActual("@mariozechner/pi-ai"); + + const buildToolUseMessage = (model: { api: string; provider: string; id: string }) => ({ + role: "assistant" as const, + content: [ + { + type: "toolCall" as const, + id: "tc-bundle-mcp-1", + name: "bundle_probe", + arguments: {}, + }, + ], + stopReason: "toolUse" as const, + api: model.api, + provider: model.provider, + model: model.id, + usage: createMockUsage(1, 1), + timestamp: Date.now(), + }); + + const buildStopMessage = ( + model: { api: string; provider: string; id: string }, + text: string, + ) => ({ + role: "assistant" as const, + content: [{ type: "text" as const, text }], + stopReason: "stop" as const, + api: model.api, + provider: model.provider, + model: model.id, + usage: createMockUsage(1, 1), + timestamp: Date.now(), + }); + + return { + ...actual, + complete: async (model: { api: string; provider: string; id: string }) => { + streamCallCount += 1; + return streamCallCount === 1 + ? buildToolUseMessage(model) + : buildStopMessage(model, "BUNDLE MCP OK FROM-BUNDLE"); + }, + completeSimple: async (model: { api: string; provider: string; id: string }) => { + streamCallCount += 1; + return streamCallCount === 1 + ? buildToolUseMessage(model) + : buildStopMessage(model, "BUNDLE MCP OK FROM-BUNDLE"); + }, + streamSimple: ( + model: { api: string; provider: string; id: string }, + context: { messages?: Array<{ role?: string; content?: unknown }> }, + ) => { + streamCallCount += 1; + const messages = (context.messages ?? []).map((message) => ({ ...message })); + observedContexts.push(messages); + const stream = actual.createAssistantMessageEventStream(); + queueMicrotask(() => { + if (streamCallCount === 1) { + stream.push({ + type: "done", + reason: "toolUse", + message: buildToolUseMessage(model), + }); + stream.end(); + return; + } + + const toolResultText = messages.flatMap((message) => + Array.isArray(message.content) + ? (message.content as Array<{ type?: string; text?: string }>) + .filter((entry) => entry.type === "text" && typeof entry.text === "string") + .map((entry) => entry.text ?? "") + : [], + ); + const sawBundleResult = toolResultText.some((text) => text.includes("FROM-BUNDLE")); + if (!sawBundleResult) { + stream.push({ + type: "done", + reason: "error", + message: { + role: "assistant" as const, + content: [], + stopReason: "error" as const, + errorMessage: "bundle MCP tool result missing from context", + api: model.api, + provider: model.provider, + model: model.id, + usage: createMockUsage(1, 0), + timestamp: Date.now(), + }, + }); + stream.end(); + return; + } + + stream.push({ + type: "done", + reason: "stop", + message: buildStopMessage(model, "BUNDLE MCP OK FROM-BUNDLE"), + }); + stream.end(); + }); + return stream; + }, + }; +}); + +let runEmbeddedPiAgent: typeof import("./pi-embedded-runner/run.js").runEmbeddedPiAgent; +let e2eWorkspace: EmbeddedPiRunnerTestWorkspace | undefined; +let agentDir: string; +let workspaceDir: string; + +beforeAll(async () => { + vi.useRealTimers(); + ({ runEmbeddedPiAgent } = await import("./pi-embedded-runner/run.js")); + e2eWorkspace = await createEmbeddedPiRunnerTestWorkspace("openclaw-bundle-mcp-pi-"); + ({ agentDir, workspaceDir } = e2eWorkspace); +}, 180_000); + +afterAll(async () => { + await cleanupEmbeddedPiRunnerTestWorkspace(e2eWorkspace); + e2eWorkspace = undefined; +}); + +const readSessionMessages = async (sessionFile: string) => { + const raw = await fs.readFile(sessionFile, "utf-8"); + return raw + .split(/\r?\n/) + .filter(Boolean) + .map( + (line) => + JSON.parse(line) as { type?: string; message?: { role?: string; content?: unknown } }, + ) + .filter((entry) => entry.type === "message") + .map((entry) => entry.message) as Array<{ role?: string; content?: unknown }>; +}; + +describe("runEmbeddedPiAgent bundle MCP e2e", () => { + it( + "loads bundle MCP into Pi, executes the MCP tool, and includes the result in the follow-up turn", + { timeout: E2E_TIMEOUT_MS }, + async () => { + streamCallCount = 0; + observedContexts = []; + + const sessionFile = path.join(workspaceDir, "session-bundle-mcp-e2e.jsonl"); + const pluginRoot = path.join(workspaceDir, ".openclaw", "extensions", "bundle-probe"); + const serverScriptPath = path.join(pluginRoot, "servers", "bundle-probe.mjs"); + await writeBundleProbeMcpServer(serverScriptPath); + await writeClaudeBundle({ pluginRoot, serverScriptPath }); + + const cfg = { + ...createEmbeddedPiRunnerOpenAiConfig(["mock-bundle-mcp"]), + plugins: { + entries: { + "bundle-probe": { enabled: true }, + }, + }, + }; + + const result = await runEmbeddedPiAgent({ + sessionId: "bundle-mcp-e2e", + sessionKey: "agent:test:bundle-mcp-e2e", + sessionFile, + workspaceDir, + config: cfg, + prompt: "Use the bundle MCP tool and report its result.", + provider: "openai", + model: "mock-bundle-mcp", + timeoutMs: 10_000, + agentDir, + runId: "run-bundle-mcp-e2e", + enqueue: immediateEnqueue, + }); + + expect(result.meta.stopReason).toBe("stop"); + expect(result.payloads?.[0]?.text).toContain("BUNDLE MCP OK FROM-BUNDLE"); + expect(streamCallCount).toBe(2); + + const followUpContext = observedContexts[1] ?? []; + const followUpTexts = followUpContext.flatMap((message) => + Array.isArray(message.content) + ? (message.content as Array<{ type?: string; text?: string }>) + .filter((entry) => entry.type === "text" && typeof entry.text === "string") + .map((entry) => entry.text ?? "") + : [], + ); + expect(followUpTexts.some((text) => text.includes("FROM-BUNDLE"))).toBe(true); + + const messages = await readSessionMessages(sessionFile); + const toolResults = messages.filter((message) => message?.role === "toolResult"); + const toolResultText = toolResults.flatMap((message) => + Array.isArray(message.content) + ? (message.content as Array<{ type?: string; text?: string }>) + .filter((entry) => entry.type === "text" && typeof entry.text === "string") + .map((entry) => entry.text ?? "") + : [], + ); + expect(toolResultText.some((text) => text.includes("FROM-BUNDLE"))).toBe(true); + }, + ); +}); diff --git a/src/agents/pi-embedded-runner/compact.ts b/src/agents/pi-embedded-runner/compact.ts index 4daef42a21f..98a3b438d21 100644 --- a/src/agents/pi-embedded-runner/compact.ts +++ b/src/agents/pi-embedded-runner/compact.ts @@ -53,6 +53,7 @@ import { supportsModelTools } from "../model-tool-support.js"; import { ensureOpenClawModelsJson } from "../models-config.js"; import { createConfiguredOllamaStreamFn } from "../ollama-stream.js"; import { resolveOwnerDisplaySetting } from "../owner-display.js"; +import { createBundleMcpToolRuntime } from "../pi-bundle-mcp-tools.js"; import { ensureSessionHeader, validateAnthropicTurns, @@ -583,12 +584,24 @@ export async function compactEmbeddedPiSessionDirect( modelContextWindowTokens: ctxInfo.tokens, modelAuthMode: resolveModelAuthMode(model.provider, params.config), }); + const toolsEnabled = supportsModelTools(runtimeModel); const tools = sanitizeToolsForGoogle({ - tools: supportsModelTools(runtimeModel) ? toolsRaw : [], + tools: toolsEnabled ? toolsRaw : [], provider, }); - const allowedToolNames = collectAllowedToolNames({ tools }); - logToolSchemasForGoogle({ tools, provider }); + const bundleMcpRuntime = toolsEnabled + ? await createBundleMcpToolRuntime({ + workspaceDir: effectiveWorkspace, + cfg: params.config, + reservedToolNames: tools.map((tool) => tool.name), + }) + : undefined; + const effectiveTools = + bundleMcpRuntime && bundleMcpRuntime.tools.length > 0 + ? [...tools, ...bundleMcpRuntime.tools] + : tools; + const allowedToolNames = collectAllowedToolNames({ tools: effectiveTools }); + logToolSchemasForGoogle({ tools: effectiveTools, provider }); const machineName = await getMachineDisplayName(); const runtimeChannel = normalizeMessageChannel(params.messageChannel ?? params.messageProvider); let runtimeCapabilities = runtimeChannel @@ -705,7 +718,7 @@ export async function compactEmbeddedPiSessionDirect( reactionGuidance, messageToolHints, sandboxInfo, - tools, + tools: effectiveTools, modelAliasLines: buildModelAliasLines(params.config), userTimezone, userTime, @@ -768,7 +781,7 @@ export async function compactEmbeddedPiSessionDirect( } const { builtInTools, customTools } = splitSdkTools({ - tools, + tools: effectiveTools, sandboxEnabled: !!sandbox?.enabled, }); @@ -1060,6 +1073,7 @@ export async function compactEmbeddedPiSessionDirect( clearPendingOnTimeout: true, }); session.dispose(); + await bundleMcpRuntime?.dispose(); } } finally { await sessionLock.release(); diff --git a/src/agents/pi-embedded-runner/run/attempt.ts b/src/agents/pi-embedded-runner/run/attempt.ts index 0ea66825ff1..dc9df12865d 100644 --- a/src/agents/pi-embedded-runner/run/attempt.ts +++ b/src/agents/pi-embedded-runner/run/attempt.ts @@ -59,6 +59,7 @@ import { supportsModelTools } from "../../model-tool-support.js"; import { createConfiguredOllamaStreamFn } from "../../ollama-stream.js"; import { createOpenAIWebSocketStreamFn, releaseWsSession } from "../../openai-ws-stream.js"; import { resolveOwnerDisplaySetting } from "../../owner-display.js"; +import { createBundleMcpToolRuntime } from "../../pi-bundle-mcp-tools.js"; import { downgradeOpenAIFunctionCallReasoningPairs, isCloudCodeAssistFormatError, @@ -1547,11 +1548,25 @@ export async function runEmbeddedAttempt( provider: params.provider, }); const clientTools = toolsEnabled ? params.clientTools : undefined; + const bundleMcpRuntime = toolsEnabled + ? await createBundleMcpToolRuntime({ + workspaceDir: effectiveWorkspace, + cfg: params.config, + reservedToolNames: [ + ...tools.map((tool) => tool.name), + ...(clientTools?.map((tool) => tool.function.name) ?? []), + ], + }) + : undefined; + const effectiveTools = + bundleMcpRuntime && bundleMcpRuntime.tools.length > 0 + ? [...tools, ...bundleMcpRuntime.tools] + : tools; const allowedToolNames = collectAllowedToolNames({ - tools, + tools: effectiveTools, clientTools, }); - logToolSchemasForGoogle({ tools, provider: params.provider }); + logToolSchemasForGoogle({ tools: effectiveTools, provider: params.provider }); const machineName = await getMachineDisplayName(); const runtimeChannel = normalizeMessageChannel(params.messageChannel ?? params.messageProvider); @@ -1673,7 +1688,7 @@ export async function runEmbeddedAttempt( runtimeInfo, messageToolHints, sandboxInfo, - tools, + tools: effectiveTools, modelAliasLines: buildModelAliasLines(params.config), userTimezone, userTime, @@ -1708,7 +1723,7 @@ export async function runEmbeddedAttempt( bootstrapFiles: hookAdjustedBootstrapFiles, injectedFiles: contextFiles, skillsPrompt, - tools, + tools: effectiveTools, }); const systemPromptOverride = createSystemPromptOverride(appendPrompt); let systemPromptText = systemPromptOverride(); @@ -1808,7 +1823,7 @@ export async function runEmbeddedAttempt( const hookRunner = getGlobalHookRunner(); const { builtInTools, customTools } = splitSdkTools({ - tools, + tools: effectiveTools, sandboxEnabled: !!sandbox?.enabled, }); @@ -2868,6 +2883,7 @@ export async function runEmbeddedAttempt( }); session?.dispose(); releaseWsSession(params.sessionId); + await bundleMcpRuntime?.dispose(); await sessionLock.release(); } } finally { diff --git a/src/agents/pi-project-settings.bundle.test.ts b/src/agents/pi-project-settings.bundle.test.ts index d297b1ef3a1..5859e18ac6e 100644 --- a/src/agents/pi-project-settings.bundle.test.ts +++ b/src/agents/pi-project-settings.bundle.test.ts @@ -79,6 +79,106 @@ describe("loadEnabledBundlePiSettingsSnapshot", () => { expect(snapshot.compaction?.keepRecentTokens).toBe(64_000); }); + it("loads enabled bundle MCP servers into the Pi settings snapshot", async () => { + const workspaceDir = await tempDirs.make("openclaw-workspace-"); + const pluginRoot = await tempDirs.make("openclaw-bundle-"); + await fs.mkdir(path.join(pluginRoot, ".claude-plugin"), { recursive: true }); + await fs.mkdir(path.join(pluginRoot, "servers"), { recursive: true }); + await fs.writeFile( + path.join(pluginRoot, ".claude-plugin", "plugin.json"), + JSON.stringify({ + name: "claude-bundle", + }), + "utf-8", + ); + await fs.writeFile( + path.join(pluginRoot, ".mcp.json"), + JSON.stringify({ + mcpServers: { + bundleProbe: { + command: "node", + args: ["./servers/probe.mjs"], + }, + }, + }), + "utf-8", + ); + hoisted.loadPluginManifestRegistry.mockReturnValue( + buildRegistry({ pluginRoot, settingsFiles: [] }), + ); + + const snapshot = loadEnabledBundlePiSettingsSnapshot({ + cwd: workspaceDir, + cfg: { + plugins: { + entries: { + "claude-bundle": { enabled: true }, + }, + }, + }, + }); + + expect(snapshot.mcpServers).toEqual({ + bundleProbe: { + command: "node", + args: [path.join(pluginRoot, "servers", "probe.mjs")], + cwd: pluginRoot, + }, + }); + }); + + it("lets top-level MCP config override bundle MCP defaults", async () => { + const workspaceDir = await tempDirs.make("openclaw-workspace-"); + const pluginRoot = await tempDirs.make("openclaw-bundle-"); + await fs.mkdir(path.join(pluginRoot, ".claude-plugin"), { recursive: true }); + await fs.writeFile( + path.join(pluginRoot, ".claude-plugin", "plugin.json"), + JSON.stringify({ + name: "claude-bundle", + }), + "utf-8", + ); + await fs.writeFile( + path.join(pluginRoot, ".mcp.json"), + JSON.stringify({ + mcpServers: { + sharedServer: { + command: "node", + args: ["./servers/bundle.mjs"], + }, + }, + }), + "utf-8", + ); + hoisted.loadPluginManifestRegistry.mockReturnValue( + buildRegistry({ pluginRoot, settingsFiles: [] }), + ); + + const snapshot = loadEnabledBundlePiSettingsSnapshot({ + cwd: workspaceDir, + cfg: { + mcp: { + servers: { + sharedServer: { + url: "https://example.com/mcp", + }, + }, + }, + plugins: { + entries: { + "claude-bundle": { enabled: true }, + }, + }, + }, + }); + + expect(snapshot.mcpServers).toEqual({ + sharedServer: { + url: "https://example.com/mcp", + }, + }); + }); + it("ignores disabled bundle plugins", async () => { const workspaceDir = await tempDirs.make("openclaw-workspace-"); const pluginRoot = await tempDirs.make("openclaw-bundle-"); diff --git a/src/agents/pi-project-settings.test.ts b/src/agents/pi-project-settings.test.ts index 92d676b8427..2ec9edf523d 100644 --- a/src/agents/pi-project-settings.test.ts +++ b/src/agents/pi-project-settings.test.ts @@ -93,4 +93,34 @@ describe("buildEmbeddedPiSettingsSnapshot", () => { expect(snapshot.compaction?.reserveTokens).toBe(32_000); expect(snapshot.hideThinkingBlock).toBe(true); }); + + it("lets project Pi settings override bundle MCP defaults", () => { + const snapshot = buildEmbeddedPiSettingsSnapshot({ + globalSettings, + pluginSettings: { + mcpServers: { + bundleProbe: { + command: "node", + args: ["/plugins/probe.mjs"], + }, + }, + }, + projectSettings: { + mcpServers: { + bundleProbe: { + command: "deno", + args: ["/workspace/probe.ts"], + }, + }, + }, + policy: "sanitize", + }); + + expect(snapshot.mcpServers).toEqual({ + bundleProbe: { + command: "deno", + args: ["/workspace/probe.ts"], + }, + }); + }); }); diff --git a/src/agents/pi-project-settings.ts b/src/agents/pi-project-settings.ts index 8e08d11bca7..fd66a6ee393 100644 --- a/src/agents/pi-project-settings.ts +++ b/src/agents/pi-project-settings.ts @@ -8,6 +8,7 @@ import { createSubsystemLogger } from "../logging/subsystem.js"; import { normalizePluginsConfig, resolveEffectiveEnableState } from "../plugins/config-state.js"; import { loadPluginManifestRegistry } from "../plugins/manifest-registry.js"; import { isRecord } from "../utils.js"; +import { loadEmbeddedPiMcpConfig } from "./embedded-pi-mcp.js"; import { applyPiCompactionSettingsFromConfig } from "./pi-settings.js"; const log = createSubsystemLogger("embedded-pi-settings"); @@ -107,6 +108,19 @@ export function loadEnabledBundlePiSettingsSnapshot(params: { } } + const embeddedPiMcp = loadEmbeddedPiMcpConfig({ + workspaceDir, + cfg: params.cfg, + }); + for (const diagnostic of embeddedPiMcp.diagnostics) { + log.warn(`bundle MCP skipped for ${diagnostic.pluginId}: ${diagnostic.message}`); + } + if (Object.keys(embeddedPiMcp.mcpServers).length > 0) { + snapshot = applyMergePatch(snapshot, { + mcpServers: embeddedPiMcp.mcpServers, + }) as PiSettingsSnapshot; + } + return snapshot; } diff --git a/src/auto-reply/commands-args.ts b/src/auto-reply/commands-args.ts index ab49b9ea68a..6f37414c053 100644 --- a/src/auto-reply/commands-args.ts +++ b/src/auto-reply/commands-args.ts @@ -51,6 +51,16 @@ const formatConfigArgs: CommandArgsFormatter = (values) => }, }); +const formatMcpArgs: CommandArgsFormatter = (values) => + formatActionArgs(values, { + formatKnownAction: (action, path) => { + if (action === "show" || action === "get") { + return path ? `${action} ${path}` : action; + } + return undefined; + }, + }); + const formatDebugArgs: CommandArgsFormatter = (values) => formatActionArgs(values, { formatKnownAction: (action) => { @@ -124,6 +134,7 @@ const formatExecArgs: CommandArgsFormatter = (values) => { export const COMMAND_ARG_FORMATTERS: Record = { config: formatConfigArgs, + mcp: formatMcpArgs, debug: formatDebugArgs, queue: formatQueueArgs, exec: formatExecArgs, diff --git a/src/auto-reply/commands-registry.data.ts b/src/auto-reply/commands-registry.data.ts index 58064473543..d4d4da530d3 100644 --- a/src/auto-reply/commands-registry.data.ts +++ b/src/auto-reply/commands-registry.data.ts @@ -452,6 +452,34 @@ function buildChatCommands(): ChatCommandDefinition[] { argsParsing: "none", formatArgs: COMMAND_ARG_FORMATTERS.config, }), + defineChatCommand({ + key: "mcp", + nativeName: "mcp", + description: "Show or set embedded Pi MCP servers.", + textAlias: "/mcp", + category: "management", + args: [ + { + name: "action", + description: "show | get | set | unset", + type: "string", + choices: ["show", "get", "set", "unset"], + }, + { + name: "path", + description: "MCP server name", + type: "string", + }, + { + name: "value", + description: "JSON config for set", + type: "string", + captureRemaining: true, + }, + ], + argsParsing: "none", + formatArgs: COMMAND_ARG_FORMATTERS.mcp, + }), defineChatCommand({ key: "debug", nativeName: "debug", diff --git a/src/auto-reply/commands-registry.ts b/src/auto-reply/commands-registry.ts index 93f8872e37b..8b0d7a5b5d6 100644 --- a/src/auto-reply/commands-registry.ts +++ b/src/auto-reply/commands-registry.ts @@ -99,6 +99,9 @@ export function isCommandEnabled(cfg: OpenClawConfig, commandKey: string): boole if (commandKey === "config") { return isCommandFlagEnabled(cfg, "config"); } + if (commandKey === "mcp") { + return isCommandFlagEnabled(cfg, "mcp"); + } if (commandKey === "debug") { return isCommandFlagEnabled(cfg, "debug"); } diff --git a/src/auto-reply/reply/commands-core.ts b/src/auto-reply/reply/commands-core.ts index 7a6cc36c05e..f969c9f5f24 100644 --- a/src/auto-reply/reply/commands-core.ts +++ b/src/auto-reply/reply/commands-core.ts @@ -22,6 +22,7 @@ import { handleStatusCommand, handleWhoamiCommand, } from "./commands-info.js"; +import { handleMcpCommand } from "./commands-mcp.js"; import { handleModelsCommand } from "./commands-models.js"; import { handlePluginCommand } from "./commands-plugin.js"; import { @@ -194,6 +195,7 @@ export async function handleCommands(params: HandleCommandsParams): Promise { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-command-mcp-")); + tempDirs.push(dir); + return dir; +} + +function buildCfg(): OpenClawConfig { + return { + commands: { + text: true, + mcp: true, + }, + }; +} + +describe("handleCommands /mcp", () => { + afterEach(async () => { + await Promise.all( + tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })), + ); + }); + + it("writes MCP config and shows it back", async () => { + await withTempHome("openclaw-command-mcp-home-", async () => { + const workspaceDir = await createWorkspace(); + const setParams = buildCommandTestParams( + '/mcp set context7={"command":"uvx","args":["context7-mcp"]}', + buildCfg(), + undefined, + { workspaceDir }, + ); + setParams.command.senderIsOwner = true; + + const setResult = await handleCommands(setParams); + expect(setResult.reply?.text).toContain('MCP server "context7" saved'); + + const showParams = buildCommandTestParams("/mcp show context7", buildCfg(), undefined, { + workspaceDir, + }); + showParams.command.senderIsOwner = true; + const showResult = await handleCommands(showParams); + expect(showResult.reply?.text).toContain('"command": "uvx"'); + expect(showResult.reply?.text).toContain('"args": ['); + }); + }); + + it("rejects internal writes without operator.admin", async () => { + await withTempHome("openclaw-command-mcp-home-", async () => { + const workspaceDir = await createWorkspace(); + const params = buildCommandTestParams( + '/mcp set context7={"command":"uvx","args":["context7-mcp"]}', + buildCfg(), + { + Provider: "webchat", + Surface: "webchat", + GatewayClientScopes: ["operator.write"], + }, + { workspaceDir }, + ); + params.command.senderIsOwner = true; + + const result = await handleCommands(params); + expect(result.reply?.text).toContain("requires operator.admin"); + }); + }); + + it("accepts non-stdio MCP config at the config layer", async () => { + await withTempHome("openclaw-command-mcp-home-", async () => { + const workspaceDir = await createWorkspace(); + const params = buildCommandTestParams( + '/mcp set remote={"url":"https://example.com/mcp"}', + buildCfg(), + undefined, + { workspaceDir }, + ); + params.command.senderIsOwner = true; + + const result = await handleCommands(params); + expect(result.reply?.text).toContain('MCP server "remote" saved'); + }); + }); +}); diff --git a/src/auto-reply/reply/commands-mcp.ts b/src/auto-reply/reply/commands-mcp.ts new file mode 100644 index 00000000000..ff805a9b878 --- /dev/null +++ b/src/auto-reply/reply/commands-mcp.ts @@ -0,0 +1,134 @@ +import { + listConfiguredMcpServers, + setConfiguredMcpServer, + unsetConfiguredMcpServer, +} from "../../config/mcp-config.js"; +import { isInternalMessageChannel } from "../../utils/message-channel.js"; +import { + rejectNonOwnerCommand, + rejectUnauthorizedCommand, + requireCommandFlagEnabled, + requireGatewayClientScopeForInternalChannel, +} from "./command-gates.js"; +import type { CommandHandler } from "./commands-types.js"; +import { parseMcpCommand } from "./mcp-commands.js"; + +function renderJsonBlock(label: string, value: unknown): string { + return `${label}\n\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``; +} + +export const handleMcpCommand: CommandHandler = async (params, allowTextCommands) => { + if (!allowTextCommands) { + return null; + } + const mcpCommand = parseMcpCommand(params.command.commandBodyNormalized); + if (!mcpCommand) { + return null; + } + const unauthorized = rejectUnauthorizedCommand(params, "/mcp"); + if (unauthorized) { + return unauthorized; + } + const allowInternalReadOnlyShow = + mcpCommand.action === "show" && isInternalMessageChannel(params.command.channel); + const nonOwner = allowInternalReadOnlyShow ? null : rejectNonOwnerCommand(params, "/mcp"); + if (nonOwner) { + return nonOwner; + } + const disabled = requireCommandFlagEnabled(params.cfg, { + label: "/mcp", + configKey: "mcp", + }); + if (disabled) { + return disabled; + } + if (mcpCommand.action === "error") { + return { + shouldContinue: false, + reply: { text: `⚠️ ${mcpCommand.message}` }, + }; + } + + if (mcpCommand.action === "show") { + const loaded = await listConfiguredMcpServers(); + if (!loaded.ok) { + return { + shouldContinue: false, + reply: { text: `⚠️ ${loaded.error}` }, + }; + } + if (mcpCommand.name) { + const server = loaded.mcpServers[mcpCommand.name]; + if (!server) { + return { + shouldContinue: false, + reply: { text: `🔌 No MCP server named "${mcpCommand.name}" in ${loaded.path}.` }, + }; + } + return { + shouldContinue: false, + reply: { + text: renderJsonBlock(`🔌 MCP server "${mcpCommand.name}" (${loaded.path})`, server), + }, + }; + } + if (Object.keys(loaded.mcpServers).length === 0) { + return { + shouldContinue: false, + reply: { text: `🔌 No MCP servers configured in ${loaded.path}.` }, + }; + } + return { + shouldContinue: false, + reply: { + text: renderJsonBlock(`🔌 MCP servers (${loaded.path})`, loaded.mcpServers), + }, + }; + } + + const missingAdminScope = requireGatewayClientScopeForInternalChannel(params, { + label: "/mcp write", + allowedScopes: ["operator.admin"], + missingText: "❌ /mcp set|unset requires operator.admin for gateway clients.", + }); + if (missingAdminScope) { + return missingAdminScope; + } + + if (mcpCommand.action === "set") { + const result = await setConfiguredMcpServer({ + name: mcpCommand.name, + server: mcpCommand.value, + }); + if (!result.ok) { + return { + shouldContinue: false, + reply: { text: `⚠️ ${result.error}` }, + }; + } + return { + shouldContinue: false, + reply: { + text: `🔌 MCP server "${mcpCommand.name}" saved to ${result.path}.`, + }, + }; + } + + const result = await unsetConfiguredMcpServer({ name: mcpCommand.name }); + if (!result.ok) { + return { + shouldContinue: false, + reply: { text: `⚠️ ${result.error}` }, + }; + } + if (!result.removed) { + return { + shouldContinue: false, + reply: { text: `🔌 No MCP server named "${mcpCommand.name}" in ${result.path}.` }, + }; + } + return { + shouldContinue: false, + reply: { text: `🔌 MCP server "${mcpCommand.name}" removed from ${result.path}.` }, + }; +}; diff --git a/src/auto-reply/reply/mcp-commands.ts b/src/auto-reply/reply/mcp-commands.ts new file mode 100644 index 00000000000..506efe015df --- /dev/null +++ b/src/auto-reply/reply/mcp-commands.ts @@ -0,0 +1,24 @@ +import { parseStandardSetUnsetSlashCommand } from "./commands-setunset-standard.js"; + +export type McpCommand = + | { action: "show"; name?: string } + | { action: "set"; name: string; value: unknown } + | { action: "unset"; name: string } + | { action: "error"; message: string }; + +export function parseMcpCommand(raw: string): McpCommand | null { + return parseStandardSetUnsetSlashCommand({ + raw, + slash: "/mcp", + invalidMessage: "Invalid /mcp syntax.", + usageMessage: "Usage: /mcp show|set|unset", + onKnownAction: (action, args) => { + if (action === "show" || action === "get") { + return { action: "show", name: args || undefined }; + } + return undefined; + }, + onSet: (name, value) => ({ action: "set", name, value }), + onUnset: (name) => ({ action: "unset", name }), + }); +} diff --git a/src/cli/mcp-cli.test.ts b/src/cli/mcp-cli.test.ts new file mode 100644 index 00000000000..299406d5f31 --- /dev/null +++ b/src/cli/mcp-cli.test.ts @@ -0,0 +1,83 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { Command } from "commander"; +import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest"; +import { withTempHome } from "../config/home-env.test-harness.js"; + +const mockLog = vi.fn(); +const mockError = vi.fn(); +const mockExit = vi.fn((code: number) => { + throw new Error(`__exit__:${code}`); +}); + +vi.mock("../runtime.js", () => ({ + defaultRuntime: { + log: (...args: unknown[]) => mockLog(...args), + error: (...args: unknown[]) => mockError(...args), + exit: (code: number) => mockExit(code), + }, +})); + +const tempDirs: string[] = []; + +async function createWorkspace(): Promise { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-cli-mcp-")); + tempDirs.push(dir); + return dir; +} + +let registerMcpCli: typeof import("./mcp-cli.js").registerMcpCli; +let sharedProgram: Command; +let previousCwd = process.cwd(); + +async function runMcpCommand(args: string[]) { + await sharedProgram.parseAsync(args, { from: "user" }); +} + +describe("mcp cli", () => { + beforeAll(async () => { + ({ registerMcpCli } = await import("./mcp-cli.js")); + sharedProgram = new Command(); + sharedProgram.exitOverride(); + registerMcpCli(sharedProgram); + }, 300_000); + + beforeEach(() => { + vi.clearAllMocks(); + previousCwd = process.cwd(); + }); + + afterEach(async () => { + process.chdir(previousCwd); + await Promise.all( + tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })), + ); + }); + + it("sets and shows a configured MCP server", async () => { + await withTempHome("openclaw-cli-mcp-home-", async () => { + const workspaceDir = await createWorkspace(); + process.chdir(workspaceDir); + + await runMcpCommand(["mcp", "set", "context7", '{"command":"uvx","args":["context7-mcp"]}']); + expect(mockLog).toHaveBeenCalledWith(expect.stringContaining('Saved MCP server "context7"')); + + mockLog.mockClear(); + await runMcpCommand(["mcp", "show", "context7", "--json"]); + expect(mockLog).toHaveBeenCalledWith(expect.stringContaining('"command": "uvx"')); + }); + }); + + it("fails when removing an unknown MCP server", async () => { + await withTempHome("openclaw-cli-mcp-home-", async () => { + const workspaceDir = await createWorkspace(); + process.chdir(workspaceDir); + + await expect(runMcpCommand(["mcp", "unset", "missing"])).rejects.toThrow("__exit__:1"); + expect(mockError).toHaveBeenCalledWith( + expect.stringContaining('No MCP server named "missing"'), + ); + }); + }); +}); diff --git a/src/cli/mcp-cli.ts b/src/cli/mcp-cli.ts new file mode 100644 index 00000000000..62831ee827d --- /dev/null +++ b/src/cli/mcp-cli.ts @@ -0,0 +1,103 @@ +import { Command } from "commander"; +import { parseConfigValue } from "../auto-reply/reply/config-value.js"; +import { + listConfiguredMcpServers, + setConfiguredMcpServer, + unsetConfiguredMcpServer, +} from "../config/mcp-config.js"; +import { defaultRuntime } from "../runtime.js"; + +function fail(message: string): never { + defaultRuntime.error(message); + defaultRuntime.exit(1); +} + +function printJson(value: unknown): void { + defaultRuntime.log(JSON.stringify(value, null, 2)); +} + +export function registerMcpCli(program: Command) { + const mcp = program.command("mcp").description("Manage OpenClaw MCP server config"); + + mcp + .command("list") + .description("List configured MCP servers") + .option("--json", "Print JSON") + .action(async (opts: { json?: boolean }) => { + const loaded = await listConfiguredMcpServers(); + if (!loaded.ok) { + fail(loaded.error); + } + if (opts.json) { + printJson(loaded.mcpServers); + return; + } + const names = Object.keys(loaded.mcpServers).toSorted(); + if (names.length === 0) { + defaultRuntime.log(`No MCP servers configured in ${loaded.path}.`); + return; + } + defaultRuntime.log(`MCP servers (${loaded.path}):`); + for (const name of names) { + defaultRuntime.log(`- ${name}`); + } + }); + + mcp + .command("show") + .description("Show one configured MCP server or the full MCP config") + .argument("[name]", "MCP server name") + .option("--json", "Print JSON") + .action(async (name: string | undefined, opts: { json?: boolean }) => { + const loaded = await listConfiguredMcpServers(); + if (!loaded.ok) { + fail(loaded.error); + } + const value = name ? loaded.mcpServers[name] : loaded.mcpServers; + if (name && !value) { + fail(`No MCP server named "${name}" in ${loaded.path}.`); + } + if (opts.json) { + printJson(value ?? {}); + return; + } + if (name) { + defaultRuntime.log(`MCP server "${name}" (${loaded.path}):`); + } else { + defaultRuntime.log(`MCP servers (${loaded.path}):`); + } + printJson(value ?? {}); + }); + + mcp + .command("set") + .description("Set one configured MCP server from a JSON object") + .argument("", "MCP server name") + .argument("", 'JSON object, for example {"command":"uvx","args":["context7-mcp"]}') + .action(async (name: string, rawValue: string) => { + const parsed = parseConfigValue(rawValue); + if (parsed.error) { + fail(parsed.error); + } + const result = await setConfiguredMcpServer({ name, server: parsed.value }); + if (!result.ok) { + fail(result.error); + } + defaultRuntime.log(`Saved MCP server "${name}" to ${result.path}.`); + }); + + mcp + .command("unset") + .description("Remove one configured MCP server") + .argument("", "MCP server name") + .action(async (name: string) => { + const result = await unsetConfiguredMcpServer({ name }); + if (!result.ok) { + fail(result.error); + } + if (!result.removed) { + fail(`No MCP server named "${name}" in ${result.path}.`); + } + defaultRuntime.log(`Removed MCP server "${name}" from ${result.path}.`); + }); +} diff --git a/src/cli/program/command-registry.ts b/src/cli/program/command-registry.ts index 1955e851357..93c4616594e 100644 --- a/src/cli/program/command-registry.ts +++ b/src/cli/program/command-registry.ts @@ -160,6 +160,19 @@ const coreEntries: CoreCliEntry[] = [ mod.registerMemoryCli(program); }, }, + { + commands: [ + { + name: "mcp", + description: "Manage embedded Pi MCP servers", + hasSubcommands: true, + }, + ], + register: async ({ program }) => { + const mod = await import("../mcp-cli.js"); + mod.registerMcpCli(program); + }, + }, { commands: [ { diff --git a/src/config/mcp-config.test.ts b/src/config/mcp-config.test.ts new file mode 100644 index 00000000000..bd7032fb8a4 --- /dev/null +++ b/src/config/mcp-config.test.ts @@ -0,0 +1,56 @@ +import fs from "node:fs/promises"; +import { describe, expect, it } from "vitest"; +import { + listConfiguredMcpServers, + setConfiguredMcpServer, + unsetConfiguredMcpServer, +} from "./mcp-config.js"; +import { withTempHomeConfig } from "./test-helpers.js"; + +describe("config mcp config", () => { + it("writes and removes top-level mcp servers", async () => { + await withTempHomeConfig({}, async () => { + const setResult = await setConfiguredMcpServer({ + name: "context7", + server: { + command: "uvx", + args: ["context7-mcp"], + }, + }); + + expect(setResult.ok).toBe(true); + const loaded = await listConfiguredMcpServers(); + expect(loaded.ok).toBe(true); + if (!loaded.ok) { + throw new Error("expected MCP config to load"); + } + expect(loaded.mcpServers.context7).toEqual({ + command: "uvx", + args: ["context7-mcp"], + }); + + const unsetResult = await unsetConfiguredMcpServer({ name: "context7" }); + expect(unsetResult.ok).toBe(true); + + const reloaded = await listConfiguredMcpServers(); + expect(reloaded.ok).toBe(true); + if (!reloaded.ok) { + throw new Error("expected MCP config to reload"); + } + expect(reloaded.mcpServers).toEqual({}); + }); + }); + + it("fails closed when the config file is invalid", async () => { + await withTempHomeConfig({}, async ({ configPath }) => { + await fs.writeFile(configPath, "{", "utf-8"); + + const loaded = await listConfiguredMcpServers(); + expect(loaded.ok).toBe(false); + if (loaded.ok) { + throw new Error("expected invalid config to fail"); + } + expect(loaded.path).toBe(configPath); + }); + }); +}); diff --git a/src/config/mcp-config.ts b/src/config/mcp-config.ts new file mode 100644 index 00000000000..eb24e3c0ae4 --- /dev/null +++ b/src/config/mcp-config.ts @@ -0,0 +1,150 @@ +import { readConfigFileSnapshot, writeConfigFile } from "./io.js"; +import type { OpenClawConfig } from "./types.openclaw.js"; +import { validateConfigObjectWithPlugins } from "./validation.js"; + +export type ConfigMcpServers = Record>; + +type ConfigMcpReadResult = + | { ok: true; path: string; config: OpenClawConfig; mcpServers: ConfigMcpServers } + | { ok: false; path: string; error: string }; + +type ConfigMcpWriteResult = + | { + ok: true; + path: string; + config: OpenClawConfig; + mcpServers: ConfigMcpServers; + removed?: boolean; + } + | { ok: false; path: string; error: string }; + +function isRecord(value: unknown): value is Record { + return value !== null && typeof value === "object" && !Array.isArray(value); +} + +export function normalizeConfiguredMcpServers(value: unknown): ConfigMcpServers { + if (!isRecord(value)) { + return {}; + } + return Object.fromEntries( + Object.entries(value) + .filter(([, server]) => isRecord(server)) + .map(([name, server]) => [name, { ...(server as Record) }]), + ); +} + +export async function listConfiguredMcpServers(): Promise { + const snapshot = await readConfigFileSnapshot(); + if (!snapshot.valid) { + return { + ok: false, + path: snapshot.path, + error: "Config file is invalid; fix it before using MCP config commands.", + }; + } + return { + ok: true, + path: snapshot.path, + config: structuredClone(snapshot.resolved), + mcpServers: normalizeConfiguredMcpServers(snapshot.resolved.mcp?.servers), + }; +} + +export async function setConfiguredMcpServer(params: { + name: string; + server: unknown; +}): Promise { + const name = params.name.trim(); + if (!name) { + return { ok: false, path: "", error: "MCP server name is required." }; + } + if (!isRecord(params.server)) { + return { ok: false, path: "", error: "MCP server config must be a JSON object." }; + } + + const loaded = await listConfiguredMcpServers(); + if (!loaded.ok) { + return loaded; + } + + const next = structuredClone(loaded.config); + const servers = normalizeConfiguredMcpServers(next.mcp?.servers); + servers[name] = { ...params.server }; + next.mcp = { + ...next.mcp, + servers, + }; + + const validated = validateConfigObjectWithPlugins(next); + if (!validated.ok) { + const issue = validated.issues[0]; + return { + ok: false, + path: loaded.path, + error: `Config invalid after MCP set (${issue.path}: ${issue.message}).`, + }; + } + await writeConfigFile(validated.config); + return { + ok: true, + path: loaded.path, + config: validated.config, + mcpServers: servers, + }; +} + +export async function unsetConfiguredMcpServer(params: { + name: string; +}): Promise { + const name = params.name.trim(); + if (!name) { + return { ok: false, path: "", error: "MCP server name is required." }; + } + + const loaded = await listConfiguredMcpServers(); + if (!loaded.ok) { + return loaded; + } + if (!Object.hasOwn(loaded.mcpServers, name)) { + return { + ok: true, + path: loaded.path, + config: loaded.config, + mcpServers: loaded.mcpServers, + removed: false, + }; + } + + const next = structuredClone(loaded.config); + const servers = normalizeConfiguredMcpServers(next.mcp?.servers); + delete servers[name]; + if (Object.keys(servers).length > 0) { + next.mcp = { + ...next.mcp, + servers, + }; + } else if (next.mcp) { + delete next.mcp.servers; + if (Object.keys(next.mcp).length === 0) { + delete next.mcp; + } + } + + const validated = validateConfigObjectWithPlugins(next); + if (!validated.ok) { + const issue = validated.issues[0]; + return { + ok: false, + path: loaded.path, + error: `Config invalid after MCP unset (${issue.path}: ${issue.message}).`, + }; + } + await writeConfigFile(validated.config); + return { + ok: true, + path: loaded.path, + config: validated.config, + mcpServers: servers, + removed: true, + }; +} diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts index 02103650589..02d9ea5f6c9 100644 --- a/src/config/schema.help.ts +++ b/src/config/schema.help.ts @@ -1093,6 +1093,8 @@ export const FIELD_HELP: Record = { "commands.bashForegroundMs": "How long bash waits before backgrounding (default: 2000; 0 backgrounds immediately).", "commands.config": "Allow /config chat command to read/write config on disk (default: false).", + "commands.mcp": + "Allow /mcp chat command to manage OpenClaw MCP server config under mcp.servers (default: false).", "commands.debug": "Allow /debug chat command for runtime-only overrides (default: false).", "commands.restart": "Allow /restart and gateway restart tool actions (default: true).", "commands.useAccessGroups": "Enforce access-group allowlists/policies for commands.", @@ -1104,6 +1106,9 @@ export const FIELD_HELP: Record = { "Optional secret used to HMAC hash owner IDs when ownerDisplay=hash. Prefer env substitution.", "commands.allowFrom": "Defines elevated command allow rules by channel and sender for owner-level command surfaces. Use narrow provider-specific identities so privileged commands are not exposed to broad chat audiences.", + mcp: "Global MCP server definitions managed by OpenClaw. Embedded Pi and other runtime adapters can consume these servers without storing them inside Pi-owned project settings.", + "mcp.servers": + "Named MCP server definitions. OpenClaw stores them in its own config and runtime adapters decide which transports are supported at execution time.", session: "Global session routing, reset, delivery policy, and maintenance controls for conversation history behavior. Keep defaults unless you need stricter isolation, retention, or delivery constraints.", "session.scope": diff --git a/src/config/schema.labels.ts b/src/config/schema.labels.ts index a88cdc1ded5..f00b9fd9226 100644 --- a/src/config/schema.labels.ts +++ b/src/config/schema.labels.ts @@ -503,6 +503,7 @@ export const FIELD_LABELS: Record = { "commands.bash": "Allow Bash Chat Command", "commands.bashForegroundMs": "Bash Foreground Window (ms)", "commands.config": "Allow /config", + "commands.mcp": "Allow /mcp", "commands.debug": "Allow /debug", "commands.restart": "Allow Restart", "commands.useAccessGroups": "Use Access Groups", @@ -510,6 +511,8 @@ export const FIELD_LABELS: Record = { "commands.ownerDisplay": "Owner ID Display", "commands.ownerDisplaySecret": "Owner ID Hash Secret", // pragma: allowlist secret "commands.allowFrom": "Command Elevated Access Rules", + mcp: "MCP", + "mcp.servers": "MCP Servers", ui: "UI", "ui.seamColor": "Accent Color", "ui.assistant": "Assistant Appearance", diff --git a/src/config/types.mcp.ts b/src/config/types.mcp.ts new file mode 100644 index 00000000000..9d6b5e5a1d6 --- /dev/null +++ b/src/config/types.mcp.ts @@ -0,0 +1,14 @@ +export type McpServerConfig = { + command?: string; + args?: string[]; + env?: Record; + cwd?: string; + workingDirectory?: string; + url?: string; + [key: string]: unknown; +}; + +export type McpConfig = { + /** Named MCP server definitions managed by OpenClaw. */ + servers?: Record; +}; diff --git a/src/config/types.messages.ts b/src/config/types.messages.ts index 002a1200b8b..e6f976f2df2 100644 --- a/src/config/types.messages.ts +++ b/src/config/types.messages.ts @@ -148,6 +148,8 @@ export type CommandsConfig = { bashForegroundMs?: number; /** Allow /config command (default: false). */ config?: boolean; + /** Allow /mcp command for project-local embedded Pi MCP settings (default: false). */ + mcp?: boolean; /** Allow /debug command (default: false). */ debug?: boolean; /** Allow restart commands/tools (default: true). */ diff --git a/src/config/types.openclaw.ts b/src/config/types.openclaw.ts index 3d1f0a90080..9997ecc6f84 100644 --- a/src/config/types.openclaw.ts +++ b/src/config/types.openclaw.ts @@ -14,6 +14,7 @@ import type { TalkConfig, } from "./types.gateway.js"; import type { HooksConfig } from "./types.hooks.js"; +import type { McpConfig } from "./types.mcp.js"; import type { MemoryConfig } from "./types.memory.js"; import type { AudioConfig, @@ -120,6 +121,7 @@ export type OpenClawConfig = { talk?: TalkConfig; gateway?: GatewayConfig; memory?: MemoryConfig; + mcp?: McpConfig; }; export type ConfigValidationIssue = { diff --git a/src/config/types.ts b/src/config/types.ts index 52e45b32aaf..47c46e48c68 100644 --- a/src/config/types.ts +++ b/src/config/types.ts @@ -33,3 +33,4 @@ export * from "./types.tts.js"; export * from "./types.tools.js"; export * from "./types.whatsapp.js"; export * from "./types.memory.js"; +export * from "./types.mcp.js"; diff --git a/src/config/zod-schema.session.ts b/src/config/zod-schema.session.ts index b8bb99b1b14..08a3af7c911 100644 --- a/src/config/zod-schema.session.ts +++ b/src/config/zod-schema.session.ts @@ -200,6 +200,7 @@ export const CommandsSchema = z bash: z.boolean().optional(), bashForegroundMs: z.number().int().min(0).max(30_000).optional(), config: z.boolean().optional(), + mcp: z.boolean().optional(), debug: z.boolean().optional(), restart: z.boolean().optional().default(true), useAccessGroups: z.boolean().optional(), diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts index 817183cab5d..b32a86dc68f 100644 --- a/src/config/zod-schema.ts +++ b/src/config/zod-schema.ts @@ -203,6 +203,24 @@ const TalkSchema = z } }); +const McpServerSchema = z + .object({ + command: z.string().optional(), + args: z.array(z.string()).optional(), + env: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(), + cwd: z.string().optional(), + workingDirectory: z.string().optional(), + url: HttpUrlSchema.optional(), + }) + .catchall(z.unknown()); + +const McpConfigSchema = z + .object({ + servers: z.record(z.string(), McpServerSchema).optional(), + }) + .strict() + .optional(); + export const OpenClawSchema = z .object({ $schema: z.string().optional(), @@ -851,6 +869,7 @@ export const OpenClawSchema = z }) .optional(), memory: MemorySchema, + mcp: McpConfigSchema, skills: z .object({ allowBundled: z.array(z.string()).optional(), diff --git a/src/plugins/bundle-mcp.test.ts b/src/plugins/bundle-mcp.test.ts index 939580f9cfe..ce4c460baf0 100644 --- a/src/plugins/bundle-mcp.test.ts +++ b/src/plugins/bundle-mcp.test.ts @@ -81,6 +81,7 @@ describe("loadEnabledBundleMcpConfig", () => { const loadedServer = loaded.config.mcpServers.bundleProbe; const loadedArgs = getServerArgs(loadedServer); const loadedServerPath = typeof loadedArgs?.[0] === "string" ? loadedArgs[0] : undefined; + const resolvedPluginRoot = await fs.realpath(pluginRoot); expect(loaded.diagnostics).toEqual([]); expect(isRecord(loadedServer) ? loadedServer.command : undefined).toBe("node"); @@ -90,6 +91,7 @@ describe("loadEnabledBundleMcpConfig", () => { throw new Error("expected bundled MCP args to include the server path"); } expect(await fs.realpath(loadedServerPath)).toBe(resolvedServerPath); + expect(loadedServer.cwd).toBe(resolvedPluginRoot); } finally { env.restore(); } @@ -164,4 +166,67 @@ describe("loadEnabledBundleMcpConfig", () => { env.restore(); } }); + + it("resolves inline Claude MCP paths from the plugin root and expands CLAUDE_PLUGIN_ROOT", async () => { + const env = captureEnv(["HOME", "USERPROFILE", "OPENCLAW_HOME", "OPENCLAW_STATE_DIR"]); + try { + const homeDir = await createTempDir("openclaw-bundle-inline-placeholder-home-"); + const workspaceDir = await createTempDir("openclaw-bundle-inline-placeholder-workspace-"); + process.env.HOME = homeDir; + process.env.USERPROFILE = homeDir; + delete process.env.OPENCLAW_HOME; + delete process.env.OPENCLAW_STATE_DIR; + + const pluginRoot = path.join(homeDir, ".openclaw", "extensions", "inline-claude"); + await fs.mkdir(path.join(pluginRoot, ".claude-plugin"), { recursive: true }); + await fs.writeFile( + path.join(pluginRoot, ".claude-plugin", "plugin.json"), + `${JSON.stringify( + { + name: "inline-claude", + mcpServers: { + inlineProbe: { + command: "${CLAUDE_PLUGIN_ROOT}/bin/server.sh", + args: ["${CLAUDE_PLUGIN_ROOT}/servers/probe.mjs", "./local-probe.mjs"], + cwd: "${CLAUDE_PLUGIN_ROOT}", + env: { + PLUGIN_ROOT: "${CLAUDE_PLUGIN_ROOT}", + }, + }, + }, + }, + null, + 2, + )}\n`, + "utf-8", + ); + + const loaded = loadEnabledBundleMcpConfig({ + workspaceDir, + cfg: { + plugins: { + entries: { + "inline-claude": { enabled: true }, + }, + }, + }, + }); + const resolvedPluginRoot = await fs.realpath(pluginRoot); + + expect(loaded.diagnostics).toEqual([]); + expect(loaded.config.mcpServers.inlineProbe).toEqual({ + command: path.join(resolvedPluginRoot, "bin", "server.sh"), + args: [ + path.join(resolvedPluginRoot, "servers", "probe.mjs"), + path.join(resolvedPluginRoot, "local-probe.mjs"), + ], + cwd: resolvedPluginRoot, + env: { + PLUGIN_ROOT: resolvedPluginRoot, + }, + }); + } finally { + env.restore(); + } + }); }); diff --git a/src/plugins/bundle-mcp.ts b/src/plugins/bundle-mcp.ts index 62c10e59156..29bd2b3a6c9 100644 --- a/src/plugins/bundle-mcp.ts +++ b/src/plugins/bundle-mcp.ts @@ -28,12 +28,18 @@ export type EnabledBundleMcpConfigResult = { config: BundleMcpConfig; diagnostics: BundleMcpDiagnostic[]; }; +export type BundleMcpRuntimeSupport = { + hasSupportedStdioServer: boolean; + unsupportedServerNames: string[]; + diagnostics: string[]; +}; const MANIFEST_PATH_BY_FORMAT: Record = { claude: CLAUDE_BUNDLE_MANIFEST_RELATIVE_PATH, codex: CODEX_BUNDLE_MANIFEST_RELATIVE_PATH, cursor: CURSOR_BUNDLE_MANIFEST_RELATIVE_PATH, }; +const CLAUDE_PLUGIN_ROOT_PLACEHOLDER = "${CLAUDE_PLUGIN_ROOT}"; function normalizePathList(value: unknown): string[] { if (typeof value === "string") { @@ -131,36 +137,68 @@ function isExplicitRelativePath(value: string): boolean { return value === "." || value === ".." || value.startsWith("./") || value.startsWith("../"); } +function expandBundleRootPlaceholders(value: string, rootDir: string): string { + if (!value.includes(CLAUDE_PLUGIN_ROOT_PLACEHOLDER)) { + return value; + } + return value.split(CLAUDE_PLUGIN_ROOT_PLACEHOLDER).join(rootDir); +} + function absolutizeBundleMcpServer(params: { + rootDir: string; baseDir: string; server: BundleMcpServerConfig; }): BundleMcpServerConfig { const next: BundleMcpServerConfig = { ...params.server }; + if (typeof next.cwd !== "string" && typeof next.workingDirectory !== "string") { + next.cwd = params.baseDir; + } + const command = next.command; - if (typeof command === "string" && isExplicitRelativePath(command)) { - next.command = path.resolve(params.baseDir, command); + if (typeof command === "string") { + const expanded = expandBundleRootPlaceholders(command, params.rootDir); + next.command = isExplicitRelativePath(expanded) + ? path.resolve(params.baseDir, expanded) + : expanded; } const cwd = next.cwd; - if (typeof cwd === "string" && !path.isAbsolute(cwd)) { - next.cwd = path.resolve(params.baseDir, cwd); + if (typeof cwd === "string") { + const expanded = expandBundleRootPlaceholders(cwd, params.rootDir); + next.cwd = path.isAbsolute(expanded) ? expanded : path.resolve(params.baseDir, expanded); } const workingDirectory = next.workingDirectory; - if (typeof workingDirectory === "string" && !path.isAbsolute(workingDirectory)) { - next.workingDirectory = path.resolve(params.baseDir, workingDirectory); + if (typeof workingDirectory === "string") { + const expanded = expandBundleRootPlaceholders(workingDirectory, params.rootDir); + next.workingDirectory = path.isAbsolute(expanded) + ? expanded + : path.resolve(params.baseDir, expanded); } if (Array.isArray(next.args)) { next.args = next.args.map((entry) => { - if (typeof entry !== "string" || !isExplicitRelativePath(entry)) { + if (typeof entry !== "string") { return entry; } - return path.resolve(params.baseDir, entry); + const expanded = expandBundleRootPlaceholders(entry, params.rootDir); + if (!isExplicitRelativePath(expanded)) { + return expanded; + } + return path.resolve(params.baseDir, expanded); }); } + if (isRecord(next.env)) { + next.env = Object.fromEntries( + Object.entries(next.env).map(([key, value]) => [ + key, + typeof value === "string" ? expandBundleRootPlaceholders(value, params.rootDir) : value, + ]), + ); + } + return next; } @@ -190,7 +228,7 @@ function loadBundleFileBackedMcpConfig(params: { mcpServers: Object.fromEntries( Object.entries(servers).map(([serverName, server]) => [ serverName, - absolutizeBundleMcpServer({ baseDir, server }), + absolutizeBundleMcpServer({ rootDir: params.rootDir, baseDir, server }), ]), ), }; @@ -211,7 +249,7 @@ function loadBundleInlineMcpConfig(params: { mcpServers: Object.fromEntries( Object.entries(servers).map(([serverName, server]) => [ serverName, - absolutizeBundleMcpServer({ baseDir: params.baseDir, server }), + absolutizeBundleMcpServer({ rootDir: params.baseDir, baseDir: params.baseDir, server }), ]), ), }; @@ -252,13 +290,35 @@ function loadBundleMcpConfig(params: { merged, loadBundleInlineMcpConfig({ raw: manifestLoaded.raw, - baseDir: path.dirname(path.join(params.rootDir, manifestRelativePath)), + baseDir: params.rootDir, }), ) as BundleMcpConfig; return { config: merged, diagnostics: [] }; } +export function inspectBundleMcpRuntimeSupport(params: { + pluginId: string; + rootDir: string; + bundleFormat: PluginBundleFormat; +}): BundleMcpRuntimeSupport { + const loaded = loadBundleMcpConfig(params); + const unsupportedServerNames: string[] = []; + let hasSupportedStdioServer = false; + for (const [serverName, server] of Object.entries(loaded.config.mcpServers)) { + if (typeof server.command === "string" && server.command.trim().length > 0) { + hasSupportedStdioServer = true; + continue; + } + unsupportedServerNames.push(serverName); + } + return { + hasSupportedStdioServer, + unsupportedServerNames, + diagnostics: loaded.diagnostics, + }; +} + export function loadEnabledBundleMcpConfig(params: { workspaceDir: string; cfg?: OpenClawConfig; diff --git a/src/plugins/loader.test.ts b/src/plugins/loader.test.ts index 808ba4c8cb7..a1e25c0ea3e 100644 --- a/src/plugins/loader.test.ts +++ b/src/plugins/loader.test.ts @@ -420,6 +420,116 @@ describe("bundle plugins", () => { ).toBe(false); }); + it("treats bundle MCP as a supported bundle surface", () => { + const workspaceDir = makeTempDir(); + const bundleRoot = path.join(workspaceDir, ".openclaw", "extensions", "claude-mcp"); + mkdirSafe(path.join(bundleRoot, ".claude-plugin")); + fs.writeFileSync( + path.join(bundleRoot, ".claude-plugin", "plugin.json"), + JSON.stringify({ + name: "Claude MCP", + }), + "utf-8", + ); + fs.writeFileSync( + path.join(bundleRoot, ".mcp.json"), + JSON.stringify({ + mcpServers: { + probe: { + command: "node", + args: ["./probe.mjs"], + }, + }, + }), + "utf-8", + ); + + const registry = loadOpenClawPlugins({ + workspaceDir, + config: { + plugins: { + entries: { + "claude-mcp": { + enabled: true, + }, + }, + }, + }, + cache: false, + }); + + const plugin = registry.plugins.find((entry) => entry.id === "claude-mcp"); + expect(plugin?.status).toBe("loaded"); + expect(plugin?.bundleFormat).toBe("claude"); + expect(plugin?.bundleCapabilities).toEqual(expect.arrayContaining(["mcpServers"])); + expect( + registry.diagnostics.some( + (diag) => + diag.pluginId === "claude-mcp" && + diag.message.includes("bundle capability detected but not wired"), + ), + ).toBe(false); + }); + + it("warns when bundle MCP only declares unsupported non-stdio transports", () => { + useNoBundledPlugins(); + const workspaceDir = makeTempDir(); + const stateDir = makeTempDir(); + const bundleRoot = path.join(workspaceDir, ".openclaw", "extensions", "claude-mcp-url"); + fs.mkdirSync(path.join(bundleRoot, ".claude-plugin"), { recursive: true }); + fs.writeFileSync( + path.join(bundleRoot, ".claude-plugin", "plugin.json"), + JSON.stringify({ + name: "Claude MCP URL", + }), + "utf-8", + ); + fs.writeFileSync( + path.join(bundleRoot, ".mcp.json"), + JSON.stringify({ + mcpServers: { + remoteProbe: { + url: "http://127.0.0.1:8787/mcp", + }, + }, + }), + "utf-8", + ); + + const registry = withEnv( + { + OPENCLAW_HOME: stateDir, + OPENCLAW_STATE_DIR: stateDir, + }, + () => + loadOpenClawPlugins({ + workspaceDir, + config: { + plugins: { + entries: { + "claude-mcp-url": { + enabled: true, + }, + }, + }, + }, + cache: false, + }), + ); + + const plugin = registry.plugins.find((entry) => entry.id === "claude-mcp-url"); + expect(plugin?.status).toBe("loaded"); + expect(plugin?.bundleCapabilities).toEqual(expect.arrayContaining(["mcpServers"])); + expect( + registry.diagnostics.some( + (diag) => + diag.pluginId === "claude-mcp-url" && + diag.message.includes("stdio only today") && + diag.message.includes("remoteProbe"), + ), + ).toBe(true); + }); + it("treats Cursor command roots as supported bundle skill surfaces", () => { useNoBundledPlugins(); const workspaceDir = makeTempDir(); diff --git a/src/plugins/loader.ts b/src/plugins/loader.ts index 873fff6b9bf..86273793006 100644 --- a/src/plugins/loader.ts +++ b/src/plugins/loader.ts @@ -11,6 +11,7 @@ import { openBoundaryFileSync } from "../infra/boundary-file-read.js"; import { resolveOpenClawPackageRootSync } from "../infra/openclaw-root.js"; import { createSubsystemLogger } from "../logging/subsystem.js"; import { resolveUserPath } from "../utils.js"; +import { inspectBundleMcpRuntimeSupport } from "./bundle-mcp.js"; import { clearPluginCommands } from "./commands.js"; import { applyTestPluginDefaults, @@ -1099,6 +1100,7 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi const unsupportedCapabilities = (record.bundleCapabilities ?? []).filter( (capability) => capability !== "skills" && + capability !== "mcpServers" && capability !== "settings" && !( capability === "commands" && @@ -1114,6 +1116,36 @@ export function loadOpenClawPlugins(options: PluginLoadOptions = {}): PluginRegi message: `bundle capability detected but not wired into OpenClaw yet: ${capability}`, }); } + if ( + enableState.enabled && + record.rootDir && + record.bundleFormat && + (record.bundleCapabilities ?? []).includes("mcpServers") + ) { + const runtimeSupport = inspectBundleMcpRuntimeSupport({ + pluginId: record.id, + rootDir: record.rootDir, + bundleFormat: record.bundleFormat, + }); + for (const message of runtimeSupport.diagnostics) { + registry.diagnostics.push({ + level: "warn", + pluginId: record.id, + source: record.source, + message, + }); + } + if (runtimeSupport.unsupportedServerNames.length > 0) { + registry.diagnostics.push({ + level: "warn", + pluginId: record.id, + source: record.source, + message: + "bundle MCP servers use unsupported transports or incomplete configs " + + `(stdio only today): ${runtimeSupport.unsupportedServerNames.join(", ")}`, + }); + } + } registry.plugins.push(record); seenIds.set(pluginId, candidate.origin); continue;