@sage-protocol/openclaw-sage 0.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@sage-protocol/openclaw-sage",
+  "version": "0.1.0",
+  "description": "Sage MCP bridge plugin for OpenClaw — prompt libraries, skills, governance, and on-chain operations",
+  "main": "src/index.ts",
+  "type": "module",
+  "openclaw": {
+    "id": "sage-mcp",
+    "displayName": "Sage Protocol",
+    "description": "MCP bridge for Sage prompt libraries, skills, and governance"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx src/mcp-bridge.test.ts"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "tsx": "^4.19.0"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,172 @@
+import { Type } from "@sinclair/typebox";
+
+import { McpBridge, type McpToolDef } from "./mcp-bridge.js";
+
+/**
+ * Minimal type stubs for OpenClaw plugin API.
+ *
+ * OpenClaw's jiti runtime resolves "openclaw/plugin-sdk" at load time.
+ * These stubs keep the code compilable standalone.
+ */
+type PluginLogger = {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+};
+
+type PluginServiceContext = {
+  config: unknown;
+  workspaceDir?: string;
+  stateDir: string;
+  logger: PluginLogger;
+};
+
+type PluginApi = {
+  id: string;
+  name: string;
+  logger: PluginLogger;
+  registerTool: (tool: unknown, opts?: { name?: string; optional?: boolean }) => void;
+  registerService: (service: {
+    id: string;
+    start: (ctx: PluginServiceContext) => void | Promise<void>;
+    stop?: (ctx: PluginServiceContext) => void | Promise<void>;
+  }) => void;
+  on: (hook: string, handler: (...args: unknown[]) => void | Promise<void>) => void;
+};
+
+/**
+ * Convert an MCP JSON Schema inputSchema into a TypeBox object schema
+ * that OpenClaw's tool system accepts.
+ */
+function mcpSchemaToTypebox(inputSchema?: Record<string, unknown>) {
+  if (!inputSchema || typeof inputSchema !== "object") {
+    return Type.Object({});
+  }
+
+  const properties = (inputSchema.properties ?? {}) as Record<string, Record<string, unknown>>;
+  const required = new Set(
+    Array.isArray(inputSchema.required) ? (inputSchema.required as string[]) : [],
+  );
+
+  const fields: Record<string, unknown> = {};
+
+  for (const [key, prop] of Object.entries(properties)) {
+    const desc = typeof prop.description === "string" ? prop.description : undefined;
+    const opts = desc ? { description: desc } : {};
+
+    let field: unknown;
+    switch (prop.type) {
+      case "number":
+      case "integer":
+        field = Type.Number(opts);
+        break;
+      case "boolean":
+        field = Type.Boolean(opts);
+        break;
+      case "array":
+        field = Type.Array(Type.Unknown(), opts);
+        break;
+      case "object":
+        field = Type.Record(Type.String(), Type.Unknown(), opts);
+        break;
+      default:
+        field = Type.String(opts);
+    }
+
+    fields[key] = required.has(key) ? field : Type.Optional(field as any);
+  }
+
+  return Type.Object(fields as any, { additionalProperties: true });
+}
+
+function toToolResult(mcpResult: unknown) {
+  const result = mcpResult as {
+    content?: Array<{ type: string; text?: string }>;
+  } | null;
+
+  const text =
+    result?.content
+      ?.map((c) => c.text ?? "")
+      .filter(Boolean)
+      .join("\n") ?? JSON.stringify(mcpResult ?? {});
+
+  return {
+    content: [{ type: "text" as const, text }],
+    details: mcpResult,
+  };
+}
+
+// ── Plugin Definition ────────────────────────────────────────────────────────
+
+let bridge: McpBridge | null = null;
+
+const plugin = {
+  id: "sage-mcp",
+  name: "Sage Protocol",
+  version: "0.1.0",
+  description:
+    "Sage MCP tools for prompt libraries, skills, governance, and on-chain operations",
+
+  register(api: PluginApi) {
+    bridge = new McpBridge("sage", ["mcp", "start"]);
+
+    bridge.on("log", (line: string) => api.logger.info(`[sage-mcp] ${line}`));
+    bridge.on("error", (err: Error) => api.logger.error(`[sage-mcp] ${err.message}`));
+
+    api.registerService({
+      id: "sage-mcp-bridge",
+      start: async (ctx) => {
+        ctx.logger.info("Starting Sage MCP bridge...");
+        try {
+          await bridge!.start();
+          ctx.logger.info("Sage MCP bridge ready");
+
+          const tools = await bridge!.listTools();
+          ctx.logger.info(`Discovered ${tools.length} MCP tools`);
+
+          for (const tool of tools) {
+            registerMcpTool(api, tool);
+          }
+        } catch (err) {
+          ctx.logger.error(
+            `Failed to start MCP bridge: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      },
+      stop: async (ctx) => {
+        ctx.logger.info("Stopping Sage MCP bridge...");
+        await bridge?.stop();
+      },
+    });
+  },
+};
+
+function registerMcpTool(api: PluginApi, tool: McpToolDef) {
+  const name = `sage_${tool.name}`;
+  const schema = mcpSchemaToTypebox(tool.inputSchema);
+
+  api.registerTool(
+    {
+      name,
+      label: `Sage: ${tool.name}`,
+      description: tool.description ?? `Sage MCP tool: ${tool.name}`,
+      parameters: schema,
+      execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+        if (!bridge) {
+          return toToolResult({ error: "MCP bridge not initialized" });
+        }
+        try {
+          const result = await bridge.callTool(tool.name, params);
+          return toToolResult(result);
+        } catch (err) {
+          return toToolResult({
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    },
+    { name, optional: true },
+  );
+}
+
+export default plugin;

package/src/mcp-bridge.ts

@@ -0,0 +1,218 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { createInterface, type Interface as ReadlineInterface } from "node:readline";
+
+/** MCP tool definition returned by tools/list */
+export type McpToolDef = {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+};
+
+/** JSON-RPC request/response types */
+type JsonRpcRequest = {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+type JsonRpcResponse = {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+const MAX_RETRIES = 3;
+const RESTART_DELAY_MS = 1000;
+
+/**
+ * Lightweight MCP stdio client.
+ *
+ * Spawns a child process that speaks JSON-RPC over stdin/stdout (MCP stdio transport).
+ * Provides methods to list tools and call them.
+ */
+export class McpBridge extends EventEmitter {
+  private proc: ChildProcess | null = null;
+  private rl: ReadlineInterface | null = null;
+  private pending = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+  private ready = false;
+  private retries = 0;
+  private stopped = false;
+
+  constructor(
+    private command: string,
+    private args: string[],
+  ) {
+    super();
+  }
+
+  async start(): Promise<void> {
+    this.stopped = false;
+    await this.spawn();
+    await this.initialize();
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true;
+    this.ready = false;
+    this.rejectAll("Bridge stopped");
+    if (this.rl) {
+      this.rl.close();
+      this.rl = null;
+    }
+    if (this.proc) {
+      this.proc.kill("SIGTERM");
+      this.proc = null;
+    }
+  }
+
+  async listTools(): Promise<McpToolDef[]> {
+    const result = (await this.request("tools/list", {})) as { tools?: McpToolDef[] };
+    return result?.tools ?? [];
+  }
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+    const result = (await this.request("tools/call", { name, arguments: args })) as {
+      content?: Array<{ type: string; text?: string }>;
+      isError?: boolean;
+    };
+
+    if (result?.isError) {
+      const text = result.content?.map((c) => c.text ?? "").join("\n") ?? "MCP tool error";
+      throw new Error(text);
+    }
+
+    return result;
+  }
+
+  // ── private ──────────────────────────────────────────────────────────
+
+  private spawn(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(this.command, this.args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env },
+      });
+
+      proc.on("error", (err) => {
+        if (!this.stopped) {
+          this.handleCrash(err);
+        }
+      });
+
+      proc.on("exit", (code) => {
+        if (!this.stopped && code !== 0) {
+          this.handleCrash(new Error(`MCP process exited with code ${code}`));
+        }
+      });
+
+      if (!proc.stdout || !proc.stdin) {
+        reject(new Error("Failed to open stdio pipes for MCP process"));
+        return;
+      }
+
+      this.proc = proc;
+
+      this.rl = createInterface({ input: proc.stdout });
+      this.rl.on("line", (line) => this.handleLine(line));
+
+      if (proc.stderr) {
+        const errRl = createInterface({ input: proc.stderr });
+        errRl.on("line", (line) => this.emit("log", line));
+      }
+
+      resolve();
+    });
+  }
+
+  private async initialize(): Promise<void> {
+    const result = (await this.request("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "openclaw-sage-plugin", version: "0.1.0" },
+    })) as { serverInfo?: { name?: string } };
+
+    this.notify("notifications/initialized", {});
+    this.ready = true;
+    this.retries = 0;
+    this.emit("ready", result?.serverInfo);
+  }
+
+  private request(method: string, params: Record<string, unknown>): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      if (!this.proc?.stdin?.writable) {
+        reject(new Error("MCP process not running"));
+        return;
+      }
+
+      const id = randomUUID();
+      const req: JsonRpcRequest = { jsonrpc: "2.0", id, method, params };
+
+      this.pending.set(id, { resolve, reject });
+      this.proc.stdin.write(JSON.stringify(req) + "\n");
+    });
+  }
+
+  private notify(method: string, params: Record<string, unknown>): void {
+    if (!this.proc?.stdin?.writable) return;
+    const msg = { jsonrpc: "2.0", method, params };
+    this.proc.stdin.write(JSON.stringify(msg) + "\n");
+  }
+
+  private handleLine(line: string): void {
+    let msg: JsonRpcResponse;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+
+    if (!msg.id) return;
+
+    const id = String(msg.id);
+    const pending = this.pending.get(id);
+    if (!pending) return;
+
+    this.pending.delete(id);
+
+    if (msg.error) {
+      pending.reject(new Error(`MCP error ${msg.error.code}: ${msg.error.message}`));
+    } else {
+      pending.resolve(msg.result);
+    }
+  }
+
+  private async handleCrash(err: Error): Promise<void> {
+    this.ready = false;
+    this.rejectAll(`MCP process crashed: ${err.message}`);
+
+    if (this.retries >= MAX_RETRIES) {
+      this.emit("error", new Error(`MCP bridge failed after ${MAX_RETRIES} retries: ${err.message}`));
+      return;
+    }
+
+    this.retries++;
+    this.emit("log", `MCP process crashed, retry ${this.retries}/${MAX_RETRIES}...`);
+
+    await new Promise((r) => setTimeout(r, RESTART_DELAY_MS));
+
+    if (!this.stopped) {
+      try {
+        await this.spawn();
+        await this.initialize();
+      } catch (retryErr) {
+        this.handleCrash(retryErr instanceof Error ? retryErr : new Error(String(retryErr)));
+      }
+    }
+  }
+
+  private rejectAll(reason: string): void {
+    for (const [, { reject }] of this.pending) {
+      reject(new Error(reason));
+    }
+    this.pending.clear();
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}