@sundaeswap/sprinkles 0.6.0 → 0.7.0

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

@@ -0,0 +1,463 @@
+/**
+ * MCP adapter for Sprinkles actions.
+ *
+ * Provides:
+ * - TypeBox to JSON Schema conversion (typeboxToJsonSchema)
+ * - 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;
+}
+
+// ---------------------------------------------------------------------------
+// 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 inputSchema = typeboxToJsonSchema(action.inputSchema);
+
+    // Register the action as an MCP tool.
+    // The high-level McpServer.tool() API accepts:
+    //   tool(name, description, schema, handler)
+    server.tool(
+      action.name,
+      action.description,
+      inputSchema,
+      // 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;
+  }
+}

package/src/Sprinkle/actions/registry.ts

@@ -0,0 +1,97 @@
+/**
+ * Action registry for storing and retrieving registered actions.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import type { AnyAction } from "./types.js";
+
+/** Regex for valid kebab-case action names */
+const KEBAB_CASE_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/**
+ * Registry for managing actions registered on a Sprinkle app.
+ * Enforces name uniqueness and schema validation at registration time.
+ */
+export class ActionRegistry<S extends TSchema> {
+  private actions: Map<string, AnyAction<S>> = new Map();
+
+  /**
+   * Register an action with the registry.
+   *
+   * Validates:
+   * - Name is kebab-case (lowercase letters, digits, hyphens)
+   * - Name is unique within this registry
+   * - inputSchema and outputSchema are present
+   *
+   * @throws Error if validation fails
+   */
+  register(action: AnyAction<S>): void {
+    if (!KEBAB_CASE_REGEX.test(action.name)) {
+      throw new Error(
+        `Invalid action name "${action.name}": must be kebab-case (e.g. "my-action", "get-balance")`,
+      );
+    }
+
+    if (this.actions.has(action.name)) {
+      throw new Error(
+        `Action "${action.name}" is already registered. Action names must be unique.`,
+      );
+    }
+
+    if (!action.inputSchema) {
+      throw new Error(
+        `Action "${action.name}" is missing inputSchema. All actions must define an inputSchema.`,
+      );
+    }
+
+    if (!action.outputSchema) {
+      throw new Error(
+        `Action "${action.name}" is missing outputSchema. All actions must define an outputSchema.`,
+      );
+    }
+
+    this.actions.set(action.name, action);
+  }
+
+  /**
+   * Retrieve an action by name.
+   * @returns The action, or undefined if not registered
+   */
+  get(name: string): AnyAction<S> | undefined {
+    return this.actions.get(name);
+  }
+
+  /**
+   * Check if an action with the given name is registered.
+   */
+  has(name: string): boolean {
+    return this.actions.has(name);
+  }
+
+  /**
+   * List all registered actions.
+   */
+  list(): AnyAction<S>[] {
+    return Array.from(this.actions.values());
+  }
+
+  /**
+   * Group all registered actions by their category.
+   * Actions without a category are placed under "default".
+   */
+  listByCategory(): Map<string, AnyAction<S>[]> {
+    const result = new Map<string, AnyAction<S>[]>();
+
+    for (const action of this.actions.values()) {
+      const category = action.category ?? "default";
+      const bucket = result.get(category);
+      if (bucket) {
+        bucket.push(action);
+      } else {
+        result.set(category, [action]);
+      }
+    }
+
+    return result;
+  }
+}