@vllnt/convex-helpers 0.1.0-canary.1e0f54a

package/src/mcp/tools/register.ts

@@ -0,0 +1,256 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { z } from "zod";
+
+import type { ConvexClient } from "../types.js";
+import { convexArgsToZod as convexArgumentsToZod } from "../validators.js";
+
+import type {
+  CallContext,
+  LifecycleHooks,
+  OnCallResult,
+  ToolDef,
+} from "./types.js";
+
+type PreparedTool = {
+  description: string;
+  name: string;
+  toolDef: ToolDef;
+  zodShape: Record<string, z.ZodTypeAny>;
+};
+
+/**
+ * Underscore-prefixed arg keys are reserved for framework-injected context.
+ *
+ * - Request args containing `_*` keys are rejected before hook invocation.
+ * - Tool-level Convex validators MAY declare `_*` fields so the action
+ *   handler receives server-injected values; these are stripped from the
+ *   published JSON Schema so MCP clients neither see nor pass them.
+ */
+function isReservedKey(key: string): boolean {
+  return key.startsWith("_");
+}
+
+function stripReservedFromShape(
+  shape: Record<string, z.ZodTypeAny>,
+): Record<string, z.ZodTypeAny> {
+  const filtered: Record<string, z.ZodTypeAny> = {};
+  for (const [key, value] of Object.entries(shape)) {
+    if (!isReservedKey(key)) {
+      filtered[key] = value;
+    }
+  }
+  return filtered;
+}
+
+export function prepareTools(tools: Record<string, ToolDef>): PreparedTool[] {
+  return Object.entries(tools).map(([name, toolDef]) => {
+    const zodSchema = toolDef.args
+      ? convexArgumentsToZod(toolDef.args)
+      : undefined;
+    const fullShape = zodSchema?.shape ?? {};
+    return {
+      description: toolDef.description ?? "",
+      name,
+      toolDef,
+      zodShape: stripReservedFromShape(fullShape),
+    };
+  });
+}
+
+/**
+ * Returns tools whose top-level args contain reserved `_*` keys.
+ *
+ * Used by `createMCPServer` at construction to surface a footgun: a tool that
+ * declares `_*` args without an `onToolCall` hook will have those args stripped
+ * from the published schema and never injected, so every dispatched call will
+ * fail Convex's own validator with "missing required arg".
+ */
+export function findToolsWithReservedArgs(
+  tools: Record<string, ToolDef>,
+): Map<string, string[]> {
+  const result = new Map<string, string[]>();
+  for (const [name, toolDef] of Object.entries(tools)) {
+    if (toolDef.args?.kind !== "object" || !toolDef.args.fields) continue;
+    const reserved = Object.keys(toolDef.args.fields).filter(isReservedKey);
+    if (reserved.length > 0) result.set(name, reserved);
+  }
+  return result;
+}
+
+async function invokeHook(
+  hooks: LifecycleHooks | undefined,
+  ctx: CallContext,
+  toolDef: ToolDef,
+): Promise<OnCallResult | undefined> {
+  try {
+    if (ctx.phase === "error" && toolDef.onError) {
+      const result = await toolDef.onError(
+        ctx as CallContext & { phase: "error" },
+      );
+      return result ?? undefined;
+    }
+    if (hooks?.onToolCall) {
+      const result = await hooks.onToolCall(ctx);
+      return result ?? undefined;
+    }
+    return;
+  } catch (hookError) {
+    console.error("[convex-mcp] hook error (swallowed)", {
+      error: hookError,
+      phase: ctx.phase,
+      requestId: ctx.requestId,
+      tool: ctx.toolName,
+    });
+    return;
+  }
+}
+
+function executeWithTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number | undefined,
+): Promise<T> {
+  if (!timeoutMs) return promise;
+
+  let handle: ReturnType<typeof setTimeout>;
+  return Promise.race([
+    promise.finally(() => {
+      clearTimeout(handle);
+    }),
+    new Promise<never>((_, reject) => {
+      handle = setTimeout(() => {
+        reject(new Error("Tool execution timed out"));
+      }, timeoutMs);
+    }),
+  ]);
+}
+
+export function registerTools(
+  mcpServer: McpServer,
+  client: ConvexClient,
+  tools: PreparedTool[],
+  hooks: LifecycleHooks | undefined,
+  requestId: string,
+  apiKey: string | undefined,
+): void {
+  for (const { description, name, toolDef, zodShape } of tools) {
+    mcpServer.tool(
+      name,
+      description,
+      zodShape,
+      async (arguments_: Record<string, unknown>) => {
+        const startedAt = Date.now();
+        const { onError: _onError, ref: _ref, ...safeDef } = toolDef;
+
+        const reservedKeys = Object.keys(arguments_).filter(isReservedKey);
+        if (reservedKeys.length > 0) {
+          console.warn("[convex-mcp] reserved-key reject", {
+            keys: reservedKeys,
+            requestId,
+            tool: name,
+          });
+          return {
+            content: [
+              {
+                text:
+                  `Reserved arg keys not allowed in request: ${reservedKeys.join(", ")}. ` +
+                  `Keys starting with "_" are reserved for framework-injected context.`,
+                type: "text" as const,
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        const baseCtx = {
+          apiKey,
+          args: arguments_,
+          requestId,
+          startedAt,
+          toolDef: safeDef,
+          toolName: name,
+        };
+
+        const beforeCtx: CallContext = { ...baseCtx, phase: "before" };
+        const beforeResult = await invokeHook(hooks, beforeCtx, toolDef);
+        if (beforeResult?.abort) {
+          return {
+            content: [
+              {
+                text: beforeResult.errorMessage ?? "Tool call rejected",
+                type: "text" as const,
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        const dispatchArguments =
+          beforeResult?.extendArgs &&
+          Object.keys(beforeResult.extendArgs).length > 0
+            ? { ...arguments_, ...beforeResult.extendArgs }
+            : arguments_;
+
+        try {
+          const callPromise = (async () => {
+            switch (toolDef.type) {
+              case "query":
+                return await client.query(toolDef.ref, dispatchArguments);
+              case "mutation":
+                return await client.mutation(toolDef.ref, dispatchArguments);
+              case "action":
+                return await client.action(toolDef.ref, dispatchArguments);
+              default:
+                throw new Error(
+                  `Unknown function type: ${String(toolDef.type)}`,
+                );
+            }
+          })();
+
+          const result = await executeWithTimeout(callPromise, toolDef.timeout);
+          const durationMs = Date.now() - startedAt;
+
+          const successCtx: CallContext = {
+            ...baseCtx,
+            durationMs,
+            phase: "success",
+            result,
+          };
+          await invokeHook(hooks, successCtx, toolDef);
+
+          return {
+            content: [
+              {
+                text: JSON.stringify(result ?? null, null, 2),
+                type: "text" as const,
+              },
+            ],
+          };
+        } catch (error) {
+          const durationMs = Date.now() - startedAt;
+          const errorCtx: CallContext = {
+            ...baseCtx,
+            durationMs,
+            error,
+            phase: "error",
+          };
+
+          const errorResult = await invokeHook(hooks, errorCtx, toolDef);
+          const errorMessage =
+            errorResult?.message ?? "Function execution failed";
+
+          console.error("[convex-mcp] tool execution failed", {
+            durationMs,
+            error,
+            requestId,
+            tool: name,
+          });
+
+          return {
+            content: [{ text: errorMessage, type: "text" as const }],
+            isError: true,
+          };
+        }
+      },
+    );
+  }
+}

package/src/mcp/tools/types.ts

@@ -0,0 +1,74 @@
+import type { ConvexValidator } from "../types.js";
+
+export type FunctionType = "action" | "mutation" | "query";
+
+export type HookResult = OnCallResult | undefined;
+export type HookReturn = HookResult | Promise<HookResult> | Promise<void>;
+
+export type ToolDef = {
+  args?: ConvexValidator;
+  description?: string;
+  onError?: (ctx: CallContext & { phase: "error" }) => HookReturn;
+  ref: unknown;
+  tags?: Record<string, string>;
+  timeout?: number;
+  type: FunctionType;
+};
+
+export type CallContext = {
+  apiKey: string | undefined;
+  args: Record<string, unknown>;
+  durationMs?: number;
+  error?: unknown;
+  phase: "before" | "error" | "success";
+  requestId: string;
+  result?: unknown;
+  startedAt: number;
+  toolDef: Omit<ToolDef, "onError" | "ref">;
+  toolName: string;
+};
+
+export type OnCallResult = {
+  /** Set true to abort execution. Only checked during "before" phase. */
+  abort?: boolean;
+  /** Custom error message when aborting (before phase). Default: "Tool call rejected" */
+  errorMessage?: string;
+  /**
+   * Server-resolved key/value pairs merged into the dispatched function's args
+   * before the Convex call. Only honored during the "before" phase.
+   *
+   * On key collision, hook-supplied values take precedence over request args
+   * (server-side wins).
+   *
+   * Convention: keys MUST use the framework-reserved underscore prefix
+   * (e.g., `_mcp_apiKey`, `_request_id`). Request args containing `_`-prefixed
+   * keys are rejected before the hook runs, so this prefix is safe for
+   * server-side context injection (auth, tracing, multi-tenancy, audit, etc.).
+   *
+   * Empty objects and undefined are no-ops (no allocation, no merge).
+   *
+   * @example
+   * ```ts
+   * hooks: {
+   *   onToolCall: async ({ apiKey, phase }) => {
+   *     if (phase !== "before") return;
+   *     const validated = await validateKey(apiKey);
+   *     if (!validated.valid) return { abort: true, errorMessage: "Invalid key" };
+   *     return {
+   *       extendArgs: {
+   *         _mcp_apiKey: apiKey,
+   *         _mcp_scopes: validated.scopes,
+   *       },
+   *     };
+   *   },
+   * }
+   * ```
+   */
+  extendArgs?: Record<string, unknown>;
+  /** Custom error message on failure (error phase). Default: "Function execution failed" */
+  message?: string;
+};
+
+export type LifecycleHooks = {
+  onToolCall?: (ctx: CallContext) => HookReturn;
+};

package/src/mcp/types.ts

@@ -0,0 +1,65 @@
+export type ConvexValidator = {
+  element?: ConvexValidator;
+  fields?: Record<string, ConvexValidator>;
+  isOptional: "optional" | "required";
+  key?: ConvexValidator;
+  kind: string;
+  members?: ConvexValidator[];
+  tableName?: string;
+  value?: unknown;
+};
+
+/**
+ * Injectable Convex client interface. Compatible with both ConvexHttpClient
+ * (production) and convex-test's `t` (testing).
+ *
+ * Uses `any` for functionRef because Convex's FunctionReference is a complex
+ * generic that cannot be expressed without importing convex internals.
+ */
+export type ConvexClient = {
+  /* eslint-disable @typescript-eslint/no-explicit-any */
+  action(functionRef: any, ...arguments_: any[]): Promise<any>;
+  mutation(functionRef: any, ...arguments_: any[]): Promise<any>;
+  query(functionRef: any, ...arguments_: any[]): Promise<any>;
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+};
+
+export type AuthConfig = {
+  convexToken?: (
+    apiKey: string,
+  ) => Promise<string | undefined> | string | undefined;
+  validate: (apiKey: string) => boolean | Promise<boolean>;
+};
+
+import type { PaginationConfig } from "./pagination/types.js";
+import type { ResourceDef } from "./resources/types.js";
+import type { LifecycleHooks, ToolDef } from "./tools/types.js";
+
+export type { PaginationConfig, ResourceDef, ToolDef };
+
+export type ServerConfig = {
+  auth: AuthConfig;
+  client?: ConvexClient;
+  convexUrl?: string;
+  hooks?: LifecycleHooks;
+  name?: string;
+  pagination?: PaginationConfig;
+  resources?: Record<string, ResourceDef>;
+  tools?: Record<string, ToolDef>;
+  version?: string;
+};
+
+export type ConvexMCPServer = {
+  handler: () => {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+  };
+};
+
+export { type ToolPage, type ToolSummary } from "./pagination/types.js";
+export {
+  type CallContext,
+  type FunctionType,
+  type LifecycleHooks,
+  type OnCallResult,
+} from "./tools/types.js";

package/src/mcp/validators.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+
+import type { ConvexValidator } from "./types.js";
+
+export class UnsupportedValidatorError extends Error {
+  constructor(kind: string) {
+    super(
+      `Unsupported Convex validator kind: "${kind}". This may be from a newer version of Convex.`,
+    );
+    this.name = "UnsupportedValidatorError";
+  }
+}
+
+function isConvexValidator(value: unknown): value is ConvexValidator {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "kind" in value &&
+    "isOptional" in value
+  );
+}
+
+function isLiteralValue(
+  value: unknown,
+): value is boolean | null | number | string {
+  const t = typeof value;
+  return t === "string" || t === "number" || t === "boolean" || value === null;
+}
+
+function isAllStringLiteralUnion(
+  members: ConvexValidator[],
+): members is (ConvexValidator & { value: string })[] {
+  return (
+    members.length > 1 &&
+    members.every((m) => m.kind === "literal" && typeof m.value === "string")
+  );
+}
+
+function hasAtLeastTwo<T>(array: T[]): array is [T, T, ...T[]] {
+  return array.length >= 2;
+}
+
+// Callers guarantee arr.length >= 2 (pre-checked by isAllStringLiteralUnion or length === 1 early return)
+function asTuple<T>(array: T[]): [T, T, ...T[]] {
+  /* v8 ignore start -- callers guarantee length >= 2 */
+  if (!hasAtLeastTwo(array)) throw new Error("Expected at least 2 elements");
+  /* v8 ignore stop */
+  return array;
+}
+
+function convertKind(validator: ConvexValidator): z.ZodTypeAny {
+  switch (validator.kind) {
+    case "string":
+      return z.string();
+
+    case "float64":
+      return z.number();
+
+    case "boolean":
+      return z.boolean();
+
+    case "null":
+      return z.null();
+
+    case "int64":
+      return z
+        .string()
+        .describe(
+          "64-bit integer as string (BigInt — JSON cannot represent bigint)",
+        );
+
+    case "bytes":
+      return z.string().describe("Binary data as base64-encoded string");
+
+    case "id":
+      return z
+        .string()
+        .describe(
+          validator.tableName
+            ? `Convex document ID for table '${validator.tableName}'`
+            : "Convex document ID",
+        );
+
+    case "literal":
+      if (!isLiteralValue(validator.value)) {
+        throw new UnsupportedValidatorError("literal (unsupported value type)");
+      }
+      return z.literal(validator.value);
+
+    case "array":
+      if (!validator.element) {
+        throw new UnsupportedValidatorError("array (missing element)");
+      }
+      return z.array(convertValidator(validator.element));
+
+    case "object": {
+      if (!validator.fields) {
+        return z.object({});
+      }
+      const shape: Record<string, z.ZodTypeAny> = {};
+      for (const [key, field] of Object.entries(validator.fields)) {
+        shape[key] = convertValidator(field);
+      }
+      return z.object(shape);
+    }
+
+    case "union": {
+      if (!validator.members || validator.members.length === 0) {
+        throw new UnsupportedValidatorError("union (missing members)");
+      }
+      if (isAllStringLiteralUnion(validator.members)) {
+        const values = validator.members.map((m) => m.value);
+        return z.enum(asTuple(values));
+      }
+      const converted = validator.members.map((m) => convertValidator(m));
+      if (converted.length === 1) {
+        const [single] = converted;
+        /* v8 ignore start -- impossible after converted.length === 1; needed for noUncheckedIndexedAccess */
+        if (!single)
+          throw new UnsupportedValidatorError("union (missing member)");
+        /* v8 ignore stop */
+        return single;
+      }
+      return z.union(asTuple(converted));
+    }
+
+    case "record": {
+      if (!validator.key || !validator.value) {
+        throw new UnsupportedValidatorError("record (missing key or value)");
+      }
+      const keyKind = validator.key.kind;
+      if (keyKind !== "string" && keyKind !== "id") {
+        throw new UnsupportedValidatorError(
+          `record key must be string or id, got "${keyKind}"`,
+        );
+      }
+      const valueValidator = validator.value;
+      if (!isConvexValidator(valueValidator)) {
+        throw new UnsupportedValidatorError("record (invalid value validator)");
+      }
+      // Key kind validated as "string" | "id" above — always maps to z.string()
+      return z.record(z.string(), convertValidator(valueValidator));
+    }
+
+    case "any":
+      return z.any();
+
+    default:
+      throw new UnsupportedValidatorError(validator.kind);
+  }
+}
+
+export function convertValidator(validator: ConvexValidator): z.ZodTypeAny {
+  const base = convertKind(validator);
+  if (validator.isOptional === "optional") {
+    return base.optional();
+  }
+  return base;
+}
+
+export function convexArgsToZod(
+  argumentsValidator: ConvexValidator,
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  if (argumentsValidator.kind !== "object") {
+    throw new Error("Convex function args must be a v.object() validator");
+  }
+  if (!argumentsValidator.fields) {
+    return z.object({});
+  }
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const [key, field] of Object.entries(argumentsValidator.fields)) {
+    shape[key] = convertValidator(field);
+  }
+  return z.object(shape);
+}