@george43g/mcp-kit 1.0.0 → 3.0.0

package/dist/testing.js.map

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

package/dist/tool-registry.d.ts

@@ -7,10 +7,13 @@
  *   - the ToolDefinition (registration metadata)
  *
  * The registry collects ToolDefinitions and converts them to the SDK's
- * `Tool[]` shape via `toMcpTools()`.
+ * `Tool[]` shape via `toMcpTools()`. Both wire schemas are DERIVED from the one
+ * Zod definition per tool by `toMcpSchema()`; there is no hand-written JSON
+ * Schema path, so the wire contract cannot drift from the validator.
  */
-import type { Tool, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import type { ZodTypeAny, z } from "zod";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { RequestInfo, Tool, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 /**
  * A single MCP content block a tool may emit.
  *
@@ -33,7 +36,15 @@ export type ContentBlock = {
     data: string;
     mimeType: string;
 };
-export interface ToolDefinition<TInput extends ZodTypeAny = ZodTypeAny, TOutput extends ZodTypeAny = ZodTypeAny> {
+/**
+ * Any Zod schema, inferring `any` — the default for an unparameterised
+ * `ToolDefinition`, so a handler written against it is not forced to narrow
+ * `unknown`. This is what `ZodTypeAny` meant under Zod 3; Zod 4's `ZodTypeAny`
+ * (a deprecated compat alias) infers `unknown`, which would have made every
+ * bare `ToolDefinition` handler a type error on upgrade.
+ */
+export type AnyZodSchema = z.ZodType<any, any>;
+export interface ToolDefinition<TInput extends z.ZodType = AnyZodSchema, TOutput extends z.ZodType = AnyZodSchema> {
     /** Snake_case tool name, e.g. "health_check". */
     name: string;
     /** One-paragraph description shown to the LLM. */
@@ -68,11 +79,104 @@ export interface ToolDefinition<TInput extends ZodTypeAny = ZodTypeAny, TOutput
     toContent?: (result: z.infer<TOutput>) => ContentBlock[];
 }
 export type AnyToolDefinition = ToolDefinition<any, any>;
+/**
+ * What a tool filter is told about the request it is answering.
+ *
+ * A structural subset of the SDK's `RequestHandlerExtra` — the second argument
+ * every `server.setRequestHandler` callback receives — so a handler can pass
+ * its `extra` straight through: `registry.toMcpTools(dev, extra)` and
+ * `dispatch(name, args, extra.signal, extra)`.
+ *
+ * Every field is optional because most calls carry none of them: stdio has no
+ * auth, and an in-process caller (a CLI, a REPL, a test) has no request at all.
+ * A filter that gates on scopes therefore sees `authInfo === undefined` there,
+ * and should decide deliberately what that means for its tools.
+ */
+export interface ToolFilterContext {
+    /** Validated access token, when the transport authenticated the request (HTTP + OAuth). */
+    authInfo?: AuthInfo;
+    /** Transport session id, when the transport has sessions. */
+    sessionId?: string;
+    /** The originating HTTP request's headers, when there was one. */
+    requestInfo?: RequestInfo;
+}
+/**
+ * Per-request tool gate: return `false` to hide a tool from `tools/list` AND
+ * refuse calls to it.
+ *
+ * Synchronous on purpose: it runs inside `toMcpTools()`, which is synchronous,
+ * and a scope check is a set lookup. Resolve anything slow (a token
+ * introspection) before the request reaches the registry — the HTTP transport's
+ * auth layer is where that belongs.
+ *
+ * A filter that THROWS is treated as `false` (fail closed): a bug in the gate
+ * must not expose the tool it was written to protect.
+ */
+export type ToolFilter<TDef extends AnyToolDefinition = AnyToolDefinition> = (tool: TDef, ctx: ToolFilterContext) => boolean;
+/**
+ * `TDef` lets a consumer carry its own per-tool metadata into the filter
+ * without a cast: declare `interface ScopedTool extends ToolDefinition { scopes:
+ * string[] }`, pass `ScopedTool[]`, and the filter receives `ScopedTool`.
+ *
+ * The filter is called on EVERY `toMcpTools()` / dispatch — never cached — so a
+ * predicate that reads live state (scopes granted by a re-auth a minute ago)
+ * sees the current value. Read that state inside the predicate.
+ */
+export interface MakeRegistryOptions<TDef extends AnyToolDefinition = AnyToolDefinition> {
+    /**
+     * Optional per-request gate, applied by BOTH `toMcpTools()` and the
+     * dispatcher. It lives on the registry rather than on either consumer so the
+     * listing and the call path cannot disagree: a filter that only hid a tool
+     * from `tools/list` would leave it callable by name (see `devOnly`).
+     */
+    filter?: ToolFilter<TDef>;
+}
 export interface ToolRegistry {
     readonly tools: readonly AnyToolDefinition[];
     get(name: string): AnyToolDefinition | undefined;
-    /** Convert all tools (or just enabled ones) to MCP SDK shape. */
-    toMcpTools(includeDevOnly?: boolean): Tool[];
+    /**
+     * Whether `def` passes the registry's filter for this request. Always `true`
+     * when no filter was configured; `false` when the filter throws.
+     */
+    allows(def: AnyToolDefinition, ctx?: ToolFilterContext): boolean;
+    /**
+     * Convert tools to MCP SDK shape: devOnly tools only when `includeDevOnly`,
+     * and only tools the filter allows for `ctx`. Schemas are converted once, at
+     * `makeRegistry()`, so a call here never throws for a schema problem.
+     */
+    toMcpTools(includeDevOnly?: boolean, ctx?: ToolFilterContext): Tool[];
 }
-export declare function makeRegistry(defs: AnyToolDefinition[]): ToolRegistry;
+/** Which side of a Zod schema to describe: what a caller sends, or what parsing yields. */
+export type McpSchemaIo = "input" | "output";
+/** A JSON Schema object as emitted by `toMcpSchema`: always `type: "object"` at the top. */
+export type McpJsonSchema = {
+    type: "object";
+    [key: string]: unknown;
+};
+/**
+ * Convert a Zod schema to the JSON Schema an MCP client accepts as a tool's
+ * `inputSchema` / `outputSchema`.
+ *
+ * - **Dialect: JSON Schema 2020-12**, the MCP default. Draft-07 output (what
+ *   `zod-to-json-schema` emitted, and what mcp-kit 2.x shipped) is rejected
+ *   outright by clients that only load the 2020-12 meta-schema — Claude Code
+ *   2.1.292 throws on `"$schema": "http://json-schema.org/draft-07/schema#"`.
+ * - **`$schema` is stripped.** 2020-12 is the dialect a schema without a label
+ *   is read as under MCP, and a schema with no label gives no client a dialect
+ *   to refuse.
+ * - **`io` matters.** `"input"` describes what a caller may send (a field with
+ *   a `.default()` is optional); `"output"` describes what parsing yields (the
+ *   same field is required, and objects are closed with
+ *   `additionalProperties: false`).
+ * - **Shared sub-schemas are inlined** (`reused: "inline"`). **Cycles are not
+ *   inlinable**, so a recursive schema still carries `$defs` / `$ref` (or a
+ *   root `$ref: "#"`). That is valid 2020-12 and kept as is.
+ * - **Unrepresentable types throw**: `z.date()`, `z.bigint()`, a transform on
+ *   the output side, and so on. The error names the tool, so a registry with a
+ *   bad schema fails at startup rather than at a client's first `tools/list`.
+ * - **The top level must be an object.** MCP requires `type: "object"` for both
+ *   schemas; anything else throws, naming the tool.
+ */
+export declare function toMcpSchema(schema: z.ZodType, io: McpSchemaIo, toolName?: string): McpJsonSchema;
+export declare function makeRegistry<TDef extends AnyToolDefinition = AnyToolDefinition>(defs: TDef[], opts?: MakeRegistryOptions<TDef>): ToolRegistry;
 //# sourceMappingURL=tool-registry.d.ts.map

package/dist/tool-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGzC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAChC,oEAAoE;GAClE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,MAAM,WAAW,cAAc,CAC7B,MAAM,SAAS,UAAU,GAAG,UAAU,EACtC,OAAO,SAAS,UAAU,GAAG,UAAU;IAEvC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,MAAM,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,WAAW,EAAE,eAAe,CAAC;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACrF;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,YAAY,EAAE,CAAC;CAC1D;AAMD,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IACjD,iEAAiE;IACjE,UAAU,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,CAAC;CAC9C;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,YAAY,CA0BpE"}
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"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"}

package/dist/tool-registry.js

@@ -7,31 +7,92 @@
  *   - the ToolDefinition (registration metadata)
  *
  * The registry collects ToolDefinitions and converts them to the SDK's
- * `Tool[]` shape via `toMcpTools()`.
+ * `Tool[]` shape via `toMcpTools()`. Both wire schemas are DERIVED from the one
+ * Zod definition per tool by `toMcpSchema()`; there is no hand-written JSON
+ * Schema path, so the wire contract cannot drift from the validator.
  */
-import { zodToJsonSchema } from "zod-to-json-schema";
-export function makeRegistry(defs) {
+import { z } from "zod";
+/**
+ * Convert a Zod schema to the JSON Schema an MCP client accepts as a tool's
+ * `inputSchema` / `outputSchema`.
+ *
+ * - **Dialect: JSON Schema 2020-12**, the MCP default. Draft-07 output (what
+ *   `zod-to-json-schema` emitted, and what mcp-kit 2.x shipped) is rejected
+ *   outright by clients that only load the 2020-12 meta-schema — Claude Code
+ *   2.1.292 throws on `"$schema": "http://json-schema.org/draft-07/schema#"`.
+ * - **`$schema` is stripped.** 2020-12 is the dialect a schema without a label
+ *   is read as under MCP, and a schema with no label gives no client a dialect
+ *   to refuse.
+ * - **`io` matters.** `"input"` describes what a caller may send (a field with
+ *   a `.default()` is optional); `"output"` describes what parsing yields (the
+ *   same field is required, and objects are closed with
+ *   `additionalProperties: false`).
+ * - **Shared sub-schemas are inlined** (`reused: "inline"`). **Cycles are not
+ *   inlinable**, so a recursive schema still carries `$defs` / `$ref` (or a
+ *   root `$ref: "#"`). That is valid 2020-12 and kept as is.
+ * - **Unrepresentable types throw**: `z.date()`, `z.bigint()`, a transform on
+ *   the output side, and so on. The error names the tool, so a registry with a
+ *   bad schema fails at startup rather than at a client's first `tools/list`.
+ * - **The top level must be an object.** MCP requires `type: "object"` for both
+ *   schemas; anything else throws, naming the tool.
+ */
+export function toMcpSchema(schema, io, toolName) {
+    const where = toolName === undefined ? `${io} schema` : `tool "${toolName}" ${io} schema`;
+    let json;
+    try {
+        json = z.toJSONSchema(schema, { target: "draft-2020-12", io, reused: "inline" });
+    }
+    catch (err) {
+        throw new Error(`toMcpSchema: ${where} cannot be represented in JSON Schema: ${err?.message ?? String(err)}. ` +
+            "Use a JSON-representable type (an ISO string instead of z.date(), a number or string instead of z.bigint()), " +
+            "or move the transform out of the schema.", { cause: err });
+    }
+    delete json.$schema;
+    if (json.type !== "object") {
+        throw new Error(`toMcpSchema: ${where} must be a Zod object (JSON Schema type "object"), got ${JSON.stringify(json.type ?? null)}. ` +
+            "MCP requires tool input and output schemas to describe an object; wrap the value, e.g. z.object({ result: ... }).");
+    }
+    return json;
+}
+export function makeRegistry(defs, opts = {}) {
     const byName = new Map(defs.map((d) => [d.name, d]));
+    // Converted eagerly: a schema that cannot be represented throws HERE, at
+    // startup, naming the tool, instead of on a client's first tools/list.
+    // Keyed by definition, not name, so two definitions sharing a name (a
+    // mistake, but representable) cannot swap schemas.
+    const wire = new Map(defs.map((d) => [
+        d,
+        {
+            name: d.name,
+            description: d.description,
+            annotations: d.annotations,
+            inputSchema: toMcpSchema(d.input, "input", d.name),
+            outputSchema: toMcpSchema(d.output, "output", d.name),
+        },
+    ]));
+    const { filter } = opts;
+    const allows = (def, ctx = {}) => {
+        if (!filter)
+            return true;
+        try {
+            // Only definitions from `defs` reach here in practice; the dispatcher
+            // looks them up through `get()`.
+            return filter(def, ctx) === true;
+        }
+        catch {
+            return false;
+        }
+    };
     return {
         tools: defs,
         get(name) {
             return byName.get(name);
         },
-        toMcpTools(includeDevOnly = false) {
+        allows,
+        toMcpTools(includeDevOnly = false, ctx = {}) {
             return defs
-                .filter((d) => includeDevOnly || !d.devOnly)
-                .map((d) => 
-            // The SDK Tool type narrows inputSchema/outputSchema to a JSON-
-            // schema with `type: "object"` literal; zodToJsonSchema returns
-            // the broader JsonSchema7Type union. Cast is safe because we
-            // only ever build Zod object schemas as tool I/O.
-            ({
-                name: d.name,
-                description: d.description,
-                annotations: d.annotations,
-                inputSchema: zodToJsonSchema(d.input),
-                outputSchema: zodToJsonSchema(d.output),
-            }));
+                .filter((d) => (includeDevOnly || !d.devOnly) && allows(d, ctx))
+                .map((d) => wire.get(d));
         },
     };
 }

package/dist/tool-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAsErD,MAAM,UAAU,YAAY,CAAC,IAAyB;IACpD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,OAAO;QACL,KAAK,EAAE,IAAI;QACX,GAAG,CAAC,IAAI;YACN,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,UAAU,CAAC,cAAc,GAAG,KAAK;YAC/B,OAAO,IAAI;iBACR,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;iBAC3C,GAAG,CACF,CAAC,CAAC,EAAE,EAAE;YACJ,gEAAgE;YAChE,gEAAgE;YAChE,6DAA6D;YAC7D,kDAAkD;YAClD,CAAC;gBACC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC;gBACrC,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC;aACxC,CAAoB,CACxB,CAAC;QACN,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@george43g/mcp-kit",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "description": "MCP server building blocks: tool registry types, dispatcher with timeout/perf/abort/error-wrap baked in, stdio + Streamable HTTP transports, sanitize() for user content, UUID-gated prompt-injection helpers.",
   "type": "module",
   "license": "MIT",
@@ -33,10 +33,16 @@
       "import": "./dist/transports/stdio.js",
       "default": "./dist/transports/stdio.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "!dist/tsconfig.tsbuildinfo",
     "src",
     "!src/**/*.test.ts",
     "README.md",
@@ -51,12 +57,12 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@george43g/robustness": ">=0.12.0 <1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.23.0",
-    "zod-to-json-schema": "^3.25.0"
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
   },
   "devDependencies": {
+    "@george43g/robustness": "workspace:*",
     "@george43g/tsconfig": "workspace:*",
     "@george43g/vitest-config": "workspace:*",
     "@semantic-release/changelog": "^6.0.3",
@@ -67,6 +73,11 @@
     "semantic-release": "^24.2.0",
     "semantic-release-monorepo": "^8.0.2",
     "typescript": "^5.7.0",
-    "vitest": "^3.2.7"
+    "vitest": "^3.2.7",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@george43g/robustness": ">=0.11.0 <1",
+    "zod": "^4.0.0"
   }
 }

package/src/dispatch.ts

@@ -31,7 +31,7 @@ import {
 import type { ZodError } from "zod";
 import { wrapToolError } from "./prompt-injection.js";
 import { sanitize } from "./sanitize.js";
-import type { ContentBlock, ToolRegistry } from "./tool-registry.js";
+import type { ContentBlock, ToolFilterContext, ToolRegistry } from "./tool-registry.js";
 
 /**
  * Replace the absolute home-directory prefix with `~` in anything headed for a
@@ -121,14 +121,29 @@ export interface BuildDispatcherOptions {
   devOnlyEnabled?: () => boolean;
 }
 
-export type Dispatch = (name: string, args: unknown, signal?: AbortSignal) => Promise<ToolResult>;
+/**
+ * Call a tool by name.
+ *
+ * `ctx` is what the registry's `filter` (see `makeRegistry`) is evaluated
+ * against. From an MCP `tools/call` handler, pass the handler's `extra`:
+ * `dispatch(name, args, extra.signal, extra)`. An in-process caller omits it,
+ * and the filter sees `{}`.
+ */
+export type Dispatch = (
+  name: string,
+  args: unknown,
+  signal?: AbortSignal,
+  ctx?: ToolFilterContext,
+) => Promise<ToolResult>;
 
 function defaultTimeoutMs(): number {
   return envNum("MCP_TOOL_TIMEOUT_DEFAULT_MS", 30_000);
 }
 
 function formatZodError(err: ZodError): string {
-  return err.errors.map((e) => `  - ${e.path.join(".") || "(root)"}: ${e.message}`).join("\n");
+  return err.issues
+    .map((e) => `  - ${e.path.map(String).join(".") || "(root)"}: ${e.message}`)
+    .join("\n");
 }
 
 export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
@@ -149,7 +164,7 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
   }
 
   const fallback = defaultTimeoutMs();
-  return async (name, args, signal) => {
+  return async (name, args, signal, ctx = {}) => {
     noteActivity();
     opts.onCall?.(name);
     const def = opts.registry.get(name);
@@ -162,8 +177,12 @@ export function buildDispatcher(opts: BuildDispatcherOptions): Dispatch {
     // construction, which the readonly type discourages but does not prevent.
     // If that ever happens the tool is gated, not exposed.
     const devGated = def?.devOnly === true && !(opts.devOnlyEnabled?.() ?? false);
+    // The registry's per-request filter gates the CALL path with the same
+    // predicate that gates the listing. Hiding a tool from tools/list while it
+    // still answers by name is the hole `devOnly` already fell into once.
+    const filtered = def !== undefined && !opts.registry.allows(def, ctx);
 
-    if (!def || devGated) {
+    if (!def || devGated || filtered) {
       opts.onError?.(name, new Error("unknown_tool"));
       return {
         content: [

package/src/index.ts

@@ -23,11 +23,17 @@ export { buildResourcesHandler } from "./resources.js";
 export { CONTENT_BUDGET, sanitize, sanitizeContent } from "./sanitize.js";
 export type {
   AnyToolDefinition,
+  AnyZodSchema,
   ContentBlock,
+  MakeRegistryOptions,
+  McpJsonSchema,
+  McpSchemaIo,
   ToolDefinition,
+  ToolFilter,
+  ToolFilterContext,
   ToolRegistry,
 } from "./tool-registry.js";
-export { makeRegistry } from "./tool-registry.js";
+export { makeRegistry, toMcpSchema } from "./tool-registry.js";
 export type { HttpServerHandle, HttpServerOptions } from "./transports/http.js";
 export { startHttpServer } from "./transports/http.js";
 export type { StartStdioOptions } from "./transports/stdio.js";