@vvedantb/server 0.0.0-stage → 0.1.1

package/dist/mcp/jsonRpc.js

@@ -0,0 +1,60 @@
+/** JSON-RPC 2.0 error codes used by MCP. */
+export const JSON_RPC_ERROR = {
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+};
+/**
+ * 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 function mcpInternalError(err) {
+    const message = err instanceof Error ? err.message : "Internal server error";
+    return {
+        status: 500,
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            error: { code: JSON_RPC_ERROR.internalError, message },
+            id: null,
+        }),
+    };
+}
+/** Success response. Key order matches the MCP SDK: result, jsonrpc, id. */
+export function rpcResult(id, result) {
+    return { result, jsonrpc: "2.0", id };
+}
+/** Error response. Key order matches the MCP SDK: jsonrpc, id, error. */
+export function rpcError(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+}
+/**
+ * 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 const SDK_PROTOCOL_VERSIONS = [
+    "2025-11-25",
+    "2025-06-18",
+    "2025-03-26",
+    "2024-11-05",
+    "2024-10-07",
+];
+/**
+ * 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 function negotiateProtocolVersion(requested, options = {}) {
+    const versions = options.versions ?? SDK_PROTOCOL_VERSIONS;
+    if (typeof requested === "string" && versions.includes(requested)) {
+        return requested;
+    }
+    const fallback = options.fallback ?? versions[0];
+    if (fallback === undefined) {
+        throw new Error("negotiateProtocolVersion needs at least one version");
+    }
+    return fallback;
+}

package/dist/mcp/metadata.d.ts

@@ -0,0 +1,59 @@
+import type { EnvSource } from "../convex/index.js";
+import { type CorsOption, type HeaderMap } from "./cors.js";
+import { type EnvUrl } from "./env.js";
+import type { HttpHandler } from "./http.js";
+import type { JsonInput } from "./json.js";
+type CommonOptions = {
+    /** CORS on every response. Default none. */
+    cors?: CorsOption;
+    /** Extra headers on every response (after CORS). */
+    headers?: HeaderMap;
+    /** Env source, read on each request. Default `process.env`. */
+    env?: EnvSource;
+};
+export type AuthorizationServerMetadataProxyOptions = CommonOptions & {
+    /** Issuer URL env var. Default `CLERK_FRONTEND_API_URL`. */
+    issuer?: EnvUrl;
+    /**
+     * How the upstream body is returned on 200:
+     * - `"json"` (default): `Response.json(await res.json())`, like app-a and app-e.
+     * - `"text"`: `await res.text()` as `application/json`, like app-c and app-d.
+     * - `"stream"`: `res.body` streamed as `application/json`, like app-b.
+     */
+    forward?: "json" | "text" | "stream";
+    /** Fetch implementation. Default the global `fetch` at request time. */
+    fetch?: (url: string) => Promise<Response>;
+};
+/**
+ * `GET /.well-known/oauth-authorization-server`: proxy
+ * `<issuer>/.well-known/oauth-authorization-server`. On a non-2xx upstream,
+ * 502 `{"error":"Failed to fetch authorization server metadata"}`.
+ */
+export declare function createAuthorizationServerMetadataProxy(options?: AuthorizationServerMetadataProxyOptions): HttpHandler<object>;
+export type ProtectedResourceMetadataOptions = CommonOptions & {
+    /** Resource path on this origin. Default `/mcp` (app-a team: `/mcp/team`). */
+    resourcePath?: string;
+    /** Authorization server URL env var. Default `CLERK_FRONTEND_API_URL`. */
+    authorizationServer?: EnvUrl;
+    /** `resource_documentation` URL env var. Default `WEB_APP_URL`. */
+    documentation?: EnvUrl;
+};
+/**
+ * `GET /.well-known/oauth-protected-resource[/...]`:
+ * `{ resource, authorization_servers: [issuer], bearer_methods_supported: ["header"], resource_documentation }`.
+ * Env is read on each request, issuer first, so a missing var throws like the apps.
+ */
+export declare function createProtectedResourceMetadata(options?: ProtectedResourceMetadataOptions): HttpHandler<object>;
+export type HealthOptions = Omit<CommonOptions, "env"> & {
+    /** Body. Default `{ status: "ok" }`. app-e: `{ status: "ok", service: "app-e" }`. */
+    body?: JsonInput;
+};
+/** `GET /health`: 200 JSON, `{"status":"ok"}` by default. */
+export declare function createHealthHandler(options?: HealthOptions): HttpHandler<object>;
+export type OptionsHandlerOptions = {
+    cors: CorsOption;
+    headers?: HeaderMap;
+};
+/** `OPTIONS` preflight: 204, no body, CORS headers only. */
+export declare function createOptionsHandler(options: OptionsHandlerOptions): HttpHandler<object>;
+export {};

package/dist/mcp/metadata.js

@@ -0,0 +1,63 @@
+import { resolveCors } from "./cors.js";
+import { readEnvUrl } from "./env.js";
+function headersFor(options, request) {
+    return { ...resolveCors(options.cors, request), ...options.headers };
+}
+/**
+ * `GET /.well-known/oauth-authorization-server`: proxy
+ * `<issuer>/.well-known/oauth-authorization-server`. On a non-2xx upstream,
+ * 502 `{"error":"Failed to fetch authorization server metadata"}`.
+ */
+export function createAuthorizationServerMetadataProxy(options = {}) {
+    const forward = options.forward ?? "json";
+    return async (_ctx, request) => {
+        const issuer = readEnvUrl(options.issuer ?? "CLERK_FRONTEND_API_URL", options.env);
+        const url = `${issuer}/.well-known/oauth-authorization-server`;
+        const res = await (options.fetch ? options.fetch(url) : fetch(url));
+        const headers = headersFor(options, request);
+        if (!res.ok) {
+            return Response.json({ error: "Failed to fetch authorization server metadata" }, { status: 502, headers: { "Content-Type": "application/json", ...headers } });
+        }
+        if (forward === "json") {
+            const metadata = await res.json();
+            return Response.json(metadata, {
+                headers: { "Content-Type": "application/json", ...headers },
+            });
+        }
+        const body = forward === "text" ? await res.text() : res.body;
+        return new Response(body, {
+            status: 200,
+            headers: { "Content-Type": "application/json", ...headers },
+        });
+    };
+}
+/**
+ * `GET /.well-known/oauth-protected-resource[/...]`:
+ * `{ resource, authorization_servers: [issuer], bearer_methods_supported: ["header"], resource_documentation }`.
+ * Env is read on each request, issuer first, so a missing var throws like the apps.
+ */
+export function createProtectedResourceMetadata(options = {}) {
+    const resourcePath = options.resourcePath ?? "/mcp";
+    return async (_ctx, request) => {
+        const origin = new URL(request.url).origin;
+        return Response.json({
+            resource: `${origin}${resourcePath}`,
+            authorization_servers: [
+                readEnvUrl(options.authorizationServer ?? "CLERK_FRONTEND_API_URL", options.env),
+            ],
+            bearer_methods_supported: ["header"],
+            resource_documentation: readEnvUrl(options.documentation ?? "WEB_APP_URL", options.env),
+        }, { headers: { "Content-Type": "application/json", ...headersFor(options, request) } });
+    };
+}
+/** `GET /health`: 200 JSON, `{"status":"ok"}` by default. */
+export function createHealthHandler(options = {}) {
+    const body = options.body ?? { status: "ok" };
+    return async (_ctx, request) => Response.json(body, {
+        headers: { "Content-Type": "application/json", ...headersFor(options, request) },
+    });
+}
+/** `OPTIONS` preflight: 204, no body, CORS headers only. */
+export function createOptionsHandler(options) {
+    return async (_ctx, request) => new Response(null, { status: 204, headers: headersFor(options, request) });
+}

package/dist/mcp/sdk.d.ts

@@ -0,0 +1,56 @@
+import { type RpcResult } from "./jsonRpc.js";
+import type { JsonValue, Thrown } from "./json.js";
+/** The part of `WebStandardStreamableHTTPServerTransport` this helper uses. */
+export type SdkTransportLike = {
+    handleRequest(request: Request, options?: {
+        parsedBody?: JsonValue;
+    }): Promise<Response>;
+};
+/** The part of `McpServer` this helper uses. */
+export type SdkServerLike<Transport> = {
+    connect(transport: Transport): Promise<void>;
+};
+export type RunSdkMcpRequestOptions<Transport extends SdkTransportLike> = {
+    /**
+     * Build a fresh, fully registered `McpServer` (one per request, as
+     * stateless mode needs). Called inside the error boundary, after the body
+     * is parsed, so a registration error also becomes the 500 result.
+     */
+    createServer: () => NoInfer<SdkServerLike<Transport>> | Promise<NoInfer<SdkServerLike<Transport>>>;
+    /** `WebStandardStreamableHTTPServerTransport` from `@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js`. */
+    Transport: new (options: {
+        sessionIdGenerator: undefined;
+        enableJsonResponse: boolean;
+    }) => Transport;
+    /** JSON-RPC body text from `createMcpHttpHandler`. */
+    body: string;
+    /** URL of the synthetic request. Default `http://localhost/mcp` (app-a team: `http://localhost/mcp/team`). */
+    url?: string;
+    /**
+     * Pass `JSON.parse(body)` as `parsedBody`, like app-a, app-b and app-c
+     * (default `true`). app-d passes nothing and lets the transport read the body.
+     */
+    parsedBody?: boolean;
+    /** Called with the error before the 500 result. Default logs "[MCP][handleMcpRequest] threw:". */
+    onError?: (message: string, error: Thrown) => void;
+};
+/**
+ * The body of the apps' `handleMcpRequest` internalAction: connect a
+ * stateless JSON-response transport, post the body, return
+ * `{ status, body }`; on a throw, 500 with a JSON-RPC -32603 error.
+ * The kit does not import the SDK; pass its classes in.
+ *
+ * ```ts
+ * // nodeActions.ts ("use node")
+ * return runSdkMcpRequest({
+ *   body,
+ *   Transport: WebStandardStreamableHTTPServerTransport,
+ *   createServer: () => {
+ *     const server = new McpServer(serverInfo);
+ *     registerTools(server, clerkUserId, ctx);
+ *     return server;
+ *   },
+ * });
+ * ```
+ */
+export declare function runSdkMcpRequest<Transport extends SdkTransportLike>(options: RunSdkMcpRequestOptions<Transport>): Promise<RpcResult>;

package/dist/mcp/sdk.js

@@ -0,0 +1,52 @@
+import { mcpInternalError } from "./jsonRpc.js";
+/**
+ * The body of the apps' `handleMcpRequest` internalAction: connect a
+ * stateless JSON-response transport, post the body, return
+ * `{ status, body }`; on a throw, 500 with a JSON-RPC -32603 error.
+ * The kit does not import the SDK; pass its classes in.
+ *
+ * ```ts
+ * // nodeActions.ts ("use node")
+ * return runSdkMcpRequest({
+ *   body,
+ *   Transport: WebStandardStreamableHTTPServerTransport,
+ *   createServer: () => {
+ *     const server = new McpServer(serverInfo);
+ *     registerTools(server, clerkUserId, ctx);
+ *     return server;
+ *   },
+ * });
+ * ```
+ */
+export async function runSdkMcpRequest(options) {
+    try {
+        const parsedBody = options.parsedBody === false ? undefined : JSON.parse(options.body);
+        const server = await options.createServer();
+        const transport = new options.Transport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        await server.connect(transport);
+        const request = new Request(options.url ?? "http://localhost/mcp", {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream",
+            },
+            body: options.body,
+        });
+        const response = parsedBody === undefined
+            ? await transport.handleRequest(request)
+            : await transport.handleRequest(request, { parsedBody });
+        return { status: response.status, body: await response.text() };
+    }
+    catch (err) {
+        const result = mcpInternalError(err);
+        const message = err instanceof Error ? err.message : "Internal server error";
+        if (options.onError)
+            options.onError(message, err);
+        else
+            console.error("[MCP][handleMcpRequest] threw:", message, err);
+        return result;
+    }
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,176 @@
+import { type JsonInput, type JsonObject, type JsonValue } from "./json.js";
+export type ToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "audio";
+    data: string;
+    mimeType: string;
+};
+/** An MCP `tools/call` result. */
+export type ToolResult = {
+    content: ToolContent[];
+    isError?: boolean;
+    structuredContent?: {
+        [key: string]: JsonInput;
+    };
+};
+/** `{ content: [{ type: "text", text }] }` (app-d `textResult`). */
+export declare function toolTextResult(text: string): ToolResult;
+/** Pretty JSON text, `JSON.stringify(data, null, 2)` (app-b and app-c `textResult`). */
+export declare function toolJsonResult(data: JsonInput): ToolResult;
+/** `{ content: [{ type: "text", text: message }], isError: true }` (every app's `errorResult`). */
+export declare function toolErrorResult(message: string): ToolResult;
+/**
+ * Run `fn` and return its value as pretty JSON, or its error as an error
+ * result. `errorLabel` prefixes the message (app-a: "Files get failed: ...").
+ * A value with no JSON form becomes "Result is not JSON" (app-d `jsonTool`).
+ */
+export declare function runTool(fn: () => Promise<JsonInput | undefined>, options?: {
+    errorLabel?: string;
+}): Promise<ToolResult>;
+/** MCP tool annotations (hints only). */
+export type ToolAnnotations = {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+};
+type Issue = {
+    path: ReadonlyArray<PropertyKey>;
+    message: string;
+};
+/**
+ * The part of a zod schema (3.25+ or 4) the kit uses. The kit never imports
+ * zod; any object with this shape works.
+ */
+export type ZodLikeSchema<Out> = {
+    safeParse(data: JsonValue): {
+        success: true;
+        data: Out;
+    } | {
+        success: false;
+        error: {
+            issues: ReadonlyArray<Issue>;
+        };
+    };
+    /** Present on zod 4 schemas. Used for `tools/list` when no converter is given. */
+    toJSONSchema?(params: {
+        target: "draft-7";
+        io: "input";
+    }): object;
+};
+/** A raw JSON Schema object (`{ type: "object", properties: {...} }`). Args are not validated unless `parseArgs` is given. */
+export type JsonSchemaObject = {
+    type: "object";
+    properties?: object;
+    required?: readonly string[];
+} & object;
+/**
+ * Turn a zod schema into JSON Schema for `tools/list`. Needed for zod 3,
+ * whose schemas have no `toJSONSchema()`:
+ * `(schema) => (schema instanceof ZodType ? zodToJsonSchema(schema) : {})`.
+ */
+export type JsonSchemaConverter = (schema: ZodLikeSchema<object>) => object;
+/** What a tool handler receives besides its arguments. */
+export type ToolContext<Principal, Ctx, Scope extends string = string> = {
+    principal: Principal;
+    ctx: Ctx;
+    scope: Scope | undefined;
+};
+type ToolMeta<Scope extends string> = {
+    name: string;
+    title?: string;
+    /** A string, or a function of the scope (app-a: personal vs team wording). */
+    description: string | ((scope: Scope | undefined) => string);
+    annotations?: ToolAnnotations;
+    /** Scopes the tool is listed and callable on. Omit for all (app-a `scopes`). */
+    scopes?: readonly Scope[];
+};
+export type ZodToolDefinition<Args extends object, Principal, Ctx, Scope extends string> = ToolMeta<Scope> & {
+    inputSchema: ZodLikeSchema<Args>;
+    /** JSON Schema for `tools/list`. Overrides any converter. */
+    jsonSchema?: object;
+    handler: (args: Args, context: ToolContext<Principal, Ctx, Scope>) => Promise<ToolResult>;
+};
+export type JsonSchemaToolDefinition<Args extends object, Principal, Ctx, Scope extends string> = ToolMeta<Scope> & {
+    inputSchema: JsonSchemaObject;
+    /** Validate and normalise raw arguments. Throw to reject; the message becomes the validation error. */
+    parseArgs: (args: JsonObject) => Args;
+    handler: (args: Args, context: ToolContext<Principal, Ctx, Scope>) => Promise<ToolResult>;
+};
+/** A defined tool. Arguments are validated inside `call`. */
+export type McpTool<Principal, Ctx, Scope extends string = string> = {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string | ((scope: Scope | undefined) => string);
+    readonly annotations?: ToolAnnotations;
+    /** Scopes the tool is on (typed as `Scope[]` in `defineTool`; plain strings here so unscoped tools fit any registry). */
+    readonly scopes?: readonly string[];
+    /** JSON Schema for `tools/list`. */
+    inputJsonSchema(convert?: JsonSchemaConverter): object;
+    /**
+     * Validate `args`, run the handler, and shape errors like the MCP SDK:
+     * invalid args become an `isError` result starting
+     * "MCP error -32602: Input validation error: Invalid arguments for tool <name>: ",
+     * a thrown error becomes an `isError` result with its message.
+     */
+    call(args: JsonObject, context: ToolContext<Principal, Ctx, Scope>): Promise<ToolResult>;
+};
+/** Format zod issues like MCP SDK 1.30+: "<message> at <path>", one per line. */
+export declare function formatIssues(issues: ReadonlyArray<Issue>): string;
+export declare function invalidArgumentsResult(toolName: string, detail: string): ToolResult;
+/**
+ * Define a tool with a zod object schema (3.25+ or 4) or a raw JSON Schema
+ * plus `parseArgs`. Type the handler's second parameter to fix
+ * `Principal` and `Ctx`:
+ *
+ * ```ts
+ * defineTool({
+ *   name: "search",
+ *   description: "Search your notes.",
+ *   inputSchema: z.object({ query: z.string() }),
+ *   handler: async ({ query }, { principal, ctx }: ToolContext<Principal, ActionCtx>) =>
+ *     toolJsonResult(await ctx.runQuery(internal.search, { userId: principal.userId, query })),
+ * });
+ * ```
+ */
+export declare function defineTool<Args extends object, Principal, Ctx, Scope extends string = string>(definition: ZodToolDefinition<Args, Principal, Ctx, Scope> | JsonSchemaToolDefinition<Args, Principal, Ctx, Scope>): McpTool<Principal, Ctx, Scope>;
+/** A `tools/list` entry. */
+export type ToolListEntry = {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: object;
+    annotations?: ToolAnnotations;
+};
+/** Throw when two tools share a name. */
+export declare function assertUniqueToolNames(tools: ReadonlyArray<{
+    name: string;
+}>): void;
+export type ToolsToListOptions<Scope extends string> = {
+    /** Keep only tools available on this scope. Tools without `scopes` are always kept. */
+    scope?: Scope;
+    /** zod to JSON Schema converter for schemas without `toJSONSchema()` (zod 3). */
+    toJsonSchema?: JsonSchemaConverter;
+};
+/** Build the `tools/list` result array, in definition order. */
+export declare function toolsToList<Principal, Ctx, Scope extends string>(tools: ReadonlyArray<McpTool<Principal, Ctx, Scope>>, options?: ToolsToListOptions<Scope>): ToolListEntry[];
+export type ToolRegistry<Principal, Ctx, Scope extends string> = {
+    readonly tools: ReadonlyArray<McpTool<Principal, Ctx, Scope>>;
+    /** Tools on a scope (all tools without `scopes`, plus those listing it). */
+    forScope(scope: Scope | undefined): ReadonlyArray<McpTool<Principal, Ctx, Scope>>;
+    /** Names on a scope, for `assertMcpTools` from server/convex. */
+    names(scope?: Scope): string[];
+    /** The tool with this name on this scope, or `undefined`. */
+    find(name: string, scope: Scope | undefined): McpTool<Principal, Ctx, Scope> | undefined;
+    list(options?: ToolsToListOptions<Scope>): ToolListEntry[];
+};
+/** A tool list with a name-uniqueness check (throws at creation) and scope filtering. */
+export declare function createToolRegistry<Principal, Ctx, Scope extends string = string>(tools: ReadonlyArray<McpTool<Principal, Ctx, Scope>>): ToolRegistry<Principal, Ctx, Scope>;
+export {};

package/dist/mcp/tools.js

@@ -0,0 +1,159 @@
+import { errorMessage } from "./json.js";
+import { JSON_RPC_ERROR } from "./jsonRpc.js";
+/** `{ content: [{ type: "text", text }] }` (app-d `textResult`). */
+export function toolTextResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+/** Pretty JSON text, `JSON.stringify(data, null, 2)` (app-b and app-c `textResult`). */
+export function toolJsonResult(data) {
+    return toolTextResult(JSON.stringify(data, null, 2));
+}
+/** `{ content: [{ type: "text", text: message }], isError: true }` (every app's `errorResult`). */
+export function toolErrorResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/**
+ * Run `fn` and return its value as pretty JSON, or its error as an error
+ * result. `errorLabel` prefixes the message (app-a: "Files get failed: ...").
+ * A value with no JSON form becomes "Result is not JSON" (app-d `jsonTool`).
+ */
+export async function runTool(fn, options = {}) {
+    const label = (message) => options.errorLabel ? `${options.errorLabel}: ${message}` : message;
+    try {
+        const text = JSON.stringify(await fn(), null, 2);
+        // JSON.stringify returns undefined for undefined, functions and symbols.
+        if (typeof text !== "string")
+            return toolErrorResult(label("Result is not JSON"));
+        return toolTextResult(text);
+    }
+    catch (err) {
+        return toolErrorResult(label(err instanceof Error ? err.message : "Tool failed"));
+    }
+}
+function dotPath(path) {
+    if (path.length === 0)
+        return "object root";
+    return path.reduce((acc, seg, index) => {
+        if (index === 0)
+            return String(seg);
+        if (typeof seg === "number")
+            return `${acc}[${seg}]`;
+        return `${acc}.${String(seg)}`;
+    }, "");
+}
+/** Format zod issues like MCP SDK 1.30+: "<message> at <path>", one per line. */
+export function formatIssues(issues) {
+    return issues
+        .map((issue) => (issue.path.length ? `${issue.message} at ${dotPath(issue.path)}` : issue.message))
+        .join("\n");
+}
+export function invalidArgumentsResult(toolName, detail) {
+    return toolErrorResult(`MCP error ${JSON_RPC_ERROR.invalidParams}: Input validation error: Invalid arguments for tool ${toolName}: ${detail}`);
+}
+function isZodTool(definition) {
+    return "safeParse" in definition.inputSchema;
+}
+/**
+ * Define a tool with a zod object schema (3.25+ or 4) or a raw JSON Schema
+ * plus `parseArgs`. Type the handler's second parameter to fix
+ * `Principal` and `Ctx`:
+ *
+ * ```ts
+ * defineTool({
+ *   name: "search",
+ *   description: "Search your notes.",
+ *   inputSchema: z.object({ query: z.string() }),
+ *   handler: async ({ query }, { principal, ctx }: ToolContext<Principal, ActionCtx>) =>
+ *     toolJsonResult(await ctx.runQuery(internal.search, { userId: principal.userId, query })),
+ * });
+ * ```
+ */
+export function defineTool(definition) {
+    if (!definition.name)
+        throw new Error("MCP tool name must not be empty");
+    const parse = (raw) => {
+        if (isZodTool(definition)) {
+            const result = definition.inputSchema.safeParse(raw);
+            return result.success
+                ? { ok: true, args: result.data }
+                : { ok: false, detail: formatIssues(result.error.issues) };
+        }
+        try {
+            return { ok: true, args: definition.parseArgs(raw) };
+        }
+        catch (err) {
+            return { ok: false, detail: errorMessage(err) };
+        }
+    };
+    return {
+        name: definition.name,
+        title: definition.title,
+        description: definition.description,
+        annotations: definition.annotations,
+        scopes: definition.scopes,
+        inputJsonSchema(convert) {
+            if (!isZodTool(definition))
+                return definition.inputSchema;
+            if (definition.jsonSchema)
+                return definition.jsonSchema;
+            if (convert)
+                return convert(definition.inputSchema);
+            if (definition.inputSchema.toJSONSchema) {
+                return definition.inputSchema.toJSONSchema({ target: "draft-7", io: "input" });
+            }
+            throw new Error(`MCP tool ${definition.name}: schema has no toJSONSchema(); pass jsonSchema or a toJsonSchema converter (zod 3)`);
+        },
+        async call(args, context) {
+            const parsed = parse(args);
+            if (!parsed.ok)
+                return invalidArgumentsResult(definition.name, parsed.detail);
+            try {
+                return await definition.handler(parsed.args, context);
+            }
+            catch (err) {
+                return toolErrorResult(errorMessage(err));
+            }
+        },
+    };
+}
+function availableIn(tool, scope) {
+    return !tool.scopes || (scope !== undefined && tool.scopes.includes(scope));
+}
+/** Throw when two tools share a name. */
+export function assertUniqueToolNames(tools) {
+    const seen = new Set();
+    for (const tool of tools) {
+        if (seen.has(tool.name))
+            throw new Error(`Duplicate MCP tool name: ${tool.name}`);
+        seen.add(tool.name);
+    }
+}
+/** Build the `tools/list` result array, in definition order. */
+export function toolsToList(tools, options = {}) {
+    return tools
+        .filter((tool) => availableIn(tool, options.scope))
+        .map((tool) => {
+        const entry = {
+            name: tool.name,
+            description: typeof tool.description === "function" ? tool.description(options.scope) : tool.description,
+            inputSchema: tool.inputJsonSchema(options.toJsonSchema),
+        };
+        if (tool.title !== undefined)
+            entry.title = tool.title;
+        if (tool.annotations !== undefined)
+            entry.annotations = tool.annotations;
+        return entry;
+    });
+}
+/** A tool list with a name-uniqueness check (throws at creation) and scope filtering. */
+export function createToolRegistry(tools) {
+    assertUniqueToolNames(tools);
+    const forScope = (scope) => tools.filter((tool) => availableIn(tool, scope));
+    return {
+        tools,
+        forScope,
+        names: (scope) => forScope(scope).map((tool) => tool.name),
+        find: (name, scope) => forScope(scope).find((tool) => tool.name === name),
+        list: (options) => toolsToList(tools, options),
+    };
+}