@aroha-sdk/mcp-bridge 1.0.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@aroha-sdk/mcp-bridge",
+  "version": "1.0.0",
+  "description": "Aroha ↔ MCP (Model Context Protocol) adapter",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@aroha-sdk/core": "^1.0.0",
+    "@aroha-sdk/registry": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0",
+    "@types/node": "^20.14.0"
+  }
+}

package/src/bridge.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect, vi } from "vitest";
+import { mcpToolsToArohaCapabilities, arohaAgentToMcpTools, type McpToolDefinition } from "./index.js";
+import type { DiscoveredAgent } from "@aroha-sdk/registry";
+import type { ArohaEnvelope, ArohaClient } from "@aroha-sdk/core";
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+
+ed.etc.sha512Sync = (...m: Parameters<typeof sha512>) => sha512(...m);
+
+function makeMcpTool(name: string, description = "A test tool"): McpToolDefinition {
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" } },
+      required: ["query"],
+    },
+  };
+}
+
+function makeDiscoveredAgent(): DiscoveredAgent {
+  return {
+    record: {
+      didHash: "0xtest-provider",
+      ownerAddress: "0xOwner",
+      manifestCID: "Qm123",
+      publicKeyB64: Buffer.alloc(32).toString("base64url"),
+      stakedWei: 1_000_000_000_000_000_000n,
+      reputationScore: 8000,
+      active: true,
+      registeredAt: Date.now() - 86400_000,
+      lastUpdatedAt: Date.now(),
+    },
+    manifest: {
+      aroha: "1.0",
+      did: "did:aroha:test-provider",
+      name: "Test Provider",
+      version: "1.0.0",
+      endpoint: "https://provider.example.com/aroha",
+      capabilities: [
+        {
+          id: "search-flights",
+          version: "1.0.0",
+          description: "Search for flights",
+          inputSchema: { type: "object", properties: { origin: { type: "string" } } },
+          outputSchema: { type: "object", properties: { flights: { type: "array" } } },
+          async: false,
+          maxResponseMs: 5000,
+          requiredTrustLevel: 1,
+          pricing: { model: "free" },
+          sagaRole: "none",
+        },
+        {
+          id: "book-flight",
+          version: "1.0.0",
+          description: "Book a flight",
+          inputSchema: { type: "object", properties: { flightId: { type: "string" } } },
+          outputSchema: { type: "object", properties: { booking: { type: "string" } } },
+          async: false,
+          maxResponseMs: 10000,
+          requiredTrustLevel: 2,
+          pricing: { model: "per-transaction", fee: "10.00" },
+          sagaRole: "participant",
+        },
+      ],
+      protocols: ["aroha/1.0"],
+      createdAt: new Date().toISOString(),
+      signature: "dummy-sig",
+    },
+    endpoint: "https://provider.example.com/aroha",
+    publicKey: new Uint8Array(32),
+  };
+}
+
+describe("mcpToolsToArohaCapabilities", () => {
+  it("converts MCP tools to Aroha capability definitions", () => {
+    const tools = [makeMcpTool("aroha_search_flights"), makeMcpTool("aroha_book_hotel")];
+    const caps = mcpToolsToArohaCapabilities(tools);
+
+    expect(caps).toHaveLength(2);
+    expect(caps[0].id).toBe("search-flights");
+    expect(caps[1].id).toBe("book-hotel");
+  });
+
+  it("sets correct default fields", () => {
+    const caps = mcpToolsToArohaCapabilities([makeMcpTool("aroha_do_thing", "Does the thing")]);
+    const cap = caps[0];
+    expect(cap.version).toBe("1.0.0");
+    expect(cap.async).toBe(false);
+    expect(cap.requiredTrustLevel).toBe(1);
+    expect(cap.pricing.model).toBe("free");
+    expect(cap.sagaRole).toBe("none");
+    expect(cap.description).toBe("Does the thing");
+  });
+
+  it("preserves the inputSchema", () => {
+    const tool = makeMcpTool("aroha_test");
+    const caps = mcpToolsToArohaCapabilities([tool]);
+    expect(caps[0].inputSchema).toEqual(tool.inputSchema);
+  });
+});
+
+describe("arohaAgentToMcpTools", () => {
+  it("produces one MCP tool per capability", async () => {
+    const priv = ed.utils.randomPrivateKey();
+    const agent = makeDiscoveredAgent();
+    const mockClient = { send: vi.fn(), stream: vi.fn(), fetchDIDDocument: vi.fn() } as unknown as ArohaClient;
+
+    const { tools } = arohaAgentToMcpTools(
+      agent,
+      "did:aroha:orchestrator",
+      priv,
+      mockClient,
+      "saga-test"
+    );
+
+    expect(tools).toHaveLength(2);
+    expect(tools[0].name).toBe("aroha_search_flights");
+    expect(tools[1].name).toBe("aroha_book_flight");
+  });
+
+  it("tool definitions include _aroha metadata", async () => {
+    const priv = ed.utils.randomPrivateKey();
+    const agent = makeDiscoveredAgent();
+    const mockClient = { send: vi.fn(), stream: vi.fn(), fetchDIDDocument: vi.fn() } as unknown as ArohaClient;
+
+    const { tools } = arohaAgentToMcpTools(
+      agent,
+      "did:aroha:orchestrator",
+      priv,
+      mockClient,
+      "saga-test"
+    );
+
+    expect(tools[0]._aroha?.agentDID).toBe("did:aroha:test-provider");
+    expect(tools[0]._aroha?.capabilityId).toBe("search-flights");
+  });
+
+  it("handleToolCall returns error for unknown tool", async () => {
+    const priv = ed.utils.randomPrivateKey();
+    const agent = makeDiscoveredAgent();
+    const mockClient = { send: vi.fn(), stream: vi.fn(), fetchDIDDocument: vi.fn() } as unknown as ArohaClient;
+
+    const { handleToolCall } = arohaAgentToMcpTools(
+      agent,
+      "did:aroha:orchestrator",
+      priv,
+      mockClient,
+      "saga-test"
+    );
+
+    const result = await handleToolCall("aroha_nonexistent", {});
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/Unknown tool/);
+  });
+
+  it("handleToolCall calls client.send and returns result", async () => {
+    const priv = ed.utils.randomPrivateKey();
+    const agent = makeDiscoveredAgent();
+
+    const mockResponse: Partial<ArohaEnvelope> = {
+      type: "ArohaResponse",
+      body: { capability: "search-flights", result: { flights: ["AA100"] } } as ArohaEnvelope["body"],
+    };
+
+    const mockClient = {
+      send: vi.fn().mockResolvedValue(mockResponse),
+      stream: vi.fn(),
+      fetchDIDDocument: vi.fn(),
+    } as unknown as ArohaClient;
+
+    const { handleToolCall } = arohaAgentToMcpTools(
+      agent,
+      "did:aroha:orchestrator",
+      priv,
+      mockClient,
+      "saga-test"
+    );
+
+    const result = await handleToolCall("aroha_search_flights", { origin: "JFK" });
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain("AA100");
+    expect(mockClient.send).toHaveBeenCalled();
+  });
+});

package/src/index.ts

@@ -0,0 +1,165 @@
+/**
+ * Aroha ↔ MCP Bridge
+ *
+ * Two directions:
+ *
+ *   toMcp()    — Wrap a discovered Aroha agent's capabilities as MCP tool definitions.
+ *                Claude Desktop / any MCP client can call them as normal tools.
+ *                The bridge transparently sends ArohaRequest messages under the hood.
+ *
+ *   fromMcp()  — Expose an MCP server's tools as a Aroha capability manifest.
+ *                Any Aroha orchestrator can discover and call the MCP server
+ *                without knowing it's MCP-backed.
+ *
+ * The bridge is purely an adapter — it translates formats.
+ * It adds no business logic and changes no message semantics.
+ */
+
+import {
+  buildEnvelope,
+  ArohaClient,
+  type ArohaEnvelope,
+} from "@aroha-sdk/core";
+import { type ArohaRequestBody, type ArohaReserveBody } from "@aroha-sdk/core";
+import { type DiscoveredAgent, type CapabilityDefinition } from "@aroha-sdk/registry";
+
+// ─── MCP Types (subset of the MCP spec we need) ───────────────────────────────
+
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  /** Aroha metadata — carried as an extension field */
+  _aroha?: {
+    agentDID: string;
+    capabilityId: string;
+    sagaRole: "none" | "participant";
+  };
+}
+
+export type McpToolCallResult = {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+};
+
+// ─── Aroha → MCP ───────────────────────────────────────────────────────────────
+
+/**
+ * Convert a discovered Aroha agent's capabilities into MCP tool definitions.
+ * Returns both the definitions (for registering with MCP) and a handler
+ * function that executes the tool call via Aroha.
+ */
+export function arohaAgentToMcpTools(
+  agent: DiscoveredAgent,
+  orchestratorDID: string,
+  orchestratorPrivateKey: Uint8Array,
+  client: ArohaClient,
+  correlationId: string
+): {
+  tools: McpToolDefinition[];
+  handleToolCall: (toolName: string, args: Record<string, unknown>) => Promise<McpToolCallResult>;
+} {
+  const tools: McpToolDefinition[] = agent.manifest.capabilities.map((cap) =>
+    capabilityToMcpTool(cap, agent.manifest.did)
+  );
+
+  const handleToolCall = async (
+    toolName: string,
+    args: Record<string, unknown>
+  ): Promise<McpToolCallResult> => {
+    const cap = agent.manifest.capabilities.find(
+      (c) => mcpToolName(c.id) === toolName
+    );
+    if (!cap) {
+      return { content: [{ type: "text", text: `Unknown tool: ${toolName}` }], isError: true };
+    }
+
+    try {
+      const body: ArohaRequestBody = { capability: cap.id, params: args };
+      const envelope = await buildEnvelope(
+        "ArohaRequest",
+        orchestratorDID,
+        agent.manifest.did,
+        body,
+        correlationId,
+        orchestratorPrivateKey
+      );
+
+      const response = await client.send(agent.endpoint, envelope);
+      if (!response) {
+        return { content: [{ type: "text", text: "Agent returned no response (async)" }] };
+      }
+
+      if (response.type === "ArohaError") {
+        const err = response.body as { message: string };
+        return { content: [{ type: "text", text: err.message }], isError: true };
+      }
+
+      const result = (response.body as { result: unknown }).result;
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: String(err) }], isError: true };
+    }
+  };
+
+  return { tools, handleToolCall };
+}
+
+// ─── MCP → Aroha ───────────────────────────────────────────────────────────────
+
+/**
+ * Convert MCP tool definitions into a Aroha capability manifest fragment.
+ * Use this to register an MCP server as a Aroha agent.
+ */
+export function mcpToolsToArohaCapabilities(
+  tools: McpToolDefinition[]
+): CapabilityDefinition[] {
+  return tools.map((tool) => ({
+    id: arohaCapabilityId(tool.name),
+    version: "1.0.0",
+    description: tool.description,
+    inputSchema: tool.inputSchema as Record<string, unknown>,
+    outputSchema: { type: "object", properties: { result: { type: "object" } } },
+    async: false,
+    maxResponseMs: 30_000,
+    requiredTrustLevel: 1,
+    pricing: { model: "free" },
+    sagaRole: "none",
+  }));
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function capabilityToMcpTool(
+  cap: CapabilityDefinition,
+  agentDID: string
+): McpToolDefinition {
+  return {
+    name: mcpToolName(cap.id),
+    description: cap.description ?? cap.id,
+    inputSchema: {
+      type: "object",
+      properties: (cap.inputSchema as { properties?: Record<string,unknown> })?.properties ?? {},
+      required: (cap.inputSchema as { required?: string[] })?.required,
+    },
+    _aroha: {
+      agentDID,
+      capabilityId: cap.id,
+      sagaRole: cap.sagaRole,
+    },
+  };
+}
+
+/** Convert a Aroha capability ID to a valid MCP tool name (snake_case). */
+function mcpToolName(capabilityId: string): string {
+  return `aroha_${capabilityId.replace(/-/g, "_")}`;
+}
+
+/** Convert an MCP tool name back to a Aroha capability ID. */
+function arohaCapabilityId(mcpName: string): string {
+  return mcpName.replace(/^aroha_/, "").replace(/_/g, "-");
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "composite": true, "outDir": "./dist", "rootDir": "./src" },
+  "references": [{ "path": "../aroha-core" }, { "path": "../aroha-registry" }],
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules"]
+}