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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-mcp",
-  "version": "5.0.0-beta.15",
+  "version": "5.0.0-beta.25",
   "description": "Generate Model Context Protocol (MCP) tool definitions from your OpenAPI specification. Expose your REST APIs as AI-callable tools for LLMs, Claude, ChatGPT, and other AI assistants.",
   "keywords": [
     "ai",
@@ -47,18 +47,18 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.19",
-    "@kubb/renderer-jsx": "5.0.0-beta.19",
-    "@kubb/plugin-client": "5.0.0-beta.15",
-    "@kubb/plugin-ts": "5.0.0-beta.15",
-    "@kubb/plugin-zod": "5.0.0-beta.15"
+    "@kubb/core": "5.0.0-beta.25",
+    "@kubb/renderer-jsx": "5.0.0-beta.25",
+    "@kubb/plugin-client": "5.0.0-beta.25",
+    "@kubb/plugin-ts": "5.0.0-beta.25",
+    "@kubb/plugin-zod": "5.0.0-beta.25"
   },
   "devDependencies": {
     "@internals/shared": "0.0.0",
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.19"
+    "@kubb/renderer-jsx": "5.0.0-beta.25"
   },
   "size-limit": [
     {

package/src/components/McpHandler.tsx

@@ -23,7 +23,7 @@ type Props = {
   /**
    * Base URL prepended to every generated request URL.
    */
-  baseURL: string | undefined
+  baseURL: string | null | undefined
   /**
    * Return type when calling fetch.
    * - 'data' returns response data only.
@@ -57,7 +57,7 @@ export function McpHandler({ name, node, resolver, baseURL, dataReturnType, para
   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) : undefined
+  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))
@@ -77,15 +77,15 @@ export function McpHandler({ name, node, resolver, baseURL, dataReturnType, para
     ? `${baseParamsSignature}, request: RequestHandlerExtra<ServerRequest, ServerNotification>`
     : 'request: RequestHandlerExtra<ServerRequest, ServerNotification>'
 
-  const pathParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalPathParams, camelCase) : undefined
-  const queryParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalQueryParams, camelCase) : undefined
-  const headerParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalHeaderParams, camelCase) : undefined
+  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}'` : undefined
-  const headers = [headerParams.length ? (headerParamsMapping ? '...mappedHeaders' : '...headers') : undefined, contentTypeHeader].filter(Boolean)
+    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: string[] = []
+  const fetchConfig: Array<string> = []
   fetchConfig.push(`method: ${JSON.stringify(node.method.toUpperCase())}`)
   fetchConfig.push(`url: ${urlPath.template}`)
   if (baseURL) fetchConfig.push(`baseURL: \`${baseURL}\``)

package/src/components/Server.tsx

@@ -43,13 +43,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
   }>
@@ -104,10 +104,10 @@ export function Server({ name, serverName, serverVersion, paramsCasing, operatio
                   }),
                 ],
               })
-            : undefined
+            : null
 
           const destructured = paramsNode ? (keysPrinter.print(paramsNode) ?? '') : ''
-          const inputSchema = entries.length ? `{ ${entries.map((e) => `${e.key}: ${e.value}`).join(', ')} }` : undefined
+          const inputSchema = entries.length ? `{ ${entries.map((e) => `${e.key}: ${e.value}`).join(', ')} }` : null
           const outputSchema = zod.responseName
 
           const config = [

package/src/generators/mcpGenerator.tsx

@@ -6,6 +6,12 @@ import { File, jsxRendererSync } from '@kubb/renderer-jsx'
 import { McpHandler } from '../components/McpHandler.tsx'
 import type { PluginMcp } from '../types.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.
+ */
 export const mcpGenerator = defineGenerator<PluginMcp>({
   name: 'mcp',
   renderer: jsxRendererSync,
@@ -25,13 +31,16 @@ export const mcpGenerator = defineGenerator<PluginMcp>({
 
     const meta = {
       name: resolver.resolveHandlerName(node),
-      file: resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      ),
       fileTs: tsResolver.resolveFile(
         { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
         {
           root,
           output: pluginTs.options?.output ?? output,
-          group: pluginTs.options?.group,
+          group: pluginTs.options?.group ?? undefined,
         },
       ),
     } as const

package/src/generators/serverGenerator.tsx

@@ -17,7 +17,7 @@ export const serverGenerator = defineGenerator<PluginMcp>({
   name: 'operations',
   renderer: jsxRendererSync,
   operations(nodes, ctx) {
-    const { config, resolver, plugin, driver, root, inputNode } = ctx
+    const { config, resolver, plugin, driver, root } = ctx
     const { output, paramsCasing, group } = ctx.options
 
     const pluginZod = driver.getPlugin(pluginZodName)
@@ -46,20 +46,23 @@ export const serverGenerator = defineGenerator<PluginMcp>({
     const operationsMapped = nodes.map((node) => {
       const { path: pathParams, query: queryParams, header: headerParams } = getOperationParameters(node, { paramsCasing })
 
-      const mcpFile = resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group })
+      const mcpFile = resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      )
 
       const zodFile = zodResolver.resolveFile(
         { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
         {
           root,
           output: pluginZod.options?.output ?? output,
-          group: pluginZod.options?.group,
+          group: pluginZod.options?.group ?? undefined,
         },
       )
 
-      const requestName = node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName(node) : undefined
+      const requestName = node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName(node) : null
       const successStatus = findSuccessStatusCode(node.responses)
-      const responseName = successStatus ? zodResolver.resolveResponseStatusName(node, successStatus) : undefined
+      const responseName = successStatus ? zodResolver.resolveResponseStatusName(node, successStatus) : null
 
       const resolveParams = (params: typeof pathParams) => params.map((p) => ({ name: p.name, schemaName: zodResolver.resolveParamName(node, p) }))
 
@@ -75,8 +78,8 @@ export const serverGenerator = defineGenerator<PluginMcp>({
         },
         zod: {
           pathParams: resolveParams(pathParams),
-          queryParams: queryParams.length ? resolveParams(queryParams) : undefined,
-          headerParams: headerParams.length ? resolveParams(headerParams) : undefined,
+          queryParams: queryParams.length ? resolveParams(queryParams) : null,
+          headerParams: headerParams.length ? resolveParams(headerParams) : null,
           requestName,
           responseName,
           file: zodFile,
@@ -108,8 +111,8 @@ export const serverGenerator = defineGenerator<PluginMcp>({
           baseName={serverFile.baseName}
           path={serverFile.path}
           meta={serverFile.meta}
-          banner={resolver.resolveBanner(inputNode, { output, config })}
-          footer={resolver.resolveFooter(inputNode, { output, config })}
+          banner={resolver.resolveBanner(ctx.meta, { output, config })}
+          footer={resolver.resolveFooter(ctx.meta, { output, config })}
         >
           <File.Import name={['McpServer']} path={'@modelcontextprotocol/sdk/server/mcp'} />
           <File.Import name={['z']} path={'zod'} />
@@ -118,8 +121,8 @@ export const serverGenerator = defineGenerator<PluginMcp>({
           {imports}
           <Server
             name={name}
-            serverName={inputNode.meta?.title ?? 'server'}
-            serverVersion={inputNode.meta?.version ?? '0.0.0'}
+            serverName={ctx.meta.title ?? 'server'}
+            serverVersion={ctx.meta.version ?? '0.0.0'}
             paramsCasing={paramsCasing}
             operations={operationsMapped}
           />
@@ -130,7 +133,7 @@ export const serverGenerator = defineGenerator<PluginMcp>({
             {`
           {
             "mcpServers": {
-              "${inputNode.meta?.title || 'server'}": {
+              "${ctx.meta.title || 'server'}": {
                 "type": "stdio",
                 "command": "npx",
                 "args": ["tsx", "${path.relative(path.dirname(jsonFile.path), serverFile.path)}"]

package/src/plugin.ts

@@ -13,8 +13,40 @@ import { serverGenerator } from './generators/serverGenerator.tsx'
 import { resolverMcp } from './resolvers/resolverMcp.ts'
 import type { PluginMcp } from './types.ts'
 
+/**
+ * Canonical plugin name for `@kubb/plugin-mcp`. Used for driver lookups and
+ * cross-plugin dependency references.
+ */
 export const pluginMcpName = 'plugin-mcp' satisfies PluginMcp['name']
 
+/**
+ * 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' },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
 export const pluginMcp = definePlugin<PluginMcp>((options) => {
   const {
     output = { path: 'mcp', barrelType: 'named' },
@@ -44,7 +76,7 @@ export const pluginMcp = definePlugin<PluginMcp>((options) => {
               return `${camelCase(ctx.group)}Requests`
             },
       } satisfies Group)
-    : undefined
+    : null
 
   return {
     name: pluginMcpName,

package/src/resolvers/resolverMcp.ts

@@ -3,12 +3,16 @@ import { defineResolver } from '@kubb/core'
 import type { PluginMcp } from '../types.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'
+ * ```
  */
 export const resolverMcp = defineResolver<PluginMcp>(() => ({
   name: 'default',

package/src/types.ts

@@ -24,44 +24,50 @@ export type ResolverMcp = Resolver & {
 
 export 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>>
 }
@@ -71,7 +77,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

package/src/utils.ts

@@ -22,43 +22,27 @@ export function zodGroupExpr(entry: string | Array<ZodParam>): string {
  * Used as fallback when no named zod schema is available for a path parameter.
  */
 export function zodExprFromSchemaNode(schema: ast.SchemaNode): string {
-  let expr: string
-  switch (schema.type) {
-    case 'enum': {
-      // namedEnumValues takes priority over enumValues
+  const baseExpr = (() => {
+    if (schema.type === 'enum') {
       const rawValues: Array<string | number | boolean> = schema.namedEnumValues?.length
         ? schema.namedEnumValues.map((v) => v.value)
         : (schema.enumValues ?? []).filter((v): v is string | number | boolean => v !== null)
 
       if (rawValues.length > 0 && rawValues.every((v) => typeof v === 'string')) {
-        expr = `z.enum([${rawValues.map((v) => JSON.stringify(v)).join(', ')}])`
-      } else if (rawValues.length > 0) {
+        return `z.enum([${rawValues.map((v) => JSON.stringify(v)).join(', ')}])`
+      }
+      if (rawValues.length > 0) {
         const literals = rawValues.map((v) => `z.literal(${JSON.stringify(v)})`)
-        expr = literals.length === 1 ? literals[0]! : `z.union([${literals.join(', ')}])`
-      } else {
-        expr = 'z.string()'
+        return literals.length === 1 ? literals[0]! : `z.union([${literals.join(', ')}])`
       }
-      break
+      return 'z.string()'
     }
-    case 'integer':
-      expr = 'z.coerce.number()'
-      break
-    case 'number':
-      expr = 'z.number()'
-      break
-    case 'boolean':
-      expr = 'z.boolean()'
-      break
-    case 'array':
-      expr = 'z.array(z.unknown())'
-      break
-    default:
-      expr = 'z.string()'
-  }
-
-  if (schema.nullable) {
-    expr = `${expr}.nullable()`
-  }
+    if (schema.type === 'integer') return 'z.coerce.number()'
+    if (schema.type === 'number') return 'z.number()'
+    if (schema.type === 'boolean') return 'z.boolean()'
+    if (schema.type === 'array') return 'z.array(z.unknown())'
+    return 'z.string()'
+  })()
 
-  return expr
+  return schema.nullable ? `${baseExpr}.nullable()` : baseExpr
 }