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

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

@@ -0,0 +1,14 @@
+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 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;AAE3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,gBAAgB,GAAG;IACtB,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,CAOpB;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,gBAAgB,EAAE,GAC5B,IAAI,CAiCN"}

package/dist/mcp/resources/register.js

@@ -0,0 +1,40 @@
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+export function prepareResources(resources) {
+    return Object.entries(resources).map(([uriPattern, resourceDef]) => ({
+        description: resourceDef.description,
+        resourceDef,
+        template: new ResourceTemplate(uriPattern, { list: undefined }),
+        uriPattern,
+    }));
+}
+export function registerResources(mcpServer, client, resources) {
+    for (const { description, resourceDef, template, uriPattern } of resources) {
+        mcpServer.resource(uriPattern, template, {
+            description,
+            mimeType: "application/json",
+        }, async (uri, parameters) => {
+            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");
+            }
+        });
+    }
+}
+//# 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;AAa3E,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,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,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3E,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,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;gBAC/D,OAAO;oBACL,QAAQ,EAAE;wBACR;4BACE,QAAQ,EAAE,kBAAkB;4BAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;4BAC7C,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/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"}

package/dist/mcp/server.js

@@ -0,0 +1,139 @@
+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";
+function createDefaultClient(convexUrl, convexToken) {
+    const client = new ConvexHttpClient(convexUrl);
+    if (convexToken) {
+        client.setAuth(convexToken);
+    }
+    return client;
+}
+function addRequestId(response, requestId) {
+    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) {
+    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;
+    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, convexToken, apiKey) {
+        const mcpServer = new McpServer({
+            name: serverName,
+            version: serverVersion,
+        });
+        let client;
+        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) {
+                    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) {
+                    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);
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

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

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

@@ -0,0 +1,16 @@
+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 declare function query(ref: unknown, options?: ToolOptions): ToolDef;
+export declare function mutation(ref: unknown, options?: ToolOptions): ToolDef;
+export declare function action(ref: unknown, options?: ToolOptions): ToolDef;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEnE,KAAK,WAAW,GAAG;IACjB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,UAAU,CAAC;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAUtE;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAUzE;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAUvE"}

package/dist/mcp/tools/helpers.js

@@ -0,0 +1,34 @@
+export function query(ref, options = {}) {
+    return {
+        args: options.args,
+        description: options.description,
+        onError: options.onError,
+        ref,
+        tags: options.tags,
+        timeout: options.timeout,
+        type: "query",
+    };
+}
+export function mutation(ref, options = {}) {
+    return {
+        args: options.args,
+        description: options.description,
+        onError: options.onError,
+        ref,
+        tags: options.tags,
+        timeout: options.timeout,
+        type: "mutation",
+    };
+}
+export function action(ref, options = {}) {
+    return {
+        args: options.args,
+        description: options.description,
+        onError: options.onError,
+        ref,
+        tags: options.tags,
+        timeout: options.timeout,
+        type: "action",
+    };
+}
+//# sourceMappingURL=helpers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/mcp/tools/helpers.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,UAAuB,EAAE;IAC3D,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG;QACH,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,OAAO;KACd,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAY,EAAE,UAAuB,EAAE;IAC9D,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG;QACH,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,UAAU;KACjB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,GAAY,EAAE,UAAuB,EAAE;IAC5D,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG;QACH,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,QAAQ;KACf,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,23 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { z } from "zod";
+import type { ConvexClient } from "../types.js";
+import type { LifecycleHooks, ToolDef } from "./types.js";
+type PreparedTool = {
+    description: string;
+    name: string;
+    toolDef: ToolDef;
+    zodShape: Record<string, z.ZodTypeAny>;
+};
+export declare function prepareTools(tools: Record<string, ToolDef>): PreparedTool[];
+/**
+ * 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 declare function findToolsWithReservedArgs(tools: Record<string, ToolDef>): Map<string, string[]>;
+export declare function registerTools(mcpServer: McpServer, client: ConvexClient, tools: PreparedTool[], hooks: LifecycleHooks | undefined, requestId: string, apiKey: string | undefined): void;
+export {};
+//# sourceMappingURL=register.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,KAAK,EAEV,cAAc,EAEd,OAAO,EACR,MAAM,YAAY,CAAC;AAEpB,KAAK,YAAY,GAAG;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;CACxC,CAAC;AA0BF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,EAAE,CAa3E;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAQvB;AAiDD,wBAAgB,aAAa,CAC3B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,YAAY,EAAE,EACrB,KAAK,EAAE,cAAc,GAAG,SAAS,EACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,IAAI,CA0HN"}

package/dist/mcp/tools/register.js

@@ -0,0 +1,195 @@
+import { convexArgsToZod as convexArgumentsToZod } from "../validators.js";
+/**
+ * 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) {
+    return key.startsWith("_");
+}
+function stripReservedFromShape(shape) {
+    const filtered = {};
+    for (const [key, value] of Object.entries(shape)) {
+        if (!isReservedKey(key)) {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}
+export function prepareTools(tools) {
+    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) {
+    const result = new Map();
+    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, ctx, toolDef) {
+    try {
+        if (ctx.phase === "error" && toolDef.onError) {
+            const result = await toolDef.onError(ctx);
+            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(promise, timeoutMs) {
+    if (!timeoutMs)
+        return promise;
+    let handle;
+    return Promise.race([
+        promise.finally(() => {
+            clearTimeout(handle);
+        }),
+        new Promise((_, reject) => {
+            handle = setTimeout(() => {
+                reject(new Error("Tool execution timed out"));
+            }, timeoutMs);
+        }),
+    ]);
+}
+export function registerTools(mcpServer, client, tools, hooks, requestId, apiKey) {
+    for (const { description, name, toolDef, zodShape } of tools) {
+        mcpServer.tool(name, description, zodShape, async (arguments_) => {
+            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",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const baseCtx = {
+                apiKey,
+                args: arguments_,
+                requestId,
+                startedAt,
+                toolDef: safeDef,
+                toolName: name,
+            };
+            const beforeCtx = { ...baseCtx, phase: "before" };
+            const beforeResult = await invokeHook(hooks, beforeCtx, toolDef);
+            if (beforeResult?.abort) {
+                return {
+                    content: [
+                        {
+                            text: beforeResult.errorMessage ?? "Tool call rejected",
+                            type: "text",
+                        },
+                    ],
+                    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 = {
+                    ...baseCtx,
+                    durationMs,
+                    phase: "success",
+                    result,
+                };
+                await invokeHook(hooks, successCtx, toolDef);
+                return {
+                    content: [
+                        {
+                            text: JSON.stringify(result ?? null, null, 2),
+                            type: "text",
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const durationMs = Date.now() - startedAt;
+                const errorCtx = {
+                    ...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" }],
+                    isError: true,
+                };
+            }
+        });
+    }
+}
+//# sourceMappingURL=register.js.map

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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAE3D,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1E,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,UAAU,CAAC;IAChE,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,KAAK,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,UAAU,CAAC;CAC/C,CAAC"}

package/dist/mcp/tools/types.js

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

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

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