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

package/dist/mcp/types.d.ts

@@ -0,0 +1,50 @@
+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 = {
+    action(functionRef: any, ...arguments_: any[]): Promise<any>;
+    mutation(functionRef: any, ...arguments_: any[]): Promise<any>;
+    query(functionRef: any, ...arguments_: any[]): Promise<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";
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC,UAAU,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IAEzB,MAAM,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,UAAU,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7D,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,UAAU,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/D,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,GAAG,UAAU,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CAE7D,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,WAAW,CAAC,EAAE,CACZ,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC;IACtD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D,CAAC;AAEF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AAEvD,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM;QACb,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC7C,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;KAC/C,CAAC;CACH,CAAC;AAEF,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC"}

package/dist/mcp/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":""}

package/dist/mcp/validators.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import type { ConvexValidator } from "./types.js";
+export declare class UnsupportedValidatorError extends Error {
+    constructor(kind: string);
+}
+export declare function convertValidator(validator: ConvexValidator): z.ZodTypeAny;
+export declare function convexArgsToZod(argumentsValidator: ConvexValidator): z.ZodObject<Record<string, z.ZodTypeAny>>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/mcp/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/mcp/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,IAAI,EAAE,MAAM;CAMzB;AA6ID,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,eAAe,GAAG,CAAC,CAAC,UAAU,CAMzE;AAED,wBAAgB,eAAe,CAC7B,kBAAkB,EAAE,eAAe,GAClC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAY3C"}

package/dist/mcp/validators.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+export class UnsupportedValidatorError extends Error {
+    constructor(kind) {
+        super(`Unsupported Convex validator kind: "${kind}". This may be from a newer version of Convex.`);
+        this.name = "UnsupportedValidatorError";
+    }
+}
+function isConvexValidator(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "kind" in value &&
+        "isOptional" in value);
+}
+function isLiteralValue(value) {
+    const t = typeof value;
+    return t === "string" || t === "number" || t === "boolean" || value === null;
+}
+function isAllStringLiteralUnion(members) {
+    return (members.length > 1 &&
+        members.every((m) => m.kind === "literal" && typeof m.value === "string"));
+}
+function hasAtLeastTwo(array) {
+    return array.length >= 2;
+}
+// Callers guarantee arr.length >= 2 (pre-checked by isAllStringLiteralUnion or length === 1 early return)
+function asTuple(array) {
+    /* 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) {
+    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 = {};
+            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) {
+    const base = convertKind(validator);
+    if (validator.isOptional === "optional") {
+        return base.optional();
+    }
+    return base;
+}
+export function convexArgsToZod(argumentsValidator) {
+    if (argumentsValidator.kind !== "object") {
+        throw new Error("Convex function args must be a v.object() validator");
+    }
+    if (!argumentsValidator.fields) {
+        return z.object({});
+    }
+    const shape = {};
+    for (const [key, field] of Object.entries(argumentsValidator.fields)) {
+        shape[key] = convertValidator(field);
+    }
+    return z.object(shape);
+}
+//# sourceMappingURL=validators.js.map

package/dist/mcp/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/mcp/validators.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@vllnt/convex-helpers",
+  "version": "0.1.0-canary.1e0f54a",
+  "description": "Typed host-side helpers for Convex backends — builders, errors, validators, relationships, pagination, HTTP, env, and observability.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@9.15.4",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc --project ./tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit --project tsconfig.test.json",
+    "typecheck:ci": "tsc --noEmit --project tsconfig.ci.json && tsc --noEmit --project tsconfig.test.json",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "generate:llms": "node scripts/generate-llms.mjs",
+    "preversion": "pnpm install --frozen-lockfile && pnpm build && pnpm test && pnpm typecheck && pnpm generate:llms"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "convex": "^1.36.1",
+    "zod": "^4.3.6"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "@vllnt/eslint-config": "^1.0.0",
+    "@vllnt/typescript": "^1.0.0",
+    "convex": "^1.36.1",
+    "convex-test": "^0.0.50",
+    "eslint": "^9.0.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/vllnt/convex-helpers#readme",
+  "bugs": {
+    "url": "https://github.com/vllnt/convex-helpers/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vllnt/convex-helpers"
+  },
+  "author": {
+    "name": "bntvllnt",
+    "url": "https://bntvllnt.com"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/bntvllnt"
+  },
+  "keywords": [
+    "convex",
+    "convex-helpers",
+    "typescript",
+    "backend",
+    "utils",
+    "mcp",
+    "model-context-protocol"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+
+import { asyncMap, NullDocumentError, nullThrows, pruneNull } from "./index.js";
+
+describe("asyncMap", () => {
+  it("returns empty array for empty input", async () => {
+    const result = await asyncMap([], (x: number) => Promise.resolve(x * 2));
+    expect(result).toEqual([]);
+  });
+
+  it("maps a single element", async () => {
+    const result = await asyncMap([1], (x) => Promise.resolve(x * 2));
+    expect(result).toEqual([2]);
+  });
+
+  it("maps multiple elements in order", async () => {
+    const result = await asyncMap([1, 2, 3], (x) => Promise.resolve(x * 2));
+    expect(result).toEqual([2, 4, 6]);
+  });
+
+  it("passes index to mapper", async () => {
+    const result = await asyncMap(
+      ["a", "b", "c"],
+      async (item, index) => `${String(index)}:${item}`,
+    );
+    expect(result).toEqual(["0:a", "1:b", "2:c"]);
+  });
+
+  it("resolves all promises and returns results in order", async () => {
+    const result = await asyncMap([10, 20, 30], (x) => Promise.resolve(x * 3));
+    expect(result).toEqual([30, 60, 90]);
+  });
+});
+
+describe("pruneNull", () => {
+  it("returns empty array for empty input", () => {
+    expect(pruneNull([])).toEqual([]);
+  });
+
+  it("removes all nulls", () => {
+    const nullValue: null = null;
+    expect(pruneNull([nullValue, nullValue])).toEqual([]);
+  });
+
+  it("removes all undefineds", () => {
+    expect(pruneNull([undefined, undefined])).toEqual([]);
+  });
+
+  it("removes mixed null and undefined", () => {
+    const nullValue: null = null;
+    expect(pruneNull([nullValue, undefined, nullValue])).toEqual([]);
+  });
+
+  it("keeps all non-null values", () => {
+    expect(pruneNull([1, 2, 3])).toEqual([1, 2, 3]);
+  });
+
+  it("filters mixed array of values and nulls", () => {
+    const nullValue: null = null;
+    expect(pruneNull([1, nullValue, 2, undefined, 3])).toEqual([1, 2, 3]);
+  });
+
+  it("works with strings", () => {
+    const nullValue: null = null;
+    expect(pruneNull(["a", nullValue, "b"])).toEqual(["a", "b"]);
+  });
+
+  it("works with objects", () => {
+    const object = { id: 1 };
+    const nullValue: null = null;
+    expect(pruneNull([object, nullValue])).toEqual([object]);
+  });
+
+  it("preserves falsy non-null values (0, false, empty string)", () => {
+    const nullValue: null = null;
+    expect(pruneNull([0, false, "", nullValue, undefined])).toEqual([
+      0,
+      false,
+      "",
+    ]);
+  });
+});
+
+describe("NullDocumentError", () => {
+  it("is an instance of Error", () => {
+    const error = new NullDocumentError();
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it("has name NullDocumentError", () => {
+    const error = new NullDocumentError();
+    expect(error.name).toBe("NullDocumentError");
+  });
+
+  it("uses default message when none provided", () => {
+    const error = new NullDocumentError();
+    expect(error.message).toBe("Expected a non-null document");
+  });
+
+  it("uses custom message when provided", () => {
+    const error = new NullDocumentError("custom message");
+    expect(error.message).toBe("custom message");
+  });
+});
+
+describe("nullThrows", () => {
+  it("returns the value when non-null", () => {
+    expect(nullThrows(42)).toBe(42);
+  });
+
+  it("returns the value when truthy string", () => {
+    expect(nullThrows("hello")).toBe("hello");
+  });
+
+  it("returns 0 (falsy but non-null)", () => {
+    expect(nullThrows(0)).toBe(0);
+  });
+
+  it("returns false (falsy but non-null)", () => {
+    expect(nullThrows(false)).toBe(false);
+  });
+
+  it("returns empty string (falsy but non-null)", () => {
+    expect(nullThrows("")).toBe("");
+  });
+
+  it("returns objects", () => {
+    const object = { id: 1 };
+    expect(nullThrows(object)).toBe(object);
+  });
+
+  it("throws NullDocumentError when value is null", () => {
+    const nullValue: null = null;
+    expect(() => {
+      nullThrows(nullValue);
+    }).toThrow(NullDocumentError);
+  });
+
+  it("throws NullDocumentError when value is undefined", () => {
+    expect(() => {
+      nullThrows(undefined);
+    }).toThrow(NullDocumentError);
+  });
+
+  it("throws with default message when no message supplied", () => {
+    const nullValue: null = null;
+    expect(() => {
+      nullThrows(nullValue);
+    }).toThrow("Expected a non-null document");
+  });
+
+  it("throws with custom message when supplied", () => {
+    const nullValue: null = null;
+    expect(() => {
+      nullThrows(nullValue, "doc 123 not found");
+    }).toThrow("doc 123 not found");
+  });
+
+  it("throws with custom message for undefined", () => {
+    expect(() => {
+      nullThrows(undefined, "missing doc");
+    }).toThrow("missing doc");
+  });
+});

package/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @module @vllnt/convex-helpers
+ * Pure host-side helpers for Convex backends.
+ */
+
+/**
+ * Applies an async function to every element of an array, returning results in order.
+ *
+ * @param list - Input array
+ * @param fn - Async mapper function
+ * @returns Promise resolving to mapped array in original order
+ * @example
+ * const docs = await asyncMap(ids, (id) => ctx.db.get(id));
+ */
+export async function asyncMap<T, TResult>(
+  list: T[],
+  fn: (item: T, index: number) => Promise<TResult>,
+): Promise<TResult[]> {
+  return Promise.all(list.map(fn));
+}
+
+/**
+ * Filters null and undefined values from an array.
+ *
+ * @param list - Input array potentially containing null/undefined
+ * @returns Array with all null and undefined values removed
+ * @example
+ * const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+ */
+export function pruneNull<T>(list: (null | T | undefined)[]): T[] {
+  return list.filter((item): item is T => item !== null && item !== undefined);
+}
+
+/**
+ * Error thrown when a required document is null or undefined.
+ */
+export class NullDocumentError extends Error {
+  constructor(message = "Expected a non-null document") {
+    super(message);
+    this.name = "NullDocumentError";
+  }
+}
+
+/**
+ * Asserts a value is non-null and non-undefined, throwing NullDocumentError when absent.
+ *
+ * @param value - Value to check
+ * @param message - Optional custom error message
+ * @returns The value, narrowed to exclude null and undefined
+ * @throws {NullDocumentError} When value is null or undefined
+ * @example
+ * const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+ */
+export function nullThrows<T>(
+  value: null | T | undefined,
+  message?: string,
+): T {
+  if (value === null || value === undefined) {
+    throw new NullDocumentError(message);
+  }
+  return value;
+}

package/src/mcp/auth.ts

@@ -0,0 +1,53 @@
+import type { AuthConfig } from "./types.js";
+
+export function extractApiKey(request: Request): string | undefined {
+  const authHeader = request.headers.get("authorization");
+  if (!authHeader) return undefined;
+
+  if (authHeader.startsWith("Bearer ")) {
+    return authHeader.slice(7);
+  }
+
+  return undefined;
+}
+
+export async function validateRequest(
+  request: Request,
+  auth: AuthConfig,
+): Promise<
+  | { apiKey: string; convexToken?: string; valid: true }
+  | { response: Response; valid: false }
+> {
+  const apiKey = extractApiKey(request);
+
+  if (!apiKey) {
+    return {
+      response: new Response(
+        JSON.stringify({
+          error:
+            "Missing or malformed API key. Use Authorization: Bearer <key>.",
+        }),
+        { headers: { "Content-Type": "application/json" }, status: 401 },
+      ),
+      valid: false,
+    };
+  }
+
+  const isValid = await auth.validate(apiKey);
+  if (!isValid) {
+    return {
+      response: new Response(JSON.stringify({ error: "Invalid API key." }), {
+        headers: { "Content-Type": "application/json" },
+        status: 401,
+      }),
+      valid: false,
+    };
+  }
+
+  let convexToken: string | undefined;
+  if (auth.convexToken) {
+    convexToken = await auth.convexToken(apiKey);
+  }
+
+  return { apiKey, convexToken, valid: true };
+}

package/src/mcp/index.ts

@@ -0,0 +1,23 @@
+export type { ToolPage, ToolSummary } from "./pagination/types.js";
+export { resource } from "./resources/helpers.js";
+export { createMCPServer } from "./server.js";
+export { action, mutation, query } from "./tools/helpers.js";
+export type {
+  AuthConfig,
+  CallContext,
+  ConvexClient,
+  ConvexMCPServer,
+  ConvexValidator,
+  FunctionType,
+  LifecycleHooks,
+  OnCallResult,
+  PaginationConfig,
+  ResourceDef,
+  ServerConfig,
+  ToolDef,
+} from "./types.js";
+export {
+  convertValidator,
+  convexArgsToZod,
+  UnsupportedValidatorError,
+} from "./validators.js";

package/src/mcp/pagination/context.ts

@@ -0,0 +1,27 @@
+import type { PaginationConfig } from "./types.js";
+
+/** Create pagination context from config. Validates pageSize >= 1. */
+export function createPaginationContext(config: PaginationConfig | undefined): {
+  enabled: boolean;
+  pageSize: number;
+  secret: string;
+  twoPhaseDiscovery: boolean;
+} {
+  if (!config) {
+    return {
+      enabled: false,
+      pageSize: 0,
+      secret: "",
+      twoPhaseDiscovery: false,
+    };
+  }
+  if (!Number.isInteger(config.pageSize) || config.pageSize < 1) {
+    throw new Error("pagination.pageSize must be a positive integer >= 1");
+  }
+  return {
+    enabled: true,
+    pageSize: config.pageSize,
+    secret: crypto.randomUUID(),
+    twoPhaseDiscovery: config.twoPhaseDiscovery ?? false,
+  };
+}