@kubb/plugin-mcp 5.0.0-beta.4 → 5.0.0-beta.42

package/package.json

@@ -1,19 +1,17 @@
 {
   "name": "@kubb/plugin-mcp",
-  "version": "5.0.0-beta.4",
-  "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.42",
+  "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"
   ],
@@ -49,17 +47,18 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.4",
-    "@kubb/renderer-jsx": "5.0.0-beta.4",
-    "@kubb/plugin-client": "5.0.0-beta.4",
-    "@kubb/plugin-ts": "5.0.0-beta.4",
-    "@kubb/plugin-zod": "5.0.0-beta.4"
+    "@kubb/core": "5.0.0-beta.42",
+    "@kubb/renderer-jsx": "5.0.0-beta.42",
+    "@kubb/plugin-client": "5.0.0-beta.42",
+    "@kubb/plugin-ts": "5.0.0-beta.42",
+    "@kubb/plugin-zod": "5.0.0-beta.42"
   },
   "devDependencies": {
+    "@internals/shared": "0.0.0",
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.4"
+    "@kubb/renderer-jsx": "5.0.0-beta.42"
   },
   "size-limit": [
     {
@@ -78,6 +77,7 @@
     "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
+    "release:stage": "pnpm stage publish --no-git-check",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

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.
@@ -50,20 +50,15 @@ function buildRemappingCode(mapping: Record<string, string>, varName: string, so
 const declarationPrinter = functionPrinter({ mode: 'declaration' })
 
 export function McpHandler({ name, node, resolver, baseURL, dataReturnType, paramsCasing }: Props): KubbReactNode {
+  if (!ast.isHttpOperationNode(node)) return null
   const urlPath = new URLPath(node.path)
   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 +78,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 +123,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 +159,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
   }>
@@ -57,69 +58,57 @@ type Props = {
 const keysPrinter = functionPrinter({ mode: 'keys' })
 
 export function Server({ name, serverName, serverVersion, paramsCasing, operations }: Props): KubbReactNode {
-  return (
-    <File.Source name={name} isExportable isIndexable>
-      <Const name={'server'} export>
-        {`
-          new McpServer({
-  name: '${serverName}',
-  version: '${serverVersion}',
-})
-          `}
-      </Const>
-
-      {operations
-        .map(({ tool, mcp, zod, node }) => {
-          const casedParams = ast.caseParams(node.parameters, paramsCasing)
-          const pathParams = casedParams.filter((p) => p.in === 'path')
-
-          const pathEntries: Array<{ key: string; value: string }> = []
-          const otherEntries: Array<{ key: string; value: string }> = []
-
-          for (const p of pathParams) {
-            const zodParam = zod.pathParams.find((zp) => zp.name === p.name)
-            pathEntries.push({ key: p.name, value: zodParam ? zodParam.schemaName : zodExprFromSchemaNode(p.schema) })
-          }
-
-          if (zod.requestName) {
-            otherEntries.push({ key: 'data', value: zod.requestName })
-          }
-
-          if (zod.queryParams) {
-            otherEntries.push({ key: 'params', value: zodGroupExpr(zod.queryParams) })
-          }
-
-          if (zod.headerParams) {
-            otherEntries.push({ key: 'headers', value: zodGroupExpr(zod.headerParams) })
-          }
-
-          otherEntries.sort((a, b) => a.key.localeCompare(b.key))
-          const entries = [...pathEntries, ...otherEntries]
-
-          const paramsNode = entries.length
-            ? ast.createFunctionParameters({
-                params: [
-                  ast.createParameterGroup({
-                    properties: entries.map((e) => ast.createFunctionParameter({ name: e.key, optional: false })),
-                  }),
-                ],
-              })
-            : undefined
-
-          const destructured = paramsNode ? (keysPrinter.print(paramsNode) ?? '') : ''
-          const inputSchema = entries.length ? `{ ${entries.map((e) => `${e.key}: ${e.value}`).join(', ')} }` : undefined
-          const outputSchema = zod.responseName
-
-          const config = [
-            tool.title ? `title: ${JSON.stringify(tool.title)}` : null,
-            `description: ${JSON.stringify(tool.description)}`,
-            outputSchema ? `outputSchema: { data: ${outputSchema} }` : null,
-          ]
-            .filter(Boolean)
-            .join(',\n  ')
-
-          if (inputSchema) {
-            return `
+  const registrations = operations
+    .map(({ tool, mcp, zod, node }) => {
+      const { path: pathParams } = getOperationParameters(node, { paramsCasing })
+
+      const pathEntries: Array<{ key: string; value: string }> = []
+      const otherEntries: Array<{ key: string; value: string }> = []
+
+      for (const p of pathParams) {
+        const zodParam = zod.pathParams.find((zp) => zp.name === p.name)
+        pathEntries.push({ key: p.name, value: zodParam ? zodParam.schemaName : zodExprFromSchemaNode(p.schema) })
+      }
+
+      if (zod.requestName) {
+        otherEntries.push({ key: 'data', value: zod.requestName })
+      }
+
+      if (zod.queryParams) {
+        otherEntries.push({ key: 'params', value: zodGroupExpr(zod.queryParams) })
+      }
+
+      if (zod.headerParams) {
+        otherEntries.push({ key: 'headers', value: zodGroupExpr(zod.headerParams) })
+      }
+
+      otherEntries.sort((a, b) => a.key.localeCompare(b.key))
+      const entries = [...pathEntries, ...otherEntries]
+
+      const paramsNode = entries.length
+        ? ast.createFunctionParameters({
+            params: [
+              ast.createParameterGroup({
+                properties: entries.map((e) => ast.createFunctionParameter({ name: e.key, optional: false })),
+              }),
+            ],
+          })
+        : null
+
+      const destructured = paramsNode ? (keysPrinter.print(paramsNode) ?? '') : ''
+      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,
+        `description: ${JSON.stringify(tool.description)}`,
+        outputSchema ? `outputSchema: { data: ${outputSchema} }` : null,
+      ]
+        .filter(Boolean)
+        .join(',\n  ')
+
+      if (inputSchema) {
+        return `
 server.registerTool(${JSON.stringify(tool.name)}, {
   ${config},
   inputSchema: ${inputSchema},
@@ -127,17 +116,33 @@ server.registerTool(${JSON.stringify(tool.name)}, {
   return ${mcp.name}(${destructured}, request)
 })
           `
-          }
+      }
 
-          return `
+      return `
 server.registerTool(${JSON.stringify(tool.name)}, {
   ${config},
 }, async (request) => {
   return ${mcp.name}(request)
 })
           `
-        })
-        .filter(Boolean)}
+    })
+    .filter(Boolean)
+    .join('\n')
+
+  return (
+    <File.Source name={name} isExportable isIndexable>
+      <Function name="getServer" export>
+        {`const server = new McpServer({
+  name: '${serverName}',
+  version: '${serverVersion}',
+})
+${registrations}
+return server`}
+      </Function>
+
+      <Const name={'server'} export>
+        {'getServer()'}
+      </Const>
 
       <Function name="startServer" async export>
         {`try {

package/src/generators/mcpGenerator.tsx

@@ -1,14 +1,22 @@
 import path from 'node:path'
+import { resolveOperationTypeNames } from '@internals/shared'
 import { ast, 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) {
+    if (!ast.isHttpOperationNode(node)) return null
     const { resolver, driver, root } = ctx
     const { output, client, paramsCasing, group } = ctx.options
 
@@ -20,30 +28,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 +57,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 +65,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 { findSuccessStatusCode, getOperationParameters } from '@internals/shared'
 import { ast, 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)
@@ -43,26 +43,26 @@ export const serverGenerator = defineGenerator<PluginMcp>({
       meta: { pluginName: plugin.name },
     }
 
-    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 operationsMapped = nodes.filter(ast.isHttpOperationNode).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) }))
 
@@ -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

@@ -1,7 +1,7 @@
 import path from 'node:path'
-import { camelCase } from '@internals/utils'
+import { createGroupConfig } from '@internals/shared'
 
-import { ast, definePlugin, type Group } from '@kubb/core'
+import { ast, definePlugin } from '@kubb/core'
 import { pluginClientName } from '@kubb/plugin-client'
 import { source as axiosClientSource } from '@kubb/plugin-client/templates/clients/axios.source'
 import { source as fetchClientSource } from '@kubb/plugin-client/templates/clients/fetch.source'
@@ -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' },
@@ -32,19 +64,7 @@ export const pluginMcp = definePlugin<PluginMcp>((options) => {
   const clientName = client?.client ?? 'axios'
   const clientImportPath = client?.importPath ?? (!client?.bundle ? `@kubb/plugin-client/clients/${clientName}` : undefined)
 
-  const groupConfig = group
-    ? ({
-        ...group,
-        name: group.name
-          ? group.name
-          : (ctx: { group: string }) => {
-              if (group.type === 'path') {
-                return `${ctx.group.split('/')[1]}`
-              }
-              return `${camelCase(ctx.group)}Requests`
-            },
-      } satisfies Group)
-    : undefined
+  const groupConfig = createGroupConfig(group, { suffix: 'Requests' })
 
   return {
     name: pluginMcpName,
@@ -87,11 +107,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)
   },
 }))