feat: map OpenCode native MCP tools to gateway mcp__ names

Author: sdziupin

README.md

@@ -30,7 +30,7 @@ Default live-test target is **Laguna S 2.1 free** (`poolside/laguna-s-2.1-free`,
 
 ### Keep agent loops, files, and context moving
 
-OpenCode tool calls park and resume (MCP-prefixed tools are tracked separately). Attachments (images, PDFs, text/binary) pass through. Auto-compact tips and tiered client compact run before the 256k window overflows. Per-turn and session usage come from SSE `usage` plus `GET /v1/usage`.
+OpenCode tool calls park and resume. MCP tools configured natively in OpenCode (`mcp:` in `opencode.json`) are mapped both ways — OpenCode's `<server>_<tool>` ↔ the gateway's `mcp__<server>__<tool>` — so the agent sees them and OpenCode executes them with its own MCP clients. Attachments (images, PDFs, text/binary) pass through. Auto-compact tips and tiered client compact run before the 256k window overflows. Per-turn and session usage come from SSE `usage` plus `GET /v1/usage`.
 
 ## Quick start
 

src/index.ts

@@ -26,6 +26,7 @@ import {
   SESSION_HEADER,
 } from "./constants.js";
 import { log } from "./log.js";
+import { setMcpServers } from "./mcp-names.js";
 import {
   encodeCommandModelSelection,
   resolveCommandModelSelection,
@@ -298,6 +299,22 @@ export const CommandCodePlugin: Plugin = async (
       // Always seed the live catalog so the provider is discoverable.
       refreshCommandModels();
       ensureProviderConfig(config as Record<string, any>, getCommandModels());
+
+      // Seed native MCP server names (from `mcp:` in opencode config) so the
+      // proxy can map tool names <server>_<tool> ↔ mcp__<server>__<tool>.
+      // This is what lets the gateway agent see OpenCode's MCP tools and
+      // lets OpenCode execute the calls natively via its own MCP clients.
+      const mcpConfig = (config as Record<string, any>).mcp;
+      if (mcpConfig && typeof mcpConfig === "object") {
+        setMcpServers(
+          Object.entries(mcpConfig as Record<string, unknown>)
+            .filter(([, entry]) => {
+              if (!entry || typeof entry !== "object") return true;
+              return (entry as { enabled?: unknown }).enabled !== false;
+            })
+            .map(([name]) => name),
+        );
+      }
     },
 
     "chat.headers": async (hookInput, output) => {

src/mcp-names.ts

@@ -0,0 +1,94 @@
+/**
+ * Bidirectional MCP tool-name mapping.
+ *
+ * OpenCode exposes MCP tools natively as `sanitize(server)_sanitize(tool)`
+ * (see McpCatalog.toolName), e.g. `linear_list_issues`.
+ * The Command Code gateway/CLI expects `mcp__<server>__<tool>`
+ * (see uniqueRegistryToolName in the `cmd` CLI bundle).
+ *
+ * Without this mapping the gateway agent never recognizes OpenCode's MCP
+ * tools as MCP (they must start with `mcp__`), and OpenCode cannot dispatch
+ * gateway-emitted `mcp__*` tool calls to its own MCP clients.
+ */
+
+/** Same sanitize both ecosystems use: [^a-zA-Z0-9_-] → "_" */
+const sanitize = (value: string): string =>
+  value.replace(/[^a-zA-Z0-9_-]/g, "_");
+
+/** Sanitized MCP server names, longest first for unambiguous prefix match. */
+let serverNames: string[] = [];
+
+/** Exact wire → native pairs seen this process (handles ambiguous names). */
+const wireToNative = new Map<string, string>();
+
+/**
+ * Register MCP server names from the merged OpenCode config (`mcp:` keys).
+ * Called once from the plugin config hook; cheap to re-call.
+ */
+export function setMcpServers(names: string[]): void {
+  serverNames = [...new Set(names.map(sanitize).filter(Boolean))].sort(
+    (a, b) => b.length - a.length,
+  );
+}
+
+export function getMcpServers(): readonly string[] {
+  return serverNames;
+}
+
+function nativeFromParts(server: string, tool: string): string {
+  return `${server}_${tool}`;
+}
+
+/**
+ * OpenCode native tool name → Command Code wire name.
+ * Non-MCP tools pass through unchanged.
+ */
+export function toWireName(nativeName: string): string {
+  if (!nativeName || nativeName.startsWith("mcp__")) return nativeName;
+  for (const server of serverNames) {
+    const prefix = `${server}_`;
+    if (nativeName.startsWith(prefix) && nativeName.length > prefix.length) {
+      const wire = `mcp__${server}__${nativeName.slice(prefix.length)}`;
+      wireToNative.set(wire, nativeName);
+      return wire;
+    }
+  }
+  return nativeName;
+}
+
+/**
+ * Command Code wire name → OpenCode native tool name.
+ * Unknown / non-MCP names pass through unchanged.
+ */
+export function toNativeName(wireName: string): string {
+  if (!wireName.startsWith("mcp__")) return wireName;
+  const known = wireToNative.get(wireName);
+  if (known) return known;
+  const rest = wireName.slice("mcp__".length);
+  const sep = rest.indexOf("__");
+  if (sep <= 0 || sep + 2 >= rest.length) return wireName;
+  const server = rest.slice(0, sep);
+  const tool = rest.slice(sep + 2);
+  if (!serverNames.includes(server)) return wireName;
+  const native = nativeFromParts(server, tool);
+  wireToNative.set(wireName, native);
+  return native;
+}
+
+/** True when the native OpenCode tool name belongs to a configured MCP server. */
+export function isNativeMcpName(nativeName: string): boolean {
+  if (!nativeName) return false;
+  if (nativeName.startsWith("mcp__") || nativeName.startsWith("mcp_")) {
+    return true;
+  }
+  for (const server of serverNames) {
+    if (nativeName.startsWith(`${server}_`)) return true;
+  }
+  return false;
+}
+
+/** Test helper. */
+export function resetMcpNamesForTests(): void {
+  serverNames = [];
+  wireToNative.clear();
+}

src/prompt.ts

@@ -11,6 +11,7 @@ import type {
   WireTool,
   WireUserContent,
 } from "./gateway-types.js";
+import { toWireName } from "./mcp-names.js";
 
 const IMAGE_OMITTED =
   "[image omitted: the active model is text-only]";
@@ -301,7 +302,9 @@ export function openaiToolsToWire(tools: OpenAITool[]): WireTool[] {
       const name = t.function?.name;
       if (!name) return null;
       return {
-        name,
+        // Gateway expects MCP tools as mcp__<server>__<tool>; OpenCode
+        // names them <server>_<tool> natively. Map so agents see them.
+        name: toWireName(name),
         description: t.function?.description || name,
         input_schema:
           (t.function?.parameters as Record<string, unknown>) || {
@@ -359,7 +362,7 @@ export function openaiMessagesToWire(
           content.push({
             type: "tool-call",
             toolCallId: id,
-            toolName: name,
+            toolName: toWireName(name),
             input,
           });
         }
@@ -377,7 +380,7 @@ export function openaiMessagesToWire(
           {
             type: "tool-result",
             toolCallId,
-            toolName: msg.name || "",
+            toolName: msg.name ? toWireName(msg.name) : "",
             output: {
               type: "text",
               value: extractTextContent(msg.content),

src/proxy.ts

@@ -39,6 +39,7 @@ import {
 import type { WireMessage, WireTool, WireUsage } from "./gateway-types.js";
 import { emptyUsage } from "./gateway-types.js";
 import { log } from "./log.js";
+import { toNativeName, toWireName } from "./mcp-names.js";
 import {
   conversationKeyFromMessages,
   getSessionUsage,
@@ -447,19 +448,22 @@ async function handleChatCompletions(
         continue;
       }
       if (event.kind === "tool_call") {
+        // Map gateway mcp__<server>__<tool> back to the OpenCode native
+        // <server>_<tool> so OpenCode executes it via its own MCP client.
+        const nativeName = toNativeName(event.name);
         if (event.providerExecuted) {
           // Server-executed tool — surface as reasoning note, do not park.
           yield {
             kind: "reasoning",
-            text: `[mcp/tool] ${event.name} (provider-executed)\n`,
+            text: `[mcp/tool] ${nativeName} (provider-executed)\n`,
           } satisfies GatewayMappedEvent;
-          recordToolCall(conversationKey, event.name);
+          recordToolCall(conversationKey, nativeName);
           continue;
         }
-        recordToolCall(conversationKey, event.name);
+        recordToolCall(conversationKey, nativeName);
         const pending: ParkedToolCall = {
           id: event.id,
-          name: event.name,
+          name: nativeName,
           arguments: event.arguments,
           resolve: () => {},
           reject: () => {},
@@ -489,7 +493,7 @@ async function handleChatCompletions(
           const assistantContent = assistantToolCalls.map((t) => ({
             type: "tool-call" as const,
             toolCallId: t.id,
-            toolName: t.name,
+            toolName: toWireName(t.name),
             input: safeParse(t.arguments),
           }));
           const nextMessages: WireMessage[] = [
@@ -507,7 +511,7 @@ async function handleChatCompletions(
                   {
                     type: "tool-result",
                     toolCallId: tool.id,
-                    toolName: tool.name,
+                    toolName: toWireName(tool.name),
                     output: { type: "text", value: result },
                   },
                 ],

src/usage.ts

@@ -7,6 +7,7 @@ import {
   emptyUsage,
   type WireUsage,
 } from "./gateway-types.js";
+import { isNativeMcpName } from "./mcp-names.js";
 
 export type ToolUsageStat = {
   name: string;
@@ -35,7 +36,9 @@ function isMcpToolName(name: string): boolean {
   return (
     name.startsWith("mcp__") ||
     name.startsWith("mcp_") ||
-    /(^|\.)mcp($|\.)/i.test(name)
+    /(^|\.)mcp($|\.)/i.test(name) ||
+    // Native OpenCode MCP names (<server>_<tool>) recorded after mapping.
+    isNativeMcpName(name)
   );
 }
 

test/smoke.ts

@@ -96,6 +96,14 @@ async function main() {
     "../src/gateway.ts"
   );
   const { detectCommandCode } = await import("../src/detect.ts");
+  const {
+    setMcpServers,
+    getMcpServers,
+    toWireName,
+    toNativeName,
+    isNativeMcpName,
+    resetMcpNamesForTests,
+  } = await import("../src/mcp-names.ts");
 
   // --- credentials ---
   assert.ok(listCommandAuthCandidates().length > 0);
@@ -318,6 +326,75 @@ claude-sonnet-5                      recommended
   assert.equal(tools.length, 2);
   assert.equal(tools[0]?.name, "bash");
 
+  // --- MCP tool-name mapping (OpenCode native <-> Command Code wire) ---
+  resetMcpNamesForTests();
+  setMcpServers(["linear", "filesystem"]);
+  assert.deepEqual([...getMcpServers()].sort(), ["filesystem", "linear"]);
+  assert.equal(toWireName("linear_list_issues"), "mcp__linear__list_issues");
+  assert.equal(toWireName("filesystem_read"), "mcp__filesystem__read");
+  assert.equal(toWireName("bash"), "bash");
+  assert.equal(toWireName("mcp__linear__list_issues"), "mcp__linear__list_issues");
+  assert.equal(toNativeName("mcp__linear__list_issues"), "linear_list_issues");
+  assert.equal(toNativeName("mcp__filesystem__read"), "filesystem_read");
+  assert.equal(toNativeName("mcp__unknown__thing"), "mcp__unknown__thing");
+  assert.equal(toNativeName("bash"), "bash");
+  assert.equal(isNativeMcpName("linear_get_issue"), true);
+  assert.equal(isNativeMcpName("bash"), false);
+
+  // Wire conversion must rename MCP tools so the gateway agent sees them.
+  const mappedTools = openaiToolsToWire([
+    {
+      type: "function",
+      function: {
+        name: "linear_list_issues",
+        description: "list issues",
+        parameters: { type: "object", properties: {} },
+      },
+    },
+    {
+      type: "function",
+      function: {
+        name: "bash",
+        description: "shell",
+        parameters: { type: "object", properties: {} },
+      },
+    },
+  ]);
+  assert.equal(mappedTools[0]?.name, "mcp__linear__list_issues");
+  assert.equal(mappedTools[1]?.name, "bash");
+
+  // History conversion must rename MCP tool calls/results consistently.
+  const wiredHistory = openaiMessagesToWire(
+    [
+      { role: "user", content: "hi" },
+      {
+        role: "assistant",
+        content: "",
+        tool_calls: [
+          {
+            id: "call_1",
+            type: "function",
+            function: { name: "linear_list_issues", arguments: "{}" },
+          },
+        ],
+      },
+      {
+        role: "tool",
+        tool_call_id: "call_1",
+        name: "linear_list_issues",
+        content: "[]",
+      },
+    ],
+    { vision: false },
+  );
+  const histAssistant = wiredHistory.messages.find((m) => m.role === "assistant");
+  const histToolCall = (histAssistant?.content as Array<{ toolName?: string }>)?.[0];
+  assert.equal(histToolCall?.toolName, "mcp__linear__list_issues");
+  const histTool = wiredHistory.messages.find((m) => m.role === "tool");
+  const histResult = (histTool?.content as Array<{ toolName?: string }>)?.[0];
+  assert.equal(histResult?.toolName, "mcp__linear__list_issues");
+  resetMcpNamesForTests();
+
   // --- compact / context ---
   const adviceOk = assessContext(10_000, 256_000);
   assert.equal(adviceOk.tier, "ok");