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

package/src/generators/serverGeneratorLegacy.tsx

@@ -0,0 +1,138 @@
+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.tsx'
+import type { PluginMcp } from '../types.ts'
+
+/**
+ * Legacy server generator for `compatibilityPreset: 'kubbV4'`.
+ *
+ * Uses grouped zod schemas for query/header params (e.g. `createPetsQueryParamsSchema`)
+ * and `resolveResponseName` for the combined response schema.
+ * Path params are always rendered inline (no named imports).
+ */
+export const serverGeneratorLegacy = defineGenerator<PluginMcp>({
+  name: 'operations',
+  operations(nodes, options) {
+    const { adapter, config, resolver, plugin, driver, root } = this
+    const { output, paramsCasing, group } = options
+
+    const pluginZod = driver.getPlugin(pluginZodName)
+
+    if (!pluginZod?.resolver) {
+      return
+    }
+
+    const name = 'server'
+    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 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 responseName = pluginZod?.resolver.resolveResponseName(node)
+
+      const zodQueryParams = queryParams.length ? pluginZod?.resolver.resolveQueryParamsName(node, queryParams[0]!) : undefined
+
+      const zodHeaderParams = headerParams.length ? pluginZod?.resolver.resolveHeaderParamsName(node, headerParams[0]!) : undefined
+
+      return {
+        tool: {
+          name: node.operationId,
+          title: node.summary || undefined,
+          description: node.description || `Make a ${node.method.toUpperCase()} request to ${node.path}`,
+        },
+        mcp: {
+          name: resolver.resolveName(node.operationId),
+          file: mcpFile,
+        },
+        zod: {
+          pathParams: [],
+          queryParams: zodQueryParams,
+          headerParams: zodHeaderParams,
+          requestName,
+          responseName,
+          file: zodFile,
+        },
+        node: node,
+      }
+    })
+
+    const imports = operationsMapped.flatMap(({ mcp, zod }) => {
+      const zodNames = [zod.queryParams, zod.headerParams, zod.requestName, zod.responseName].filter(Boolean) as string[]
+
+      return [
+        <File.Import key={mcp.name} name={[mcp.name]} root={serverFile.path} path={mcp.file.path} />,
+        zod.file && zodNames.length > 0 && <File.Import key={`zod-${mcp.name}`} name={zodNames.sort()} root={serverFile.path} path={zod.file.path} />,
+      ].filter(Boolean)
+    })
+
+    return (
+      <>
+        <File
+          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'} />
+          <File.Import name={['StdioServerTransport']} path={'@modelcontextprotocol/sdk/server/stdio'} />
+
+          {imports}
+          <Server
+            name={name}
+            serverName={adapter.rootNode?.meta?.title ?? 'server'}
+            serverVersion={(adapter.document as { openapi?: string })?.openapi ?? adapter.rootNode?.meta?.version ?? '0.0.0'}
+            paramsCasing={paramsCasing}
+            operations={operationsMapped}
+          />
+        </File>
+
+        <File baseName={jsonFile.baseName} path={jsonFile.path} meta={jsonFile.meta}>
+          <File.Source name={name}>
+            {`
+          {
+            "mcpServers": {
+              "${adapter.rootNode?.meta?.title || 'server'}": {
+                "type": "stdio",
+                "command": "npx",
+                "args": ["tsx", "${path.relative(path.dirname(jsonFile.path), serverFile.path)}"]
+              }
+            }
+          }
+          `}
+          </File.Source>
+        </File>
+      </>
+    )
+  },
+})

package/src/index.ts

@@ -1,2 +1,12 @@
+export { McpHandler } from './components/McpHandler.tsx'
+export { Server } from './components/Server.tsx'
+
+export { mcpGenerator } from './generators/mcpGenerator.tsx'
+export { serverGenerator } from './generators/serverGenerator.tsx'
+export { serverGeneratorLegacy } from './generators/serverGeneratorLegacy.tsx'
+
 export { pluginMcp, pluginMcpName } from './plugin.ts'
-export type { PluginMcp } from './types.ts'
+
+export { resolverMcp } from './resolvers/resolverMcp.ts'
+
+export type { PluginMcp, ResolverMcp } from './types.ts'

package/src/plugin.ts

@@ -1,111 +1,110 @@
 import path from 'node:path'
 import { camelCase } from '@internals/utils'
-import { definePlugin, type Group, getBarrelFiles, getMode } from '@kubb/core'
+import { createPlugin, type Group, getPreset, mergeGenerators } 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'
 import { source as configSource } from '@kubb/plugin-client/templates/config.source'
-import { OperationGenerator, pluginOasName } from '@kubb/plugin-oas'
 import { pluginTsName } from '@kubb/plugin-ts'
 import { pluginZodName } from '@kubb/plugin-zod'
-import { mcpGenerator, serverGenerator } from './generators'
+import { version } from '../package.json'
+import { presets } from './presets.ts'
 import type { PluginMcp } from './types.ts'
 
 export const pluginMcpName = 'plugin-mcp' satisfies PluginMcp['name']
 
-export const pluginMcp = definePlugin<PluginMcp>((options) => {
+export const pluginMcp = createPlugin<PluginMcp>((options) => {
   const {
     output = { path: 'mcp', barrelType: 'named' },
     group,
     exclude = [],
     include,
     override = [],
-    transformers = {},
-    generators = [mcpGenerator, serverGenerator].filter(Boolean),
-    contentType,
     paramsCasing,
     client,
+    compatibilityPreset = 'default',
+    resolver: userResolver,
+    transformer: userTransformer,
+    generators: userGenerators = [],
   } = options
 
   const clientName = client?.client ?? 'axios'
   const clientImportPath = client?.importPath ?? (!client?.bundle ? `@kubb/plugin-client/clients/${clientName}` : undefined)
 
+  const preset = getPreset({
+    preset: compatibilityPreset,
+    presets,
+    resolver: userResolver,
+    transformer: userTransformer,
+    generators: userGenerators,
+  })
+
+  const generators = preset.generators ?? []
+  const mergedGenerator = mergeGenerators(generators)
+
   return {
     name: pluginMcpName,
-    options: {
-      output,
-      group,
-      paramsCasing,
-      client: {
-        client: clientName,
-        clientType: client?.clientType ?? 'function',
-        importPath: clientImportPath,
-        dataReturnType: client?.dataReturnType ?? 'data',
-        bundle: client?.bundle,
-        baseURL: client?.baseURL,
-        paramsCasing: client?.paramsCasing,
-      },
+    version,
+    get resolver() {
+      return preset.resolver
     },
-    pre: [pluginOasName, pluginTsName, pluginZodName].filter(Boolean),
-    resolvePath(baseName, pathMode, options) {
-      const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = pathMode ?? getMode(path.resolve(root, output.path))
-
-      if (mode === 'single') {
-        /**
-         * when output is a file then we will always append to the same file(output file), see fileManager.addOrAppend
-         * Other plugins then need to call addOrAppend instead of just add from the fileManager class
-         */
-        return path.resolve(root, output.path)
-      }
-
-      if (group && (options?.group?.path || options?.group?.tag)) {
-        const groupName: Group['name'] = group?.name
-          ? group.name
-          : (ctx) => {
-              if (group?.type === 'path') {
-                return `${ctx.group.split('/')[1]}`
-              }
-              return `${camelCase(ctx.group)}Requests`
-            }
-
-        return path.resolve(
-          root,
-          output.path,
-          groupName({
-            group: group.type === 'path' ? options.group.path! : options.group.tag!,
-          }),
-          baseName,
-        )
-      }
-
-      return path.resolve(root, output.path, baseName)
+    get transformer() {
+      return preset.transformer
     },
-    resolveName(name, type) {
-      const resolvedName = camelCase(name, {
-        isFile: type === 'file',
-      })
-
-      if (type) {
-        return transformers?.name?.(resolvedName, type) || resolvedName
+    get options() {
+      return {
+        output,
+        exclude,
+        include,
+        override,
+        group: 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,
+        paramsCasing,
+        client: {
+          client: clientName,
+          clientType: client?.clientType ?? 'function',
+          importPath: clientImportPath,
+          dataReturnType: client?.dataReturnType ?? 'data',
+          bundle: client?.bundle,
+          baseURL: client?.baseURL,
+          paramsCasing: client?.paramsCasing,
+        },
+        resolver: preset.resolver,
       }
-
-      return resolvedName
     },
-    async install() {
-      const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = getMode(path.resolve(root, output.path))
-      const oas = await this.getOas()
-      const baseURL = await this.getBaseURL()
+    pre: [pluginTsName, pluginZodName].filter(Boolean),
+    async schema(node, options) {
+      return mergedGenerator.schema?.call(this, node, options)
+    },
+    async operation(node, options) {
+      return mergedGenerator.operation?.call(this, node, options)
+    },
+    async operations(nodes, options) {
+      return mergedGenerator.operations?.call(this, nodes, options)
+    },
+    async buildStart() {
+      const { adapter, driver } = this
+      const root = this.root
 
+      const baseURL = adapter?.rootNode?.meta?.baseURL
       if (baseURL) {
-        this.plugin.options.client.baseURL = baseURL
+        this.plugin.options.client.baseURL = this.plugin.options.client.baseURL || baseURL
       }
 
-      const hasClientPlugin = !!this.pluginManager.getPluginByName(pluginClientName)
+      const hasClientPlugin = !!driver.getPlugin(pluginClientName)
 
       if (this.plugin.options.client.bundle && !hasClientPlugin && !this.plugin.options.client.importPath) {
-        // pre add bundled fetch
         await this.addFile({
           baseName: 'fetch.ts',
           path: path.resolve(root, '.kubb/fetch.ts'),
@@ -139,32 +138,7 @@ export const pluginMcp = definePlugin<PluginMcp>((options) => {
         })
       }
 
-      const operationGenerator = new OperationGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        pluginManager: this.pluginManager,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        exclude,
-        include,
-        override,
-        mode,
-      })
-
-      const files = await operationGenerator.build(...generators)
-      await this.upsertFile(...files)
-
-      const barrelFiles = await getBarrelFiles(this.fabric.files, {
-        type: output.barrelType ?? 'named',
-        root,
-        output,
-        meta: {
-          pluginName: this.plugin.name,
-        },
-      })
-
-      await this.upsertFile(...barrelFiles)
+      await this.openInStudio({ ast: true })
     },
   }
 })

package/src/presets.ts

@@ -0,0 +1,25 @@
+import { definePresets } from '@kubb/core'
+import { mcpGenerator } from './generators/mcpGenerator.tsx'
+import { serverGenerator } from './generators/serverGenerator.tsx'
+import { serverGeneratorLegacy } from './generators/serverGeneratorLegacy.tsx'
+import { resolverMcp } from './resolvers/resolverMcp.ts'
+import type { ResolverMcp } from './types.ts'
+
+/**
+ * Built-in preset registry for `@kubb/plugin-mcp`.
+ *
+ * - `default` — v5 naming with individual zod schemas and per-status responses.
+ * - `kubbV4`  — legacy naming with grouped zod schemas and combined responses.
+ */
+export const presets = definePresets<ResolverMcp>({
+  default: {
+    name: 'default',
+    resolver: resolverMcp,
+    generators: [mcpGenerator, serverGenerator],
+  },
+  kubbV4: {
+    name: 'kubbV4',
+    resolver: resolverMcp,
+    generators: [mcpGenerator, serverGeneratorLegacy],
+  },
+})

package/src/resolvers/resolverMcp.ts

@@ -0,0 +1,29 @@
+import { camelCase } from '@internals/utils'
+import { defineResolver } from '@kubb/core'
+import type { PluginMcp } from '../types.ts'
+
+/**
+ * Resolver for `@kubb/plugin-mcp` that provides the default naming
+ * and path-resolution helpers used by the plugin.
+ *
+ * @example
+ * ```ts
+ * import { resolverMcp } from '@kubb/plugin-mcp'
+ *
+ * resolverMcp.default('addPet', 'function') // -> 'addPetHandler'
+ * resolverMcp.resolveName('show pet by id')  // -> 'showPetByIdHandler'
+ * ```
+ */
+export const resolverMcp = defineResolver<PluginMcp>(() => ({
+  name: 'default',
+  pluginName: 'plugin-mcp',
+  default(name, type) {
+    if (type === 'file') {
+      return camelCase(name, { isFile: true })
+    }
+    return camelCase(name, { suffix: 'handler' })
+  },
+  resolveName(name) {
+    return this.default(name, 'function')
+  },
+}))

package/src/types.ts

@@ -1,21 +1,41 @@
-import type { Group, Output, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
-
-import type { contentType, Oas } from '@kubb/oas'
+import type { Visitor } from '@kubb/ast/types'
+import type {
+  CompatibilityPreset,
+  Exclude,
+  Generator,
+  Group,
+  Include,
+  Output,
+  Override,
+  PluginFactoryOptions,
+  ResolvePathOptions,
+  Resolver,
+  UserGroup,
+} from '@kubb/core'
 import type { ClientImportPath, PluginClient } from '@kubb/plugin-client'
-import type { Exclude, Include, Override, ResolvePathOptions } from '@kubb/plugin-oas'
-import type { Generator } from '@kubb/plugin-oas/generators'
+
+/**
+ * The concrete resolver type for `@kubb/plugin-mcp`.
+ * Extends the base `Resolver` with a `resolveName` helper for MCP handler function names.
+ */
+export type ResolverMcp = Resolver & {
+  /**
+   * Resolves the handler function name for a given raw operation name.
+   * @example
+   * resolver.resolveName('show pet by id') // -> 'showPetByIdHandler'
+   */
+  resolveName(this: ResolverMcp, name: string): string
+}
 
 export type Options = {
   /**
-   * Specify the export location for the files and define the behavior of the output
+   * Specify the export location for the files and define the behavior of the output.
    * @default { path: 'mcp', barrelType: 'named' }
    */
-  output?: Output<Oas>
+  output?: Output
   /**
-   * Define which contentType should be used.
-   * By default, the first JSON valid mediaType is used
+   * Client configuration for HTTP request generation.
    */
-  contentType?: contentType
   client?: ClientImportPath & Pick<PluginClient['options'], 'clientType' | 'dataReturnType' | 'baseURL' | 'bundle' | 'paramsCasing'>
   /**
    * Transform parameter names to a specific casing format.
@@ -25,9 +45,9 @@ export type Options = {
    */
   paramsCasing?: 'camelcase'
   /**
-   * Group the mcp requests based on the provided name.
+   * Group the MCP requests based on the provided name.
    */
-  group?: Group
+  group?: UserGroup
   /**
    * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
    */
@@ -40,23 +60,44 @@ export type Options = {
    * Array containing override parameters to override `options` based on tags/operations/methods/paths.
    */
   override?: Array<Override<ResolvedOptions>>
-  transformers?: {
-    /**
-     * Customize the names based on the type that is provided by the plugin.
-     */
-    name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
-  }
   /**
-   * Define some generators next to the Mcp generators.
+   * Apply a compatibility naming preset.
+   * @default 'default'
+   */
+  compatibilityPreset?: CompatibilityPreset
+  /**
+   * A single resolver whose methods override the default resolver's naming conventions.
+   * When a method returns `null` or `undefined`, the default resolver's result is used instead.
+   */
+  resolver?: Partial<ResolverMcp> & ThisType<ResolverMcp>
+  /**
+   * A single AST visitor applied before printing.
+   * When a visitor method returns `null` or `undefined`, the preset transformer's result is used instead.
+   */
+  transformer?: Visitor
+  /**
+   * Define some generators next to the default MCP generators.
    */
   generators?: Array<Generator<PluginMcp>>
 }
 
 type ResolvedOptions = {
-  output: Output<Oas>
-  group: Options['group']
+  output: Output
+  exclude: Array<Exclude>
+  include: Array<Include> | undefined
+  override: Array<Override<ResolvedOptions>>
+  group: Group | undefined
   client: Pick<PluginClient['options'], 'client' | 'clientType' | 'dataReturnType' | 'importPath' | 'baseURL' | 'bundle' | 'paramsCasing'>
   paramsCasing: Options['paramsCasing']
+  resolver: ResolverMcp
 }
 
-export type PluginMcp = PluginFactoryOptions<'plugin-mcp', Options, ResolvedOptions, never, ResolvePathOptions>
+export type PluginMcp = PluginFactoryOptions<'plugin-mcp', Options, ResolvedOptions, never, ResolvePathOptions, ResolverMcp>
+
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-mcp': PluginMcp
+    }
+  }
+}

package/src/utils.ts

@@ -0,0 +1,97 @@
+import { camelCase } from '@internals/utils'
+import type { OperationNode, SchemaNode, StatusCode } from '@kubb/ast/types'
+
+/**
+ * Find the first 2xx response status code from an operation's responses.
+ */
+export function findSuccessStatusCode(responses: Array<{ statusCode: number | string }>): StatusCode | undefined {
+  for (const res of responses) {
+    const code = Number(res.statusCode)
+    if (code >= 200 && code < 300) {
+      return res.statusCode as StatusCode
+    }
+  }
+  return undefined
+}
+
+export type ZodParam = {
+  name: string
+  schemaName: string
+}
+
+/**
+ * Render a group param value — either a group schema name directly (kubbV4),
+ * or compose individual schemas into `z.object({ ... })` (v5).
+ */
+export function zodGroupExpr(entry: string | Array<ZodParam>): string {
+  if (typeof entry === 'string') {
+    return entry
+  }
+  const entries = entry.map((p) => `${JSON.stringify(p.name)}: ${p.schemaName}`)
+  return `z.object({ ${entries.join(', ')} })`
+}
+
+/**
+ * Build JSDoc comment lines from an OperationNode.
+ */
+export function getComments(node: OperationNode): Array<string> {
+  return [
+    node.description && `@description ${node.description}`,
+    node.summary && `@summary ${node.summary}`,
+    node.deprecated && '@deprecated',
+    `{@link ${node.path.replaceAll('{', ':').replaceAll('}', '')}}`,
+  ].filter((x): x is string => Boolean(x))
+}
+
+/**
+ * Build a mapping of original param names → camelCase names.
+ * Returns `undefined` when no names actually change (no remapping needed).
+ */
+export function getParamsMapping(params: Array<{ name: string }>): Record<string, string> | undefined {
+  if (!params.length) {
+    return undefined
+  }
+
+  const mapping: Record<string, string> = {}
+  let hasDifference = false
+
+  for (const p of params) {
+    const camelName = camelCase(p.name)
+    mapping[p.name] = camelName
+    if (p.name !== camelName) {
+      hasDifference = true
+    }
+  }
+
+  return hasDifference ? mapping : undefined
+}
+
+/**
+ * Convert a SchemaNode type to an inline Zod expression string.
+ * Used as fallback when no named zod schema is available for a path parameter.
+ */
+export function zodExprFromSchemaNode(schema: SchemaNode): string {
+  let expr: string
+  switch (schema.type) {
+    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()`
+  }
+
+  return expr
+}