@kubb/plugin-mcp 5.2.0 → 5.2.3

package/dist/index.d.cts

@@ -0,0 +1,241 @@
+import { Exclude, Group, Include, Output, OutputOptions, Override, PluginType, Resolver, ResolverPatch, ast } from "kubb/kit";
+import { ResolverTs } from "@kubb/plugin-ts";
+import { KubbReactNode } from "kubb/jsx";
+import "@kubb/plugin-zod";
+//#region src/components/McpHandler.d.ts
+type Props$1 = {
+  /**
+   * Name of the handler function.
+   */
+  name: string;
+  /**
+   * Name of the contract client `<op>` the handler calls.
+   */
+  clientName: string;
+  /**
+   * AST operation node.
+   */
+  node: ast.HttpOperationNode;
+  /**
+   * TypeScript resolver for resolving param/data/response type names.
+   */
+  resolver: ResolverTs;
+  /**
+   * The registered client plugin's `returnType`, read by the caller off `resolveClientOperation`.
+   */
+  returnType?: 'full' | 'data' | 'plain';
+};
+export declare function McpHandler({ name, clientName, node, resolver, returnType }: Props$1): KubbReactNode;
+//#endregion
+//#region src/components/Server.d.ts
+type ZodParam = {
+  name: string;
+  schemaName: string;
+};
+type Props = {
+  /**
+   * Human-readable server name passed to `new McpServer({ name })`.
+   */
+  serverName: string;
+  /**
+   * Semantic version string passed to `new McpServer({ version })`.
+   */
+  serverVersion: string;
+  /**
+   * Operations to register as MCP tools, each carrying its handler,
+   * zod schema, and AST node metadata.
+   */
+  operations: Array<{
+    tool: {
+      name: string;
+      title?: string;
+      description: string;
+    };
+    mcp: {
+      name: string;
+      file: ast.FileNode;
+    };
+    zod: {
+      pathParams: Array<ZodParam>;
+      /**
+       * Query params — individual schemas to compose into `z.object({ ... })`.
+       */
+      queryParams?: Array<ZodParam> | null;
+      /**
+       * Header params — individual schemas to compose into `z.object({ ... })`.
+       */
+      headerParams?: Array<ZodParam> | null;
+      requestName?: string | null;
+      responseName?: string | null;
+    };
+  }>;
+};
+export declare function Server({ serverName, serverVersion, operations }: Props): KubbReactNode;
+//#endregion
+//#region ../../internals/client/src/resolveClient.d.ts
+/**
+ * The client selector accepted by a consumer's `client` option. Each calls a registered contract
+ * client plugin.
+ */
+type ClientSelector = 'fetch' | 'axios' | 'client';
+/**
+ * The resolved client strategy stored in a consumer plugin's options: the generated code always
+ * imports and calls a registered contract client plugin's `<op>`. The client runtime lives in
+ * plugin-axios / plugin-fetch, so nothing is bundled by the consumer.
+ */
+type ResolvedContractClient = {
+  kind: 'contract';
+  pluginName: string;
+};
+//#endregion
+//#region src/types.d.ts
+/**
+ * Resolver for MCP that provides naming methods for handler functions.
+ */
+type ResolverMcp = Resolver & {
+  /**
+   * Naming for the generated MCP tool handler functions.
+   */
+  handler: {
+    /**
+     * Resolves the handler function name for an operation.
+     *
+     * @example Resolving handler function names
+     * `resolver.handler.name(operationNode) // -> 'showPetByIdHandler'`
+     */
+    name(node: ast.OperationNode): string;
+  };
+};
+/**
+ * Where the generated MCP tool handlers are written and how they are exported, plus the optional
+ * `group` strategy. The `group` option organizes `output.mode: 'directory'` output into per-tag or per-path subdirectories.
+ *
+ * @default { path: 'mcp', barrel: { type: 'named' } }
+ */
+type Options = OutputOptions & {
+  /**
+   * Selects the HTTP client each MCP handler calls. Every client plugin speaks the `RequestResult`
+   * contract, so each handler calls a contract `<op>` that takes one grouped `{ path, query, headers,
+   * body }` object.
+   *
+   * `'fetch'` / `'axios'` / `'client'` calls the `@kubb/plugin-fetch` / `@kubb/plugin-axios` /
+   * `@kubb/plugin-client` functions. When a single client plugin is registered it is auto-detected, so the
+   * string is only needed to disambiguate several client plugins. Register one of those plugins.
+   * Options such as `baseURL` live there, or in your own module with `@kubb/plugin-client`.
+   */
+  client?: ClientSelector;
+  /**
+   * Skip operations matching at least one entry in the list.
+   */
+  exclude?: Array<Exclude>;
+  /**
+   * Restrict generation to operations matching at least one entry in the list.
+   */
+  include?: Array<Include>;
+  /**
+   * Apply a different options object to operations matching a pattern.
+   */
+  override?: Array<Override<ResolvedOptions>>;
+  /**
+   * Override how handler names and file paths are built. Methods you omit fall
+   * back to the default `resolverMcp`.
+   */
+  resolver?: ResolverPatch<ResolverMcp>;
+  /**
+   * Macros applied to each operation node before printing.
+   */
+  macros?: Array<ast.Macro>;
+};
+type ResolvedOptions = {
+  output: Output;
+  exclude: Array<Exclude>;
+  include: Array<Include> | undefined;
+  override: Array<Override<ResolvedOptions>>;
+  group: Group | null;
+  /**
+   * The resolved client strategy the generators branch on.
+   */
+  client: ResolvedContractClient;
+  resolver: ResolverMcp;
+};
+type PluginMcp = PluginType<'plugin-mcp', Options, ResolvedOptions, ResolverMcp>;
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-mcp': PluginMcp;
+    }
+  }
+}
+//#endregion
+//#region src/generators/mcpGenerator.d.ts
+/**
+ * Built-in operation generator for `@kubb/plugin-mcp`. Emits one MCP tool
+ * handler per OpenAPI operation. The handler takes the grouped `{ path, query,
+ * headers, body }` config and forwards it to the registered client plugin's
+ * (`@kubb/plugin-axios` / `@kubb/plugin-fetch`) `<op>` function.
+ */
+export declare const mcpGenerator: import("kubb/kit").Generator<PluginMcp, unknown>;
+//#endregion
+//#region src/generators/serverGenerator.d.ts
+/**
+ * Default v5 server generator for `@kubb/plugin-mcp`.
+ *
+ * Uses individual zod schemas for each param (e.g. `createPetsPathUuidSchema`, `createPetsQueryOffsetSchema`)
+ * and `resolveResponseStatusName` for per-status response schemas.
+ * Query and header params are composed into `z.object({ ... })` from individual schemas.
+ */
+export declare const serverGenerator: import("kubb/kit").Generator<PluginMcp, unknown>;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * Canonical plugin name for `@kubb/plugin-mcp`. Used for driver lookups and
+ * cross-plugin dependency references.
+ */
+export declare const pluginMcpName = "plugin-mcp";
+/**
+ * Generates a Model Context Protocol (MCP) server from an OpenAPI spec. Every
+ * operation becomes a typed MCP tool that AI assistants (Claude Desktop, Claude
+ * Code, MCP-compatible clients) can call directly. Each handler calls a contract
+ * client `<op>` from a registered `@kubb/plugin-axios` or `@kubb/plugin-fetch`.
+ * Next to the handlers it writes `server.ts`, a `start.ts` entry that serves the
+ * tools over stdio, and a `.mcp.json` that runs `start.ts` with `tsx`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb/config'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginZod } from '@kubb/plugin-zod'
+ * import { pluginFetch } from '@kubb/plugin-fetch'
+ * import { pluginMcp } from '@kubb/plugin-mcp'
+ *
+ * export default defineConfig({
+ *   input: './petStore.yaml',
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginZod(),
+ *     pluginFetch({ baseURL: 'https://petstore.swagger.io/v2' }),
+ *     pluginMcp({ output: { path: 'mcp' } }),
+ *   ],
+ * })
+ * ```
+ */
+export declare const pluginMcp: import("kubb/kit").PluginFactory<PluginMcp>;
+//#endregion
+//#region src/resolvers/resolverMcp.d.ts
+/**
+ * Default resolver used by `@kubb/plugin-mcp`. Decides the names and file
+ * paths for every generated MCP tool handler. Function names get a `Handler`
+ * suffix so an operation `addPet` becomes `addPetHandler`.
+ *
+ * @example Resolve a handler name
+ * ```ts
+ * import { resolverMcp } from '@kubb/plugin-mcp'
+ *
+ * resolverMcp.name('addPet') // 'addPetHandler'
+ * ```
+ */
+export declare const resolverMcp: ResolverMcp;
+//#endregion
+export { type PluginMcp, type ResolverMcp, pluginMcp as default };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,7 +1,6 @@
-import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
 import { Exclude, Group, Include, Output, OutputOptions, Override, PluginType, Resolver, ResolverPatch, ast } from "kubb/kit";
-import { KubbReactNode } from "kubb/jsx";
 import { ResolverTs } from "@kubb/plugin-ts";
+import { KubbReactNode } from "kubb/jsx";
 import "@kubb/plugin-zod";
 //#region src/components/McpHandler.d.ts
 type Props$1 = {
@@ -16,7 +15,7 @@ type Props$1 = {
   /**
    * AST operation node.
    */
-  node: ast.OperationNode;
+  node: ast.HttpOperationNode;
   /**
    * TypeScript resolver for resolving param/data/response type names.
    */
@@ -28,13 +27,11 @@ type Props$1 = {
 };
 export declare function McpHandler({ name, clientName, node, resolver, returnType }: Props$1): KubbReactNode;
 //#endregion
-//#region src/utils.d.ts
+//#region src/components/Server.d.ts
 type ZodParam = {
   name: string;
   schemaName: string;
 };
-//#endregion
-//#region src/components/Server.d.ts
 type Props = {
   /**
    * Human-readable server name passed to `new McpServer({ name })`.
@@ -63,41 +60,33 @@ type Props = {
       /**
        * Query params — individual schemas to compose into `z.object({ ... })`.
        */
-      queryParams?: string | Array<ZodParam> | null;
+      queryParams?: Array<ZodParam> | null;
       /**
        * Header params — individual schemas to compose into `z.object({ ... })`.
        */
-      headerParams?: string | Array<ZodParam> | null;
+      headerParams?: Array<ZodParam> | null;
       requestName?: string | null;
       responseName?: string | null;
     };
-    node: ast.OperationNode;
   }>;
 };
 export declare function Server({ serverName, serverVersion, operations }: Props): KubbReactNode;
 //#endregion
 //#region ../../internals/client/src/resolveClient.d.ts
-/**
- * Resolves which client plugin a consumer (react-query, vue-query, swr, mcp) should call for an
- * operation, shared so the selection rules and diagnostics stay in one place.
- *
- * Every client runtime lives in a dedicated client plugin, so a consumer always calls a registered
- * contract client plugin (plugin-fetch, plugin-axios, or plugin-client) and never emits its own
- * inline client:
- *
- * - `contract` — a registered contract client plugin owns the `<op>` functions and the consumer
- *   imports and calls them.
- * - `error` — no client plugin is registered, several are registered without a selector, the
- *   requested one is missing, or `client` is not a known selector.
- *
- * The `client` string selects explicitly (`'fetch'` / `'axios'` / `'client'`); when it is unset a
- * lone registered contract client plugin is picked up automatically.
- */
 /**
  * The client selector accepted by a consumer's `client` option. Each calls a registered contract
  * client plugin.
  */
 type ClientSelector = 'fetch' | 'axios' | 'client';
+/**
+ * The resolved client strategy stored in a consumer plugin's options: the generated code always
+ * imports and calls a registered contract client plugin's `<op>`. The client runtime lives in
+ * plugin-axios / plugin-fetch, so nothing is bundled by the consumer.
+ */
+type ResolvedContractClient = {
+  kind: 'contract';
+  pluginName: string;
+};
 //#endregion
 //#region src/types.d.ts
 /**
@@ -157,14 +146,6 @@ type Options = OutputOptions & {
    */
   macros?: Array<ast.Macro>;
 };
-/**
- * The resolved client strategy for the generated handlers, computed once during setup. The handlers
- * always import and call a registered contract client plugin's `<op>`.
- */
-type ResolvedClient = {
-  kind: 'contract';
-  pluginName: string;
-};
 type ResolvedOptions = {
   output: Output;
   exclude: Array<Exclude>;
@@ -174,7 +155,7 @@ type ResolvedOptions = {
   /**
    * The resolved client strategy the generators branch on.
    */
-  client: ResolvedClient;
+  client: ResolvedContractClient;
   resolver: ResolverMcp;
 };
 type PluginMcp = PluginType<'plugin-mcp', Options, ResolvedOptions, ResolverMcp>;