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

package/src/mcp/pagination/cursor.ts

@@ -0,0 +1,99 @@
+type CursorPayload = {
+  m: string;
+  o: number;
+  v: 1;
+};
+
+const SEPARATOR = ".";
+
+function isCursorPayload(value: unknown): value is CursorPayload {
+  if (typeof value !== "object" || value === null) return false;
+  const object = value as Record<string, unknown>;
+  return (
+    typeof object.v === "number" &&
+    typeof object.m === "string" &&
+    typeof object.o === "number"
+  );
+}
+
+async function importKey(
+  secret: string,
+  usages: KeyUsage[],
+): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { hash: "SHA-256", name: "HMAC" },
+    false,
+    usages,
+  );
+}
+
+async function hmacSign(payload: string, secret: string): Promise<ArrayBuffer> {
+  const key = await importKey(secret, ["sign"]);
+  return crypto.subtle.sign("HMAC", key, new TextEncoder().encode(payload));
+}
+
+async function hmacVerify(
+  payload: string,
+  signature: string,
+  secret: string,
+): Promise<boolean> {
+  let sigBytes: Uint8Array<ArrayBuffer>;
+  try {
+    sigBytes = new Uint8Array(
+      Array.from(atob(signature), (c) => c.charCodeAt(0)),
+    );
+  } catch {
+    return false;
+  }
+  const key = await importKey(secret, ["verify"]);
+  return crypto.subtle.verify(
+    "HMAC",
+    key,
+    sigBytes,
+    new TextEncoder().encode(payload),
+  );
+}
+
+function arrayBufferToBase64(buf: ArrayBuffer): string {
+  return btoa(
+    Array.from(new Uint8Array(buf), (b) => String.fromCharCode(b)).join(""),
+  );
+}
+
+export async function encodeCursor(
+  method: string,
+  offset: number,
+  secret: string,
+): Promise<string> {
+  const payload: CursorPayload = { m: method, o: offset, v: 1 };
+  const json = JSON.stringify(payload);
+  const b64 = btoa(json);
+  const sig = await hmacSign(b64, secret);
+  return `${b64}${SEPARATOR}${arrayBufferToBase64(sig)}`;
+}
+
+export async function decodeCursor(
+  cursor: string,
+  expectedMethod: string,
+  secret: string,
+): Promise<{ error: string } | { offset: number }> {
+  const separatorIndex = cursor.lastIndexOf(SEPARATOR);
+  if (separatorIndex === -1) return { error: "invalid or expired cursor" };
+
+  const b64 = cursor.slice(0, separatorIndex);
+  const sig = cursor.slice(separatorIndex + 1);
+
+  const valid = await hmacVerify(b64, sig, secret);
+  if (!valid) return { error: "invalid or expired cursor" };
+
+  // Safe to parse without try-catch: HMAC verification above guarantees b64 is
+  // a payload we signed, so atob + JSON.parse will not throw.
+  const raw: unknown = JSON.parse(atob(b64));
+  if (!isCursorPayload(raw)) return { error: "invalid or expired cursor" };
+  if (raw.v !== 1) return { error: "invalid or expired cursor" };
+  if (raw.m !== expectedMethod) return { error: "invalid or expired cursor" };
+  if (raw.o < 0) return { error: "invalid or expired cursor" };
+  return { offset: raw.o };
+}

package/src/mcp/pagination/handlers.ts

@@ -0,0 +1,172 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+import { decodeCursor, encodeCursor } from "./cursor.js";
+import type { ToolPage } from "./types.js";
+
+type McpTool = {
+  description?: string;
+  inputSchema: Record<string, unknown>;
+  name: string;
+};
+
+type ToolListFn = () => Promise<McpTool[]>;
+type OrigHandler = (
+  request: unknown,
+  extra: unknown,
+) => Promise<{ tools: McpTool[] }>;
+
+/* v8 ignore start -- canary: only triggers if SDK removes tools/list handler */
+function assertHandler(handler: OrigHandler | undefined): OrigHandler {
+  if (!handler)
+    throw new Error(
+      "[convex-mcp] tools/list handler not found — SDK API may have changed.",
+    );
+  return handler;
+}
+/* v8 ignore stop */
+
+export function getOriginalToolsList(mcpServer: McpServer): ToolListFn {
+  type HandlerMap = Map<string, OrigHandler>;
+  const handlers = (
+    mcpServer.server as unknown as { _requestHandlers: HandlerMap }
+  )._requestHandlers;
+  const origHandler = assertHandler(handlers.get("tools/list"));
+
+  return async (): Promise<McpTool[]> => {
+    const result = await origHandler(
+      { method: "tools/list", params: {} },
+      { signal: new AbortController().signal },
+    );
+    return result.tools;
+  };
+}
+
+async function paginateTools<T extends object>(
+  tools: T[],
+  method: string,
+  pageSize: number,
+  cursor: string,
+  secret: string,
+): Promise<ToolPage<T> | { error: string }> {
+  let offset = 0;
+
+  if (cursor !== "") {
+    const decoded = await decodeCursor(cursor, method, secret);
+    if ("error" in decoded) return { error: decoded.error };
+    offset = decoded.offset;
+  }
+
+  /* v8 ignore start -- unreachable from public API: HMAC prevents crafting out-of-bounds cursors */
+  if (offset >= tools.length && tools.length > 0)
+    return { error: "invalid or expired cursor" };
+  /* v8 ignore stop */
+
+  const page = tools.slice(offset, offset + pageSize);
+  const hasMore = offset + pageSize < tools.length;
+  const nextCursor = hasMore
+    ? await encodeCursor(method, offset + pageSize, secret)
+    : undefined;
+
+  return { nextCursor, tools: page };
+}
+
+export function registerPaginationHandlers(
+  mcpServer: McpServer,
+  getAllTools: ToolListFn,
+  pageSize: number,
+  secret: string,
+): void {
+  mcpServer.server.setRequestHandler(
+    ListToolsRequestSchema,
+    async (request) => {
+      const cursor = request.params?.cursor;
+      const allTools = await getAllTools();
+
+      if (cursor === undefined) {
+        return { tools: allTools };
+      }
+
+      const result = await paginateTools(
+        allTools,
+        "tools/list",
+        pageSize,
+        cursor,
+        secret,
+      );
+      if ("error" in result) {
+        throw new McpError(ErrorCode.InvalidParams, result.error);
+      }
+      return { nextCursor: result.nextCursor, tools: result.tools };
+    },
+  );
+}
+
+export function registerTwoPhaseHandlers(
+  mcpServer: McpServer,
+  getAllTools: ToolListFn,
+  pageSize: number,
+  secret: string,
+): void {
+  const listSummarySchema = z.object({
+    method: z.literal("tools/list_summary"),
+    params: z.object({ cursor: z.string().optional() }).optional(),
+  });
+
+  mcpServer.server.setRequestHandler(listSummarySchema, async (request) => {
+    const allTools = await getAllTools();
+    const summaries = allTools.map((t) => ({
+      /* v8 ignore next -- both branches tested; v8 misreports ternary in .map() */
+      description: t.description === undefined ? "" : t.description,
+      name: t.name,
+    }));
+
+    const cursor = request.params?.cursor;
+    if (cursor === undefined) {
+      return { tools: summaries };
+    }
+
+    const result = await paginateTools(
+      summaries,
+      "tools/list_summary",
+      pageSize,
+      cursor,
+      secret,
+    );
+    if ("error" in result) {
+      throw new McpError(ErrorCode.InvalidParams, result.error);
+    }
+    return { nextCursor: result.nextCursor, tools: result.tools };
+  });
+
+  const describeSchema = z.object({
+    method: z.literal("tools/describe"),
+    params: z.object({ name: z.string().optional() }).optional(),
+  });
+
+  mcpServer.server.setRequestHandler(describeSchema, async (request) => {
+    const name = request.params?.name;
+    if (!name) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        "Invalid params: 'name' is required",
+      );
+    }
+
+    const allTools = await getAllTools();
+    const tool = allTools.find((t) => t.name === name);
+    if (!tool) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `Invalid params: tool '${name}' not found`,
+      );
+    }
+
+    return { tool };
+  });
+}

package/src/mcp/pagination/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Opt-in pagination for `tools/list` and two-phase tool discovery.
+ *
+ * `pageSize` is required for all pagination features including `twoPhaseDiscovery`.
+ * Must be >= 1. When enabled, `tools/list` without a cursor still returns ALL tools
+ * (backwards-compatible). Cursor pagination activates only when the client sends a cursor.
+ *
+ * `twoPhaseDiscovery` enables non-standard custom MCP methods (`tools/list_summary`,
+ * `tools/describe`). These are NOT part of the MCP spec — only custom agents that
+ * explicitly call these methods will benefit.
+ */
+export type PaginationConfig = {
+  /** Number of tools per page when client sends a cursor. Must be >= 1. */
+  pageSize: number;
+  /** Enable `tools/list_summary` + `tools/describe` custom methods. Default: false. */
+  twoPhaseDiscovery?: boolean;
+};
+
+export type ToolSummary = {
+  description: string;
+  name: string;
+};
+
+export type ToolPage<T extends object> = {
+  nextCursor?: string;
+  tools: T[];
+};

package/src/mcp/resources/helpers.ts

@@ -0,0 +1,19 @@
+import type { ConvexValidator } from "../types.js";
+
+import type { ResourceDef } from "./types.js";
+
+type ResourceOptions = {
+  args?: ConvexValidator;
+  description?: string;
+};
+
+export function resource(
+  ref: unknown,
+  options: ResourceOptions = {},
+): ResourceDef {
+  return {
+    args: options.args,
+    description: options.description,
+    ref,
+  };
+}

package/src/mcp/resources/register.ts

@@ -0,0 +1,63 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+import type { ConvexClient } from "../types.js";
+
+import type { ResourceDef } from "./types.js";
+
+type PreparedResource = {
+  description: string | undefined;
+  resourceDef: ResourceDef;
+  template: ResourceTemplate;
+  uriPattern: string;
+};
+
+export function prepareResources(
+  resources: Record<string, ResourceDef>,
+): PreparedResource[] {
+  return Object.entries(resources).map(([uriPattern, resourceDef]) => ({
+    description: resourceDef.description,
+    resourceDef,
+    template: new ResourceTemplate(uriPattern, { list: undefined }),
+    uriPattern,
+  }));
+}
+
+export function registerResources(
+  mcpServer: McpServer,
+  client: ConvexClient,
+  resources: PreparedResource[],
+): void {
+  for (const { description, resourceDef, template, uriPattern } of resources) {
+    mcpServer.resource(
+      uriPattern,
+      template,
+      {
+        description,
+        mimeType: "application/json",
+      },
+      async (uri, parameters: Record<string, unknown>) => {
+        try {
+          const result = await client.query(resourceDef.ref, parameters);
+          return {
+            contents: [
+              {
+                mimeType: "application/json",
+                text: JSON.stringify(result ?? null, null, 2),
+                uri: uri.href,
+              },
+            ],
+          };
+        } catch (error) {
+          console.error("[convex-mcp] resource read failed", {
+            error,
+            resource: uriPattern,
+          });
+          // Mask the raw Convex error from the client (parity with the tool
+          // handler); the real error is logged server-side above.
+          throw new Error("Resource read failed");
+        }
+      },
+    );
+  }
+}

package/src/mcp/resources/types.ts

@@ -0,0 +1,7 @@
+import type { ConvexValidator } from "../types.js";
+
+export type ResourceDef = {
+  args?: ConvexValidator;
+  description?: string;
+  ref: unknown;
+};

package/src/mcp/server.ts

@@ -0,0 +1,209 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { ConvexHttpClient } from "convex/browser";
+
+import { validateRequest } from "./auth.js";
+import { createPaginationContext } from "./pagination/context.js";
+import {
+  getOriginalToolsList,
+  registerPaginationHandlers,
+  registerTwoPhaseHandlers,
+} from "./pagination/handlers.js";
+import { prepareResources, registerResources } from "./resources/register.js";
+import {
+  findToolsWithReservedArgs as findToolsWithReservedArguments,
+  prepareTools,
+  registerTools,
+} from "./tools/register.js";
+import type { ConvexClient, ConvexMCPServer, ServerConfig } from "./types.js";
+
+function createDefaultClient(
+  convexUrl: string,
+  convexToken?: string,
+): ConvexClient {
+  const client = new ConvexHttpClient(convexUrl);
+  if (convexToken) {
+    client.setAuth(convexToken);
+  }
+  return client;
+}
+
+function addRequestId(response: Response, requestId: string): Response {
+  const headers = new Headers(response.headers);
+  headers.set("X-Request-Id", requestId);
+  return new Response(response.body, {
+    headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+}
+
+export function createMCPServer(config: ServerConfig): ConvexMCPServer {
+  if (!config.auth?.validate) {
+    throw new Error(
+      "Auth is required. Provide auth.validate to createMCPServer(). " +
+        "This package enforces default-deny — no open MCP endpoints.",
+    );
+  }
+
+  const injectedClient = config.client;
+
+  if (injectedClient && config.auth.convexToken) {
+    throw new Error(
+      "Cannot use both 'client' and 'auth.convexToken'. When providing a custom client, " +
+        "handle auth token propagation in your client implementation directly.",
+    );
+  }
+
+  let resolvedConvexUrl: string | undefined;
+  if (!injectedClient) {
+    resolvedConvexUrl =
+      config.convexUrl ??
+      process.env.CONVEX_URL ??
+      process.env.NEXT_PUBLIC_CONVEX_URL;
+    if (!resolvedConvexUrl) {
+      throw new Error(
+        "Convex URL not found. Set CONVEX_URL or NEXT_PUBLIC_CONVEX_URL environment variable, " +
+          "or pass convexUrl or client to createMCPServer().",
+      );
+    }
+  }
+
+  const serverName = config.name ?? "convex-mcp";
+  const serverVersion = config.version ?? "0.1.0";
+  const hooks = config.hooks;
+
+  const prepared = prepareTools(config.tools ?? {});
+  const preparedRes = prepareResources(config.resources ?? {});
+  const paginationCtx = createPaginationContext(config.pagination);
+
+  if (!hooks?.onToolCall) {
+    const stripped = findToolsWithReservedArguments(config.tools ?? {});
+    if (stripped.size > 0) {
+      const summary = [...stripped.entries()]
+        .map(([tool, keys]) => `${tool} (${keys.join(", ")})`)
+        .join("; ");
+      console.warn(
+        `[convex-mcp] tools declare reserved \`_*\` args but no onToolCall hook is configured. ` +
+          `These args are stripped from the published schema and will never be injected, ` +
+          `so every dispatched call will fail Convex validation. ` +
+          `Configure hooks.onToolCall to inject them via extendArgs. Affected tools: ${summary}`,
+      );
+    }
+  }
+
+  function createServerAndTransport(
+    requestId: string,
+    convexToken?: string,
+    apiKey?: string,
+  ): {
+    mcpServer: McpServer;
+    transport: WebStandardStreamableHTTPServerTransport;
+  } {
+    const mcpServer = new McpServer({
+      name: serverName,
+      version: serverVersion,
+    });
+
+    let client: ConvexClient;
+    if (injectedClient) {
+      client = injectedClient;
+    } else {
+      /* v8 ignore start -- configuration validation guarantees a URL when no client is injected */
+      if (!resolvedConvexUrl)
+        throw new Error("Convex URL not found after configuration validation.");
+      /* v8 ignore stop */
+      client = createDefaultClient(resolvedConvexUrl, convexToken);
+    }
+
+    registerTools(mcpServer, client, prepared, hooks, requestId, apiKey);
+    registerResources(mcpServer, client, preparedRes);
+
+    // CRITICAL: Override MUST happen AFTER registerTools() — McpServer's lazy-init
+    // registers the default tools/list handler on the first tool() call.
+    // Overriding before would cause assertCanSetRequestHandler to throw.
+    const hasTools = prepared.length > 0;
+    if (hasTools && paginationCtx.enabled) {
+      const getAllTools = getOriginalToolsList(mcpServer);
+      registerPaginationHandlers(
+        mcpServer,
+        getAllTools,
+        paginationCtx.pageSize,
+        paginationCtx.secret,
+      );
+      if (paginationCtx.twoPhaseDiscovery) {
+        registerTwoPhaseHandlers(
+          mcpServer,
+          getAllTools,
+          paginationCtx.pageSize,
+          paginationCtx.secret,
+        );
+      }
+    }
+
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+
+    return { mcpServer, transport };
+  }
+
+  return {
+    handler() {
+      return {
+        async GET(request: Request): Promise<Response> {
+          const requestId = crypto.randomUUID();
+          const authResult = await validateRequest(request, config.auth);
+          if (!authResult.valid)
+            return addRequestId(authResult.response, requestId);
+
+          const { mcpServer, transport } = createServerAndTransport(
+            requestId,
+            authResult.convexToken,
+            authResult.apiKey,
+          );
+          await mcpServer.connect(transport);
+          const response = await transport.handleRequest(request);
+          return addRequestId(response, requestId);
+        },
+        async POST(request: Request): Promise<Response> {
+          const requestId = crypto.randomUUID();
+          const authResult = await validateRequest(request, config.auth);
+          if (!authResult.valid)
+            return addRequestId(authResult.response, requestId);
+
+          const contentType = request.headers.get("content-type");
+          if (!contentType?.includes("application/json")) {
+            return addRequestId(
+              new Response(
+                JSON.stringify({
+                  error: {
+                    code: -32_700,
+                    message:
+                      "Unsupported Media Type: expected application/json",
+                  },
+                  id: null,
+                  jsonrpc: "2.0",
+                }),
+                {
+                  headers: { "Content-Type": "application/json" },
+                  status: 415,
+                },
+              ),
+              requestId,
+            );
+          }
+
+          const { mcpServer, transport } = createServerAndTransport(
+            requestId,
+            authResult.convexToken,
+            authResult.apiKey,
+          );
+          await mcpServer.connect(transport);
+          const response = await transport.handleRequest(request);
+          return addRequestId(response, requestId);
+        },
+      };
+    },
+  };
+}

package/src/mcp/tools/helpers.ts

@@ -0,0 +1,47 @@
+import type { ConvexValidator } from "../types.js";
+
+import type { CallContext, HookReturn, ToolDef } from "./types.js";
+
+type ToolOptions = {
+  args?: ConvexValidator;
+  description?: string;
+  onError?: (ctx: CallContext & { phase: "error" }) => HookReturn;
+  tags?: Record<string, string>;
+  timeout?: number;
+};
+
+export function query(ref: unknown, options: ToolOptions = {}): ToolDef {
+  return {
+    args: options.args,
+    description: options.description,
+    onError: options.onError,
+    ref,
+    tags: options.tags,
+    timeout: options.timeout,
+    type: "query",
+  };
+}
+
+export function mutation(ref: unknown, options: ToolOptions = {}): ToolDef {
+  return {
+    args: options.args,
+    description: options.description,
+    onError: options.onError,
+    ref,
+    tags: options.tags,
+    timeout: options.timeout,
+    type: "mutation",
+  };
+}
+
+export function action(ref: unknown, options: ToolOptions = {}): ToolDef {
+  return {
+    args: options.args,
+    description: options.description,
+    onError: options.onError,
+    ref,
+    tags: options.tags,
+    timeout: options.timeout,
+    type: "action",
+  };
+}