@kubb/plugin-mcp 5.0.0-beta.22 → 5.0.0-beta.25

package/dist/index.d.ts

@@ -28,44 +28,50 @@ type ResolverMcp = Resolver & {
 };
 type Options = {
   /**
-   * Specify the export location for the files and define the behavior of the output.
-   * @default { path: 'mcp', barrelType: 'named' }
+   * Where the generated MCP tool handlers are written and how they are exported.
+   *
+   * @default { path: 'mcp', barrel: { type: 'named' } }
    */
   output?: Output;
   /**
-   * Client configuration for HTTP request generation.
+   * HTTP client used by each MCP handler to call the underlying API. Mirrors a
+   * subset of `pluginClient` options.
    */
   client?: ClientImportPath & Pick<PluginClient['options'], 'clientType' | 'dataReturnType' | 'baseURL' | 'bundle' | 'paramsCasing'>;
   /**
-   * Apply casing to parameter names to match your configuration.
+   * Rename parameter properties in the generated handlers. The HTTP layer still
+   * uses the original spec names; Kubb writes the mapping for you.
+   *
+   * @note Must match the value of `paramsCasing` on `@kubb/plugin-ts`.
    */
   paramsCasing?: 'camelcase';
   /**
-   * Group the MCP requests based on the provided name.
+   * Split generated files into subfolders based on the operation's tag.
    */
   group?: Group;
   /**
-   * Tags, operations, or paths to exclude from generation.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>;
   /**
-   * Tags, operations, or paths to include in generation.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>;
   /**
-   * Override options for specific tags, operations, or paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>;
   /**
-   * Override naming conventions for function names and types.
+   * Override how handler names and file paths are built. Methods you omit fall
+   * back to the default `resolverMcp`.
    */
   resolver?: Partial<ResolverMcp> & ThisType<ResolverMcp>;
   /**
-   * AST visitor to transform generated nodes.
+   * AST visitor applied to each operation node before printing.
    */
   transformer?: ast.Visitor;
   /**
-   * Additional generators alongside the default generators.
+   * Custom generators that run alongside the built-in MCP generators.
    */
   generators?: Array<Generator<PluginMcp>>;
 };
@@ -74,7 +80,7 @@ type ResolvedOptions = {
   exclude: Array<Exclude>;
   include: Array<Include> | undefined;
   override: Array<Override<ResolvedOptions>>;
-  group: Group | undefined;
+  group: Group | null;
   client: Pick<PluginClient['options'], 'client' | 'clientType' | 'dataReturnType' | 'importPath' | 'baseURL' | 'bundle' | 'paramsCasing'>;
   paramsCasing: Options['paramsCasing'];
   resolver: ResolverMcp;
@@ -170,13 +176,13 @@ type Props = {
       /**
        * Query params — individual schemas to compose into `z.object({ ... })`.
        */
-      queryParams?: string | Array<ZodParam>;
+      queryParams?: string | Array<ZodParam> | null;
       /**
        * Header params — individual schemas to compose into `z.object({ ... })`.
        */
-      headerParams?: string | Array<ZodParam>;
-      requestName?: string;
-      responseName?: string;
+      headerParams?: string | Array<ZodParam> | null;
+      requestName?: string | null;
+      responseName?: string | null;
     };
     node: ast.OperationNode;
   }>;
@@ -190,6 +196,12 @@ declare function Server({
 }: Props): KubbReactNode;
 //#endregion
 //#region src/generators/mcpGenerator.d.ts
+/**
+ * Built-in operation generator for `@kubb/plugin-mcp`. Emits one MCP tool
+ * handler per OpenAPI operation, wiring the input Zod schema, the HTTP call,
+ * and the response shape into a single function that an MCP server can
+ * register as a callable tool.
+ */
 declare const mcpGenerator: _$_kubb_core0.Generator<PluginMcp, unknown>;
 //#endregion
 //#region src/generators/serverGenerator.d.ts
@@ -203,17 +215,53 @@ declare const mcpGenerator: _$_kubb_core0.Generator<PluginMcp, unknown>;
 declare const serverGenerator: _$_kubb_core0.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.
+ */
 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.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginClient } from '@kubb/plugin-client'
+ * import { pluginZod } from '@kubb/plugin-zod'
+ * import { pluginMcp } from '@kubb/plugin-mcp'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginClient(),
+ *     pluginZod(),
+ *     pluginMcp({
+ *       output: { path: './mcp' },
+ *       client: { baseURL: 'https://petstore.swagger.io/v2' },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
 declare const pluginMcp: (options?: Options | undefined) => _$_kubb_core0.Plugin<PluginMcp>;
 //#endregion
 //#region src/resolvers/resolverMcp.d.ts
 /**
- * Naming convention resolver for MCP plugin.
+ * 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`.
  *
- * Provides default naming helpers using camelCase with a `handler` suffix for functions.
+ * @example Resolve a handler name
+ * ```ts
+ * import { resolverMcp } from '@kubb/plugin-mcp'
  *
- * @example
- * `resolverMcp.default('addPet', 'function')  // → 'addPetHandler'`
+ * resolverMcp.default('addPet', 'function') // 'addPetHandler'
+ * ```
  */
 declare const resolverMcp: ResolverMcp;
 //#endregion

package/dist/index.js

@@ -220,12 +220,12 @@ var URLPath = class {
 	get object() {
 		return this.toObject();
 	}
-	/** Returns a map of path parameter names, or `undefined` when the path has no parameters.
+	/** Returns a map of path parameter names, or `null` when the path has no parameters.
 	*
 	* @example
 	* ```ts
 	* new URLPath('/pet/{petId}').params // { petId: 'petId' }
-	* new URLPath('/pet').params         // undefined
+	* new URLPath('/pet').params         // null
 	* ```
 	*/
 	get params() {
@@ -288,7 +288,7 @@ var URLPath = class {
 			const key = replacer ? replacer(param) : param;
 			params[key] = key;
 		});
-		return Object.keys(params).length > 0 ? params : void 0;
+		return Object.keys(params).length > 0 ? params : null;
 	}
 	/** Converts the OpenAPI path to Express-style colon syntax.
 	*
@@ -304,9 +304,9 @@ var URLPath = class {
 //#endregion
 //#region ../../internals/shared/src/operation.ts
 function getOperationLink(node, link) {
-	if (!link) return;
-	if (typeof link === "function") return link(node);
-	if (link === "urlPath") return node.path ? `{@link ${new URLPath(node.path).URL}}` : void 0;
+	if (!link) return null;
+	if (typeof link === "function") return link(node) ?? null;
+	if (link === "urlPath") return node.path ? `{@link ${new URLPath(node.path).URL}}` : null;
 	return `{@link ${node.path.replaceAll("{", ":").replaceAll("}", "")}}`;
 }
 function buildOperationComments(node, options = {}) {
@@ -337,15 +337,15 @@ function getOperationParameters(node, options = {}) {
 }
 function getStatusCodeNumber(statusCode) {
 	const code = Number(statusCode);
-	return Number.isNaN(code) ? void 0 : code;
+	return Number.isNaN(code) ? null : code;
 }
 function isSuccessStatusCode(statusCode) {
 	const code = getStatusCodeNumber(statusCode);
-	return code !== void 0 && code >= 200 && code < 300;
+	return code !== null && code >= 200 && code < 300;
 }
 function isErrorStatusCode(statusCode) {
 	const code = getStatusCodeNumber(statusCode);
-	return code !== void 0 && code >= 400;
+	return code !== null && code >= 400;
 }
 function resolveErrorNames(node, resolver) {
 	return node.responses.filter((response) => isErrorStatusCode(response.statusCode)).map((response) => resolver.resolveResponseStatusName(node, response.statusCode));
@@ -372,7 +372,7 @@ function resolveOperationTypeNames(node, resolver, options = {}) {
 		...query.map((param) => resolver.resolveQueryParamsName(node, param)),
 		...header.map((param) => resolver.resolveHeaderParamsName(node, param))
 	];
-	const bodyAndResponseNames = [node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : void 0, resolver.resolveResponseName(node)];
+	const bodyAndResponseNames = [node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null, resolver.resolveResponseName(node)];
 	const result = (options.order === "body-response-first" ? [
 		...bodyAndResponseNames,
 		...paramNames,
@@ -387,6 +387,7 @@ function resolveOperationTypeNames(node, resolver, options = {}) {
 }
 function findSuccessStatusCode(responses) {
 	for (const response of responses) if (isSuccessStatusCode(response.statusCode)) return response.statusCode;
+	return null;
 }
 //#endregion
 //#region ../../internals/shared/src/params.ts
@@ -398,10 +399,10 @@ function buildParamsMapping(originalParams, mappedParams) {
 		mapping[param.name] = mappedName;
 		if (param.name !== mappedName) hasChanged = true;
 	});
-	return hasChanged ? mapping : void 0;
+	return hasChanged ? mapping : null;
 }
 function buildTransformedParamsMapping(params, transformName) {
-	if (!params.length) return;
+	if (!params.length) return null;
 	return buildParamsMapping(params, params.map((param) => ({
 		...param,
 		name: transformName(param.name)
@@ -422,7 +423,7 @@ function McpHandler({ name, node, resolver, baseURL, dataReturnType, paramsCasin
 	const isFormData = contentType === "multipart/form-data";
 	const { query: queryParams, header: headerParams } = getOperationParameters(node, { paramsCasing });
 	const { path: originalPathParams, query: originalQueryParams, header: originalHeaderParams } = getOperationParameters(node);
-	const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : void 0;
+	const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null;
 	const responseName = resolver.resolveResponseName(node);
 	const errorResponses = node.responses.filter((r) => Number(r.statusCode) >= 400).map((r) => resolver.resolveResponseStatusName(node, r.statusCode));
 	const generics = [
@@ -438,11 +439,11 @@ function McpHandler({ name, node, resolver, baseURL, dataReturnType, paramsCasin
 	});
 	const baseParamsSignature = declarationPrinter.print(paramsNode) ?? "";
 	const paramsSignature = baseParamsSignature ? `${baseParamsSignature}, request: RequestHandlerExtra<ServerRequest, ServerNotification>` : "request: RequestHandlerExtra<ServerRequest, ServerNotification>";
-	const pathParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalPathParams, camelCase) : void 0;
-	const queryParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalQueryParams, camelCase) : void 0;
-	const headerParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalHeaderParams, camelCase) : void 0;
-	const contentTypeHeader = contentType && contentType !== "application/json" && contentType !== "multipart/form-data" ? `'Content-Type': '${contentType}'` : void 0;
-	const headers = [headerParams.length ? headerParamsMapping ? "...mappedHeaders" : "...headers" : void 0, contentTypeHeader].filter(Boolean);
+	const pathParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalPathParams, camelCase) : null;
+	const queryParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalQueryParams, camelCase) : null;
+	const headerParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalHeaderParams, camelCase) : null;
+	const contentTypeHeader = contentType && contentType !== "application/json" && contentType !== "multipart/form-data" ? `'Content-Type': '${contentType}'` : null;
+	const headers = [headerParams.length ? headerParamsMapping ? "...mappedHeaders" : "...headers" : null, contentTypeHeader].filter(Boolean);
 	const fetchConfig = [];
 	fetchConfig.push(`method: ${JSON.stringify(node.method.toUpperCase())}`);
 	fetchConfig.push(`url: ${urlPath.template}`);
@@ -585,9 +586,9 @@ function Server({ name, serverName, serverVersion, paramsCasing, operations }) {
 				const paramsNode = entries.length ? ast.createFunctionParameters({ params: [ast.createParameterGroup({ properties: entries.map((e) => ast.createFunctionParameter({
 					name: e.key,
 					optional: false
-				})) })] }) : void 0;
+				})) })] }) : null;
 				const destructured = paramsNode ? keysPrinter.print(paramsNode) ?? "" : "";
-				const inputSchema = entries.length ? `{ ${entries.map((e) => `${e.key}: ${e.value}`).join(", ")} }` : void 0;
+				const inputSchema = entries.length ? `{ ${entries.map((e) => `${e.key}: ${e.value}`).join(", ")} }` : null;
 				const outputSchema = zod.responseName;
 				const config = [
 					tool.title ? `title: ${JSON.stringify(tool.title)}` : null,
@@ -628,6 +629,12 @@ server.registerTool(${JSON.stringify(tool.name)}, {
 }
 //#endregion
 //#region src/generators/mcpGenerator.tsx
+/**
+* Built-in operation generator for `@kubb/plugin-mcp`. Emits one MCP tool
+* handler per OpenAPI operation, wiring the input Zod schema, the HTTP call,
+* and the response shape into a single function that an MCP server can
+* register as a callable tool.
+*/
 const mcpGenerator = defineGenerator({
 	name: "mcp",
 	renderer: jsxRendererSync,
@@ -651,7 +658,7 @@ const mcpGenerator = defineGenerator({
 			}, {
 				root,
 				output,
-				group
+				group: group ?? void 0
 			}),
 			fileTs: tsResolver.resolveFile({
 				name: node.operationId,
@@ -661,7 +668,7 @@ const mcpGenerator = defineGenerator({
 			}, {
 				root,
 				output: pluginTs.options?.output ?? output,
-				group: pluginTs.options?.group
+				group: pluginTs.options?.group ?? void 0
 			})
 		};
 		return /* @__PURE__ */ jsxs(File, {
@@ -787,7 +794,7 @@ const serverGenerator = defineGenerator({
 			}, {
 				root,
 				output,
-				group
+				group: group ?? void 0
 			});
 			const zodFile = zodResolver.resolveFile({
 				name: node.operationId,
@@ -797,11 +804,11 @@ const serverGenerator = defineGenerator({
 			}, {
 				root,
 				output: pluginZod.options?.output ?? output,
-				group: pluginZod.options?.group
+				group: pluginZod.options?.group ?? void 0
 			});
-			const requestName = node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName(node) : void 0;
+			const requestName = node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName(node) : null;
 			const successStatus = findSuccessStatusCode(node.responses);
-			const responseName = successStatus ? zodResolver.resolveResponseStatusName(node, successStatus) : void 0;
+			const responseName = successStatus ? zodResolver.resolveResponseStatusName(node, successStatus) : null;
 			const resolveParams = (params) => params.map((p) => ({
 				name: p.name,
 				schemaName: zodResolver.resolveParamName(node, p)
@@ -818,8 +825,8 @@ const serverGenerator = defineGenerator({
 				},
 				zod: {
 					pathParams: resolveParams(pathParams),
-					queryParams: queryParams.length ? resolveParams(queryParams) : void 0,
-					headerParams: headerParams.length ? resolveParams(headerParams) : void 0,
+					queryParams: queryParams.length ? resolveParams(queryParams) : null,
+					headerParams: headerParams.length ? resolveParams(headerParams) : null,
 					requestName,
 					responseName,
 					file: zodFile
@@ -904,12 +911,16 @@ const serverGenerator = defineGenerator({
 //#endregion
 //#region src/resolvers/resolverMcp.ts
 /**
-* Naming convention resolver for MCP plugin.
+* 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`.
 *
-* Provides default naming helpers using camelCase with a `handler` suffix for functions.
+* @example Resolve a handler name
+* ```ts
+* import { resolverMcp } from '@kubb/plugin-mcp'
 *
-* @example
-* `resolverMcp.default('addPet', 'function')  // → 'addPetHandler'`
+* resolverMcp.default('addPet', 'function') // 'addPetHandler'
+* ```
 */
 const resolverMcp = defineResolver(() => ({
 	name: "default",
@@ -930,7 +941,39 @@ const resolverMcp = defineResolver(() => ({
 }));
 //#endregion
 //#region src/plugin.ts
+/**
+* Canonical plugin name for `@kubb/plugin-mcp`. Used for driver lookups and
+* cross-plugin dependency references.
+*/
 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.
+*
+* @example
+* ```ts
+* import { defineConfig } from 'kubb'
+* import { pluginTs } from '@kubb/plugin-ts'
+* import { pluginClient } from '@kubb/plugin-client'
+* import { pluginZod } from '@kubb/plugin-zod'
+* import { pluginMcp } from '@kubb/plugin-mcp'
+*
+* export default defineConfig({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   plugins: [
+*     pluginTs(),
+*     pluginClient(),
+*     pluginZod(),
+*     pluginMcp({
+*       output: { path: './mcp' },
+*       client: { baseURL: 'https://petstore.swagger.io/v2' },
+*     }),
+*   ],
+* })
+* ```
+*/
 const pluginMcp = definePlugin((options) => {
 	const { output = {
 		path: "mcp",
@@ -944,7 +987,7 @@ const pluginMcp = definePlugin((options) => {
 			if (group.type === "path") return `${ctx.group.split("/")[1]}`;
 			return `${camelCase(ctx.group)}Requests`;
 		}
-	} : void 0;
+	} : null;
 	return {
 		name: pluginMcpName,
 		options,