@kubb/plugin-mcp 5.0.0-alpha.9 → 5.0.0-beta.3

package/src/plugin.ts

@@ -1,170 +1,122 @@
 import path from 'node:path'
 import { camelCase } from '@internals/utils'
-import { createPlugin, type Group, getBarrelFiles, getMode } from '@kubb/core'
+
+import { ast, definePlugin, type Group } 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 { mcpGenerator } from './generators/mcpGenerator.tsx'
+import { serverGenerator } from './generators/serverGenerator.tsx'
+import { resolverMcp } from './resolvers/resolverMcp.ts'
 import type { PluginMcp } from './types.ts'
 
 export const pluginMcpName = 'plugin-mcp' satisfies PluginMcp['name']
 
-export const pluginMcp = createPlugin<PluginMcp>((options) => {
+export const pluginMcp = definePlugin<PluginMcp>((options) => {
   const {
     output = { path: 'mcp', barrelType: 'named' },
     group,
     exclude = [],
     include,
     override = [],
-    transformers = {},
-    generators = [mcpGenerator, serverGenerator].filter(Boolean),
-    contentType,
     paramsCasing,
     client,
+    resolver: userResolver,
+    transformer: userTransformer,
+    generators: userGenerators = [],
   } = options
 
   const clientName = client?.client ?? 'axios'
   const clientImportPath = client?.importPath ?? (!client?.bundle ? `@kubb/plugin-client/clients/${clientName}` : undefined)
 
-  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,
-      },
-    },
-    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
+  const groupConfig = group
+    ? ({
+        ...group,
+        name: group.name
           ? group.name
-          : (ctx) => {
-              if (group?.type === 'path') {
+          : (ctx: { group: string }) => {
+              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)
-    },
-    resolveName(name, type) {
-      const resolvedName = camelCase(name, {
-        isFile: type === 'file',
-      })
-
-      if (type) {
-        return transformers?.name?.(resolvedName, type) || resolvedName
-      }
-
-      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()
-
-      if (baseURL) {
-        this.plugin.options.client.baseURL = baseURL
-      }
-
-      const hasClientPlugin = !!this.driver.getPluginByName(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'),
-          sources: [
-            {
-              name: 'fetch',
-              value: this.plugin.options.client.client === 'fetch' ? fetchClientSource : axiosClientSource,
-              isExportable: true,
-              isIndexable: true,
             },
-          ],
-          imports: [],
-          exports: [],
-        })
-      }
+      } satisfies Group)
+    : undefined
 
-      if (!hasClientPlugin) {
-        await this.addFile({
-          baseName: 'config.ts',
-          path: path.resolve(root, '.kubb/config.ts'),
-          sources: [
-            {
-              name: 'config',
-              value: configSource,
-              isExportable: false,
-              isIndexable: false,
-            },
-          ],
-          imports: [],
-          exports: [],
+  return {
+    name: pluginMcpName,
+    options,
+    dependencies: [pluginTsName, pluginZodName],
+    hooks: {
+      'kubb:plugin:setup'(ctx) {
+        const resolver = userResolver ? { ...resolverMcp, ...userResolver } : resolverMcp
+
+        ctx.setOptions({
+          output,
+          exclude,
+          include,
+          override,
+          group: groupConfig,
+          paramsCasing,
+          client: {
+            client: clientName,
+            clientType: client?.clientType ?? 'function',
+            importPath: clientImportPath,
+            dataReturnType: client?.dataReturnType ?? 'data',
+            bundle: client?.bundle,
+            baseURL: client?.baseURL,
+            paramsCasing: client?.paramsCasing,
+          },
+          resolver,
         })
-      }
-
-      const operationGenerator = new OperationGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        driver: this.driver,
-        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)
+        ctx.setResolver(resolver)
+        if (userTransformer) {
+          ctx.setTransformer(userTransformer)
+        }
+        ctx.addGenerator(mcpGenerator)
+        ctx.addGenerator(serverGenerator)
+        for (const gen of userGenerators) {
+          ctx.addGenerator(gen)
+        }
+
+        const root = path.resolve(ctx.config.root, ctx.config.output.path)
+        const hasClientPlugin = ctx.config.plugins?.some((p) => p.name === pluginClientName)
+
+        if (client?.bundle && !hasClientPlugin && !clientImportPath) {
+          ctx.injectFile({
+            baseName: 'fetch.ts',
+            path: path.resolve(root, '.kubb/fetch.ts'),
+            sources: [
+              ast.createSource({
+                name: 'fetch',
+                nodes: [ast.createText(clientName === 'fetch' ? fetchClientSource : axiosClientSource)],
+                isExportable: true,
+                isIndexable: true,
+              }),
+            ],
+          })
+        }
+
+        if (!hasClientPlugin) {
+          ctx.injectFile({
+            baseName: 'config.ts',
+            path: path.resolve(root, '.kubb/config.ts'),
+            sources: [
+              ast.createSource({
+                name: 'config',
+                nodes: [ast.createText(configSource)],
+                isExportable: false,
+                isIndexable: false,
+              }),
+            ],
+          })
+        }
+      },
     },
   }
 })
+
+export default pluginMcp

package/src/resolvers/resolverMcp.ts

@@ -0,0 +1,25 @@
+import { camelCase } from '@internals/utils'
+import { defineResolver } from '@kubb/core'
+import type { PluginMcp } from '../types.ts'
+
+/**
+ * Naming convention resolver for MCP plugin.
+ *
+ * Provides default naming helpers using camelCase with a `handler` suffix for functions.
+ *
+ * @example
+ * `resolverMcp.default('addPet', 'function')  // → 'addPetHandler'`
+ */
+export const resolverMcp = defineResolver<PluginMcp>((ctx) => ({
+  name: 'default',
+  pluginName: 'plugin-mcp',
+  default(name, type) {
+    if (type === 'file') {
+      return camelCase(name, { isFile: true })
+    }
+    return camelCase(name, { suffix: 'handler' })
+  },
+  resolveName(name) {
+    return ctx.default(name, 'function')
+  },
+}))

package/src/types.ts

@@ -1,62 +1,80 @@
-import type { Group, Output, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
-
-import type { contentType, Oas } from '@kubb/oas'
+import type { ast, Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver } 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'
+
+/**
+ * Resolver for MCP that provides naming methods for handler functions.
+ */
+export type ResolverMcp = Resolver & {
+  /**
+   * Resolves the handler function name for an operation.
+   *
+   * @example Resolving handler function names
+   * `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.
-   * When set to 'camelcase', parameter names in path, query, and header params will be transformed to camelCase.
-   * This should match the paramsCasing setting used in @kubb/plugin-ts.
-   * @default undefined
+   * Apply casing to parameter names to match your configuration.
    */
   paramsCasing?: 'camelcase'
   /**
-   * Group the mcp requests based on the provided name.
+   * Group the MCP requests based on the provided name.
    */
   group?: Group
   /**
-   * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
+   * Tags, operations, or paths to exclude from generation.
    */
   exclude?: Array<Exclude>
   /**
-   * Array containing include parameters to include tags/operations/methods/paths.
+   * Tags, operations, or paths to include in generation.
    */
   include?: Array<Include>
   /**
-   * Array containing override parameters to override `options` based on tags/operations/methods/paths.
+   * Override options for specific tags, operations, or 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.
+   * Override naming conventions for function names and types.
+   */
+  resolver?: Partial<ResolverMcp> & ThisType<ResolverMcp>
+  /**
+   * AST visitor to transform generated nodes.
+   */
+  transformer?: ast.Visitor
+  /**
+   * Additional generators alongside the default 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, ResolverMcp>
+
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-mcp': PluginMcp
+    }
+  }
+}

package/src/utils.ts

@@ -0,0 +1,113 @@
+import { camelCase } from '@internals/utils'
+import type { ast } from '@kubb/core'
+
+/**
+ * Find the first 2xx response status code from an operation's responses.
+ */
+export function findSuccessStatusCode(responses: Array<{ statusCode: number | string }>): ast.StatusCode | undefined {
+  for (const res of responses) {
+    const code = Number(res.statusCode)
+    if (code >= 200 && code < 300) {
+      return res.statusCode as ast.StatusCode
+    }
+  }
+  return undefined
+}
+
+export type ZodParam = {
+  name: string
+  schemaName: string
+}
+
+/**
+ * Render a group param value — compose individual schemas into `z.object({ ... })`,
+ * or use a schema name string directly.
+ */
+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: ast.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: ast.SchemaNode): string {
+  let expr: string
+  switch (schema.type) {
+    case 'enum': {
+      // namedEnumValues takes priority over enumValues
+      const rawValues: Array<string | number | boolean> = schema.namedEnumValues?.length
+        ? schema.namedEnumValues.map((v) => v.value)
+        : (schema.enumValues ?? []).filter((v): v is string | number | boolean => v !== null)
+
+      if (rawValues.length > 0 && rawValues.every((v) => typeof v === 'string')) {
+        expr = `z.enum([${rawValues.map((v) => JSON.stringify(v)).join(', ')}])`
+      } else if (rawValues.length > 0) {
+        const literals = rawValues.map((v) => `z.literal(${JSON.stringify(v)})`)
+        expr = literals.length === 1 ? literals[0]! : `z.union([${literals.join(', ')}])`
+      } else {
+        expr = 'z.string()'
+      }
+      break
+    }
+    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
+}