@kubb/plugin-mcp 5.0.0-alpha.3 → 5.0.0-alpha.31

package/src/components/Server.tsx

@@ -1,16 +1,34 @@
-import { camelCase, isValidVarName } from '@internals/utils'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { SchemaObject } from '@kubb/oas'
-import type { OperationSchemas } from '@kubb/plugin-oas'
-import { isOptional } from '@kubb/plugin-oas/utils'
-import { Const, File, FunctionParams } from '@kubb/react-fabric'
+import { caseParams, createFunctionParameter, createFunctionParameters, createParameterGroup } from '@kubb/ast'
+import type { OperationNode } from '@kubb/ast/types'
+import type { KubbFile } from '@kubb/core'
+import { functionPrinter } from '@kubb/plugin-ts'
+import { Const, File, Function } from '@kubb/react-fabric'
 import type { FabricReactNode } from '@kubb/react-fabric/types'
+import type { PluginMcp } from '../types.ts'
+import type { ZodParam } from '../utils.ts'
+import { zodExprFromSchemaNode, zodGroupExpr } from '../utils.ts'
 
 type Props = {
+  /**
+   * Variable name for the MCP server instance (e.g. 'server').
+   */
   name: string
+  /**
+   * Human-readable server name passed to `new McpServer({ name })`.
+   */
   serverName: string
+  /**
+   * Semantic version string passed to `new McpServer({ version })`.
+   */
   serverVersion: string
-  paramsCasing?: 'camelcase'
+  /**
+   * How to style your params.
+   */
+  paramsCasing?: PluginMcp['resolvedOptions']['paramsCasing']
+  /**
+   * Operations to register as MCP tools, each carrying its handler,
+   * zod schema, and AST node metadata.
+   */
   operations: Array<{
     tool: {
       name: string
@@ -22,94 +40,23 @@ type Props = {
       file: KubbFile.File
     }
     zod: {
-      name: string
-      file: KubbFile.File
-      schemas: OperationSchemas
-    }
-    type: {
-      schemas: OperationSchemas
+      pathParams: Array<ZodParam>
+      /**
+       * Query params — either a group schema name (kubbV4) or individual schemas to compose (v5).
+       */
+      queryParams?: string | Array<ZodParam>
+      /**
+       * Header params — either a group schema name (kubbV4) or individual schemas to compose (v5).
+       */
+      headerParams?: string | Array<ZodParam>
+      requestName?: string
+      responseName?: string
     }
+    node: OperationNode
   }>
 }
 
-type GetParamsProps = {
-  schemas: OperationSchemas
-  paramsCasing?: 'camelcase'
-}
-
-function zodExprFromOasSchema(schema: SchemaObject): string {
-  const types = Array.isArray(schema.type) ? schema.type : [schema.type]
-  const baseType = types.find((t) => t && t !== 'null')
-  const isNullableType = types.includes('null')
-
-  let expr: string
-  switch (baseType) {
-    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 (isNullableType) {
-    expr = `${expr}.nullable()`
-  }
-
-  return expr
-}
-
-function getParams({ schemas, paramsCasing }: GetParamsProps) {
-  const pathParamProperties = schemas.pathParams?.schema?.properties ?? {}
-  const requiredFields = Array.isArray(schemas.pathParams?.schema?.required) ? schemas.pathParams.schema.required : []
-
-  const pathParamEntries = Object.entries(pathParamProperties).reduce<Record<string, { value: string; optional: boolean }>>(
-    (acc, [originalKey, propSchema]) => {
-      const key = paramsCasing === 'camelcase' || !isValidVarName(originalKey) ? camelCase(originalKey) : originalKey
-      acc[key] = {
-        value: zodExprFromOasSchema(propSchema as SchemaObject),
-        optional: !requiredFields.includes(originalKey),
-      }
-      return acc
-    },
-    {},
-  )
-
-  return FunctionParams.factory({
-    data: {
-      mode: 'object',
-      children: {
-        ...pathParamEntries,
-        data: schemas.request?.name
-          ? {
-              value: schemas.request?.name,
-              optional: isOptional(schemas.request?.schema),
-            }
-          : undefined,
-        params: schemas.queryParams?.name
-          ? {
-              value: schemas.queryParams?.name,
-              optional: isOptional(schemas.queryParams?.schema),
-            }
-          : undefined,
-        headers: schemas.headerParams?.name
-          ? {
-              value: schemas.headerParams?.name,
-              optional: isOptional(schemas.headerParams?.schema),
-            }
-          : undefined,
-      },
-    },
-  })
-}
+const keysPrinter = functionPrinter({ mode: 'keys' })
 
 export function Server({ name, serverName, serverVersion, paramsCasing, operations }: Props): FabricReactNode {
   return (
@@ -124,9 +71,46 @@ export function Server({ name, serverName, serverVersion, paramsCasing, operatio
       </Const>
 
       {operations
-        .map(({ tool, mcp, zod }) => {
-          const paramsClient = getParams({ schemas: zod.schemas, paramsCasing })
-          const outputSchema = zod.schemas.response?.name
+        .map(({ tool, mcp, zod, node }) => {
+          const casedParams = 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
+            ? createFunctionParameters({
+                params: [
+                  createParameterGroup({
+                    properties: entries.map((e) => 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,
@@ -136,13 +120,13 @@ export function Server({ name, serverName, serverVersion, paramsCasing, operatio
             .filter(Boolean)
             .join(',\n  ')
 
-          if (zod.schemas.request?.name || zod.schemas.headerParams?.name || zod.schemas.queryParams?.name || zod.schemas.pathParams?.name) {
+          if (inputSchema) {
             return `
 server.registerTool(${JSON.stringify(tool.name)}, {
   ${config},
-  inputSchema: ${paramsClient.toObjectValue()},
-}, async (${paramsClient.toObject()}) => {
-  return ${mcp.name}(${paramsClient.toObject()})
+  inputSchema: ${inputSchema},
+}, async (${destructured}) => {
+  return ${mcp.name}(${destructured})
 })
           `
           }
@@ -151,24 +135,22 @@ server.registerTool(${JSON.stringify(tool.name)}, {
 server.registerTool(${JSON.stringify(tool.name)}, {
   ${config},
 }, async () => {
-  return ${mcp.name}(${paramsClient.toObject()})
+  return ${mcp.name}()
 })
           `
         })
         .filter(Boolean)}
 
-      {`
-export async function startServer() {
-  try {
+      <Function name="startServer" async export>
+        {`try {
     const transport = new StdioServerTransport()
     await server.connect(transport)
 
   } catch (error) {
     console.error('Failed to start server:', error)
     process.exit(1)
-  }
-}
-`}
+  }`}
+      </Function>
     </File.Source>
   )
 }

package/src/generators/mcpGenerator.tsx

@@ -1,109 +1,87 @@
 import path from 'node:path'
-import { Client } from '@kubb/plugin-client/components'
-import { createReactGenerator } from '@kubb/plugin-oas/generators'
-import { useOas, useOperationManager } from '@kubb/plugin-oas/hooks'
-import { getBanner, getFooter } from '@kubb/plugin-oas/utils'
+import { caseParams } from '@kubb/ast'
+import { defineGenerator } from '@kubb/core'
 import { pluginTsName } from '@kubb/plugin-ts'
 import { File } from '@kubb/react-fabric'
-import type { PluginMcp } from '../types'
+import { McpHandler } from '../components/McpHandler.tsx'
+import type { PluginMcp } from '../types.ts'
 
-export const mcpGenerator = createReactGenerator<PluginMcp>({
+export const mcpGenerator = defineGenerator<PluginMcp>({
   name: 'mcp',
-  Operation({ config, operation, generator, plugin }) {
-    const { options } = plugin
-    const oas = useOas()
+  operation(node, options) {
+    const { resolver, driver, root } = this
+    const { output, client, paramsCasing, group } = options
 
-    const { getSchemas, getName, getFile } = useOperationManager(generator)
+    const pluginTs = driver.getPlugin(pluginTsName)
 
-    const mcp = {
-      name: getName(operation, { type: 'function', suffix: 'handler' }),
-      file: getFile(operation),
+    if (!pluginTs?.resolver) {
+      return null
     }
 
-    const type = {
-      file: getFile(operation, { pluginName: pluginTsName }),
-      schemas: getSchemas(operation, { pluginName: pluginTsName, type: 'type' }),
-    }
+    const casedParams = 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) => pluginTs.resolver.resolvePathParamsName(node, p)),
+      ...queryParams.map((p) => pluginTs.resolver.resolveQueryParamsName(node, p)),
+      ...headerParams.map((p) => pluginTs.resolver.resolveHeaderParamsName(node, p)),
+      node.requestBody?.schema ? pluginTs.resolver.resolveDataName(node) : undefined,
+      pluginTs.resolver.resolveResponseName(node),
+      ...node.responses.filter((r) => Number(r.statusCode) >= 400).map((r) => pluginTs.resolver.resolveResponseStatusName(node, r.statusCode)),
+    ].filter(Boolean)
+
+    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 }),
+      fileTs: pluginTs.resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        {
+          root,
+          output: pluginTs.options?.output ?? output,
+          group: pluginTs.options?.group,
+        },
+      ),
+    } as const
 
     return (
-      <File
-        baseName={mcp.file.baseName}
-        path={mcp.file.path}
-        meta={mcp.file.meta}
-        banner={getBanner({ oas, output: options.output })}
-        footer={getFooter({ oas, output: options.output })}
-      >
-        {options.client.importPath ? (
+      <File baseName={meta.file.baseName} path={meta.file.path} meta={meta.file.meta}>
+        {meta.fileTs && importedTypeNames.length > 0 && (
+          <File.Import name={Array.from(new Set(importedTypeNames)).sort()} root={meta.file.path} path={meta.fileTs.path} isTypeOnly />
+        )}
+        <File.Import name={['CallToolResult']} path={'@modelcontextprotocol/sdk/types'} isTypeOnly />
+        <File.Import name={['buildFormData']} root={meta.file.path} path={path.resolve(root, '.kubb/config.ts')} />
+        {client.importPath ? (
           <>
-            <File.Import name={'fetch'} path={options.client.importPath} />
-            <File.Import name={['Client', 'RequestConfig', 'ResponseErrorConfig']} path={options.client.importPath} isTypeOnly />
-            {options.client.dataReturnType === 'full' && <File.Import name={['ResponseConfig']} path={options.client.importPath} isTypeOnly />}
+            <File.Import name={['Client', 'RequestConfig', 'ResponseErrorConfig']} path={client.importPath} isTypeOnly />
+            <File.Import name={'fetch'} path={client.importPath} />
+            {client.dataReturnType === 'full' && <File.Import name={['ResponseConfig']} path={client.importPath} isTypeOnly />}
           </>
         ) : (
           <>
-            <File.Import name={['fetch']} root={mcp.file.path} path={path.resolve(config.root, config.output.path, '.kubb/fetch.ts')} />
             <File.Import
               name={['Client', 'RequestConfig', 'ResponseErrorConfig']}
-              root={mcp.file.path}
-              path={path.resolve(config.root, config.output.path, '.kubb/fetch.ts')}
+              root={meta.file.path}
+              path={path.resolve(root, '.kubb/fetch.ts')}
               isTypeOnly
             />
-            {options.client.dataReturnType === 'full' && (
-              <File.Import name={['ResponseConfig']} root={mcp.file.path} path={path.resolve(config.root, config.output.path, '.kubb/fetch.ts')} isTypeOnly />
+            <File.Import name={['fetch']} root={meta.file.path} path={path.resolve(root, '.kubb/fetch.ts')} />
+            {client.dataReturnType === 'full' && (
+              <File.Import name={['ResponseConfig']} root={meta.file.path} path={path.resolve(root, '.kubb/fetch.ts')} isTypeOnly />
             )}
           </>
         )}
-        <File.Import name={['buildFormData']} root={mcp.file.path} path={path.resolve(config.root, config.output.path, '.kubb/config.ts')} />
-        <File.Import name={['CallToolResult']} path={'@modelcontextprotocol/sdk/types'} isTypeOnly />
-        <File.Import
-          name={[
-            type.schemas.request?.name,
-            type.schemas.response.name,
-            type.schemas.pathParams?.name,
-            type.schemas.queryParams?.name,
-            type.schemas.headerParams?.name,
-            ...(type.schemas.statusCodes?.map((item) => item.name) || []),
-          ].filter(Boolean)}
-          root={mcp.file.path}
-          path={type.file.path}
-          isTypeOnly
-        />
 
-        <Client
-          name={mcp.name}
-          isConfigurable={false}
-          returnType={'Promise<CallToolResult>'}
-          baseURL={options.client.baseURL}
-          operation={operation}
-          typeSchemas={type.schemas}
-          zodSchemas={undefined}
-          dataReturnType={options.client.dataReturnType || 'data'}
-          paramsType={'object'}
-          paramsCasing={options.client?.paramsCasing || options.paramsCasing}
-          pathParamsType={'object'}
-          parser={'client'}
-        >
-          {options.client.dataReturnType === 'data' &&
-            `return {
-            content: [
-              {
-                type: 'text',
-                text: JSON.stringify(res.data)
-              }
-            ],
-            structuredContent: { data: res.data }
-           }`}
-          {options.client.dataReturnType === 'full' &&
-            `return {
-            content: [
-              {
-                type: 'text',
-                text: JSON.stringify(res)
-              }
-            ],
-            structuredContent: { data: res.data }
-           }`}
-        </Client>
+        <McpHandler
+          name={meta.name}
+          node={node}
+          resolver={pluginTs.resolver}
+          baseURL={client.baseURL}
+          dataReturnType={client.dataReturnType || 'data'}
+          paramsCasing={paramsCasing}
+        />
       </File>
     )
   },

package/src/generators/serverGenerator.tsx

@@ -1,81 +1,116 @@
-import { usePluginManager } from '@kubb/core/hooks'
-import { createReactGenerator } from '@kubb/plugin-oas/generators'
-import { useOas, useOperationManager } from '@kubb/plugin-oas/hooks'
-import { getBanner, getFooter } from '@kubb/plugin-oas/utils'
-import { pluginTsName } from '@kubb/plugin-ts'
+import path from 'node:path'
+import { caseParams } from '@kubb/ast'
+import { defineGenerator } from '@kubb/core'
 import { pluginZodName } from '@kubb/plugin-zod'
 import { File } from '@kubb/react-fabric'
-import { Server } from '../components/Server'
-import type { PluginMcp } from '../types'
+import { Server } from '../components/Server.tsx'
+import type { PluginMcp } from '../types.ts'
+import { findSuccessStatusCode } from '../utils.ts'
 
-export const serverGenerator = createReactGenerator<PluginMcp>({
+/**
+ * Default server generator for `compatibilityPreset: 'default'` (v5).
+ *
+ * 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 const serverGenerator = defineGenerator<PluginMcp>({
   name: 'operations',
-  Operations({ operations, generator, plugin }) {
-    const pluginManager = usePluginManager()
-    const { options } = plugin
+  operations(nodes, options) {
+    const { adapter, config, resolver, plugin, driver, root } = this
+    const { output, paramsCasing, group } = options
 
-    const oas = useOas()
-    const { getFile, getName, getSchemas } = useOperationManager(generator)
+    const pluginZod = driver.getPlugin(pluginZodName)
+
+    if (!pluginZod?.resolver) {
+      return
+    }
 
     const name = 'server'
-    const file = pluginManager.getFile({ name, extname: '.ts', pluginName: plugin.name })
+    const serverFilePath = path.resolve(root, output.path, 'server.ts')
+    const serverFile = {
+      baseName: 'server.ts' as const,
+      path: serverFilePath,
+      meta: { pluginName: plugin.name },
+    }
+
+    const jsonFilePath = path.resolve(root, output.path, '.mcp.json')
+    const jsonFile = {
+      baseName: '.mcp.json' as const,
+      path: jsonFilePath,
+      meta: { pluginName: plugin.name },
+    }
+
+    const operationsMapped = nodes.map((node) => {
+      const casedParams = 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 mcpFile = resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group })
+
+      const zodFile = pluginZod.resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        {
+          root,
+          output: pluginZod.options?.output ?? output,
+          group: pluginZod.options?.group,
+        },
+      )
+
+      const requestName = node.requestBody?.schema ? pluginZod.resolver.resolveDataName(node) : undefined
+      const successStatus = findSuccessStatusCode(node.responses)
+      const responseName = successStatus ? pluginZod.resolver.resolveResponseStatusName(node, successStatus) : undefined
 
-    const jsonFile = pluginManager.getFile({ name: '.mcp', extname: '.json', pluginName: plugin.name })
+      const resolveParams = (params: typeof pathParams) => params.map((p) => ({ name: p.name, schemaName: pluginZod.resolver.resolveParamName(node, p) }))
 
-    const operationsMapped = operations.map((operation) => {
       return {
         tool: {
-          name: operation.getOperationId() || operation.getSummary() || `${operation.method.toUpperCase()} ${operation.path}`,
-          title: operation.getSummary() || undefined,
-          description: operation.getDescription() || `Make a ${operation.method.toUpperCase()} request to ${operation.path}`,
+          name: node.operationId,
+          title: node.summary || undefined,
+          description: node.description || `Make a ${node.method.toUpperCase()} request to ${node.path}`,
         },
         mcp: {
-          name: getName(operation, {
-            type: 'function',
-            suffix: 'handler',
-          }),
-          file: getFile(operation),
+          name: resolver.resolveName(node.operationId),
+          file: mcpFile,
         },
         zod: {
-          name: getName(operation, {
-            type: 'function',
-            pluginName: pluginZodName,
-          }),
-          schemas: getSchemas(operation, { pluginName: pluginZodName, type: 'function' }),
-          file: getFile(operation, { pluginName: pluginZodName }),
-        },
-        type: {
-          schemas: getSchemas(operation, { pluginName: pluginTsName, type: 'type' }),
+          pathParams: resolveParams(pathParams),
+          queryParams: queryParams.length ? resolveParams(queryParams) : undefined,
+          headerParams: headerParams.length ? resolveParams(headerParams) : undefined,
+          requestName,
+          responseName,
+          file: zodFile,
         },
+        node: node,
       }
     })
 
     const imports = operationsMapped.flatMap(({ mcp, zod }) => {
+      const zodNames = [
+        ...zod.pathParams.map((p) => p.schemaName),
+        ...(zod.queryParams ?? []).map((p) => p.schemaName),
+        ...(zod.headerParams ?? []).map((p) => p.schemaName),
+        zod.requestName,
+        zod.responseName,
+      ].filter(Boolean)
+
+      const uniqueNames = [...new Set(zodNames)].sort()
+
       return [
-        <File.Import key={mcp.name} name={[mcp.name]} root={file.path} path={mcp.file.path} />,
-        <File.Import
-          key={zod.name}
-          name={[
-            zod.schemas.request?.name,
-            zod.schemas.pathParams?.name,
-            zod.schemas.queryParams?.name,
-            zod.schemas.headerParams?.name,
-            zod.schemas.response?.name,
-          ].filter(Boolean)}
-          root={file.path}
-          path={zod.file.path}
-        />,
-      ]
+        <File.Import key={mcp.name} name={[mcp.name]} root={serverFile.path} path={mcp.file.path} />,
+        uniqueNames.length > 0 && <File.Import key={`zod-${mcp.name}`} name={uniqueNames} root={serverFile.path} path={zod.file.path} />,
+      ].filter(Boolean)
     })
 
     return (
       <>
         <File
-          baseName={file.baseName}
-          path={file.path}
-          meta={file.meta}
-          banner={getBanner({ oas, output: options.output, config: pluginManager.config })}
-          footer={getFooter({ oas, output: options.output })}
+          baseName={serverFile.baseName}
+          path={serverFile.path}
+          meta={serverFile.meta}
+          banner={resolver.resolveBanner(adapter.rootNode, { output, config })}
+          footer={resolver.resolveFooter(adapter.rootNode, { output, config })}
         >
           <File.Import name={['McpServer']} path={'@modelcontextprotocol/sdk/server/mcp'} />
           <File.Import name={['z']} path={'zod'} />
@@ -84,9 +119,9 @@ export const serverGenerator = createReactGenerator<PluginMcp>({
           {imports}
           <Server
             name={name}
-            serverName={oas.api.info?.title}
-            serverVersion={oas.getVersion()}
-            paramsCasing={options.paramsCasing}
+            serverName={adapter.rootNode?.meta?.title ?? 'server'}
+            serverVersion={adapter.rootNode?.meta?.version ?? '0.0.0'}
+            paramsCasing={paramsCasing}
             operations={operationsMapped}
           />
         </File>
@@ -96,10 +131,10 @@ export const serverGenerator = createReactGenerator<PluginMcp>({
             {`
           {
             "mcpServers": {
-              "${oas.api.info?.title || 'server'}": {
+              "${adapter.rootNode?.meta?.title || 'server'}": {
                 "type": "stdio",
                 "command": "npx",
-                "args": ["tsx", "${file.path}"]
+                "args": ["tsx", "${path.relative(path.dirname(jsonFile.path), serverFile.path)}"]
               }
             }
           }