@sundaeswap/sprinkles 0.6.1 → 0.8.0

package/src/Sprinkle/actions/mcp-adapter.ts

@@ -0,0 +1,638 @@
+/**
+ * MCP adapter for Sprinkles actions.
+ *
+ * Provides:
+ * - TypeBox to JSON Schema conversion (typeboxToJsonSchema)
+ * - TypeBox to Zod conversion for MCP SDK compatibility (typeboxToZod)
+ * - BigInt string coercion for MCP input (coerceMcpInput)
+ * - Lazy MCP SDK import with graceful error (getMcpSdk)
+ * - MCP server creation from registered actions (createMcpServer)
+ * - MCP orchestrator that starts a stdio server (runMcp)
+ */
+
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+import type { TSchema } from "@sinclair/typebox";
+import { bigIntReplacer } from "../encryption.js";
+import {
+  isArray,
+  isBigInt,
+  isBoolean,
+  isInteger,
+  isLiteral,
+  isNull,
+  isNumber,
+  isObject,
+  isOptional,
+  isString,
+  isUnion,
+  isSensitive,
+} from "../type-guards.js";
+import type { AnyAction } from "./types.js";
+import { executeAction } from "./runner.js";
+
+// Re-import Sprinkle as a type only to avoid circular deps
+import type { Sprinkle } from "../index.js";
+
+// Load package version for MCP server identification
+// Robustly find package.json - works from both src and dist directories
+function loadPackageVersion(): string {
+  const require = createRequire(import.meta.url);
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  
+  // Try multiple possible paths (handles src vs dist/esm vs dist/cjs)
+  const candidates = [
+    resolve(__dirname, "../../../package.json"),     // from src/Sprinkle/actions
+    resolve(__dirname, "../../../../package.json"),  // from dist/*/Sprinkle/actions
+  ];
+  
+  for (const candidate of candidates) {
+    try {
+      const pkg = require(candidate) as { version: string };
+      return pkg.version;
+    } catch {
+      // Try next candidate
+    }
+  }
+  
+  return "0.0.0"; // Fallback if package.json not found
+}
+
+const PACKAGE_VERSION: string = loadPackageVersion();
+
+// ---------------------------------------------------------------------------
+// TypeBox to JSON Schema conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a TypeBox schema to a plain JSON Schema object.
+ *
+ * Strips TypeBox-internal symbols and properties (Kind, OptionalKind, $id)
+ * and maps TypeBox-specific types to their JSON Schema equivalents:
+ * - BigInt -> { type: "string", pattern: "^-?[0-9]+$" } (JSON has no BigInt)
+ * - Sensitive string fields -> add writeOnly: true
+ * - Optional -> recurse on inner schema (Optional does not change Kind)
+ * - Union -> { anyOf: [...] }
+ * - Literal -> { type, const }
+ * - Null -> { type: "null" }
+ * - Unknown/unsupported -> {} (accepts anything)
+ */
+export function typeboxToJsonSchema(schema: TSchema): Record<string, unknown> {
+  // Optional in TypeBox doesn't change the Kind, but marks the schema with
+  // OptionalKind. We can check for it and recurse transparently since all
+  // other guards still work correctly on optional-wrapped schemas.
+  //
+  // We intentionally do NOT strip optional here -- the containing Object
+  // converter decides whether to include a property in `required` based
+  // on the isOptional guard applied to the property schema.
+
+  if (isBigInt(schema)) {
+    return {
+      type: "string",
+      pattern: "^-?[0-9]+$",
+      description: "BigInt value as string",
+    };
+  }
+
+  if (isString(schema)) {
+    const result: Record<string, unknown> = { type: "string" };
+    if (schema.description !== undefined) result.description = schema.description;
+    if (schema.title !== undefined) result.title = schema.title;
+    if (schema.examples !== undefined) result.examples = schema.examples;
+    if (schema.pattern !== undefined) result.pattern = schema.pattern;
+    if (schema.minLength !== undefined) result.minLength = schema.minLength;
+    if (schema.maxLength !== undefined) result.maxLength = schema.maxLength;
+    if (schema.default !== undefined) result.default = schema.default;
+    // Sensitive fields are write-only (never returned in responses)
+    if (isSensitive(schema)) result.writeOnly = true;
+    return result;
+  }
+
+  if (isNumber(schema)) {
+    const result: Record<string, unknown> = { type: "number" };
+    if (schema.minimum !== undefined) result.minimum = schema.minimum;
+    if (schema.maximum !== undefined) result.maximum = schema.maximum;
+    if (schema.description !== undefined) result.description = schema.description;
+    if (schema.default !== undefined) result.default = schema.default;
+    return result;
+  }
+
+  if (isInteger(schema)) {
+    const result: Record<string, unknown> = { type: "integer" };
+    if (schema.minimum !== undefined) result.minimum = schema.minimum;
+    if (schema.maximum !== undefined) result.maximum = schema.maximum;
+    if (schema.description !== undefined) result.description = schema.description;
+    if (schema.default !== undefined) result.default = schema.default;
+    return result;
+  }
+
+  if (isBoolean(schema)) {
+    const result: Record<string, unknown> = { type: "boolean" };
+    if (schema.description !== undefined) result.description = schema.description;
+    if (schema.default !== undefined) result.default = schema.default;
+    return result;
+  }
+
+  if (isNull(schema)) {
+    return { type: "null" };
+  }
+
+  if (isArray(schema)) {
+    const result: Record<string, unknown> = { type: "array" };
+    const itemSchema = (schema as { items?: TSchema }).items;
+    if (itemSchema) {
+      result.items = typeboxToJsonSchema(itemSchema);
+    }
+    if (schema.minItems !== undefined) result.minItems = schema.minItems;
+    if (schema.maxItems !== undefined) result.maxItems = schema.maxItems;
+    if (schema.description !== undefined) result.description = schema.description;
+    return result;
+  }
+
+  if (isObject(schema)) {
+    const properties = schema.properties as Record<string, TSchema>;
+    const required: string[] = schema.required as string[] ?? [];
+    const convertedProperties: Record<string, unknown> = {};
+
+    for (const [propName, propSchema] of Object.entries(properties)) {
+      convertedProperties[propName] = typeboxToJsonSchema(propSchema);
+    }
+
+    const result: Record<string, unknown> = {
+      type: "object",
+      properties: convertedProperties,
+    };
+
+    if (required.length > 0) {
+      result.required = required;
+    }
+
+    if (schema.description !== undefined) result.description = schema.description;
+
+    return result;
+  }
+
+  if (isUnion(schema)) {
+    return {
+      anyOf: schema.anyOf.map((member: TSchema) => typeboxToJsonSchema(member)),
+    };
+  }
+
+  if (isLiteral(schema)) {
+    const value = schema.const;
+    let type: string;
+    if (typeof value === "string") {
+      type = "string";
+    } else if (typeof value === "number") {
+      type = "number";
+    } else if (typeof value === "boolean") {
+      type = "boolean";
+    } else {
+      // Fallback for unexpected literal types
+      return {};
+    }
+    return { type, const: value };
+  }
+
+  // Unknown / unsupported TypeBox type: emit empty schema (accepts anything)
+  // This is a safe fallback that allows the MCP tool to still receive input.
+  console.warn(
+    `[mcp-adapter] Unsupported TypeBox kind: ${(schema as Record<string, unknown>)["[Kind]"] ?? "(unknown)"}. Emitting empty schema.`,
+  );
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Input coercion: BigInt string -> BigInt
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce MCP JSON input values to the types expected by a TypeBox schema.
+ *
+ * MCP transmits all values as JSON, which has no BigInt type. When the schema
+ * expects a BigInt, the value arrives as a numeric string (e.g. "12345678").
+ * This function recursively walks the schema and input, converting BigInt
+ * string values to actual BigInt where needed.
+ *
+ * For all other types the value is passed through unchanged.
+ */
+export function coerceMcpInput(input: unknown, schema: TSchema): unknown {
+  if (input === null || input === undefined) return input;
+
+  if (isBigInt(schema)) {
+    if (typeof input === "bigint") return input;
+    if (typeof input === "string" && /^-?[0-9]+$/.test(input)) {
+      try {
+        return BigInt(input);
+      } catch {
+        return input;
+      }
+    }
+    if (typeof input === "number") {
+      try {
+        return BigInt(Math.trunc(input));
+      } catch {
+        return input;
+      }
+    }
+    return input;
+  }
+
+  if (isArray(schema)) {
+    const itemSchema = (schema as { items?: TSchema }).items;
+    if (Array.isArray(input) && itemSchema) {
+      return input.map((item) => coerceMcpInput(item, itemSchema));
+    }
+    return input;
+  }
+
+  if (isObject(schema)) {
+    if (typeof input !== "object" || Array.isArray(input)) return input;
+    const properties = schema.properties as Record<string, TSchema>;
+    const result: Record<string, unknown> = { ...(input as Record<string, unknown>) };
+    for (const [propName, propSchema] of Object.entries(properties)) {
+      if (propName in result) {
+        result[propName] = coerceMcpInput(result[propName], propSchema);
+      }
+    }
+    return result;
+  }
+
+  if (isUnion(schema)) {
+    // For unions, we try each member schema in order and return the first
+    // successful coercion. BigInt members take priority over string members
+    // since they have a narrower, unambiguous pattern.
+    for (const member of schema.anyOf) {
+      if (isBigInt(member)) {
+        if (typeof input === "string" && /^-?[0-9]+$/.test(input)) {
+          return coerceMcpInput(input, member);
+        }
+      }
+    }
+    // No BigInt match; return as-is for other union members
+    return input;
+  }
+
+  // For all other types (String, Number, Integer, Boolean, Literal, Null):
+  // pass through unchanged -- MCP JSON already represents them correctly
+  return input;
+}
+
+// ---------------------------------------------------------------------------
+// TypeBox to Zod conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * Zod module shape (the parts we use from zod).
+ * Typed loosely since zod is a transitive dependency of @modelcontextprotocol/sdk,
+ * not a direct dependency of Sprinkles.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ZodType = any;
+interface IZodModule {
+  string: () => ZodType;
+  number: () => ZodType;
+  boolean: () => ZodType;
+  literal: (value: unknown) => ZodType;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  object: (shape: Record<string, any>) => ZodType;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  array: (item: any) => ZodType;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  union: (members: any[]) => ZodType;
+  nullType: () => ZodType;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any: () => any;
+}
+
+let _zod: IZodModule | undefined;
+
+/**
+ * Lazily import the Zod module.
+ * Zod is a transitive dependency of @modelcontextprotocol/sdk, so it's
+ * guaranteed to be available when MCP mode is used.
+ */
+async function getZod(): Promise<IZodModule> {
+  if (_zod) return _zod;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mod = (await import("zod")) as any;
+    _zod = {
+      string: () => mod.string(),
+      number: () => mod.number(),
+      boolean: () => mod.boolean(),
+      literal: (v: unknown) => mod.literal(v),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      object: (shape: Record<string, any>) => mod.object(shape),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      array: (item: any) => mod.array(item),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      union: (members: any[]) => mod.union(members),
+      nullType: () => mod.nullType(),
+      any: () => mod.any(),
+    };
+    return _zod;
+  } catch {
+    throw new Error(
+      "MCP mode requires zod (via @modelcontextprotocol/sdk). Install @modelcontextprotocol/sdk.",
+    );
+  }
+}
+
+/**
+ * Convert a TypeBox schema to a Zod schema for MCP SDK compatibility.
+ *
+ * The MCP SDK (v1.27+) expects Zod schemas for tool input validation,
+ * not plain JSON Schema objects. This function converts TypeBox schemas
+ * to their Zod equivalents so the SDK correctly registers tool parameters.
+ *
+ * BigInt fields are represented as z.string() with a regex pattern since
+ * JSON (and thus MCP) has no BigInt type. The coerceMcpInput function
+ * handles converting these string values back to BigInt at call time.
+ */
+export async function typeboxToZod(schema: TSchema): Promise<ZodType> {
+  const z = await getZod();
+  return _typeboxToZod(schema, z);
+}
+
+function _typeboxToZod(schema: TSchema, z: IZodModule): ZodType {
+  if (isBigInt(schema)) {
+    // BigInt -> string with regex pattern (JSON has no BigInt)
+    return z.string().regex(/^-?[0-9]+$/);
+  }
+
+  if (isString(schema)) {
+    let s = z.string();
+    if (schema.description) s = s.describe(schema.description);
+    return s;
+  }
+
+  if (isNumber(schema) || isInteger(schema)) {
+    let n = z.number();
+    if (schema.description) n = n.describe(schema.description);
+    return n;
+  }
+
+  if (isBoolean(schema)) {
+    let b = z.boolean();
+    if (schema.description) b = b.describe(schema.description);
+    return b;
+  }
+
+  if (isNull(schema)) {
+    return z.nullType();
+  }
+
+  if (isLiteral(schema)) {
+    return z.literal(schema.const);
+  }
+
+  if (isArray(schema)) {
+    const itemSchema = (schema as { items?: TSchema }).items;
+    if (itemSchema) {
+      return z.array(_typeboxToZod(itemSchema, z));
+    }
+    return z.array(z.any());
+  }
+
+  if (isObject(schema)) {
+    const properties = schema.properties as Record<string, TSchema>;
+    const shape: Record<string, ZodType> = {};
+
+    for (const [propName, propSchema] of Object.entries(properties)) {
+      let zodProp = _typeboxToZod(propSchema, z);
+      if (isOptional(propSchema)) {
+        zodProp = zodProp.optional();
+      }
+      shape[propName] = zodProp;
+    }
+
+    return z.object(shape);
+  }
+
+  if (isUnion(schema)) {
+    const members = schema.anyOf.map((member: TSchema) =>
+      _typeboxToZod(member, z),
+    );
+    if (members.length >= 2) {
+      return z.union(members);
+    }
+    return members[0] ?? z.any();
+  }
+
+  // Fallback: accept anything
+  return z.any();
+}
+
+/**
+ * Convert a TypeBox object schema to a Zod "raw shape" (Record<string, ZodType>).
+ * This is the format expected by the MCP SDK's tool() API.
+ */
+export async function typeboxToZodShape(
+  schema: TSchema,
+): Promise<Record<string, ZodType>> {
+  const z = await getZod();
+
+  if (!isObject(schema)) {
+    // Non-object input schemas get wrapped as { input: zodSchema }
+    return { input: _typeboxToZod(schema, z) };
+  }
+
+  const properties = schema.properties as Record<string, TSchema>;
+  const shape: Record<string, ZodType> = {};
+
+  for (const [propName, propSchema] of Object.entries(properties)) {
+    let zodProp = _typeboxToZod(propSchema, z);
+    if (isOptional(propSchema)) {
+      zodProp = zodProp.optional();
+    }
+    shape[propName] = zodProp;
+  }
+
+  return shape;
+}
+
+// ---------------------------------------------------------------------------
+// Lazy MCP SDK import
+// ---------------------------------------------------------------------------
+
+/**
+ * MCP SDK module shape (the parts we use from @modelcontextprotocol/sdk).
+ * Typed loosely to avoid a hard dependency at compile time.
+ */
+interface IMcpSdkModule {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  McpServer: new (opts: { name: string; version: string }) => any;
+}
+
+interface IStdioTransportModule {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  StdioServerTransport: new () => any;
+}
+
+/**
+ * Lazily import the MCP SDK server module.
+ *
+ * Throws a clear, actionable error if the SDK is not installed, rather than
+ * a cryptic "Cannot find module" Node error.
+ */
+export async function getMcpSdk(): Promise<IMcpSdkModule> {
+  try {
+    return (await import(
+      "@modelcontextprotocol/sdk/server/mcp.js"
+    )) as IMcpSdkModule;
+  } catch {
+    throw new Error(
+      "MCP mode requires @modelcontextprotocol/sdk. Install it with: npm install @modelcontextprotocol/sdk",
+    );
+  }
+}
+
+/**
+ * Lazily import the MCP SDK stdio transport module.
+ */
+async function getMcpStdioTransport(): Promise<IStdioTransportModule> {
+  try {
+    return (await import(
+      "@modelcontextprotocol/sdk/server/stdio.js"
+    )) as IStdioTransportModule;
+  } catch {
+    throw new Error(
+      "MCP mode requires @modelcontextprotocol/sdk. Install it with: npm install @modelcontextprotocol/sdk",
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MCP server creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an MCP server and register all actions from a Sprinkle instance as
+ * MCP tools.
+ *
+ * Each action becomes a tool with:
+ * - name: action.name
+ * - description: action.description
+ * - input schema: typeboxToJsonSchema(action.inputSchema)
+ * - handler: coerces input, executes action, returns JSON result
+ *
+ * The Sprinkle instance must already be initialized with a profile before
+ * this function is called.
+ *
+ * @param sprinkle   - Fully-initialized Sprinkle instance
+ * @param serverName - Name to use for the MCP server
+ * @returns          The configured McpServer instance (not yet connected)
+ */
+export async function createMcpServer<S extends TSchema>(
+  sprinkle: Sprinkle<S>,
+  serverName: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Promise<any> {
+  const { McpServer } = await getMcpSdk();
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const server = new McpServer({ name: serverName, version: PACKAGE_VERSION });
+
+  const actions = sprinkle.listActions() as AnyAction<S>[];
+
+  for (const action of actions) {
+    const zodShape = await typeboxToZodShape(action.inputSchema);
+
+    // Register the action as an MCP tool.
+    // The high-level McpServer.tool() API accepts a Zod raw shape
+    // (Record<string, ZodType>) for input validation.
+    server.tool(
+      action.name,
+      action.description,
+      zodShape,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      async (input: unknown): Promise<any> => {
+        const coercedInput = coerceMcpInput(input, action.inputSchema);
+
+        const context = {
+          sprinkle,
+          settings: sprinkle.settings,
+        };
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = await executeAction(action as any, coercedInput, context as any);
+
+        if (result.success) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result.data, bigIntReplacer),
+              },
+            ],
+          };
+        } else {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    error: {
+                      code: result.error.code,
+                      message: result.error.message,
+                      details: result.error.details,
+                    },
+                  },
+                  bigIntReplacer,
+                ),
+              },
+            ],
+            isError: true,
+          };
+        }
+      },
+    );
+  }
+
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// MCP orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Start an MCP server on stdio transport.
+ *
+ * This function:
+ * 1. Creates the MCP server and registers all actions as tools
+ * 2. Creates a StdioServerTransport
+ * 3. Connects the server to the transport
+ *
+ * IMPORTANT: All logging in this function goes to stderr. stdout is reserved
+ * for the MCP protocol messages.
+ *
+ * The Sprinkle instance must already be initialized with a profile. Profile
+ * initialization is the responsibility of the caller (Sprinkle.Run()).
+ *
+ * @param sprinkle   - Fully-initialized Sprinkle instance
+ * @param serverName - Name to use for the MCP server
+ */
+export async function runMcp<S extends TSchema>(
+  sprinkle: Sprinkle<S>,
+  serverName: string,
+): Promise<void> {
+  const { StdioServerTransport } = await getMcpStdioTransport();
+
+  const server = await createMcpServer(sprinkle, serverName);
+  const transport = new StdioServerTransport();
+
+  try {
+    await server.connect(transport);
+  } catch (err) {
+    // Log errors to stderr only -- stdout is the MCP transport channel
+    process.stderr.write(
+      `[sprinkle-mcp] Failed to start MCP server: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    throw err;
+  }
+}