@vvedantb/server 0.0.0-stage → 0.1.1

package/dist/mcp/explorer.js

@@ -0,0 +1,299 @@
+import { isJsonObject } from "./json.js";
+import { defineTool, toolErrorResult, toolJsonResult, toolTextResult, } from "./tools.js";
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DOCUMENT_ID = /^[a-zA-Z0-9_]+$/;
+const SYSTEM_FIELDS = ["_id", "_creationTime"];
+const DEFAULT_NAMES = {
+    listTables: "list_tables",
+    queryTable: "query_table",
+    countTable: "count_table",
+    getDocument: "get_document",
+    runQuery: "run_query",
+};
+const DEFAULT_DESCRIPTIONS = {
+    listTables: "List the tables you can query.",
+    queryTable: "Read a page of documents from a table, scoped to your user.",
+    countTable: "Count documents you can access in a table.",
+    getDocument: "Get a single document by Convex id. Returns null when it is missing or outside your scope.",
+    runQuery: "Run read-only query code against your scoped data.",
+};
+function defaultDenied(op) {
+    switch (op.kind) {
+        case "query_table":
+            return `Cannot query table "${op.table}". Use list_tables.`;
+        case "count_table":
+            return `Cannot count table "${op.table}".`;
+        case "get_document":
+            return "Document not found or not accessible.";
+        case "list_tables":
+            return "Cannot list tables.";
+    }
+}
+function toResult(value) {
+    return typeof value === "string" ? toolTextResult(value) : toolJsonResult(value);
+}
+class ArgError extends Error {
+}
+function optionalString(args, key) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new ArgError(`Expected string at ${key}`);
+    return value;
+}
+function requiredString(args, key) {
+    const value = optionalString(args, key);
+    if (value === undefined)
+        throw new ArgError(`Required at ${key}`);
+    return value;
+}
+function optionalNumber(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number")
+        throw new ArgError(`Expected number at ${key}`);
+    return value;
+}
+function fieldMap(value, key, accept, expected) {
+    if (value === undefined)
+        return undefined;
+    if (!isJsonObject(value))
+        throw new ArgError(`Expected object at ${key}`);
+    const out = {};
+    for (const [field, fieldValue] of Object.entries(value)) {
+        if (!accept(fieldValue))
+            throw new ArgError(`Expected ${expected} at ${key}.${field}`);
+        out[field] = fieldValue;
+    }
+    return out;
+}
+const isFilterValue = (v) => v === null || typeof v === "string" || typeof v === "boolean" || (typeof v === "number" && Number.isFinite(v));
+const isFiniteNumber = (v) => typeof v === "number" && Number.isFinite(v);
+/**
+ * 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 function createExplorerTools(config) {
+    if (typeof config.execute !== "function") {
+        throw new Error("createExplorerTools: execute is required (a user-scoped executor)");
+    }
+    if (typeof config.tables !== "function" && !Array.isArray(config.tables)) {
+        throw new Error("createExplorerTools: tables is required");
+    }
+    if (config.runQuery !== undefined && typeof config.runQuery !== "function") {
+        throw new Error("createExplorerTools: runQuery must be a function");
+    }
+    const { execute, runQuery, tables, scopes } = config;
+    const defaultLimit = config.limits?.default ?? 100;
+    const maxLimit = config.limits?.max ?? 1000;
+    if (!(defaultLimit >= 1 && maxLimit >= defaultLimit)) {
+        throw new Error("createExplorerTools: limits need 1 <= default <= max");
+    }
+    const features = config.features ?? {};
+    const names = { ...DEFAULT_NAMES, ...config.names };
+    const descriptions = { ...DEFAULT_DESCRIPTIONS, ...config.descriptions };
+    const unknownTable = config.messages?.unknownTable ??
+        ((table, _tool) => `Access denied: table "${table}" is not available via MCP.`);
+    const denied = config.messages?.denied ?? defaultDenied;
+    const invalidId = config.messages?.invalidId ?? "Invalid document ID format. IDs should be alphanumeric.";
+    const entries = typeof tables === "function" ? null : tables.map((t) => (typeof t === "string" ? { name: t } : t));
+    const entryFor = (table) => {
+        if (!IDENTIFIER.test(table))
+            return null;
+        if (typeof tables === "function")
+            return tables(table) ? { name: table } : null;
+        return entries?.find((entry) => entry.name === table) ?? null;
+    };
+    const checkFields = (entry, filters) => {
+        const allowed = entry.fields?.map((f) => (typeof f === "string" ? f : f.name));
+        for (const map of [filters.eq, filters.gte, filters.lte]) {
+            for (const field of Object.keys(map ?? {})) {
+                if (!IDENTIFIER.test(field))
+                    return `Invalid field name "${field}".`;
+                if (allowed && !allowed.includes(field) && !SYSTEM_FIELDS.includes(field)) {
+                    return `Unknown field "${field}" on table "${entry.name}".`;
+                }
+            }
+        }
+        return null;
+    };
+    const parseFilters = (args) => {
+        if (!features.filters)
+            return null;
+        const filters = {};
+        const eq = fieldMap(args.eq, "eq", isFilterValue, "string, number, boolean or null");
+        const gte = fieldMap(args.gte, "gte", isFiniteNumber, "number");
+        const lte = fieldMap(args.lte, "lte", isFiniteNumber, "number");
+        if (eq)
+            filters.eq = eq;
+        if (gte)
+            filters.gte = gte;
+        if (lte)
+            filters.lte = lte;
+        return eq || gte || lte ? filters : null;
+    };
+    const run = async (op, context) => {
+        const value = await execute(op, context);
+        return value === null ? toolErrorResult(denied(op)) : toResult(value);
+    };
+    const tableProperty = { type: "string", description: "Table name from list_tables" };
+    const filterProperties = features.filters
+        ? {
+            eq: {
+                type: "object",
+                additionalProperties: { type: ["string", "number", "boolean", "null"] },
+                description: "Top-level fields that must equal these values",
+            },
+            gte: { type: "object", additionalProperties: { type: "number" }, description: "Top-level fields >= these numbers" },
+            lte: { type: "object", additionalProperties: { type: "number" }, description: "Top-level fields <= these numbers" },
+        }
+        : {};
+    const common = { annotations: { readOnlyHint: true }, scopes };
+    const tools = [];
+    tools.push(defineTool({
+        ...common,
+        name: names.listTables,
+        description: descriptions.listTables,
+        inputSchema: { type: "object", properties: {} },
+        parseArgs: () => ({}),
+        handler: (_args, context) => run({ kind: "list_tables" }, context),
+    }));
+    const queryProperties = {
+        type: "object",
+        properties: {
+            table: tableProperty,
+            order: { type: "string", enum: ["asc", "desc"], default: "desc", description: "Sort order by creation time" },
+            limit: {
+                type: "number",
+                default: defaultLimit,
+                maximum: maxLimit,
+                description: `Max documents to return (default ${defaultLimit}, max ${maxLimit})`,
+            },
+            ...(features.cursor
+                ? { cursor: { type: "string", description: "Pagination cursor from a previous query" } }
+                : {}),
+            ...filterProperties,
+        },
+        required: ["table"],
+    };
+    tools.push(defineTool({
+        ...common,
+        name: names.queryTable,
+        description: descriptions.queryTable,
+        inputSchema: queryProperties,
+        parseArgs: (args) => {
+            const order = optionalString(args, "order") ?? "desc";
+            if (order !== "asc" && order !== "desc")
+                throw new ArgError('Expected "asc" or "desc" at order');
+            const rawLimit = optionalNumber(args, "limit");
+            const limit = rawLimit === undefined || !Number.isFinite(rawLimit)
+                ? defaultLimit
+                : Math.min(Math.max(1, Math.floor(rawLimit)), maxLimit);
+            const cursor = features.cursor ? (optionalString(args, "cursor") ?? null) : null;
+            return {
+                kind: "query_table",
+                table: requiredString(args, "table"),
+                order,
+                limit,
+                cursor,
+                filters: parseFilters(args),
+            };
+        },
+        handler: async (op, context) => {
+            const entry = entryFor(op.table);
+            if (!entry)
+                return toolErrorResult(unknownTable(op.table, op.kind));
+            const fieldError = op.filters ? checkFields(entry, op.filters) : null;
+            if (fieldError)
+                return toolErrorResult(fieldError);
+            return run(op, context);
+        },
+    }));
+    tools.push(defineTool({
+        ...common,
+        name: names.countTable,
+        description: descriptions.countTable,
+        inputSchema: { type: "object", properties: { table: tableProperty, ...filterProperties }, required: ["table"] },
+        parseArgs: (args) => ({ kind: "count_table", table: requiredString(args, "table"), filters: parseFilters(args) }),
+        handler: async (op, context) => {
+            const entry = entryFor(op.table);
+            if (!entry)
+                return toolErrorResult(unknownTable(op.table, op.kind));
+            const fieldError = op.filters ? checkFields(entry, op.filters) : null;
+            if (fieldError)
+                return toolErrorResult(fieldError);
+            return run(op, context);
+        },
+    }));
+    if (features.getDocument ?? true) {
+        tools.push(defineTool({
+            ...common,
+            name: names.getDocument,
+            description: descriptions.getDocument,
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string", description: "Convex document id" } },
+                required: ["id"],
+            },
+            parseArgs: (args) => ({ id: requiredString(args, "id") }),
+            handler: async ({ id }, context) => {
+                if (!DOCUMENT_ID.test(id))
+                    return toolErrorResult(invalidId);
+                return run({ kind: "get_document", id }, context);
+            },
+        }));
+    }
+    if (runQuery) {
+        tools.push(defineTool({
+            ...common,
+            name: names.runQuery,
+            description: descriptions.runQuery,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    code: { type: "string", description: "Handler body. Must return a value." },
+                    ...(features.runQueryTables
+                        ? {
+                            tables: { type: "array", items: { type: "string" }, description: "Tables to load" },
+                            limitPerTable: { type: "number", description: "Rows to load per table" },
+                        }
+                        : {}),
+                },
+                required: ["code"],
+            },
+            parseArgs: (args) => {
+                const parsed = { code: requiredString(args, "code") };
+                if (!features.runQueryTables)
+                    return parsed;
+                const rawTables = args.tables;
+                if (rawTables !== undefined) {
+                    if (!Array.isArray(rawTables))
+                        throw new ArgError("Expected array at tables");
+                    parsed.tables = rawTables.map((t, i) => {
+                        if (typeof t !== "string")
+                            throw new ArgError(`Expected string at tables[${i}]`);
+                        return t;
+                    });
+                }
+                const limitPerTable = optionalNumber(args, "limitPerTable");
+                if (limitPerTable !== undefined) {
+                    if (!Number.isFinite(limitPerTable))
+                        throw new ArgError("Expected finite number at limitPerTable");
+                    parsed.limitPerTable = limitPerTable;
+                }
+                return parsed;
+            },
+            handler: async (args, context) => {
+                const missing = args.tables?.find((table) => !entryFor(table));
+                if (missing !== undefined)
+                    return toolErrorResult(unknownTable(missing, "run_query"));
+                return runQuery(args, context);
+            },
+        }));
+    }
+    return tools;
+}

package/dist/mcp/http.d.ts

@@ -0,0 +1,105 @@
+import { type CorsOption, type HeaderMap } from "./cors.js";
+import type { JsonValue, Thrown } from "./json.js";
+import type { RpcResult } from "./jsonRpc.js";
+/** A Convex `httpAction` body: `httpAction(handler)`. */
+export type HttpHandler<Ctx> = (ctx: Ctx, request: Request) => Promise<Response>;
+/** Default `WWW-Authenticate` resource metadata path. */
+export declare const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+/** Response messages. Defaults are the strings every app sends today. */
+export type McpHttpMessages = {
+    missingToken: string;
+    invalidToken: string;
+    methodNotAllowed: string;
+    invalidJson: string;
+};
+export declare const DEFAULT_MCP_HTTP_MESSAGES: McpHttpMessages;
+export type McpHttpLogEvent = {
+    type: "auth-failed";
+} | {
+    type: "authenticate-threw";
+    error: Thrown;
+} | {
+    type: "invalid-json";
+    error: Thrown;
+};
+export type McpHttpLogger = (event: McpHttpLogEvent) => void;
+/**
+ * Logs with the app-a strings: "[MCP][mcpHandler] token verification failed"
+ * and "[MCP][mcpHandler] failed to parse JSON body:". app-c logs only the
+ * first (`log: (e) => e.type === "auth-failed" && consoleMcpLogger(e)`);
+ * app-b and app-d log nothing (`log: false`).
+ */
+export declare const consoleMcpLogger: McpHttpLogger;
+export type AuthenticateArgs<Ctx, Scope extends string> = {
+    /** Bearer token from the `Authorization` header (never empty). */
+    token: string;
+    request: Request;
+    ctx: Ctx;
+    scope: Scope | undefined;
+};
+export type HandleRpcArgs<Principal, Ctx, Scope extends string> = {
+    principal: Principal;
+    /** JSON-RPC body text: re-encoded (`body: "json"`) or as received (`body: "text"`). */
+    body: string;
+    /** The parsed body. */
+    json: JsonValue;
+    request: Request;
+    ctx: Ctx;
+    scope: Scope | undefined;
+};
+export type McpHttpHandlerConfig<Principal, Ctx, Scope extends string = string> = {
+    /**
+     * Verify the bearer token. Return the principal, or `null` to answer 401
+     * "Invalid or expired token". Authorisation (Pro claims, legacy JWTs, API
+     * key scopes, user lookup) belongs here, in the app.
+     */
+    authenticate: (args: AuthenticateArgs<Ctx, Scope>) => Promise<Principal | null>;
+    /**
+     * Run the JSON-RPC request. Either the app's own (for example an
+     * internalAction that runs the MCP SDK) or `createMcpDispatcher(...).handleRpc`.
+     * The result is sent with `Content-Type: application/json` plus CORS.
+     */
+    handleRpc: (args: HandleRpcArgs<Principal, Ctx, Scope>) => Promise<RpcResult>;
+    /** Opaque value passed to `authenticate` and `handleRpc` (app-a: "personal" | "team"). */
+    scope?: Scope;
+    /** Path for `WWW-Authenticate: Bearer resource_metadata="<origin><path>"`. Default `/.well-known/oauth-protected-resource`. */
+    resourceMetadataPath?: string;
+    /** Full resource metadata URL. Overrides `resourceMetadataPath`. */
+    resourceMetadataUrl?: (request: Request) => string;
+    /** Methods answered 405 (stateless server). Default `["GET", "DELETE"]`. */
+    rejectMethods?: readonly string[];
+    /** When to reject those methods. Default `"after-auth"` (all four apps); app-e checks before auth. */
+    methodCheck?: "after-auth" | "before-auth";
+    /**
+     * `"json"` (default): `JSON.stringify(await request.json())`, like app-a, app-b, app-c.
+     * `"text"`: raw text, checked with `JSON.parse`, like app-d.
+     */
+    body?: "json" | "text";
+    /** CORS on every response. Default none. With CORS set, `OPTIONS` returns a 204 preflight. */
+    cors?: CorsOption;
+    /** Extra headers on every response (after CORS). */
+    headers?: HeaderMap;
+    messages?: Partial<McpHttpMessages>;
+    /** Log hook. Default `consoleMcpLogger`; `false` for none. */
+    log?: McpHttpLogger | false;
+    /**
+     * When `authenticate` throws. `"throw"` (default, as the apps today): the
+     * error escapes, so Convex answers 500. `"unauthorized"`: log
+     * `authenticate-threw` and answer 401 "Invalid or expired token".
+     */
+    onAuthenticateError?: "throw" | "unauthorized";
+};
+/**
+ * Build the `/mcp` handler: bearer check, `authenticate`, method check,
+ * body parsing, then `handleRpc`.
+ *
+ * ```ts
+ * export const mcpHandler = httpAction(
+ *   createMcpHttpHandler<Credentials, ActionCtx>({
+ *     authenticate: ({ ctx, token }) => ctx.runAction(internal.mcp.nodeActions.verifyAccessToken, { token }),
+ *     handleRpc: ({ ctx, principal, body }) => ctx.runAction(internal.mcp.nodeActions.handleMcpRequest, { clerkUserId: principal.clerkUserId, body }),
+ *   }),
+ * );
+ * ```
+ */
+export declare function createMcpHttpHandler<Principal, Ctx, Scope extends string = string>(config: McpHttpHandlerConfig<Principal, Ctx, Scope>): HttpHandler<Ctx>;

package/dist/mcp/http.js

@@ -0,0 +1,123 @@
+import { extractBearerToken } from "../convex/index.js";
+import { resolveCors } from "./cors.js";
+/** Default `WWW-Authenticate` resource metadata path. */
+export const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+export const DEFAULT_MCP_HTTP_MESSAGES = {
+    missingToken: "Missing Authorization header",
+    invalidToken: "Invalid or expired token",
+    methodNotAllowed: "Method not supported in stateless mode",
+    invalidJson: "Invalid JSON body",
+};
+/**
+ * Logs with the app-a strings: "[MCP][mcpHandler] token verification failed"
+ * and "[MCP][mcpHandler] failed to parse JSON body:". app-c logs only the
+ * first (`log: (e) => e.type === "auth-failed" && consoleMcpLogger(e)`);
+ * app-b and app-d log nothing (`log: false`).
+ */
+export const consoleMcpLogger = (event) => {
+    switch (event.type) {
+        case "auth-failed":
+            console.error("[MCP][mcpHandler] token verification failed");
+            return;
+        case "authenticate-threw":
+            console.error("[MCP][mcpHandler] authenticate threw:", event.error);
+            return;
+        case "invalid-json":
+            console.error("[MCP][mcpHandler] failed to parse JSON body:", event.error);
+            return;
+    }
+};
+/**
+ * Build the `/mcp` handler: bearer check, `authenticate`, method check,
+ * body parsing, then `handleRpc`.
+ *
+ * ```ts
+ * export const mcpHandler = httpAction(
+ *   createMcpHttpHandler<Credentials, ActionCtx>({
+ *     authenticate: ({ ctx, token }) => ctx.runAction(internal.mcp.nodeActions.verifyAccessToken, { token }),
+ *     handleRpc: ({ ctx, principal, body }) => ctx.runAction(internal.mcp.nodeActions.handleMcpRequest, { clerkUserId: principal.clerkUserId, body }),
+ *   }),
+ * );
+ * ```
+ */
+export function createMcpHttpHandler(config) {
+    const messages = { ...DEFAULT_MCP_HTTP_MESSAGES, ...config.messages };
+    const rejectMethods = config.rejectMethods ?? ["GET", "DELETE"];
+    const methodCheck = config.methodCheck ?? "after-auth";
+    const bodyMode = config.body ?? "json";
+    const log = config.log === false ? undefined : (config.log ?? consoleMcpLogger);
+    const onAuthenticateError = config.onAuthenticateError ?? "throw";
+    const scope = config.scope;
+    return async (ctx, request) => {
+        const baseHeaders = {
+            ...resolveCors(config.cors, request),
+            ...config.headers,
+        };
+        const json = (body, status, extra = {}) => Response.json(body, {
+            status,
+            headers: { "Content-Type": "application/json", ...baseHeaders, ...extra },
+        });
+        const resourceMetadataUrl = config.resourceMetadataUrl
+            ? config.resourceMetadataUrl(request)
+            : `${new URL(request.url).origin}${config.resourceMetadataPath ?? PROTECTED_RESOURCE_METADATA_PATH}`;
+        const unauthorized = (message) => json({ error: message }, 401, {
+            "WWW-Authenticate": `Bearer resource_metadata="${resourceMetadataUrl}"`,
+        });
+        const rejectsMethod = () => rejectMethods.includes(request.method);
+        const methodNotAllowed = () => json({ error: messages.methodNotAllowed }, 405);
+        if (request.method === "OPTIONS" && config.cors) {
+            return new Response(null, { status: 204, headers: baseHeaders });
+        }
+        if (methodCheck === "before-auth" && rejectsMethod()) {
+            return methodNotAllowed();
+        }
+        const token = extractBearerToken(request.headers.get("Authorization"));
+        if (!token)
+            return unauthorized(messages.missingToken);
+        let principal;
+        try {
+            principal = await config.authenticate({ token, request, ctx, scope });
+        }
+        catch (error) {
+            if (onAuthenticateError === "throw")
+                throw error;
+            log?.({ type: "authenticate-threw", error });
+            principal = null;
+        }
+        if (principal === null || principal === undefined) {
+            log?.({ type: "auth-failed" });
+            return unauthorized(messages.invalidToken);
+        }
+        if (methodCheck === "after-auth" && rejectsMethod()) {
+            return methodNotAllowed();
+        }
+        let body;
+        let parsed;
+        try {
+            if (bodyMode === "text") {
+                body = await request.text();
+                parsed = JSON.parse(body);
+            }
+            else {
+                parsed = await request.json();
+                body = JSON.stringify(parsed);
+            }
+        }
+        catch (error) {
+            log?.({ type: "invalid-json", error });
+            return json({ error: messages.invalidJson }, 400);
+        }
+        const result = await config.handleRpc({
+            principal,
+            body,
+            json: parsed,
+            request,
+            ctx,
+            scope,
+        });
+        return new Response(result.body, {
+            status: result.status,
+            headers: { "Content-Type": "application/json", ...baseHeaders },
+        });
+    };
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,10 @@
+export { mcpCors, type CorsOption, type HeaderMap } from "./cors.js";
+export { createMcpDispatcher, parseRpcBody, type McpDispatcher, type McpDispatcherConfig, } from "./dispatcher.js";
+export { readEnvUrl, type EnvFallbackMode, type EnvUrl } from "./env.js";
+export { createExplorerTools, type ExplorerFilters, type ExplorerOperation, type ExplorerToolKey, type ExplorerToolsConfig, type FilterValue, type RunQueryArgs, type TableCatalog, type TableEntry, } from "./explorer.js";
+export { consoleMcpLogger, createMcpHttpHandler, DEFAULT_MCP_HTTP_MESSAGES, PROTECTED_RESOURCE_METADATA_PATH, type AuthenticateArgs, type HandleRpcArgs, type HttpHandler, type McpHttpHandlerConfig, type McpHttpLogEvent, type McpHttpLogger, type McpHttpMessages, } from "./http.js";
+export { errorMessage, isJsonObject, type JsonInput, type JsonObject, type JsonValue, type Thrown, } from "./json.js";
+export { JSON_RPC_ERROR, mcpInternalError, negotiateProtocolVersion, rpcError, rpcResult, SDK_PROTOCOL_VERSIONS, type JsonRpcFailure, type JsonRpcId, type JsonRpcSuccess, type ProtocolVersionOptions, type RpcResult, } from "./jsonRpc.js";
+export { createAuthorizationServerMetadataProxy, createHealthHandler, createOptionsHandler, createProtectedResourceMetadata, type AuthorizationServerMetadataProxyOptions, type HealthOptions, type OptionsHandlerOptions, type ProtectedResourceMetadataOptions, } from "./metadata.js";
+export { runSdkMcpRequest, type RunSdkMcpRequestOptions, type SdkServerLike, type SdkTransportLike, } from "./sdk.js";
+export { assertUniqueToolNames, createToolRegistry, defineTool, formatIssues, invalidArgumentsResult, runTool, toolErrorResult, toolJsonResult, toolsToList, toolTextResult, type JsonSchemaConverter, type JsonSchemaObject, type JsonSchemaToolDefinition, type McpTool, type ToolAnnotations, type ToolContent, type ToolContext, type ToolListEntry, type ToolRegistry, type ToolResult, type ToolsToListOptions, type ZodLikeSchema, type ZodToolDefinition, } from "./tools.js";

package/dist/mcp/index.js

@@ -0,0 +1,10 @@
+export { mcpCors } from "./cors.js";
+export { createMcpDispatcher, parseRpcBody, } from "./dispatcher.js";
+export { readEnvUrl } from "./env.js";
+export { createExplorerTools, } from "./explorer.js";
+export { consoleMcpLogger, createMcpHttpHandler, DEFAULT_MCP_HTTP_MESSAGES, PROTECTED_RESOURCE_METADATA_PATH, } from "./http.js";
+export { errorMessage, isJsonObject, } from "./json.js";
+export { JSON_RPC_ERROR, mcpInternalError, negotiateProtocolVersion, rpcError, rpcResult, SDK_PROTOCOL_VERSIONS, } from "./jsonRpc.js";
+export { createAuthorizationServerMetadataProxy, createHealthHandler, createOptionsHandler, createProtectedResourceMetadata, } from "./metadata.js";
+export { runSdkMcpRequest, } from "./sdk.js";
+export { assertUniqueToolNames, createToolRegistry, defineTool, formatIssues, invalidArgumentsResult, runTool, toolErrorResult, toolJsonResult, toolsToList, toolTextResult, } from "./tools.js";

package/dist/mcp/json.d.ts

@@ -0,0 +1,18 @@
+/** A JSON value as produced by `JSON.parse`. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A JSON object as produced by `JSON.parse`. */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * Anything `JSON.stringify` turns into JSON text. Wider than `JsonValue` so
+ * Convex documents with optional fields can be passed without a cast.
+ */
+export type JsonInput = object | string | number | boolean | null;
+export declare function isJsonObject(value: JsonValue | undefined): value is JsonObject;
+/** Any thrown value. `catch` bindings are assignable to it without a cast. */
+export type Thrown = {} | null | undefined;
+/** `err.message` for an `Error`, otherwise `String(err)`, like the MCP SDK. */
+export declare function errorMessage(err: Thrown): string;

package/dist/mcp/json.js

@@ -0,0 +1,7 @@
+export function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** `err.message` for an `Error`, otherwise `String(err)`, like the MCP SDK. */
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/mcp/jsonRpc.d.ts

@@ -0,0 +1,61 @@
+import type { JsonValue, Thrown } from "./json.js";
+export type JsonRpcId = string | number | null;
+/** JSON-RPC 2.0 error codes used by MCP. */
+export declare const JSON_RPC_ERROR: {
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+};
+/** A JSON-RPC 2.0 success response. */
+export type JsonRpcSuccess = {
+    result: JsonValue | object;
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+};
+/** A JSON-RPC 2.0 error response. */
+export type JsonRpcFailure = {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    error: {
+        code: number;
+        message: string;
+    };
+};
+/**
+ * What `handleRpc` returns: an HTTP status and the response body text.
+ * Same shape as the apps' `handleMcpRequest` internalAction result.
+ */
+export type RpcResult = {
+    status: number;
+    body: string;
+};
+/**
+ * The 500 body the apps' `handleMcpRequest` returns when it throws:
+ * `{"jsonrpc":"2.0","error":{"code":-32603,"message":...},"id":null}`.
+ * The message is `err.message`, or "Internal server error" for non-Errors.
+ */
+export declare function mcpInternalError(err: Thrown): RpcResult;
+/** Success response. Key order matches the MCP SDK: result, jsonrpc, id. */
+export declare function rpcResult(id: JsonRpcId, result: JsonValue | object): JsonRpcSuccess;
+/** Error response. Key order matches the MCP SDK: jsonrpc, id, error. */
+export declare function rpcError(id: JsonRpcId, code: number, message: string): JsonRpcFailure;
+/**
+ * Protocol versions the MCP SDK 1.29.0 to 1.32.1 accept (the versions the
+ * apps lock today), newest first. `SUPPORTED_PROTOCOL_VERSIONS` in the SDK's
+ * `types.js`.
+ */
+export declare const SDK_PROTOCOL_VERSIONS: readonly string[];
+export type ProtocolVersionOptions = {
+    /** Versions the server accepts. Default `SDK_PROTOCOL_VERSIONS`. */
+    versions?: readonly string[];
+    /** Answer for an unsupported or missing request. Default `versions[0]`, like the SDK. */
+    fallback?: string;
+};
+/**
+ * Echo the client's version when supported, else the fallback. The SDK
+ * falls back to its latest version; app-e's gateway falls back to
+ * "2025-03-26" (`{ versions: ["2025-06-18", "2025-03-26", "2024-11-05"], fallback: "2025-03-26" }`).
+ */
+export declare function negotiateProtocolVersion(requested: JsonValue | undefined, options?: ProtocolVersionOptions): string;