@kubb/plugin-mcp 5.0.0-beta.3 → 5.0.0-beta.30

package/package.json

@@ -1,19 +1,17 @@
 {
   "name": "@kubb/plugin-mcp",
-  "version": "5.0.0-beta.3",
-  "description": "Model Context Protocol (MCP) plugin for Kubb, generating MCP-compatible tools and schemas from OpenAPI specifications for AI assistants.",
+  "version": "5.0.0-beta.30",
+  "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",
     "ai-tools",
-    "claude",
-    "code-generator",
+    "code-generation",
     "codegen",
     "kubb",
     "llm",
     "mcp",
     "model-context-protocol",
     "openapi",
-    "plugins",
     "swagger",
     "typescript"
   ],
@@ -27,7 +25,7 @@
   "files": [
     "src",
     "dist",
-    "plugin.json",
+    "extension.yaml",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -49,17 +47,18 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.3",
-    "@kubb/renderer-jsx": "5.0.0-beta.3",
-    "@kubb/plugin-client": "5.0.0-beta.3",
-    "@kubb/plugin-ts": "5.0.0-beta.3",
-    "@kubb/plugin-zod": "5.0.0-beta.3"
+    "@kubb/core": "5.0.0-beta.29",
+    "@kubb/renderer-jsx": "5.0.0-beta.29",
+    "@kubb/plugin-client": "5.0.0-beta.30",
+    "@kubb/plugin-ts": "5.0.0-beta.30",
+    "@kubb/plugin-zod": "5.0.0-beta.30"
   },
   "devDependencies": {
+    "@internals/shared": "0.0.0",
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.3"
+    "@kubb/renderer-jsx": "5.0.0-beta.29"
   },
   "size-limit": [
     {

package/src/components/McpHandler.tsx

@@ -1,11 +1,11 @@
-import { isValidVarName, URLPath } from '@internals/utils'
+import { buildOperationComments, buildTransformedParamsMapping, getOperationParameters } from '@internals/shared'
+import { camelCase, isValidVarName, URLPath } from '@internals/utils'
 import { ast } from '@kubb/core'
 import type { ResolverTs } from '@kubb/plugin-ts'
 import { functionPrinter } from '@kubb/plugin-ts'
 import { File, Function } from '@kubb/renderer-jsx'
 import type { KubbReactNode } from '@kubb/renderer-jsx/types'
 import type { PluginMcp } from '../types.ts'
-import { getComments, getParamsMapping } from '../utils.ts'
 
 type Props = {
   /**
@@ -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.
@@ -54,16 +54,10 @@ export function McpHandler({ name, node, resolver, baseURL, dataReturnType, para
   const contentType = node.requestBody?.content?.[0]?.contentType
   const isFormData = contentType === 'multipart/form-data'
 
-  const casedParams = ast.caseParams(node.parameters, paramsCasing)
-  const queryParams = casedParams.filter((p) => p.in === 'query')
-  const headerParams = casedParams.filter((p) => p.in === 'header')
+  const { query: queryParams, header: headerParams } = getOperationParameters(node, { paramsCasing })
+  const { path: originalPathParams, query: originalQueryParams, header: originalHeaderParams } = getOperationParameters(node)
 
-  // Use original (uncased) parameters for mapping so original→camelCase difference is detected
-  const originalPathParams = node.parameters.filter((p) => p.in === 'path')
-  const originalQueryParams = node.parameters.filter((p) => p.in === 'query')
-  const originalHeaderParams = node.parameters.filter((p) => p.in === 'header')
-
-  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))
@@ -83,15 +77,15 @@ export function McpHandler({ name, node, resolver, baseURL, dataReturnType, para
     ? `${baseParamsSignature}, request: RequestHandlerExtra<ServerRequest, ServerNotification>`
     : 'request: RequestHandlerExtra<ServerRequest, ServerNotification>'
 
-  const pathParamsMapping = paramsCasing ? getParamsMapping(originalPathParams) : undefined
-  const queryParamsMapping = paramsCasing ? getParamsMapping(originalQueryParams) : undefined
-  const headerParamsMapping = paramsCasing ? getParamsMapping(originalHeaderParams) : 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}\``)
@@ -128,7 +122,7 @@ export function McpHandler({ name, node, resolver, baseURL, dataReturnType, para
         export
         params={paramsSignature}
         JSDoc={{
-          comments: getComments(node),
+          comments: buildOperationComments(node),
         }}
         returnType={'Promise<CallToolResult>'}
       >
@@ -164,7 +158,7 @@ export function McpHandler({ name, node, resolver, baseURL, dataReturnType, para
         <br />
         {isFormData && requestName && 'const formData = buildFormData(requestData)'}
         <br />
-        {`const res = await fetch<${generics.join(', ')}>({ ${fetchConfig.join(', ')} }, request)`}
+        {`const res = await client<${generics.join(', ')}>({ ${fetchConfig.join(', ')} }, request)`}
         <br />
         {callToolResult}
       </Function>

package/src/components/Server.tsx

@@ -1,3 +1,4 @@
+import { getOperationParameters } from '@internals/shared'
 import { ast } from '@kubb/core'
 import { functionPrinter } from '@kubb/plugin-ts'
 import { Const, File, Function } from '@kubb/renderer-jsx'
@@ -42,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
   }>
@@ -70,8 +71,7 @@ export function Server({ name, serverName, serverVersion, paramsCasing, operatio
 
       {operations
         .map(({ tool, mcp, zod, node }) => {
-          const casedParams = ast.caseParams(node.parameters, paramsCasing)
-          const pathParams = casedParams.filter((p) => p.in === 'path')
+          const { path: pathParams } = getOperationParameters(node, { paramsCasing })
 
           const pathEntries: Array<{ key: string; value: string }> = []
           const otherEntries: Array<{ key: string; value: string }> = []
@@ -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

@@ -1,13 +1,20 @@
 import path from 'node:path'
-import { ast, defineGenerator } from '@kubb/core'
+import { resolveOperationTypeNames } from '@internals/shared'
+import { defineGenerator } from '@kubb/core'
 import { pluginTsName } from '@kubb/plugin-ts'
-import { File, jsxRenderer } from '@kubb/renderer-jsx'
+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: jsxRenderer,
+  renderer: jsxRendererSync,
   operation(node, ctx) {
     const { resolver, driver, root } = ctx
     const { output, client, paramsCasing, group } = ctx.options
@@ -20,30 +27,20 @@ export const mcpGenerator = defineGenerator<PluginMcp>({
 
     const tsResolver = driver.getResolver(pluginTsName)
 
-    const casedParams = ast.caseParams(node.parameters, paramsCasing)
-
-    const pathParams = casedParams.filter((p) => p.in === 'path')
-    const queryParams = casedParams.filter((p) => p.in === 'query')
-    const headerParams = casedParams.filter((p) => p.in === 'header')
-
-    const importedTypeNames = [
-      ...pathParams.map((p) => tsResolver.resolvePathParamsName(node, p)),
-      ...queryParams.map((p) => tsResolver.resolveQueryParamsName(node, p)),
-      ...headerParams.map((p) => tsResolver.resolveHeaderParamsName(node, p)),
-      node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : undefined,
-      tsResolver.resolveResponseName(node),
-      ...node.responses.filter((r) => Number(r.statusCode) >= 400).map((r) => tsResolver.resolveResponseStatusName(node, r.statusCode)),
-    ].filter(Boolean)
+    const importedTypeNames = resolveOperationTypeNames(node, tsResolver, { paramsCasing, responseStatusNames: 'error' })
 
     const meta = {
-      name: resolver.resolveName(node.operationId),
-      file: resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      name: resolver.resolveHandlerName(node),
+      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
@@ -59,7 +56,7 @@ export const mcpGenerator = defineGenerator<PluginMcp>({
         {client.importPath ? (
           <>
             <File.Import name={['Client', 'RequestConfig', 'ResponseErrorConfig']} path={client.importPath} isTypeOnly />
-            <File.Import name={'fetch'} path={client.importPath} />
+            <File.Import name={'client'} path={client.importPath} />
             {client.dataReturnType === 'full' && <File.Import name={['ResponseConfig']} path={client.importPath} isTypeOnly />}
           </>
         ) : (
@@ -67,12 +64,12 @@ export const mcpGenerator = defineGenerator<PluginMcp>({
             <File.Import
               name={['Client', 'RequestConfig', 'ResponseErrorConfig']}
               root={meta.file.path}
-              path={path.resolve(root, '.kubb/fetch.ts')}
+              path={path.resolve(root, '.kubb/client.ts')}
               isTypeOnly
             />
-            <File.Import name={['fetch']} root={meta.file.path} path={path.resolve(root, '.kubb/fetch.ts')} />
+            <File.Import name={['client']} root={meta.file.path} path={path.resolve(root, '.kubb/client.ts')} />
             {client.dataReturnType === 'full' && (
-              <File.Import name={['ResponseConfig']} root={meta.file.path} path={path.resolve(root, '.kubb/fetch.ts')} isTypeOnly />
+              <File.Import name={['ResponseConfig']} root={meta.file.path} path={path.resolve(root, '.kubb/client.ts')} isTypeOnly />
             )}
           </>
         )}

package/src/generators/serverGenerator.tsx

@@ -1,10 +1,10 @@
 import path from 'node:path'
-import { ast, defineGenerator } from '@kubb/core'
+import { findSuccessStatusCode, getOperationParameters } from '@internals/shared'
+import { defineGenerator } from '@kubb/core'
 import { pluginZodName } from '@kubb/plugin-zod'
-import { File, jsxRenderer } from '@kubb/renderer-jsx'
+import { File, jsxRendererSync } from '@kubb/renderer-jsx'
 import { Server } from '../components/Server.tsx'
 import type { PluginMcp } from '../types.ts'
-import { findSuccessStatusCode } from '../utils.ts'
 
 /**
  * Default v5 server generator for `@kubb/plugin-mcp`.
@@ -15,9 +15,9 @@ import { findSuccessStatusCode } from '../utils.ts'
  */
 export const serverGenerator = defineGenerator<PluginMcp>({
   name: 'operations',
-  renderer: jsxRenderer,
+  renderer: jsxRendererSync,
   operations(nodes, ctx) {
-    const { adapter, config, resolver, plugin, driver, root } = ctx
+    const { config, resolver, plugin, driver, root } = ctx
     const { output, paramsCasing, group } = ctx.options
 
     const pluginZod = driver.getPlugin(pluginZodName)
@@ -44,25 +44,25 @@ export const serverGenerator = defineGenerator<PluginMcp>({
     }
 
     const operationsMapped = nodes.map((node) => {
-      const casedParams = ast.caseParams(node.parameters, paramsCasing)
-      const pathParams = casedParams.filter((p) => p.in === 'path')
-      const queryParams = casedParams.filter((p) => p.in === 'query')
-      const headerParams = casedParams.filter((p) => p.in === 'header')
+      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) }))
 
@@ -73,13 +73,13 @@ export const serverGenerator = defineGenerator<PluginMcp>({
           description: node.description || `Make a ${node.method.toUpperCase()} request to ${node.path}`,
         },
         mcp: {
-          name: resolver.resolveName(node.operationId),
+          name: resolver.resolveHandlerName(node),
           file: mcpFile,
         },
         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,
@@ -95,7 +95,7 @@ export const serverGenerator = defineGenerator<PluginMcp>({
         ...(zod.headerParams ?? []).map((p) => p.schemaName),
         zod.requestName,
         zod.responseName,
-      ].filter(Boolean)
+      ].filter((name): name is string => Boolean(name))
 
       const uniqueNames = [...new Set(zodNames)].sort()
 
@@ -111,8 +111,8 @@ export const serverGenerator = defineGenerator<PluginMcp>({
           baseName={serverFile.baseName}
           path={serverFile.path}
           meta={serverFile.meta}
-          banner={resolver.resolveBanner(adapter.inputNode, { output, config })}
-          footer={resolver.resolveFooter(adapter.inputNode, { output, config })}
+          banner={resolver.resolveBanner(ctx.meta, { output, config, file: { path: serverFile.path, baseName: serverFile.baseName } })}
+          footer={resolver.resolveFooter(ctx.meta, { output, config, file: { path: serverFile.path, baseName: serverFile.baseName } })}
         >
           <File.Import name={['McpServer']} path={'@modelcontextprotocol/sdk/server/mcp'} />
           <File.Import name={['z']} path={'zod'} />
@@ -121,8 +121,8 @@ export const serverGenerator = defineGenerator<PluginMcp>({
           {imports}
           <Server
             name={name}
-            serverName={adapter.inputNode?.meta?.title ?? 'server'}
-            serverVersion={adapter.inputNode?.meta?.version ?? '0.0.0'}
+            serverName={ctx.meta.title ?? 'server'}
+            serverVersion={ctx.meta.version ?? '0.0.0'}
             paramsCasing={paramsCasing}
             operations={operationsMapped}
           />
@@ -133,7 +133,7 @@ export const serverGenerator = defineGenerator<PluginMcp>({
             {`
           {
             "mcpServers": {
-              "${adapter.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,
@@ -87,11 +119,11 @@ export const pluginMcp = definePlugin<PluginMcp>((options) => {
 
         if (client?.bundle && !hasClientPlugin && !clientImportPath) {
           ctx.injectFile({
-            baseName: 'fetch.ts',
-            path: path.resolve(root, '.kubb/fetch.ts'),
+            baseName: 'client.ts',
+            path: path.resolve(root, '.kubb/client.ts'),
             sources: [
               ast.createSource({
-                name: 'fetch',
+                name: 'client',
                 nodes: [ast.createText(clientName === 'fetch' ? fetchClientSource : axiosClientSource)],
                 isExportable: true,
                 isIndexable: true,

package/src/resolvers/resolverMcp.ts

@@ -3,14 +3,18 @@ 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>((ctx) => ({
+export const resolverMcp = defineResolver<PluginMcp>(() => ({
   name: 'default',
   pluginName: 'plugin-mcp',
   default(name, type) {
@@ -20,6 +24,12 @@ export const resolverMcp = defineResolver<PluginMcp>((ctx) => ({
     return camelCase(name, { suffix: 'handler' })
   },
   resolveName(name) {
-    return ctx.default(name, 'function')
+    return this.default(name, 'function')
+  },
+  resolvePathName(name, type) {
+    return this.default(name, type)
+  },
+  resolveHandlerName(node) {
+    return this.resolveName(node.operationId)
   },
 }))

package/src/types.ts

@@ -6,54 +6,68 @@ import type { ClientImportPath, PluginClient } from '@kubb/plugin-client'
  */
 export type ResolverMcp = Resolver & {
   /**
-   * Resolves the handler function name for an operation.
+   * Resolves the base handler function name for an operation.
    *
    * @example Resolving handler function names
    * `resolver.resolveName('show pet by id') // -> 'showPetByIdHandler'`
    */
   resolveName(this: ResolverMcp, name: string): string
+  /**
+   * Resolves the output file name for an MCP module.
+   */
+  resolvePathName(this: ResolverMcp, name: string, type?: 'file' | 'function' | 'type' | 'const'): string
+  /**
+   * Resolves the handler function name for an operation.
+   */
+  resolveHandlerName(this: ResolverMcp, node: ast.OperationNode): string
 }
 
 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>>
 }
@@ -63,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