@ryuhq/sdk 0.1.14 → 0.2.0

package/dist/mcp/server.d.cts

@@ -0,0 +1,126 @@
+import { McpStdioCommand } from './client.cjs';
+
+/**
+ * SDK MCP stdio server — exposes a set of SDK Runnables (and optional
+ * passthrough registrations from Ghost / Shadow) as MCP tools over stdio,
+ * so any MCP host can discover and call them.
+ *
+ * The server speaks the same JSON-RPC 2.0 / newline-delimited protocol as
+ * `apps/core/src/sidecar/mcp/client.rs` and as `client.ts` in this package.
+ *
+ * POLICY NOTE: this server does NOT implement tool-approval, permission grants,
+ * or any Gateway-level policy.  Approval stays in the chat layer; policy stays
+ * in the Gateway (per issue #86).  Callers must not route policy decisions
+ * through this server.
+ *
+ * ## Minimal Runnable contract
+ *
+ * The full `defineAgent / defineWorkflow / defineTool / defineSkill` authoring
+ * API is delivered by issue #205.  This unit only needs the *consume side*:
+ * an executable object with a name and a `run()` method.  Once #205 ships, its
+ * builders will produce objects that satisfy this same interface.
+ */
+
+/** JSON Schema fragment — enough to describe a tool's input arguments. */
+interface JsonSchema {
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    type?: string;
+    [key: string]: unknown;
+}
+/**
+ * The minimal executable Runnable interface consumed by this bridge.
+ *
+ * When #205 ships its `defineAgent / defineTool / ...` API, those builders must
+ * return objects that satisfy this interface so they plug straight in here
+ * without any adapter.
+ */
+interface SdkRunnable {
+    /** Human-readable description shown to MCP hosts. */
+    description?: string;
+    /** JSON Schema for the tool's input arguments. */
+    inputSchema?: JsonSchema;
+    /** Stable, unique tool name (no spaces; used as the MCP tool name). */
+    name: string;
+    /**
+     * Execute the runnable with the given arguments and return a result.
+     * The result is JSON-encoded into an MCP `text` content block.
+     */
+    run(args: unknown): Promise<unknown>;
+}
+/**
+ * A passthrough registration forwards `tools/list` + `tools/call` to a remote
+ * MCP server (e.g. Ghost at its stdio command, or Shadow at :3030).  The tools
+ * are re-advertised under their original names; calls are forwarded verbatim.
+ *
+ * This is the mechanism by which orphaned Ghost (29 computer-use tools) and
+ * Shadow (:3030 capture/search tools) can be advertised to any MCP host without
+ * embedding their implementation in the SDK.
+ */
+interface PassthroughRegistration {
+    /** Command descriptor for the upstream MCP stdio server. */
+    command: McpStdioCommand;
+    /** Label used in error messages (e.g. "ghost", "shadow"). */
+    label: string;
+}
+/**
+ * Unwrap an MCP `tools/call` content-block envelope back to a plain value.
+ * If the text is valid JSON it is parsed; otherwise the raw string is returned.
+ *
+ * This is exported so tests can verify that `decode(wrapContent(x))` round-trips
+ * back to `x` and that `client.callTool()` output matches a direct `run()`.
+ */
+declare function unwrapContent(raw: unknown): unknown;
+/**
+ * An MCP stdio server that exposes SDK Runnables and optional passthrough
+ * registrations as MCP tools.
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from "@ryuhq/sdk/mcp/server"
+ *
+ * const server = new McpServer()
+ *   .register({ name: "greet", run: (a) => Promise.resolve(`Hello!`) })
+ *
+ * await server.serve()  // reads stdin, writes stdout until EOF
+ * ```
+ */
+declare class McpServer {
+    private readonly runnables;
+    private readonly passthroughs;
+    /**
+     * Register an SDK Runnable as an MCP tool.
+     * Returns `this` for chaining.
+     */
+    register(runnable: SdkRunnable): this;
+    /**
+     * Register a passthrough to an external MCP stdio server (e.g. Ghost or
+     * Shadow).  Tools from that server are fetched lazily and re-advertised.
+     * Returns `this` for chaining.
+     */
+    passthrough(registration: PassthroughRegistration): this;
+    /** Fetch all tools: local Runnables + passthrough tools. */
+    private allTools;
+    /** Handle a `tools/call` request. */
+    private handleCallTool;
+    /**
+     * Handle a single parsed JSON-RPC request line. Returns the response to write
+     * (or null for notifications that require no response).
+     */
+    private handleRequest;
+    /** Handle a `tools/call` JSON-RPC request. */
+    private handleToolsCall;
+    /**
+     * Start reading JSON-RPC requests from the given readable stream and writing
+     * responses to the given writable stream.
+     *
+     * Defaults to `process.stdin` / `process.stdout`.  Passing explicit streams
+     * lets tests inject a pair of in-process pipes.
+     *
+     * Resolves when the input stream ends (EOF).
+     */
+    serve(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<void>;
+}
+
+export { type JsonSchema, McpServer, type PassthroughRegistration, type SdkRunnable, unwrapContent };

package/dist/mcp/server.d.ts

@@ -0,0 +1,126 @@
+import { McpStdioCommand } from './client.js';
+
+/**
+ * SDK MCP stdio server — exposes a set of SDK Runnables (and optional
+ * passthrough registrations from Ghost / Shadow) as MCP tools over stdio,
+ * so any MCP host can discover and call them.
+ *
+ * The server speaks the same JSON-RPC 2.0 / newline-delimited protocol as
+ * `apps/core/src/sidecar/mcp/client.rs` and as `client.ts` in this package.
+ *
+ * POLICY NOTE: this server does NOT implement tool-approval, permission grants,
+ * or any Gateway-level policy.  Approval stays in the chat layer; policy stays
+ * in the Gateway (per issue #86).  Callers must not route policy decisions
+ * through this server.
+ *
+ * ## Minimal Runnable contract
+ *
+ * The full `defineAgent / defineWorkflow / defineTool / defineSkill` authoring
+ * API is delivered by issue #205.  This unit only needs the *consume side*:
+ * an executable object with a name and a `run()` method.  Once #205 ships, its
+ * builders will produce objects that satisfy this same interface.
+ */
+
+/** JSON Schema fragment — enough to describe a tool's input arguments. */
+interface JsonSchema {
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    type?: string;
+    [key: string]: unknown;
+}
+/**
+ * The minimal executable Runnable interface consumed by this bridge.
+ *
+ * When #205 ships its `defineAgent / defineTool / ...` API, those builders must
+ * return objects that satisfy this interface so they plug straight in here
+ * without any adapter.
+ */
+interface SdkRunnable {
+    /** Human-readable description shown to MCP hosts. */
+    description?: string;
+    /** JSON Schema for the tool's input arguments. */
+    inputSchema?: JsonSchema;
+    /** Stable, unique tool name (no spaces; used as the MCP tool name). */
+    name: string;
+    /**
+     * Execute the runnable with the given arguments and return a result.
+     * The result is JSON-encoded into an MCP `text` content block.
+     */
+    run(args: unknown): Promise<unknown>;
+}
+/**
+ * A passthrough registration forwards `tools/list` + `tools/call` to a remote
+ * MCP server (e.g. Ghost at its stdio command, or Shadow at :3030).  The tools
+ * are re-advertised under their original names; calls are forwarded verbatim.
+ *
+ * This is the mechanism by which orphaned Ghost (29 computer-use tools) and
+ * Shadow (:3030 capture/search tools) can be advertised to any MCP host without
+ * embedding their implementation in the SDK.
+ */
+interface PassthroughRegistration {
+    /** Command descriptor for the upstream MCP stdio server. */
+    command: McpStdioCommand;
+    /** Label used in error messages (e.g. "ghost", "shadow"). */
+    label: string;
+}
+/**
+ * Unwrap an MCP `tools/call` content-block envelope back to a plain value.
+ * If the text is valid JSON it is parsed; otherwise the raw string is returned.
+ *
+ * This is exported so tests can verify that `decode(wrapContent(x))` round-trips
+ * back to `x` and that `client.callTool()` output matches a direct `run()`.
+ */
+declare function unwrapContent(raw: unknown): unknown;
+/**
+ * An MCP stdio server that exposes SDK Runnables and optional passthrough
+ * registrations as MCP tools.
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from "@ryuhq/sdk/mcp/server"
+ *
+ * const server = new McpServer()
+ *   .register({ name: "greet", run: (a) => Promise.resolve(`Hello!`) })
+ *
+ * await server.serve()  // reads stdin, writes stdout until EOF
+ * ```
+ */
+declare class McpServer {
+    private readonly runnables;
+    private readonly passthroughs;
+    /**
+     * Register an SDK Runnable as an MCP tool.
+     * Returns `this` for chaining.
+     */
+    register(runnable: SdkRunnable): this;
+    /**
+     * Register a passthrough to an external MCP stdio server (e.g. Ghost or
+     * Shadow).  Tools from that server are fetched lazily and re-advertised.
+     * Returns `this` for chaining.
+     */
+    passthrough(registration: PassthroughRegistration): this;
+    /** Fetch all tools: local Runnables + passthrough tools. */
+    private allTools;
+    /** Handle a `tools/call` request. */
+    private handleCallTool;
+    /**
+     * Handle a single parsed JSON-RPC request line. Returns the response to write
+     * (or null for notifications that require no response).
+     */
+    private handleRequest;
+    /** Handle a `tools/call` JSON-RPC request. */
+    private handleToolsCall;
+    /**
+     * Start reading JSON-RPC requests from the given readable stream and writing
+     * responses to the given writable stream.
+     *
+     * Defaults to `process.stdin` / `process.stdout`.  Passing explicit streams
+     * lets tests inject a pair of in-process pipes.
+     *
+     * Resolves when the input stream ends (EOF).
+     */
+    serve(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<void>;
+}
+
+export { type JsonSchema, McpServer, type PassthroughRegistration, type SdkRunnable, unwrapContent };

package/dist/mcp/server.js

@@ -0,0 +1,9 @@
+import {
+  McpServer,
+  unwrapContent
+} from "../chunk-FZSFZOIN.js";
+import "../chunk-VLIRNNAE.js";
+export {
+  McpServer,
+  unwrapContent
+};

package/dist/mcp.cjs

@@ -0,0 +1,376 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/mcp/index.ts
+var mcp_exports = {};
+__export(mcp_exports, {
+  MCP_PROTOCOL_VERSION: () => MCP_PROTOCOL_VERSION,
+  McpServer: () => McpServer,
+  callTool: () => callTool,
+  listTools: () => listTools,
+  unwrapContent: () => unwrapContent
+});
+module.exports = __toCommonJS(mcp_exports);
+
+// src/mcp/client.ts
+var import_node_child_process = require("child_process");
+var import_node_readline = require("readline");
+var MCP_PROTOCOL_VERSION = "2024-11-05";
+var RPC_TIMEOUT_MS = 6e4;
+var McpConnection = class _McpConnection {
+  proc;
+  nextId = 1;
+  closed = false;
+  waiters = [];
+  constructor(proc) {
+    this.proc = proc;
+  }
+  /** Spawn the server and complete the MCP `initialize` handshake. */
+  static async connect(cmd) {
+    const env = { ...process.env, ...cmd.env ?? {} };
+    const proc = (0, import_node_child_process.spawn)(cmd.command, cmd.args ?? [], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env
+    });
+    if (!(proc.stdin && proc.stdout)) {
+      proc.kill();
+      throw new Error(`MCP server '${cmd.command}' stdin/stdout unavailable`);
+    }
+    if (proc.stderr) {
+      proc.stderr.on("data", (chunk) => {
+        process.stderr.write(`[mcp-server] ${chunk.toString()}`);
+      });
+    }
+    const conn = new _McpConnection(proc);
+    const rl = (0, import_node_readline.createInterface)({
+      input: proc.stdout,
+      crlfDelay: Number.POSITIVE_INFINITY
+    });
+    rl.on("line", (rawLine) => {
+      const trimmed = rawLine.trim();
+      if (!trimmed) {
+        return;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        return;
+      }
+      if (parsed.id === void 0 || parsed.id === null) {
+        return;
+      }
+      const idx = conn.waiters.findIndex((w) => w.id === parsed.id);
+      if (idx === -1) {
+        return;
+      }
+      const [waiter] = conn.waiters.splice(idx, 1);
+      if (!waiter) {
+        return;
+      }
+      clearTimeout(waiter.timer);
+      if (parsed.error) {
+        waiter.reject(new Error(`MCP error: ${JSON.stringify(parsed.error)}`));
+      } else {
+        waiter.resolve(parsed.result ?? null);
+      }
+    });
+    rl.on("close", () => {
+      for (const waiter of conn.waiters.splice(0)) {
+        clearTimeout(waiter.timer);
+        waiter.reject(new Error("MCP server closed the connection"));
+      }
+    });
+    await conn.request("initialize", {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "ryu-sdk", version: "0.0.1" }
+    });
+    conn.notify("notifications/initialized", {});
+    return conn;
+  }
+  /** Send a JSON-RPC request and return the `result` field. */
+  request(method, params) {
+    const id = this.nextId++;
+    const frame = JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      method,
+      params
+    });
+    this.write(frame);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`MCP request '${method}' timed out`)),
+        RPC_TIMEOUT_MS
+      );
+      this.waiters.push({ id, resolve, reject, timer });
+    });
+  }
+  /** Send a JSON-RPC notification (no response expected). */
+  notify(method, params) {
+    const frame = JSON.stringify({ jsonrpc: "2.0", method, params });
+    this.write(frame);
+  }
+  write(frame) {
+    if (this.closed) {
+      return;
+    }
+    this.proc.stdin?.write(`${frame}
+`);
+  }
+  /** Graceful shutdown: close stdin, then kill. */
+  async shutdown() {
+    this.closed = true;
+    this.proc.stdin?.end();
+    await new Promise((resolve) => {
+      this.proc.once("exit", () => resolve());
+      this.proc.kill();
+      setTimeout(resolve, 500);
+    });
+  }
+};
+async function listTools(cmd) {
+  const conn = await McpConnection.connect(cmd);
+  let result;
+  try {
+    result = await conn.request("tools/list", {});
+  } finally {
+    await conn.shutdown();
+  }
+  const tools = result?.tools ?? [];
+  return tools.map((t) => {
+    const tool = t;
+    const name = tool.name;
+    if (typeof name !== "string") {
+      return null;
+    }
+    return {
+      name,
+      description: typeof tool.description === "string" ? tool.description : void 0,
+      inputSchema: tool.inputSchema
+    };
+  }).filter((t) => t !== null);
+}
+async function callTool(cmd, tool, args) {
+  const conn = await McpConnection.connect(cmd);
+  try {
+    return await conn.request("tools/call", { name: tool, arguments: args });
+  } finally {
+    await conn.shutdown();
+  }
+}
+
+// src/mcp/server.ts
+var import_node_readline2 = require("readline");
+function respond(id, result) {
+  return { jsonrpc: "2.0", id: id ?? null, result };
+}
+function respondError(id, code, message) {
+  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+}
+function wrapContent(value) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof value === "string" ? value : JSON.stringify(value)
+      }
+    ]
+  };
+}
+function unwrapContent(raw) {
+  const r = raw;
+  const text = r?.content?.[0]?.text;
+  if (text === void 0) {
+    return raw;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+var McpServer = class {
+  runnables = /* @__PURE__ */ new Map();
+  passthroughs = [];
+  /**
+   * Register an SDK Runnable as an MCP tool.
+   * Returns `this` for chaining.
+   */
+  register(runnable) {
+    this.runnables.set(runnable.name, runnable);
+    return this;
+  }
+  /**
+   * Register a passthrough to an external MCP stdio server (e.g. Ghost or
+   * Shadow).  Tools from that server are fetched lazily and re-advertised.
+   * Returns `this` for chaining.
+   */
+  passthrough(registration) {
+    this.passthroughs.push(registration);
+    return this;
+  }
+  /** Fetch all tools: local Runnables + passthrough tools. */
+  async allTools() {
+    const local = [...this.runnables.values()].map((r) => ({
+      name: r.name,
+      description: r.description,
+      inputSchema: r.inputSchema
+    }));
+    const remote = [];
+    for (const pt of this.passthroughs) {
+      try {
+        const tools = await listTools(pt.command);
+        remote.push(...tools);
+      } catch (err) {
+        process.stderr.write(
+          `[mcp-server] passthrough '${pt.label}' list_tools failed: ${err}
+`
+        );
+      }
+    }
+    return [...local, ...remote];
+  }
+  /** Handle a `tools/call` request. */
+  async handleCallTool(name, args) {
+    const local = this.runnables.get(name);
+    if (local) {
+      const result = await local.run(args);
+      return wrapContent(result);
+    }
+    for (const pt of this.passthroughs) {
+      try {
+        const tools = await listTools(pt.command);
+        if (tools.some((t) => t.name === name)) {
+          return await callTool(pt.command, name, args);
+        }
+      } catch {
+      }
+    }
+    throw new Error(`Unknown tool: ${name}`);
+  }
+  /**
+   * Handle a single parsed JSON-RPC request line. Returns the response to write
+   * (or null for notifications that require no response).
+   */
+  async handleRequest(req, initialized, write) {
+    const { id, method, params } = req;
+    if (method === "initialize") {
+      initialized.value = true;
+      write(
+        respond(id, {
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name: "ryu-sdk-server", version: "0.0.1" }
+        })
+      );
+      return;
+    }
+    if (method === "notifications/initialized") {
+      return;
+    }
+    if (!initialized.value) {
+      write(respondError(id, -32002, "Server not initialized"));
+      return;
+    }
+    if (method === "tools/list") {
+      try {
+        const tools = await this.allTools();
+        write(respond(id, { tools }));
+      } catch (err) {
+        write(respondError(id, -32603, String(err)));
+      }
+      return;
+    }
+    if (method === "tools/call") {
+      await this.handleToolsCall(id, params, write);
+      return;
+    }
+    write(respondError(id, -32601, `Method not found: ${method}`));
+  }
+  /** Handle a `tools/call` JSON-RPC request. */
+  async handleToolsCall(id, params, write) {
+    const p = params;
+    const toolName = p?.name;
+    const toolArgs = p?.arguments ?? {};
+    if (typeof toolName !== "string") {
+      write(respondError(id, -32602, "tools/call requires 'name'"));
+      return;
+    }
+    try {
+      const result = await this.handleCallTool(toolName, toolArgs);
+      write(respond(id, result));
+    } catch (err) {
+      write(
+        respond(id, {
+          content: [{ type: "text", text: String(err) }],
+          isError: true
+        })
+      );
+    }
+  }
+  /**
+   * Start reading JSON-RPC requests from the given readable stream and writing
+   * responses to the given writable stream.
+   *
+   * Defaults to `process.stdin` / `process.stdout`.  Passing explicit streams
+   * lets tests inject a pair of in-process pipes.
+   *
+   * Resolves when the input stream ends (EOF).
+   */
+  serve(input = process.stdin, output = process.stdout) {
+    const write = (obj) => {
+      output.write(`${JSON.stringify(obj)}
+`);
+    };
+    const initialized = { value: false };
+    return new Promise((resolve) => {
+      const rl = (0, import_node_readline2.createInterface)({
+        input,
+        crlfDelay: Number.POSITIVE_INFINITY
+      });
+      rl.on("line", (rawLine) => {
+        const line = rawLine.trim();
+        if (!line) {
+          return;
+        }
+        let req;
+        try {
+          req = JSON.parse(line);
+        } catch {
+          write(respondError(null, -32700, "Parse error"));
+          return;
+        }
+        this.handleRequest(req, initialized, write).catch((err) => {
+          write(respondError(req.id, -32603, String(err)));
+        });
+      });
+      rl.on("close", resolve);
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MCP_PROTOCOL_VERSION,
+  McpServer,
+  callTool,
+  listTools,
+  unwrapContent
+});

package/dist/mcp.d.cts

@@ -0,0 +1,2 @@
+export { MCP_PROTOCOL_VERSION, McpStdioCommand, McpTool, callTool, listTools } from './mcp/client.cjs';
+export { JsonSchema, McpServer, PassthroughRegistration, SdkRunnable, unwrapContent } from './mcp/server.cjs';

package/dist/mcp.d.ts

@@ -0,0 +1,2 @@
+export { MCP_PROTOCOL_VERSION, McpStdioCommand, McpTool, callTool, listTools } from './mcp/client.js';
+export { JsonSchema, McpServer, PassthroughRegistration, SdkRunnable, unwrapContent } from './mcp/server.js';

package/dist/mcp.js

@@ -0,0 +1,17 @@
+import "./chunk-TXSHHZF2.js";
+import {
+  McpServer,
+  unwrapContent
+} from "./chunk-FZSFZOIN.js";
+import {
+  MCP_PROTOCOL_VERSION,
+  callTool,
+  listTools
+} from "./chunk-VLIRNNAE.js";
+export {
+  MCP_PROTOCOL_VERSION,
+  McpServer,
+  callTool,
+  listTools,
+  unwrapContent
+};