@vllnt/convex-helpers 0.1.0-canary.df58580 → 0.1.0

package/README.md

@@ -26,6 +26,7 @@ See [ROADMAP.md](./ROADMAP.md) for the planned module surface.
 - `asyncMap` — parallel async map that preserves order
 - `pruneNull` — filter null/undefined from arrays
 - `nullThrows` — non-null assertion with typed `NullDocumentError`
+- `./mcp` — expose Convex functions as MCP tools (`createMCPServer` + `query`/`mutation`/`action`/`resource`), default-deny auth, optional cursor pagination
 - [planned] `./builders` — `customQuery`/`customMutation`/`customAction`/`customCtx`
 - [planned] `./errors` — typed `AppError` + HTTP-status map
 - [planned] `./auth` — provider-agnostic `requireIdentity`/`getCurrentSubject`
@@ -59,6 +60,38 @@ const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
 const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
 ```
 
+### MCP tools — `./mcp`
+
+Expose Convex functions to LLM agents over the Model Context Protocol. The `./mcp` entry is
+tree-shakeable — backend-only consumers pull zero MCP code. It needs two optional peer deps:
+
+```bash
+pnpm add @modelcontextprotocol/sdk zod
+```
+
+```ts
+import { createMCPServer, query, mutation } from "@vllnt/convex-helpers/mcp";
+import { api } from "./_generated/api";
+import { v } from "convex/values";
+
+export const mcp = createMCPServer({
+  auth: { validate: async (key) => key === process.env.MCP_API_KEY },
+  tools: {
+    list_projects: query(api.projects.list, { args: v.object({}), description: "List all projects" }),
+    create_project: mutation(api.projects.create, {
+      args: v.object({ name: v.string() }),
+      description: "Create a project",
+    }),
+  },
+});
+
+// Mount the route handler (e.g. Next.js App Router)
+export const { GET, POST } = mcp.handler();
+```
+
+Migrating from `@vllnt/convex-mcp`? Change the import to `@vllnt/convex-helpers/mcp` — the API is
+identical. See [docs/API.md](./docs/API.md#mcp-tools-mcp) for the full `./mcp` reference.
+
 ## API Reference
 
 See [docs/API.md](./docs/API.md) for full API reference with signatures and examples.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EACvC,IAAI,EAAE,CAAC,EAAE,EACT,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,EAAE,CAAC,CAEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAEhE;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,SAAiC;CAIrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,IAAI,GAAG,CAAC,GAAG,SAAS,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,CAKH"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EACvC,IAAI,EAAE,CAAC,EAAE,EACT,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,EAAE,CAAC,CAEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAEhE;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,SAAiC,EAGnD;CACF;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,IAAI,GAAG,CAAC,GAAG,SAAS,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,CAKH"}

package/dist/mcp/auth.d.ts

@@ -0,0 +1,11 @@
+import type { AuthConfig } from "./types.js";
+export declare function extractApiKey(request: Request): string | undefined;
+export declare function validateRequest(request: Request, auth: AuthConfig): Promise<{
+    apiKey: string;
+    convexToken?: string;
+    valid: true;
+} | {
+    response: Response;
+    valid: false;
+}>;
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/mcp/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASlE;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,UAAU,GACf,OAAO,CACN;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACrD;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CACvC,CAiCA"}

package/dist/mcp/auth.js

@@ -0,0 +1,36 @@
+export function extractApiKey(request) {
+    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, auth) {
+    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;
+    if (auth.convexToken) {
+        convexToken = await auth.convexToken(apiKey);
+    }
+    return { apiKey, convexToken, valid: true };
+}
+//# sourceMappingURL=auth.js.map

package/dist/mcp/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/mcp/auth.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAElC,IAAI,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAgB,EAChB,IAAgB;IAKhB,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,QAAQ,EAAE,IAAI,QAAQ,CACpB,IAAI,CAAC,SAAS,CAAC;gBACb,KAAK,EACH,gEAAgE;aACnE,CAAC,EACF,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CACjE;YACD,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,QAAQ,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,EAAE;gBACpE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,MAAM,EAAE,GAAG;aACZ,CAAC;YACF,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;IAED,IAAI,WAA+B,CAAC;IACpC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC9C,CAAC"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,7 @@
+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";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,OAAO,GACR,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,5 @@
+export { resource } from "./resources/helpers.js";
+export { createMCPServer } from "./server.js";
+export { action, mutation, query } from "./tools/helpers.js";
+export { convertValidator, convexArgsToZod, UnsupportedValidatorError, } from "./validators.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAe7D,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC"}

package/dist/mcp/pagination/context.d.ts

@@ -0,0 +1,9 @@
+import type { PaginationConfig } from "./types.js";
+/** Create pagination context from config. Validates pageSize >= 1. */
+export declare function createPaginationContext(config: PaginationConfig | undefined): {
+    enabled: boolean;
+    pageSize: number;
+    secret: string;
+    twoPhaseDiscovery: boolean;
+};
+//# sourceMappingURL=context.d.ts.map

package/dist/mcp/pagination/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/mcp/pagination/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,GAAG;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,OAAO,CAAC;CAC5B,CAkBA"}

package/dist/mcp/pagination/context.js

@@ -0,0 +1,21 @@
+/** Create pagination context from config. Validates pageSize >= 1. */
+export function createPaginationContext(config) {
+    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,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/mcp/pagination/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/mcp/pagination/context.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,UAAU,uBAAuB,CAAC,MAAoC;IAM1E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,OAAO,EAAE,KAAK;YACd,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,EAAE;YACV,iBAAiB,EAAE,KAAK;SACzB,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO;QACL,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE;QAC3B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,IAAI,KAAK;KACrD,CAAC;AACJ,CAAC"}

package/dist/mcp/pagination/cursor.d.ts

@@ -0,0 +1,7 @@
+export declare function encodeCursor(method: string, offset: number, secret: string): Promise<string>;
+export declare function decodeCursor(cursor: string, expectedMethod: string, secret: string): Promise<{
+    error: string;
+} | {
+    offset: number;
+}>;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/mcp/pagination/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../../src/mcp/pagination/cursor.ts"],"names":[],"mappings":"AAgEA,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBjD"}

package/dist/mcp/pagination/cursor.js

@@ -0,0 +1,60 @@
+const SEPARATOR = ".";
+function isCursorPayload(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const object = value;
+    return (typeof object.v === "number" &&
+        typeof object.m === "string" &&
+        typeof object.o === "number");
+}
+async function importKey(secret, usages) {
+    return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { hash: "SHA-256", name: "HMAC" }, false, usages);
+}
+async function hmacSign(payload, secret) {
+    const key = await importKey(secret, ["sign"]);
+    return crypto.subtle.sign("HMAC", key, new TextEncoder().encode(payload));
+}
+async function hmacVerify(payload, signature, secret) {
+    let sigBytes;
+    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) {
+    return btoa(Array.from(new Uint8Array(buf), (b) => String.fromCharCode(b)).join(""));
+}
+export async function encodeCursor(method, offset, secret) {
+    const payload = { 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, expectedMethod, secret) {
+    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 = 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 };
+}
+//# sourceMappingURL=cursor.js.map

package/dist/mcp/pagination/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../src/mcp/pagination/cursor.ts"],"names":[],"mappings":"AAMA,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,OAAO,CACL,OAAO,MAAM,CAAC,CAAC,KAAK,QAAQ;QAC5B,OAAO,MAAM,CAAC,CAAC,KAAK,QAAQ;QAC5B,OAAO,MAAM,CAAC,CAAC,KAAK,QAAQ,CAC7B,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,SAAS,CACtB,MAAc,EACd,MAAkB;IAElB,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,CAC5B,KAAK,EACL,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAChC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,EACjC,KAAK,EACL,MAAM,CACP,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,OAAe,EAAE,MAAc;IACrD,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,KAAK,UAAU,UAAU,CACvB,OAAe,EACf,SAAiB,EACjB,MAAc;IAEd,IAAI,QAAiC,CAAC;IACtC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,UAAU,CACvB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CACpD,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CACzB,MAAM,EACN,GAAG,EACH,QAAQ,EACR,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAClC,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAAC,GAAgB;IAC3C,OAAO,IAAI,CACT,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CACxE,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAc,EACd,MAAc,EACd,MAAc;IAEd,MAAM,OAAO,GAAkB,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,GAAG,GAAG,GAAG,SAAS,GAAG,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAc,EACd,cAAsB,EACtB,MAAc;IAEd,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IACrD,IAAI,cAAc,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC;IAEzE,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC;IAE7C,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC;IAE1D,6EAA6E;IAC7E,4DAA4D;IAC5D,MAAM,GAAG,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC;IACzE,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC;IAC/D,IAAI,GAAG,CAAC,CAAC,KAAK,cAAc;QAAE,OAAO,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC;IAC5E,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC;IAC7D,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;AAC3B,CAAC"}

package/dist/mcp/pagination/handlers.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+type McpTool = {
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    name: string;
+};
+type ToolListFn = () => Promise<McpTool[]>;
+export declare function getOriginalToolsList(mcpServer: McpServer): ToolListFn;
+export declare function registerPaginationHandlers(mcpServer: McpServer, getAllTools: ToolListFn, pageSize: number, secret: string): void;
+export declare function registerTwoPhaseHandlers(mcpServer: McpServer, getAllTools: ToolListFn, pageSize: number, secret: string): void;
+export {};
+//# sourceMappingURL=handlers.d.ts.map

package/dist/mcp/pagination/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/mcp/pagination/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAWzE,KAAK,OAAO,GAAG;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,UAAU,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;AAgB3C,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,GAAG,UAAU,CAcrE;AA+BD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,IAAI,CAwBN;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,IAAI,CAyDN"}

package/dist/mcp/pagination/handlers.js

@@ -0,0 +1,91 @@
+import { ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { decodeCursor, encodeCursor } from "./cursor.js";
+/* v8 ignore start -- canary: only triggers if SDK removes tools/list handler */
+function assertHandler(handler) {
+    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) {
+    const handlers = mcpServer.server._requestHandlers;
+    const origHandler = assertHandler(handlers.get("tools/list"));
+    return async () => {
+        const result = await origHandler({ method: "tools/list", params: {} }, { signal: new AbortController().signal });
+        return result.tools;
+    };
+}
+async function paginateTools(tools, method, pageSize, cursor, secret) {
+    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, getAllTools, pageSize, secret) {
+    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, getAllTools, pageSize, secret) {
+    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 };
+    });
+}
+//# sourceMappingURL=handlers.js.map

package/dist/mcp/pagination/handlers.js.map

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

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

@@ -0,0 +1,26 @@
+/**
+ * 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[];
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/mcp/pagination/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,EAAE,CAAC;CACZ,CAAC"}

package/dist/mcp/pagination/types.js

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

package/dist/mcp/pagination/types.js.map

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

package/dist/mcp/resources/helpers.d.ts

@@ -0,0 +1,9 @@
+import type { ConvexValidator } from "../types.js";
+import type { ResourceDef } from "./types.js";
+type ResourceOptions = {
+    args?: ConvexValidator;
+    description?: string;
+};
+export declare function resource(ref: unknown, options?: ResourceOptions): ResourceDef;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/mcp/resources/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/mcp/resources/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,QAAQ,CACtB,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,eAAoB,GAC5B,WAAW,CAMb"}

package/dist/mcp/resources/helpers.js

@@ -0,0 +1,8 @@
+export function resource(ref, options = {}) {
+    return {
+        args: options.args,
+        description: options.description,
+        ref,
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/mcp/resources/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/mcp/resources/helpers.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,QAAQ,CACtB,GAAY,EACZ,OAAO,GAAoB,EAAE;IAE7B,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,GAAG;KACJ,CAAC;AACJ,CAAC"}

package/dist/mcp/resources/register.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConvexClient } from "../types.js";
+import { convexArgsToZod } from "../validators.js";
+import type { ResourceDef } from "./types.js";
+type PreparedResource = {
+    argsSchema: ReturnType<typeof convexArgsToZod> | undefined;
+    description: string | undefined;
+    resourceDef: ResourceDef;
+    template: ResourceTemplate;
+    uriPattern: string;
+};
+export declare function prepareResources(resources: Record<string, ResourceDef>): PreparedResource[];
+export declare function registerResources(mcpServer: McpServer, client: ConvexClient, resources: PreparedResource[]): void;
+export {};
+//# sourceMappingURL=register.d.ts.map

package/dist/mcp/resources/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/mcp/resources/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAG3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,gBAAgB,GAAG;IACtB,UAAU,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,GAAG,SAAS,CAAC;IAC3D,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GACrC,gBAAgB,EAAE,CAUpB;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,gBAAgB,EAAE,GAC5B,IAAI,CA4CN"}

package/dist/mcp/resources/register.js

@@ -0,0 +1,46 @@
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { stringifyConvex } from "../serialization.js";
+import { convexArgsToZod } from "../validators.js";
+export function prepareResources(resources) {
+    return Object.entries(resources).map(([uriPattern, resourceDef]) => ({
+        argsSchema: resourceDef.args
+            ? convexArgsToZod(resourceDef.args)
+            : undefined,
+        description: resourceDef.description,
+        resourceDef,
+        template: new ResourceTemplate(uriPattern, { list: undefined }),
+        uriPattern,
+    }));
+}
+export function registerResources(mcpServer, client, resources) {
+    for (const { argsSchema, description, resourceDef, template, uriPattern, } of resources) {
+        mcpServer.resource(uriPattern, template, {
+            description,
+            mimeType: "application/json",
+        }, async (uri, parameters) => {
+            try {
+                const validatedParameters = argsSchema?.parse(parameters) ?? parameters;
+                const result = await client.query(resourceDef.ref, validatedParameters);
+                return {
+                    contents: [
+                        {
+                            mimeType: "application/json",
+                            text: stringifyConvex(result),
+                            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");
+            }
+        });
+    }
+}
+//# sourceMappingURL=register.js.map

package/dist/mcp/resources/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/mcp/resources/register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAE3E,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAYnD,MAAM,UAAU,gBAAgB,CAC9B,SAAsC;IAEtC,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC;QACnE,UAAU,EAAE,WAAW,CAAC,IAAI;YAC1B,CAAC,CAAC,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC;YACnC,CAAC,CAAC,SAAS;QACb,WAAW,EAAE,WAAW,CAAC,WAAW;QACpC,WAAW;QACX,QAAQ,EAAE,IAAI,gBAAgB,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC/D,UAAU;KACX,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,SAAoB,EACpB,MAAoB,EACpB,SAA6B;IAE7B,KAAK,MAAM,EACT,UAAU,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,UAAU,GACX,IAAI,SAAS,EAAE,CAAC;QACf,SAAS,CAAC,QAAQ,CAChB,UAAU,EACV,QAAQ,EACR;YACE,WAAW;YACX,QAAQ,EAAE,kBAAkB;SAC7B,EACD,KAAK,EAAE,GAAG,EAAE,UAAmC,EAAE,EAAE;YACjD,IAAI,CAAC;gBACH,MAAM,mBAAmB,GACvB,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC;gBAC9C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAC/B,WAAW,CAAC,GAAG,EACf,mBAAmB,CACpB,CAAC;gBACF,OAAO;oBACL,QAAQ,EAAE;wBACR;4BACE,QAAQ,EAAE,kBAAkB;4BAC5B,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC;4BAC7B,GAAG,EAAE,GAAG,CAAC,IAAI;yBACd;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE;oBACjD,KAAK;oBACL,QAAQ,EAAE,UAAU;iBACrB,CAAC,CAAC;gBACH,kEAAkE;gBAClE,wDAAwD;gBACxD,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;AACH,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/mcp/resources/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;CACd,CAAC"}

package/dist/mcp/resources/types.js

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

package/dist/mcp/resources/types.js.map

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

package/dist/mcp/serialization.d.ts

@@ -0,0 +1,3 @@
+/** Serialize native Convex values using Convex's lossless tagged JSON format. */
+export declare function stringifyConvex(value: unknown): string;
+//# sourceMappingURL=serialization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../src/mcp/serialization.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD"}

package/dist/mcp/serialization.js

@@ -0,0 +1,6 @@
+import { convexToJson } from "convex/values";
+/** Serialize native Convex values using Convex's lossless tagged JSON format. */
+export function stringifyConvex(value) {
+    return JSON.stringify(convexToJson((value ?? null)), null, 2);
+}
+//# sourceMappingURL=serialization.js.map

package/dist/mcp/serialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.js","sourceRoot":"","sources":["../../src/mcp/serialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,eAAe,CAAC;AAEzD,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,KAAK,IAAI,IAAI,CAAU,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACzE,CAAC"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,3 @@
+import type { ConvexMCPServer, ServerConfig } from "./types.js";
+export declare function createMCPServer(config: ServerConfig): ConvexMCPServer;
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAgB,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAuB9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAwKrE"}