@xi-era/acp-adapter-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 xi-era (open-source community arm of Stellxis)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/dist/bin.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+// src/bin.ts
+import { AcpClient, AcpError as AcpError2 } from "@xi-era/acp-sdk/client";
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport as McpStdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { AcpError, AcpErrorCode } from "@xi-era/acp-sdk/client";
+import { componentIdToToolName, toolNameToComponentId, isValidComponentId } from "@xi-era/acp-sdk/client";
+import { AcpServer } from "@xi-era/acp-sdk/server";
+import { AcpClient as AcpClientImpl } from "@xi-era/acp-sdk/client";
+import { createMemoryClient } from "@xi-era/acp-sdk/server";
+function invokerFromClient(client) {
+  return {
+    discover: () => client.discover(),
+    call: (id, input) => client.call(id, input),
+    callConcatenated: async (id, input) => {
+      let text = "";
+      let binary = Buffer.alloc(0);
+      let sawBinary = false;
+      for await (const chunk of client.callStream(id, input)) {
+        if (chunk.bin === true) {
+          sawBinary = true;
+          binary = Buffer.concat([binary, Buffer.from(String(chunk.data), "base64")]);
+        } else if (typeof chunk.data === "string") {
+          text += chunk.data;
+        } else if (chunk.data !== null) {
+          text += JSON.stringify(chunk.data);
+        }
+      }
+      return sawBinary ? binary.toString("base64") : text;
+    }
+  };
+}
+function invokerFromServer(server) {
+  const client = new AcpClientImpl({ transport: createMemoryClient(server) });
+  return invokerFromClient(client);
+}
+function descriptorToMcpTool(d) {
+  return {
+    name: componentIdToToolName(d.id),
+    description: d.description,
+    inputSchema: d.inputSchema ?? { type: "object", properties: {}, required: [] }
+  };
+}
+function chunkDataToString(data) {
+  if (data === null || data === void 0) return "";
+  if (typeof data === "string") return data;
+  return JSON.stringify(data);
+}
+function createMcpBridgeServer(target, options = {}) {
+  const invoker = target instanceof AcpServer ? invokerFromServer(target) : invokerFromClient(target);
+  const mcpServer = new Server(
+    { name: options.name ?? "acp-bridge", version: options.version ?? "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+  mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
+    const descriptors = await invoker.discover();
+    return { tools: descriptors.map(descriptorToMcpTool) };
+  });
+  mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const componentId = toolNameToComponentId(name);
+    try {
+      let result;
+      try {
+        result = await invoker.call(componentId, args ?? null);
+      } catch (e) {
+        if (e instanceof AcpError && e.code === AcpErrorCode.STREAM_REQUIRED) {
+          result = await invoker.callConcatenated(componentId, args ?? null);
+        } else {
+          throw e;
+        }
+      }
+      return {
+        content: [{ type: "text", text: chunkDataToString(result) || JSON.stringify(result) }],
+        isError: false
+      };
+    } catch (e) {
+      const message = e instanceof AcpError ? `ACP error ${e.code}: ${e.message}` : e instanceof Error ? e.message : String(e);
+      return { content: [{ type: "text", text: message }], isError: true };
+    }
+  });
+  return mcpServer;
+}
+async function serveMcpFromAcp(target, options = {}) {
+  const mcpServer = createMcpBridgeServer(target, options);
+  await mcpServer.connect(new McpStdioServerTransport());
+}
+
+// src/bin.ts
+var url = process.argv[2];
+if (!url) {
+  process.stderr.write("usage: acp-mcp <acp-url>   e.g. acp-mcp http://localhost:8080\n");
+  process.exit(1);
+}
+var normalized = url.replace(/\/+$/, "").endsWith("/acp") ? url : `${url.replace(/\/+$/, "")}/acp`;
+try {
+  const client = new AcpClient({ url: normalized, timeoutMs: 6e4 });
+  await client.connect();
+  await serveMcpFromAcp(client, { name: "acp-bridge" });
+} catch (e) {
+  if (e instanceof AcpError2) {
+    process.stderr.write(`acp-mcp: ACP error ${e.code}: ${e.message}
+`);
+  } else {
+    process.stderr.write(`acp-mcp: ${e instanceof Error ? e.message : String(e)}
+`);
+  }
+  process.exit(1);
+}
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bin.ts","../src/index.ts"],"sourcesContent":["/**\n * acp-mcp — CLI: bridges a remote ACP server to MCP stdio, mountable by\n * Claude Desktop / Cursor:\n *   { \"mcpServers\": { \"acp\": { \"command\": \"npx\", \"args\": [\"-y\", \"@xi-era/acp-adapter-mcp\", \"http://host:8080\"] } } }\n */\nimport { AcpClient, AcpError } from \"@xi-era/acp-sdk/client\";\nimport { serveMcpFromAcp } from \"./index.js\";\n\nconst url = process.argv[2];\nif (!url) {\n  process.stderr.write(\"usage: acp-mcp <acp-url>   e.g. acp-mcp http://localhost:8080\\n\");\n  process.exit(1);\n}\n\nconst normalized = url.replace(/\\/+$/, \"\").endsWith(\"/acp\") ? url : `${url.replace(/\\/+$/, \"\")}/acp`;\n\ntry {\n  const client = new AcpClient({ url: normalized, timeoutMs: 60_000 });\n  await client.connect();\n  await serveMcpFromAcp(client, { name: \"acp-bridge\" });\n} catch (e) {\n  if (e instanceof AcpError) {\n    process.stderr.write(`acp-mcp: ACP error ${e.code}: ${e.message}\\n`);\n  } else {\n    process.stderr.write(`acp-mcp: ${e instanceof Error ? e.message : String(e)}\\n`);\n  }\n  process.exit(1);\n}\n","/**\n * ACP <-> MCP bidirectional bridge (spec 附录 A).\n *\n * Direction 1 (ACP -> MCP): {@link serveMcpFromAcp} exposes an ACP server or\n * client as an MCP stdio server, mountable by Claude Desktop / Cursor etc.\n *\n * Direction 2 (MCP -> ACP): {@link mcpToolsToComponents} wraps an MCP client's\n * tools as ACP component definitions.\n */\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport as McpStdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { CallToolRequestSchema, ListToolsRequestSchema } from \"@modelcontextprotocol/sdk/types.js\";\nimport type { ComponentDescriptor } from \"@xi-era/acp-sdk/client\";\nimport type { AcpClient } from \"@xi-era/acp-sdk/client\";\nimport { AcpError, AcpErrorCode } from \"@xi-era/acp-sdk/client\";\nimport { componentIdToToolName, toolNameToComponentId, isValidComponentId } from \"@xi-era/acp-sdk/client\";\nimport type { ComponentDef } from \"@xi-era/acp-sdk/server\";\nimport { AcpServer } from \"@xi-era/acp-sdk/server\";\nimport { AcpClient as AcpClientImpl } from \"@xi-era/acp-sdk/client\";\nimport { createMemoryClient } from \"@xi-era/acp-sdk/server\";\n\n// ---------------------------------------------------------------------------\n// Internal unified invoker for either an in-process AcpServer or a remote client\n// ---------------------------------------------------------------------------\n\ninterface AcpInvoker {\n  discover(): Promise<ComponentDescriptor[]>;\n  call(componentId: string, input: unknown): Promise<unknown>;\n  /** Concatenates chunks (spec 附录 A: text concat / base64 concat) into one value. */\n  callConcatenated(componentId: string, input: unknown): Promise<unknown>;\n}\n\nfunction invokerFromClient(client: AcpClient): AcpInvoker {\n  return {\n    discover: () => client.discover(),\n    call: (id, input) => client.call(id, input),\n    callConcatenated: async (id, input) => {\n      let text = \"\";\n      let binary = Buffer.alloc(0);\n      let sawBinary = false;\n      for await (const chunk of client.callStream(id, input)) {\n        if (chunk.bin === true) {\n          sawBinary = true;\n          binary = Buffer.concat([binary, Buffer.from(String(chunk.data), \"base64\")]);\n        } else if (typeof chunk.data === \"string\") {\n          text += chunk.data;\n        } else if (chunk.data !== null) {\n          text += JSON.stringify(chunk.data);\n        }\n      }\n      return sawBinary ? binary.toString(\"base64\") : text;\n    },\n  };\n}\n\nfunction invokerFromServer(server: AcpServer): AcpInvoker {\n  const client = new AcpClientImpl({ transport: createMemoryClient(server) });\n  return invokerFromClient(client);\n}\n\n// ---------------------------------------------------------------------------\n// Direction 1: ACP -> MCP\n// ---------------------------------------------------------------------------\n\nexport interface ServeMcpOptions {\n  /** MCP server name advertised to clients; default \"acp-bridge\". */\n  name?: string;\n  /** MCP server version; default \"0.1.0\". */\n  version?: string;\n}\n\nfunction descriptorToMcpTool(d: ComponentDescriptor) {\n  return {\n    name: componentIdToToolName(d.id),\n    description: d.description,\n    inputSchema: d.inputSchema ?? { type: \"object\", properties: {}, required: [] },\n  };\n}\n\n/** Concatenates streamed chunks for MCP consumption (text concat / base64 concat). */\nfunction chunkDataToString(data: unknown): string {\n  if (data === null || data === undefined) return \"\";\n  if (typeof data === \"string\") return data;\n  return JSON.stringify(data);\n}\n\n/**\n * Builds the MCP server that exposes the target's ACP components as MCP tools.\n * tools/list <- discover; tools/call <- call (retrying with stream and\n * concatenating chunks when the component requires streaming).\n */\nexport function createMcpBridgeServer(\n  target: AcpServer | AcpClient,\n  options: ServeMcpOptions = {}\n): Server {\n  const invoker =\n    target instanceof AcpServer ? invokerFromServer(target) : invokerFromClient(target);\n\n  const mcpServer = new Server(\n    { name: options.name ?? \"acp-bridge\", version: options.version ?? \"0.1.0\" },\n    { capabilities: { tools: {} } }\n  );\n\n  mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {\n    const descriptors = await invoker.discover();\n    return { tools: descriptors.map(descriptorToMcpTool) };\n  });\n\n  mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {\n    const { name, arguments: args } = request.params;\n    const componentId = toolNameToComponentId(name);\n    try {\n      let result: unknown;\n      try {\n        result = await invoker.call(componentId, args ?? null);\n      } catch (e) {\n        if (e instanceof AcpError && e.code === AcpErrorCode.STREAM_REQUIRED) {\n          result = await invoker.callConcatenated(componentId, args ?? null);\n        } else {\n          throw e;\n        }\n      }\n      return {\n        content: [{ type: \"text\" as const, text: chunkDataToString(result) || JSON.stringify(result) }],\n        isError: false,\n      };\n    } catch (e) {\n      const message =\n        e instanceof AcpError\n          ? `ACP error ${e.code}: ${e.message}`\n          : e instanceof Error\n            ? e.message\n            : String(e);\n      return { content: [{ type: \"text\" as const, text: message }], isError: true };\n    }\n  });\n\n  return mcpServer;\n}\n\n/**\n * Serves {@link createMcpBridgeServer} over MCP stdio (Claude Desktop / Cursor).\n */\nexport async function serveMcpFromAcp(\n  target: AcpServer | AcpClient,\n  options: ServeMcpOptions = {}\n): Promise<void> {\n  const mcpServer = createMcpBridgeServer(target, options);\n  await mcpServer.connect(new McpStdioServerTransport());\n}\n\n// ---------------------------------------------------------------------------\n// Direction 2: MCP -> ACP\n// ---------------------------------------------------------------------------\n\n/** Minimal structural subset of the MCP Client class used by the bridge. */\nexport interface McpClientLike {\n  listTools(): Promise<{ tools: { name: string; description?: string; inputSchema?: object }[] }>;\n  callTool(request: { name: string; arguments?: unknown }): Promise<{\n    content?: { type: string; text?: string }[];\n    isError?: boolean;\n  }>;\n}\n\ninterface McpToolContentText {\n  type: string;\n  text?: string;\n}\n\n/**\n * Wraps an MCP client's tools as ACP component definitions. Tool names map\n * back via \"_\" -> \".\" (spec §7.1); names that do not form a valid\n * component_id are rejected with a clear error.\n */\nexport async function mcpToolsToComponents(\n  mcpClient: McpClientLike\n): Promise<ComponentDef[]> {\n  const { tools } = await mcpClient.listTools();\n  return tools.map((tool) => {\n    const id = toolNameToComponentId(tool.name);\n    if (!isValidComponentId(id)) {\n      throw new Error(\n        `MCP tool name \"${tool.name}\" maps to invalid ACP component id \"${id}\" (spec §7.1)`\n      );\n    }\n    return {\n      id,\n      name: tool.name,\n      description: tool.description ?? tool.name,\n      version: \"0.0.0\",\n      inputSchema: tool.inputSchema,\n      stream: false,\n      meta: { viaMcpBridge: true },\n      handle: async (input: unknown) => {\n        const result = await mcpClient.callTool({ name: tool.name, arguments: input ?? {} });\n        const parts: McpToolContentText[] = result.content ?? [];\n        const text = parts\n          .map((p) => (p.type === \"text\" ? (p.text ?? \"\") : JSON.stringify(p)))\n          .join(\"\\n\");\n        if (result.isError) {\n          throw new AcpError(AcpErrorCode.UPSTREAM_ERROR, text || \"MCP tool error\");\n        }\n        return { mcp: { content: parts }, text };\n      },\n    };\n  });\n}\n"],"mappings":"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","names":["AcpError","AcpError"]}

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { AcpClient } from '@xi-era/acp-sdk/client';
+import { AcpServer, ComponentDef } from '@xi-era/acp-sdk/server';
+
+/**
+ * ACP <-> MCP bidirectional bridge (spec 附录 A).
+ *
+ * Direction 1 (ACP -> MCP): {@link serveMcpFromAcp} exposes an ACP server or
+ * client as an MCP stdio server, mountable by Claude Desktop / Cursor etc.
+ *
+ * Direction 2 (MCP -> ACP): {@link mcpToolsToComponents} wraps an MCP client's
+ * tools as ACP component definitions.
+ */
+
+interface ServeMcpOptions {
+    /** MCP server name advertised to clients; default "acp-bridge". */
+    name?: string;
+    /** MCP server version; default "0.1.0". */
+    version?: string;
+}
+/**
+ * Builds the MCP server that exposes the target's ACP components as MCP tools.
+ * tools/list <- discover; tools/call <- call (retrying with stream and
+ * concatenating chunks when the component requires streaming).
+ */
+declare function createMcpBridgeServer(target: AcpServer | AcpClient, options?: ServeMcpOptions): Server;
+/**
+ * Serves {@link createMcpBridgeServer} over MCP stdio (Claude Desktop / Cursor).
+ */
+declare function serveMcpFromAcp(target: AcpServer | AcpClient, options?: ServeMcpOptions): Promise<void>;
+/** Minimal structural subset of the MCP Client class used by the bridge. */
+interface McpClientLike {
+    listTools(): Promise<{
+        tools: {
+            name: string;
+            description?: string;
+            inputSchema?: object;
+        }[];
+    }>;
+    callTool(request: {
+        name: string;
+        arguments?: unknown;
+    }): Promise<{
+        content?: {
+            type: string;
+            text?: string;
+        }[];
+        isError?: boolean;
+    }>;
+}
+/**
+ * Wraps an MCP client's tools as ACP component definitions. Tool names map
+ * back via "_" -> "." (spec §7.1); names that do not form a valid
+ * component_id are rejected with a clear error.
+ */
+declare function mcpToolsToComponents(mcpClient: McpClientLike): Promise<ComponentDef[]>;
+
+export { type McpClientLike, type ServeMcpOptions, createMcpBridgeServer, mcpToolsToComponents, serveMcpFromAcp };

package/dist/index.js

@@ -0,0 +1,121 @@
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport as McpStdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { AcpError, AcpErrorCode } from "@xi-era/acp-sdk/client";
+import { componentIdToToolName, toolNameToComponentId, isValidComponentId } from "@xi-era/acp-sdk/client";
+import { AcpServer } from "@xi-era/acp-sdk/server";
+import { AcpClient as AcpClientImpl } from "@xi-era/acp-sdk/client";
+import { createMemoryClient } from "@xi-era/acp-sdk/server";
+function invokerFromClient(client) {
+  return {
+    discover: () => client.discover(),
+    call: (id, input) => client.call(id, input),
+    callConcatenated: async (id, input) => {
+      let text = "";
+      let binary = Buffer.alloc(0);
+      let sawBinary = false;
+      for await (const chunk of client.callStream(id, input)) {
+        if (chunk.bin === true) {
+          sawBinary = true;
+          binary = Buffer.concat([binary, Buffer.from(String(chunk.data), "base64")]);
+        } else if (typeof chunk.data === "string") {
+          text += chunk.data;
+        } else if (chunk.data !== null) {
+          text += JSON.stringify(chunk.data);
+        }
+      }
+      return sawBinary ? binary.toString("base64") : text;
+    }
+  };
+}
+function invokerFromServer(server) {
+  const client = new AcpClientImpl({ transport: createMemoryClient(server) });
+  return invokerFromClient(client);
+}
+function descriptorToMcpTool(d) {
+  return {
+    name: componentIdToToolName(d.id),
+    description: d.description,
+    inputSchema: d.inputSchema ?? { type: "object", properties: {}, required: [] }
+  };
+}
+function chunkDataToString(data) {
+  if (data === null || data === void 0) return "";
+  if (typeof data === "string") return data;
+  return JSON.stringify(data);
+}
+function createMcpBridgeServer(target, options = {}) {
+  const invoker = target instanceof AcpServer ? invokerFromServer(target) : invokerFromClient(target);
+  const mcpServer = new Server(
+    { name: options.name ?? "acp-bridge", version: options.version ?? "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+  mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
+    const descriptors = await invoker.discover();
+    return { tools: descriptors.map(descriptorToMcpTool) };
+  });
+  mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const componentId = toolNameToComponentId(name);
+    try {
+      let result;
+      try {
+        result = await invoker.call(componentId, args ?? null);
+      } catch (e) {
+        if (e instanceof AcpError && e.code === AcpErrorCode.STREAM_REQUIRED) {
+          result = await invoker.callConcatenated(componentId, args ?? null);
+        } else {
+          throw e;
+        }
+      }
+      return {
+        content: [{ type: "text", text: chunkDataToString(result) || JSON.stringify(result) }],
+        isError: false
+      };
+    } catch (e) {
+      const message = e instanceof AcpError ? `ACP error ${e.code}: ${e.message}` : e instanceof Error ? e.message : String(e);
+      return { content: [{ type: "text", text: message }], isError: true };
+    }
+  });
+  return mcpServer;
+}
+async function serveMcpFromAcp(target, options = {}) {
+  const mcpServer = createMcpBridgeServer(target, options);
+  await mcpServer.connect(new McpStdioServerTransport());
+}
+async function mcpToolsToComponents(mcpClient) {
+  const { tools } = await mcpClient.listTools();
+  return tools.map((tool) => {
+    const id = toolNameToComponentId(tool.name);
+    if (!isValidComponentId(id)) {
+      throw new Error(
+        `MCP tool name "${tool.name}" maps to invalid ACP component id "${id}" (spec \xA77.1)`
+      );
+    }
+    return {
+      id,
+      name: tool.name,
+      description: tool.description ?? tool.name,
+      version: "0.0.0",
+      inputSchema: tool.inputSchema,
+      stream: false,
+      meta: { viaMcpBridge: true },
+      handle: async (input) => {
+        const result = await mcpClient.callTool({ name: tool.name, arguments: input ?? {} });
+        const parts = result.content ?? [];
+        const text = parts.map((p) => p.type === "text" ? p.text ?? "" : JSON.stringify(p)).join("\n");
+        if (result.isError) {
+          throw new AcpError(AcpErrorCode.UPSTREAM_ERROR, text || "MCP tool error");
+        }
+        return { mcp: { content: parts }, text };
+      }
+    };
+  });
+}
+export {
+  createMcpBridgeServer,
+  mcpToolsToComponents,
+  serveMcpFromAcp
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * ACP <-> MCP bidirectional bridge (spec 附录 A).\n *\n * Direction 1 (ACP -> MCP): {@link serveMcpFromAcp} exposes an ACP server or\n * client as an MCP stdio server, mountable by Claude Desktop / Cursor etc.\n *\n * Direction 2 (MCP -> ACP): {@link mcpToolsToComponents} wraps an MCP client's\n * tools as ACP component definitions.\n */\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport as McpStdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { CallToolRequestSchema, ListToolsRequestSchema } from \"@modelcontextprotocol/sdk/types.js\";\nimport type { ComponentDescriptor } from \"@xi-era/acp-sdk/client\";\nimport type { AcpClient } from \"@xi-era/acp-sdk/client\";\nimport { AcpError, AcpErrorCode } from \"@xi-era/acp-sdk/client\";\nimport { componentIdToToolName, toolNameToComponentId, isValidComponentId } from \"@xi-era/acp-sdk/client\";\nimport type { ComponentDef } from \"@xi-era/acp-sdk/server\";\nimport { AcpServer } from \"@xi-era/acp-sdk/server\";\nimport { AcpClient as AcpClientImpl } from \"@xi-era/acp-sdk/client\";\nimport { createMemoryClient } from \"@xi-era/acp-sdk/server\";\n\n// ---------------------------------------------------------------------------\n// Internal unified invoker for either an in-process AcpServer or a remote client\n// ---------------------------------------------------------------------------\n\ninterface AcpInvoker {\n  discover(): Promise<ComponentDescriptor[]>;\n  call(componentId: string, input: unknown): Promise<unknown>;\n  /** Concatenates chunks (spec 附录 A: text concat / base64 concat) into one value. */\n  callConcatenated(componentId: string, input: unknown): Promise<unknown>;\n}\n\nfunction invokerFromClient(client: AcpClient): AcpInvoker {\n  return {\n    discover: () => client.discover(),\n    call: (id, input) => client.call(id, input),\n    callConcatenated: async (id, input) => {\n      let text = \"\";\n      let binary = Buffer.alloc(0);\n      let sawBinary = false;\n      for await (const chunk of client.callStream(id, input)) {\n        if (chunk.bin === true) {\n          sawBinary = true;\n          binary = Buffer.concat([binary, Buffer.from(String(chunk.data), \"base64\")]);\n        } else if (typeof chunk.data === \"string\") {\n          text += chunk.data;\n        } else if (chunk.data !== null) {\n          text += JSON.stringify(chunk.data);\n        }\n      }\n      return sawBinary ? binary.toString(\"base64\") : text;\n    },\n  };\n}\n\nfunction invokerFromServer(server: AcpServer): AcpInvoker {\n  const client = new AcpClientImpl({ transport: createMemoryClient(server) });\n  return invokerFromClient(client);\n}\n\n// ---------------------------------------------------------------------------\n// Direction 1: ACP -> MCP\n// ---------------------------------------------------------------------------\n\nexport interface ServeMcpOptions {\n  /** MCP server name advertised to clients; default \"acp-bridge\". */\n  name?: string;\n  /** MCP server version; default \"0.1.0\". */\n  version?: string;\n}\n\nfunction descriptorToMcpTool(d: ComponentDescriptor) {\n  return {\n    name: componentIdToToolName(d.id),\n    description: d.description,\n    inputSchema: d.inputSchema ?? { type: \"object\", properties: {}, required: [] },\n  };\n}\n\n/** Concatenates streamed chunks for MCP consumption (text concat / base64 concat). */\nfunction chunkDataToString(data: unknown): string {\n  if (data === null || data === undefined) return \"\";\n  if (typeof data === \"string\") return data;\n  return JSON.stringify(data);\n}\n\n/**\n * Builds the MCP server that exposes the target's ACP components as MCP tools.\n * tools/list <- discover; tools/call <- call (retrying with stream and\n * concatenating chunks when the component requires streaming).\n */\nexport function createMcpBridgeServer(\n  target: AcpServer | AcpClient,\n  options: ServeMcpOptions = {}\n): Server {\n  const invoker =\n    target instanceof AcpServer ? invokerFromServer(target) : invokerFromClient(target);\n\n  const mcpServer = new Server(\n    { name: options.name ?? \"acp-bridge\", version: options.version ?? \"0.1.0\" },\n    { capabilities: { tools: {} } }\n  );\n\n  mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {\n    const descriptors = await invoker.discover();\n    return { tools: descriptors.map(descriptorToMcpTool) };\n  });\n\n  mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {\n    const { name, arguments: args } = request.params;\n    const componentId = toolNameToComponentId(name);\n    try {\n      let result: unknown;\n      try {\n        result = await invoker.call(componentId, args ?? null);\n      } catch (e) {\n        if (e instanceof AcpError && e.code === AcpErrorCode.STREAM_REQUIRED) {\n          result = await invoker.callConcatenated(componentId, args ?? null);\n        } else {\n          throw e;\n        }\n      }\n      return {\n        content: [{ type: \"text\" as const, text: chunkDataToString(result) || JSON.stringify(result) }],\n        isError: false,\n      };\n    } catch (e) {\n      const message =\n        e instanceof AcpError\n          ? `ACP error ${e.code}: ${e.message}`\n          : e instanceof Error\n            ? e.message\n            : String(e);\n      return { content: [{ type: \"text\" as const, text: message }], isError: true };\n    }\n  });\n\n  return mcpServer;\n}\n\n/**\n * Serves {@link createMcpBridgeServer} over MCP stdio (Claude Desktop / Cursor).\n */\nexport async function serveMcpFromAcp(\n  target: AcpServer | AcpClient,\n  options: ServeMcpOptions = {}\n): Promise<void> {\n  const mcpServer = createMcpBridgeServer(target, options);\n  await mcpServer.connect(new McpStdioServerTransport());\n}\n\n// ---------------------------------------------------------------------------\n// Direction 2: MCP -> ACP\n// ---------------------------------------------------------------------------\n\n/** Minimal structural subset of the MCP Client class used by the bridge. */\nexport interface McpClientLike {\n  listTools(): Promise<{ tools: { name: string; description?: string; inputSchema?: object }[] }>;\n  callTool(request: { name: string; arguments?: unknown }): Promise<{\n    content?: { type: string; text?: string }[];\n    isError?: boolean;\n  }>;\n}\n\ninterface McpToolContentText {\n  type: string;\n  text?: string;\n}\n\n/**\n * Wraps an MCP client's tools as ACP component definitions. Tool names map\n * back via \"_\" -> \".\" (spec §7.1); names that do not form a valid\n * component_id are rejected with a clear error.\n */\nexport async function mcpToolsToComponents(\n  mcpClient: McpClientLike\n): Promise<ComponentDef[]> {\n  const { tools } = await mcpClient.listTools();\n  return tools.map((tool) => {\n    const id = toolNameToComponentId(tool.name);\n    if (!isValidComponentId(id)) {\n      throw new Error(\n        `MCP tool name \"${tool.name}\" maps to invalid ACP component id \"${id}\" (spec §7.1)`\n      );\n    }\n    return {\n      id,\n      name: tool.name,\n      description: tool.description ?? tool.name,\n      version: \"0.0.0\",\n      inputSchema: tool.inputSchema,\n      stream: false,\n      meta: { viaMcpBridge: true },\n      handle: async (input: unknown) => {\n        const result = await mcpClient.callTool({ name: tool.name, arguments: input ?? {} });\n        const parts: McpToolContentText[] = result.content ?? [];\n        const text = parts\n          .map((p) => (p.type === \"text\" ? (p.text ?? \"\") : JSON.stringify(p)))\n          .join(\"\\n\");\n        if (result.isError) {\n          throw new AcpError(AcpErrorCode.UPSTREAM_ERROR, text || \"MCP tool error\");\n        }\n        return { mcp: { content: parts }, text };\n      },\n    };\n  });\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@xi-era/acp-adapter-mcp",
+  "version": "0.1.0",
+  "description": "ACP (Agent-Component-Protocol) <-> MCP bidirectional bridge — expose ACP components as MCP tools for Claude/Cursor, and wrap MCP tools as ACP components.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "acp-mcp": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "acp",
+    "mcp",
+    "bridge",
+    "adapter",
+    "agent",
+    "iot"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xi-era/acp-protocol.git",
+    "directory": "packages/acp-adapter-mcp"
+  },
+  "homepage": "https://github.com/xi-era/acp-protocol",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@xi-era/acp-sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "tsup": "^8.3.0"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}