@vvedantb/server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vvedantb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @vvedantb/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server-side helpers for Convex backends. One package, two subpaths.
+
+| Import | What it holds | Docs |
+| --- | --- | --- |
+| `@vvedantb/server/convex` | Query-limit errors, Clerk auth config, bearer tokens, env, MCP CORS and server info. | [docs/convex.md](docs/convex.md) |
+| `@vvedantb/server/mcp` | MCP server scaffolding for Convex `httpAction`s: bearer-auth handler, OAuth metadata, a pure JSON-RPC dispatcher, tool helpers and explorer tools. | [docs/mcp.md](docs/mcp.md) |
+
+There is no `.` export. Import from a subpath.
+
+```sh
+npm install @vvedantb/server
+```
+
+```ts
+import { extractBearerToken } from "@vvedantb/server/convex";
+import { createMcpHttpHandler } from "@vvedantb/server/mcp";
+```
+
+## Peers
+
+Both are optional.
+
+- `@clerk/backend` `>=1`: only for `getClerkClient`.
+- `zod` `^3.25.0 || ^4.0.0`: only if you pass zod schemas to `defineTool`.
+
+No React, no web dependencies. Compiled ESM with types in `dist`, built on pack.
+
+## Layout
+
+```
+src/convex/        @vvedantb/server/convex
+src/mcp/           @vvedantb/server/mcp (imports ../convex by relative path)
+tests/convex/      vitest
+tests/mcp/         vitest, with fixtures/ (SDK captures, app references)
+docs/              convex.md, mcp.md, migration.md, migrated/<app>/
+scripts/           capture-sdk-fixtures.mjs
+```
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/server build
+pnpm --filter @vvedantb/server test
+pnpm --filter @vvedantb/server typecheck
+```

package/dist/convex/authConfig.d.ts

@@ -0,0 +1,18 @@
+export type ClerkAuthConfigEnv = {
+    CLERK_FRONTEND_API_URL?: string | undefined;
+};
+/**
+ * Convex `auth.config.ts` for Clerk. The domain comes from
+ * `CLERK_FRONTEND_API_URL`; the application ID is always `"convex"`.
+ *
+ * ```ts
+ * import { clerkAuthConfig } from "@vvedantb/server/convex";
+ * export default clerkAuthConfig();
+ * ```
+ */
+export declare function clerkAuthConfig(env?: ClerkAuthConfigEnv): {
+    providers: Array<{
+        domain: string | undefined;
+        applicationID: string;
+    }>;
+};

package/dist/convex/authConfig.js

@@ -0,0 +1,19 @@
+/**
+ * Convex `auth.config.ts` for Clerk. The domain comes from
+ * `CLERK_FRONTEND_API_URL`; the application ID is always `"convex"`.
+ *
+ * ```ts
+ * import { clerkAuthConfig } from "@vvedantb/server/convex";
+ * export default clerkAuthConfig();
+ * ```
+ */
+export function clerkAuthConfig(env = process.env) {
+    return {
+        providers: [
+            {
+                domain: env.CLERK_FRONTEND_API_URL,
+                applicationID: "convex",
+            },
+        ],
+    };
+}

package/dist/convex/bearerToken.d.ts

@@ -0,0 +1,2 @@
+/** Extract the token from an `Authorization: Bearer <token>` header value. */
+export declare function extractBearerToken(authHeader: string | null): string | null;

package/dist/convex/bearerToken.js

@@ -0,0 +1,11 @@
+/** Extract the token from an `Authorization: Bearer <token>` header value. */
+export function extractBearerToken(authHeader) {
+    if (!authHeader)
+        return null;
+    const [scheme, token, ...rest] = authHeader.split(" ");
+    if (rest.length > 0 || !scheme || !token)
+        return null;
+    if (scheme.toLowerCase() !== "bearer")
+        return null;
+    return token;
+}

package/dist/convex/clerk.d.ts

@@ -0,0 +1,13 @@
+export type ClerkClientEnv = {
+    CLERK_SECRET_KEY?: string | undefined;
+    CLERK_PUBLISHABLE_KEY?: string | undefined;
+};
+/**
+ * Build a Clerk backend client from env. The factory is injected so this
+ * package does not import `@clerk/backend`; pass its `createClerkClient`.
+ * Throws when either key is missing.
+ */
+export declare function getClerkClient<T>(createClerkClient: (opts: {
+    secretKey: string;
+    publishableKey: string;
+}) => T, env?: ClerkClientEnv): T;

package/dist/convex/clerk.js

@@ -0,0 +1,17 @@
+/**
+ * Build a Clerk backend client from env. The factory is injected so this
+ * package does not import `@clerk/backend`; pass its `createClerkClient`.
+ * Throws when either key is missing.
+ */
+export function getClerkClient(createClerkClient, env = process.env) {
+    const secretKey = env.CLERK_SECRET_KEY;
+    const publishableKey = env.CLERK_PUBLISHABLE_KEY;
+    if (!secretKey || !publishableKey) {
+        const missing = [
+            secretKey ? null : "CLERK_SECRET_KEY",
+            publishableKey ? null : "CLERK_PUBLISHABLE_KEY",
+        ].filter((name) => name !== null);
+        throw new Error(`${missing.join(" and ")} is not set in Convex env`);
+    }
+    return createClerkClient({ secretKey, publishableKey });
+}

package/dist/convex/convexQueryLimits.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Convex query resource-limit detection for MCP test queries.
+ *
+ * `run_test_function` failures like "Too many bytes read in a single function
+ * execution (limit: 16777216 bytes)" used to throw out of `runTestQuery` as
+ * an uncaught Server Error. Callers map the formatted message to an MCP
+ * `isError` result instead.
+ */
+export declare function isConvexResourceLimitError(message: string): boolean;
+/** User-facing MCP error text for a failed test query. */
+export declare function formatConvexQueryError(message: string): string;

package/dist/convex/convexQueryLimits.js

@@ -0,0 +1,28 @@
+/**
+ * Convex query resource-limit detection for MCP test queries.
+ *
+ * `run_test_function` failures like "Too many bytes read in a single function
+ * execution (limit: 16777216 bytes)" used to throw out of `runTestQuery` as
+ * an uncaught Server Error. Callers map the formatted message to an MCP
+ * `isError` result instead.
+ */
+const CONVEX_RESOURCE_LIMIT_HINT = "Use smaller limits, paginate, or query with a selective index range.";
+const CONVEX_RESOURCE_LIMIT_MARKERS = [
+    "too many bytes read",
+    "too many documents read",
+    "too many bytes written",
+    "too many writes in a single function",
+    "function execution timed out",
+    "maximum execution duration",
+    "consider using smaller limits in your queries",
+];
+export function isConvexResourceLimitError(message) {
+    const lowered = message.toLowerCase();
+    return CONVEX_RESOURCE_LIMIT_MARKERS.some((marker) => lowered.includes(marker));
+}
+/** User-facing MCP error text for a failed test query. */
+export function formatConvexQueryError(message) {
+    if (!isConvexResourceLimitError(message))
+        return message;
+    return `This query exceeded a Convex resource limit (bytes read, documents read, or execution time). ${CONVEX_RESOURCE_LIMIT_HINT} Details: ${message}`;
+}

package/dist/convex/cors.d.ts

@@ -0,0 +1,11 @@
+/** CORS headers for stateless MCP HTTP handlers. */
+export declare function mcpCorsHeaders(origin?: string): Record<string, string>;
+/** Response for an `OPTIONS` preflight request: 204 with CORS headers. */
+export declare function corsPreflight(origin?: string): Response;
+export type JsonWithCorsInit = {
+    status?: number;
+    origin?: string;
+    extraHeaders?: Record<string, string>;
+};
+/** JSON response with CORS headers. `extraHeaders` win over the CORS defaults. */
+export declare function jsonWithCors(body: unknown, init?: JsonWithCorsInit): Response;

package/dist/convex/cors.js

@@ -0,0 +1,20 @@
+/** CORS headers for stateless MCP HTTP handlers. */
+export function mcpCorsHeaders(origin = "*") {
+    return {
+        "Access-Control-Allow-Origin": origin,
+        "Access-Control-Allow-Methods": "GET,POST,DELETE,OPTIONS",
+        "Access-Control-Allow-Headers": "Authorization,Content-Type",
+        "Access-Control-Allow-Credentials": "false",
+    };
+}
+/** Response for an `OPTIONS` preflight request: 204 with CORS headers. */
+export function corsPreflight(origin) {
+    return new Response(null, { status: 204, headers: mcpCorsHeaders(origin) });
+}
+/** JSON response with CORS headers. `extraHeaders` win over the CORS defaults. */
+export function jsonWithCors(body, init = {}) {
+    return Response.json(body, {
+        status: init.status ?? 200,
+        headers: { ...mcpCorsHeaders(init.origin), ...init.extraHeaders },
+    });
+}

package/dist/convex/env.d.ts

@@ -0,0 +1,5 @@
+export type EnvSource = Record<string, string | undefined>;
+/** Read a required env var. Throws when it is unset or empty. */
+export declare function requiredEnv(name: string, env?: EnvSource): string;
+/** Read a required env var used as a URL prefix, stripping one trailing slash. */
+export declare function requiredEnvUrl(name: string, env?: EnvSource): string;

package/dist/convex/env.js

@@ -0,0 +1,12 @@
+/** Read a required env var. Throws when it is unset or empty. */
+export function requiredEnv(name, env = process.env) {
+    const value = env[name];
+    if (!value) {
+        throw new Error(`${name} is not set in Convex env`);
+    }
+    return value;
+}
+/** Read a required env var used as a URL prefix, stripping one trailing slash. */
+export function requiredEnvUrl(name, env = process.env) {
+    return requiredEnv(name, env).replace(/\/$/, "");
+}

package/dist/convex/index.d.ts

@@ -0,0 +1,8 @@
+export { clerkAuthConfig, type ClerkAuthConfigEnv } from "./authConfig.js";
+export { extractBearerToken } from "./bearerToken.js";
+export { getClerkClient, type ClerkClientEnv } from "./clerk.js";
+export { corsPreflight, jsonWithCors, mcpCorsHeaders, type JsonWithCorsInit, } from "./cors.js";
+export { formatConvexQueryError, isConvexResourceLimitError, } from "./convexQueryLimits.js";
+export { requiredEnv, requiredEnvUrl, type EnvSource } from "./env.js";
+export { defineMcpServerInfo, type McpServerInfo } from "./mcpServerInfo.js";
+export { assertMcpTools, expectMcpToolCount } from "./mcpTestHelpers.js";

package/dist/convex/index.js

@@ -0,0 +1,8 @@
+export { clerkAuthConfig } from "./authConfig.js";
+export { extractBearerToken } from "./bearerToken.js";
+export { getClerkClient } from "./clerk.js";
+export { corsPreflight, jsonWithCors, mcpCorsHeaders, } from "./cors.js";
+export { formatConvexQueryError, isConvexResourceLimitError, } from "./convexQueryLimits.js";
+export { requiredEnv, requiredEnvUrl } from "./env.js";
+export { defineMcpServerInfo } from "./mcpServerInfo.js";
+export { assertMcpTools, expectMcpToolCount } from "./mcpTestHelpers.js";

package/dist/convex/mcpServerInfo.d.ts

@@ -0,0 +1,6 @@
+export type McpServerInfo = {
+    name: string;
+    version: string;
+};
+/** Build the MCP `serverInfo` object. The caller owns the name and version. */
+export declare function defineMcpServerInfo(options: McpServerInfo): McpServerInfo;

package/dist/convex/mcpServerInfo.js

@@ -0,0 +1,8 @@
+/** Build the MCP `serverInfo` object. The caller owns the name and version. */
+export function defineMcpServerInfo(options) {
+    if (!options.name)
+        throw new Error("MCP server name must not be empty");
+    if (!options.version)
+        throw new Error("MCP server version must not be empty");
+    return { name: options.name, version: options.version };
+}

package/dist/convex/mcpTestHelpers.d.ts

@@ -0,0 +1,7 @@
+/** Throw unless exactly `expected` tools are listed. The error lists the names. */
+export declare function expectMcpToolCount(toolNames: readonly string[], expected: number): void;
+/**
+ * Throw unless the sorted, de-duplicated tool names equal the expected set.
+ * The error names the missing and unexpected tools.
+ */
+export declare function assertMcpTools(toolNames: readonly string[], expected: readonly string[]): void;

package/dist/convex/mcpTestHelpers.js

@@ -0,0 +1,22 @@
+function format(names) {
+    return names.length === 0 ? "(none)" : names.join(", ");
+}
+/** Throw unless exactly `expected` tools are listed. The error lists the names. */
+export function expectMcpToolCount(toolNames, expected) {
+    if (toolNames.length !== expected) {
+        throw new Error(`Expected ${expected} MCP tools but found ${toolNames.length}: ${format(toolNames)}`);
+    }
+}
+/**
+ * Throw unless the sorted, de-duplicated tool names equal the expected set.
+ * The error names the missing and unexpected tools.
+ */
+export function assertMcpTools(toolNames, expected) {
+    const actualSet = new Set(toolNames);
+    const expectedSet = new Set(expected);
+    const missing = [...expectedSet].filter((n) => !actualSet.has(n)).sort();
+    const unexpected = [...actualSet].filter((n) => !expectedSet.has(n)).sort();
+    if (missing.length === 0 && unexpected.length === 0)
+        return;
+    throw new Error(`MCP tools differ. Missing: ${format(missing)}. Unexpected: ${format(unexpected)}. Actual: ${format([...actualSet].sort())}`);
+}

package/dist/mcp/cors.d.ts

@@ -0,0 +1,14 @@
+export type HeaderMap = Record<string, string>;
+/**
+ * CORS headers for every response.
+ * - `false` (default): no CORS headers, like app-a and app-c.
+ * - a header map: sent as-is, like app-b and app-d (see `mcpCors`).
+ * - a function: computed per request, e.g. to reflect `Origin` like app-e.
+ */
+export type CorsOption = false | HeaderMap | ((request: Request) => HeaderMap);
+/**
+ * server/convex's `mcpCorsHeaders(origin)` with `overrides` applied on top.
+ * app-b: `mcpCors({ "Access-Control-Allow-Headers": "Content-Type, Authorization, MCP-Protocol-Version", "Access-Control-Max-Age": "86400" })`.
+ */
+export declare function mcpCors(overrides?: HeaderMap, origin?: string): HeaderMap;
+export declare function resolveCors(cors: CorsOption | undefined, request: Request): HeaderMap;

package/dist/mcp/cors.js

@@ -0,0 +1,13 @@
+import { mcpCorsHeaders } from "../convex/index";
+/**
+ * server/convex's `mcpCorsHeaders(origin)` with `overrides` applied on top.
+ * app-b: `mcpCors({ "Access-Control-Allow-Headers": "Content-Type, Authorization, MCP-Protocol-Version", "Access-Control-Max-Age": "86400" })`.
+ */
+export function mcpCors(overrides = {}, origin) {
+    return { ...mcpCorsHeaders(origin), ...overrides };
+}
+export function resolveCors(cors, request) {
+    if (!cors)
+        return {};
+    return typeof cors === "function" ? cors(request) : cors;
+}

package/dist/mcp/dispatcher.d.ts

@@ -0,0 +1,39 @@
+import type { McpServerInfo } from "../convex/index";
+import type { HandleRpcArgs } from "./http.js";
+import { type JsonObject, type JsonValue } from "./json.js";
+import { type ProtocolVersionOptions, type RpcResult } from "./jsonRpc.js";
+import { type JsonSchemaConverter, type McpTool } from "./tools.js";
+export type McpDispatcherConfig<Principal, Ctx, Scope extends string = string> = {
+    /** `serverInfo` in the initialize result (server/convex `defineMcpServerInfo`), or a function of the scope (app-a). */
+    serverInfo: McpServerInfo | ((scope: Scope | undefined) => McpServerInfo);
+    /** Tools. Names must be unique (checked at creation). */
+    tools: ReadonlyArray<McpTool<Principal, Ctx, Scope>>;
+    /** Supported protocol versions and fallback. Default: the SDK 1.29 to 1.32 list, fallback "2025-11-25". */
+    protocol?: ProtocolVersionOptions;
+    /** `capabilities` in the initialize result. Default `{ tools: { listChanged: true } }`, as `McpServer` sends. */
+    capabilities?: JsonObject;
+    /** `instructions` in the initialize result. Omitted by default. */
+    instructions?: string;
+    /** zod to JSON Schema converter for zod 3 schemas. */
+    toJsonSchema?: JsonSchemaConverter;
+};
+export type McpDispatcher<Principal, Ctx, Scope extends string = string> = {
+    /** Same contract as `createMcpHttpHandler`'s `handleRpc`. */
+    handleRpc(args: Pick<HandleRpcArgs<Principal, Ctx, Scope>, "principal" | "json" | "ctx" | "scope">): Promise<RpcResult>;
+};
+/**
+ * A self-contained MCP JSON-RPC server for stateless HTTP: no SDK, no Node
+ * APIs. Handles initialize, ping, tools/list, tools/call, notifications
+ * (202, empty body) and batches. Other methods get -32601. Output follows
+ * MCP SDK 1.30+ with `enableJsonResponse: true`; see the README for the
+ * exact differences.
+ */
+export declare function createMcpDispatcher<Principal, Ctx, Scope extends string = string>(config: McpDispatcherConfig<Principal, Ctx, Scope>): McpDispatcher<Principal, Ctx, Scope>;
+/** Parse a JSON-RPC body string for `handleRpc`. Returns the SDK's 400 -32700 result on bad JSON. */
+export declare function parseRpcBody(body: string): {
+    ok: true;
+    json: JsonValue;
+} | {
+    ok: false;
+    result: RpcResult;
+};

package/dist/mcp/dispatcher.js

@@ -0,0 +1,105 @@
+import { isJsonObject } from "./json.js";
+import { JSON_RPC_ERROR, negotiateProtocolVersion, rpcError, rpcResult, } from "./jsonRpc.js";
+import { createToolRegistry, toolErrorResult, } from "./tools.js";
+function readMessage(value) {
+    if (!isJsonObject(value) || value.jsonrpc !== "2.0" || typeof value.method !== "string")
+        return null;
+    const id = value.id;
+    if (id !== undefined && id !== null && typeof id !== "string" && typeof id !== "number")
+        return null;
+    const params = value.params;
+    if (params !== undefined && !isJsonObject(params))
+        return null;
+    return { id, method: value.method, params: params ?? {} };
+}
+function stringOrUndefined(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * A self-contained MCP JSON-RPC server for stateless HTTP: no SDK, no Node
+ * APIs. Handles initialize, ping, tools/list, tools/call, notifications
+ * (202, empty body) and batches. Other methods get -32601. Output follows
+ * MCP SDK 1.30+ with `enableJsonResponse: true`; see the README for the
+ * exact differences.
+ */
+export function createMcpDispatcher(config) {
+    const registry = createToolRegistry(config.tools);
+    const capabilities = config.capabilities ?? { tools: { listChanged: true } };
+    async function answer(message, context) {
+        const id = message.id ?? null;
+        switch (message.method) {
+            case "initialize": {
+                const serverInfo = typeof config.serverInfo === "function" ? config.serverInfo(context.scope) : config.serverInfo;
+                return rpcResult(id, {
+                    protocolVersion: negotiateProtocolVersion(message.params.protocolVersion, config.protocol),
+                    capabilities,
+                    serverInfo,
+                    ...(config.instructions === undefined ? {} : { instructions: config.instructions }),
+                });
+            }
+            case "ping":
+                return rpcResult(id, {});
+            case "tools/list":
+                return rpcResult(id, {
+                    tools: registry.list({ scope: context.scope, toJsonSchema: config.toJsonSchema }),
+                });
+            case "tools/call": {
+                const name = stringOrUndefined(message.params.name) ?? "";
+                const tool = registry.find(name, context.scope);
+                if (!tool) {
+                    return rpcResult(id, toolErrorResult(`MCP error ${JSON_RPC_ERROR.invalidParams}: Tool ${name} not found`));
+                }
+                const args = message.params.arguments;
+                return rpcResult(id, await tool.call(isJsonObject(args) ? args : {}, context));
+            }
+            default:
+                return rpcError(id, JSON_RPC_ERROR.methodNotFound, "Method not found");
+        }
+    }
+    return {
+        async handleRpc({ principal, json, ctx, scope }) {
+            const context = { principal, ctx, scope };
+            const batch = Array.isArray(json);
+            const items = batch ? json : [json];
+            const messages = items.map(readMessage);
+            if (items.length === 0 || messages.some((message) => message === null)) {
+                return {
+                    status: 400,
+                    body: JSON.stringify({
+                        jsonrpc: "2.0",
+                        error: { code: JSON_RPC_ERROR.invalidRequest, message: "Invalid Request" },
+                        id: null,
+                    }),
+                };
+            }
+            const responses = [];
+            for (const message of messages) {
+                // Notifications (no id) get no response, as in JSON-RPC 2.0.
+                if (message && message.id !== undefined)
+                    responses.push(await answer(message, context));
+            }
+            if (responses.length === 0)
+                return { status: 202, body: "" };
+            return { status: 200, body: JSON.stringify(batch ? responses : responses[0]) };
+        },
+    };
+}
+/** Parse a JSON-RPC body string for `handleRpc`. Returns the SDK's 400 -32700 result on bad JSON. */
+export function parseRpcBody(body) {
+    try {
+        return { ok: true, json: JSON.parse(body) };
+    }
+    catch {
+        return {
+            ok: false,
+            result: {
+                status: 400,
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    error: { code: JSON_RPC_ERROR.parseError, message: "Parse error: Invalid JSON" },
+                    id: null,
+                }),
+            },
+        };
+    }
+}

package/dist/mcp/env.d.ts

@@ -0,0 +1,23 @@
+import { type EnvSource } from "../convex/index";
+/**
+ * How a fallback env var is chosen. They differ only when the primary is
+ * unset or empty, and in which name the "is not set" error mentions.
+ *
+ * | mode | rule | used by |
+ * | --- | --- | --- |
+ * | `"fallback-if-set"` | fallback only when primary is empty and fallback is non-empty; else primary | app-d |
+ * | `"prefer-primary"` | primary when non-empty, else fallback (error names the fallback) | app-c |
+ * | `"nullish"` | `env[name] ?? env[fallback]`, read as `name` (an empty primary does not fall back) | app-b |
+ */
+export type EnvFallbackMode = "fallback-if-set" | "prefer-primary" | "nullish";
+/** An env var holding a URL. A plain string is a name with no fallback. */
+export type EnvUrl = string | {
+    name: string;
+    fallback?: string;
+    fallbackMode?: EnvFallbackMode;
+};
+/**
+ * Read a URL from env through server/convex's `requiredEnvUrl` (throws
+ * "<NAME> is not set in Convex env", strips one trailing slash).
+ */
+export declare function readEnvUrl(source: EnvUrl, env?: EnvSource): string;

package/dist/mcp/env.js

@@ -0,0 +1,20 @@
+import { requiredEnvUrl } from "../convex/index";
+/**
+ * Read a URL from env through server/convex's `requiredEnvUrl` (throws
+ * "<NAME> is not set in Convex env", strips one trailing slash).
+ */
+export function readEnvUrl(source, env = process.env) {
+    if (typeof source === "string")
+        return requiredEnvUrl(source, env);
+    const { name, fallback } = source;
+    if (!fallback)
+        return requiredEnvUrl(name, env);
+    switch (source.fallbackMode ?? "fallback-if-set") {
+        case "fallback-if-set":
+            return requiredEnvUrl(!env[name] && !!env[fallback] ? fallback : name, env);
+        case "prefer-primary":
+            return requiredEnvUrl(env[name] ? name : fallback, env);
+        case "nullish":
+            return requiredEnvUrl(name, { [name]: env[name] ?? env[fallback] });
+    }
+}

package/dist/mcp/explorer.d.ts

@@ -0,0 +1,98 @@
+import { type JsonInput } from "./json.js";
+import { type McpTool, type ToolContext, type ToolResult } from "./tools.js";
+/** A table the explorer tools may read. `fields`, when given, limits filter field names. */
+export type TableEntry = {
+    name: string;
+    fields?: ReadonlyArray<string | {
+        name: string;
+    }>;
+} & object;
+/**
+ * Tables the tools accept: a fixed list (app-b, app-d), or a predicate for
+ * catalogs read at runtime (app-c: a deny-list). Names must also match
+ * `^[A-Za-z_][A-Za-z0-9_]*$`.
+ */
+export type TableCatalog = ReadonlyArray<string | TableEntry> | ((table: string) => boolean);
+export type FilterValue = string | number | boolean | null;
+/** Top-level field filters (app-d `eq` / `gte` / `lte`). */
+export type ExplorerFilters = {
+    eq?: Record<string, FilterValue>;
+    gte?: Record<string, number>;
+    lte?: Record<string, number>;
+};
+/** A validated request for the app's executor. Table names are already checked against the catalog. */
+export type ExplorerOperation = {
+    kind: "list_tables";
+} | {
+    kind: "query_table";
+    table: string;
+    order: "asc" | "desc";
+    limit: number;
+    /** `null` unless `features.cursor` is on and the caller sent one. */
+    cursor: string | null;
+    /** `null` unless `features.filters` is on and the caller sent some. */
+    filters: ExplorerFilters | null;
+} | {
+    kind: "count_table";
+    table: string;
+    filters: ExplorerFilters | null;
+} | {
+    kind: "get_document";
+    id: string;
+};
+/** Validated `run_query` arguments. `tables` is set only with `features.runQueryTables`. */
+export type RunQueryArgs = {
+    code: string;
+    tables?: string[];
+    limitPerTable?: number;
+};
+export type ExplorerToolKey = "listTables" | "queryTable" | "countTable" | "getDocument" | "runQuery";
+export type ExplorerToolsConfig<Principal, Ctx, Scope extends string = string> = {
+    tables: TableCatalog;
+    /**
+     * Run a validated operation for `context.principal`. The executor MUST
+     * enforce per-user scoping; the kit only checks names and limits. Return
+     * the payload (a string is sent as-is, anything else as pretty JSON) or
+     * `null` to deny. A throw becomes an `isError` result with its message.
+     */
+    execute: (op: ExplorerOperation, context: ToolContext<Principal, Ctx, Scope>) => Promise<JsonInput | null>;
+    /** Optional `run_query`. The kit validates arguments only; evaluation and scoping are the app's. */
+    runQuery?: (args: RunQueryArgs, context: ToolContext<Principal, Ctx, Scope>) => Promise<ToolResult>;
+    /** `limit` default and maximum for query_table. Default 100 and 1000 (app-b, app-c; app-d: 50 and 200). */
+    limits?: {
+        default?: number;
+        max?: number;
+    };
+    features?: {
+        /** `cursor` argument on query_table (app-b). Default false. */
+        cursor?: boolean;
+        /** `eq` / `gte` / `lte` on query_table and count_table (app-d). Default false. */
+        filters?: boolean;
+        /** get_document tool. Default true. */
+        getDocument?: boolean;
+        /** `tables` and `limitPerTable` on run_query (app-d). Default false. */
+        runQueryTables?: boolean;
+    };
+    names?: Partial<Record<ExplorerToolKey, string>>;
+    descriptions?: Partial<Record<ExplorerToolKey, string>>;
+    messages?: {
+        /**
+         * Unknown or malformed table, per tool. Default app-c's
+         * "Access denied: table "<t>" is not available via MCP.".
+         */
+        unknownTable?: (table: string, tool: "query_table" | "count_table" | "run_query") => string;
+        /** Executor returned `null`. Default app-b's "Cannot query table "<t>". Use list_tables." and similar. */
+        denied?: (op: ExplorerOperation) => string;
+        /** get_document id is not `^[a-zA-Z0-9_]+$`. Default app-c's text. */
+        invalidId?: string;
+    };
+    /** Scopes the tools are on (app-a-style). Omit for all. */
+    scopes?: readonly Scope[];
+};
+/**
+ * list_tables, query_table, count_table, get_document and (with `runQuery`)
+ * run_query, backed by the app's user-scoped `execute` callback. Arguments
+ * and table names are checked before the callback runs, so a table outside
+ * the catalog never reaches it. The kit never reads the database.
+ */
+export declare function createExplorerTools<Principal, Ctx, Scope extends string = string>(config: ExplorerToolsConfig<Principal, Ctx, Scope>): McpTool<Principal, Ctx, Scope>[];