@kubb/mcp 5.0.0-beta.4 → 5.0.0-beta.40

package/src/tools/generate.ts

@@ -1,210 +1,147 @@
 import { AsyncEventEmitter } from '@internals/utils'
-import { type Config, createKubb, type KubbHooks } from '@kubb/core'
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.d.ts'
-import type { z } from 'zod'
-import type { generateSchema } from '../schemas/generateSchema.ts'
+import { type Config, createKubb, type Diagnostic, Diagnostics, type KubbHooks } from '@kubb/core'
+import { defineTool } from 'tmcp/tool'
+import { tool } from 'tmcp/utils'
+import type * as v from 'valibot'
+import { generateSchema } from '../schemas/generateSchema.ts'
+import { formatDiagnostics } from '../utils/formatDiagnostics.ts'
 import { NotifyTypes } from '../types.ts'
 import { loadUserConfig } from '../utils/loadUserConfig.ts'
 import { resolveCwd } from '../utils/resolveCwd.ts'
 import { resolveUserConfig } from '../utils/resolveUserConfig.ts'
 
-interface NotificationHandler {
-  sendNotification(method: string, params: unknown): Promise<void>
-}
-
-/**
- * Build tool that generates code from OpenAPI specs using Kubb.
- * Sends real-time notifications of build progress and events.
- */
-export async function generate(schema: z.infer<typeof generateSchema>, handler: NotificationHandler): Promise<CallToolResult> {
-  const { config: configPath, input, output, logLevel } = schema
-
-  try {
-    const hooks = new AsyncEventEmitter<KubbHooks>()
-    const messages: string[] = []
-
-    // Helper to send notifications
-    const notify = async (type: string, message: string, data?: Record<string, unknown>) => {
-      messages.push(`${type}: ${message}`)
-
-      await handler.sendNotification('kubb/progress', {
-        type,
-        message,
-        timestamp: new Date().toISOString(),
-        ...data,
-      })
-    }
-
-    // Capture events for output and send notifications
-    hooks.on('kubb:info', async ({ message }: { message: string }) => {
-      await notify(NotifyTypes.INFO, message)
-    })
-
-    hooks.on('kubb:success', async ({ message }: { message: string }) => {
-      await notify(NotifyTypes.SUCCESS, message)
-    })
+export const generateTool = defineTool(
+  {
+    name: 'generate',
+    description: 'Generate OpenAPI spec helpers using Kubb configuration',
+    schema: generateSchema,
+  },
+  async function generate(schema: v.InferInput<typeof generateSchema>) {
+    const { config: configPath, input, output, logLevel } = schema
 
-    hooks.on('kubb:error', async ({ error }: { error: Error }) => {
-      await notify(NotifyTypes.ERROR, error.message, { stack: error.stack })
-    })
+    try {
+      const hooks = new AsyncEventEmitter<KubbHooks>()
+      const messages: Array<string> = []
 
-    hooks.on('kubb:warn', async ({ message }: { message: string }) => {
-      await notify(NotifyTypes.WARN, message)
-    })
+      const notify = async (type: string, message: string, data?: Record<string, unknown>) => {
+        messages.push(data ? `${type}: ${message} ${JSON.stringify(data)}` : `${type}: ${message}`)
+      }
 
-    // Plugin lifecycle events
-    hooks.on('kubb:plugin:start', async ({ plugin }) => {
-      await notify(NotifyTypes.PLUGIN_START, `Plugin starting: ${plugin.name}`)
-    })
+      hooks.on('kubb:info', async ({ message }: { message: string }) => {
+        await notify(NotifyTypes.INFO, message)
+      })
 
-    hooks.on('kubb:plugin:end', async ({ plugin, duration }) => {
-      await notify(NotifyTypes.PLUGIN_END, `Plugin finished: ${plugin.name}`, {
-        duration,
+      hooks.on('kubb:success', async ({ message }: { message: string }) => {
+        await notify(NotifyTypes.SUCCESS, message)
       })
-    })
 
-    // File processing events
-    hooks.on('kubb:files:processing:start', async () => {
-      await notify(NotifyTypes.FILES_START, 'Starting file processing')
-    })
+      hooks.on('kubb:error', async ({ error }: { error: Error }) => {
+        await notify(NotifyTypes.ERROR, error.message)
+      })
 
-    hooks.on('kubb:file:processing:update', async ({ file }: { file: { name: string } }) => {
-      await notify(NotifyTypes.FILE_UPDATE, `Processing file: ${file.name}`)
-    })
+      hooks.on('kubb:warn', async ({ message }: { message: string }) => {
+        await notify(NotifyTypes.WARN, message)
+      })
 
-    hooks.on('kubb:files:processing:end', async () => {
-      await notify(NotifyTypes.FILES_END, 'File processing complete')
-    })
+      hooks.on('kubb:diagnostic', async ({ diagnostic }: { diagnostic: Diagnostic }) => {
+        await notify(NotifyTypes.DIAGNOSTIC, diagnostic.message, Diagnostics.serialize(diagnostic))
+      })
 
-    // Generation events
-    hooks.on('kubb:generation:start', async () => {
-      await notify(NotifyTypes.GENERATION_START, 'Generation started')
-    })
+      hooks.on('kubb:plugin:start', async ({ plugin }) => {
+        await notify(NotifyTypes.PLUGIN_START, `Plugin starting: ${plugin.name}`)
+      })
 
-    hooks.on('kubb:generation:end', async () => {
-      await notify(NotifyTypes.GENERATION_END, 'Generation ended')
-    })
+      hooks.on('kubb:plugin:end', async ({ plugin, duration }) => {
+        await notify(NotifyTypes.PLUGIN_END, `Plugin finished: ${plugin.name}`, { duration })
+      })
 
-    // Load and process configuration
-    let userConfig: Config
-    let cwd: string
+      hooks.on('kubb:files:processing:start', async () => {
+        await notify(NotifyTypes.FILES_START, 'Starting file processing')
+      })
 
-    try {
-      const configResult = await loadUserConfig(configPath, { notify })
-      userConfig = configResult.userConfig
-      cwd = configResult.cwd
+      hooks.on('kubb:files:processing:update', async ({ files }: { files: Array<{ file: { name: string } }> }) => {
+        await notify(NotifyTypes.FILES_UPDATE, `Processing ${files.length} files`)
+      })
 
-      if (Array.isArray(userConfig) && userConfig.length) {
-        throw new Error('Array type in kubb.config.ts is not supported in this tool. Please provide a single configuration object.')
-      }
+      hooks.on('kubb:files:processing:end', async () => {
+        await notify(NotifyTypes.FILES_END, 'File processing complete')
+      })
 
-      userConfig = await resolveUserConfig(userConfig, {
-        configPath,
-        logLevel,
+      hooks.on('kubb:generation:start', async () => {
+        await notify(NotifyTypes.GENERATION_START, 'Generation started')
       })
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error)
-      await notify(NotifyTypes.CONFIG_ERROR, errorMessage)
-      return {
-        content: [
-          {
-            type: 'text',
-            text: errorMessage,
-          },
-        ],
-        isError: true,
-      }
-    }
 
-    const inputPath = input ?? (userConfig.input && 'path' in userConfig.input ? userConfig.input.path : undefined)
-
-    // Override config with CLI options
-    const config: Config = {
-      ...userConfig,
-      root: resolveCwd(userConfig, cwd),
-      input: inputPath
-        ? {
-            ...userConfig.input,
-            path: inputPath,
-          }
-        : userConfig.input,
-      output: output
-        ? {
-            ...userConfig.output,
-            path: output,
-          }
-        : userConfig.output,
-    }
+      hooks.on('kubb:generation:end', async () => {
+        await notify(NotifyTypes.GENERATION_END, 'Generation ended')
+      })
 
-    await notify(NotifyTypes.CONFIG_READY, 'Configuration ready', {
-      root: config.root,
-    })
+      let userConfig: Config
+      let cwd: string
+
+      try {
+        const configResult = await loadUserConfig(configPath, { notify })
+        userConfig = configResult.userConfig
+        cwd = configResult.cwd
+
+        if (Array.isArray(userConfig)) {
+          throw new Error('Array type in kubb.config.ts is not supported in this tool. Please provide a single configuration object.')
+        }
+
+        userConfig = await resolveUserConfig(userConfig, {
+          configPath,
+          logLevel,
+        })
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error)
+        await notify(NotifyTypes.CONFIG_ERROR, errorMessage)
+        return tool.error(errorMessage)
+      }
 
-    // Setup and build
-    await notify(NotifyTypes.SETUP_START, 'Setting up Kubb')
+      const inputPath = input ?? (userConfig.input && 'path' in userConfig.input ? userConfig.input.path : undefined)
+
+      const config: Config = {
+        ...userConfig,
+        root: resolveCwd(userConfig, cwd),
+        input: inputPath
+          ? {
+              ...userConfig.input,
+              path: inputPath,
+            }
+          : userConfig.input,
+        output: output
+          ? {
+              ...userConfig.output,
+              path: output,
+            }
+          : userConfig.output,
+      }
 
-    const kubb = createKubb(config, { hooks })
-    await kubb.setup()
-    await notify(NotifyTypes.SETUP_END, 'Kubb setup complete')
+      await notify(NotifyTypes.CONFIG_READY, 'Configuration ready')
+      await notify(NotifyTypes.SETUP_START, 'Setting up Kubb')
 
-    await notify(NotifyTypes.BUILD_START, 'Starting build')
-    const { files, failedPlugins, error } = await kubb.safeBuild()
-    await notify(NotifyTypes.BUILD_END, `Build complete - Generated ${files.length} files`)
+      const kubb = createKubb(config, { hooks })
+      await kubb.setup()
+      await notify(NotifyTypes.SETUP_END, 'Kubb setup complete')
 
-    if (error || failedPlugins.size > 0) {
-      const allErrors: Error[] = [
-        error,
-        ...Array.from(failedPlugins)
-          .filter((it) => it.error)
-          .map((it) => it.error),
-      ].filter(Boolean)
+      await notify(NotifyTypes.BUILD_START, 'Starting build')
+      const { files, diagnostics } = await kubb.safeBuild()
+      await notify(NotifyTypes.BUILD_END, `Build complete - Generated ${files.length} files`)
 
-      await notify(NotifyTypes.BUILD_FAILED, `Build failed with ${allErrors.length} error(s)`, {
-        errorCount: allErrors.length,
-        errors: allErrors.map((err) => err.message),
-      })
+      const problems = diagnostics.filter(Diagnostics.isProblem)
+      const errors = problems.filter((diagnostic) => diagnostic.severity === 'error')
+      if (errors.length > 0) {
+        await notify(NotifyTypes.BUILD_FAILED, `Build failed with ${errors.length} diagnostic(s)`)
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Build failed:\n${allErrors.map((err) => err.message).join('\n')}\n\n${messages.join('\n')}`,
-          },
-        ],
-        isError: true,
+        const serialized = problems.map((diagnostic) => Diagnostics.serialize(diagnostic))
+        return tool.error(`Build failed:\n${formatDiagnostics(serialized)}\n\n\`\`\`json\n${JSON.stringify(serialized, null, 2)}\n\`\`\``)
       }
-    }
 
-    await notify(NotifyTypes.BUILD_SUCCESS, `Build completed successfully - Generated ${files.length} files`, {
-      filesCount: files.length,
-    })
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Build completed successfully!\n\nGenerated ${files.length} files\n\n${messages.join('\n')}`,
-        },
-      ],
-    }
-  } catch (caughtError) {
-    const error = caughtError as Error
-
-    await handler.sendNotification('kubb/progress', {
-      type: NotifyTypes.FATAL_ERROR,
-      message: error.message,
-      stack: error.stack,
-      timestamp: new Date().toISOString(),
-    })
-
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Build error: ${error.message}\n${error.stack || ''}`,
-        },
-      ],
-      isError: true,
+      await notify(NotifyTypes.BUILD_SUCCESS, `Build completed successfully - Generated ${files.length} files`)
+
+      return tool.text(`Build completed successfully!\n\nGenerated ${files.length} files\n\n${messages.join('\n')}`)
+    } catch (caughtError) {
+      const serialized = Diagnostics.serialize(Diagnostics.from(caughtError))
+      return tool.error(`Build error:\n${formatDiagnostics([serialized])}\n\n\`\`\`json\n${JSON.stringify(serialized, null, 2)}\n\`\`\``)
     }
-  }
-}
+  },
+)

package/src/tools/init.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { availablePlugins, generateConfigFile, KUBB_CONFIG_FILENAME, type PluginOption } from '@internals/shared'
+import { defineTool } from 'tmcp/tool'
+import { tool } from 'tmcp/utils'
+import { initSchema } from '../schemas/initSchema.ts'
+
+export function resolvePlugins(pluginsFlag: string | undefined): Array<PluginOption> {
+  if (!pluginsFlag) {
+    return []
+  }
+  const requested = pluginsFlag
+    .split(',')
+    .map((v) => v.trim())
+    .filter(Boolean)
+  return availablePlugins.filter((p) => requested.includes(p.value))
+}
+
+export const initTool = defineTool(
+  {
+    name: 'init',
+    description: 'Scaffold a kubb.config.ts in the current directory (non-interactive). Does not install packages.',
+    schema: initSchema,
+  },
+  async ({ input = './openapi.yaml', output = './src/gen', plugins }) => {
+    const selected = resolvePlugins(plugins)
+    const content = generateConfigFile({ selectedPlugins: selected, inputPath: input, outputPath: output })
+    const dest = path.join(process.cwd(), KUBB_CONFIG_FILENAME)
+    if (fs.existsSync(dest)) {
+      return tool.error(`${KUBB_CONFIG_FILENAME} already exists at ${dest}. Delete it first before running init again.`)
+    }
+    fs.writeFileSync(dest, content, 'utf-8')
+    const packageList = ['kubb', ...selected.map((p) => p.packageName)].join(' ')
+    return tool.text(`Created kubb.config.ts\n\nInstall packages:\n  npm install ${packageList}\n\nThen run:\n  npx kubb generate`)
+  },
+)

package/src/tools/validate.ts

@@ -0,0 +1,28 @@
+import { Diagnostics } from '@kubb/core'
+import { defineTool } from 'tmcp/tool'
+import { tool } from 'tmcp/utils'
+import { validateSchema } from '../schemas/validateSchema.ts'
+import { formatDiagnostics } from '../utils/formatDiagnostics.ts'
+
+export const validateTool = defineTool(
+  {
+    name: 'validate',
+    description: 'Validate an OpenAPI/Swagger specification file or URL',
+    schema: validateSchema,
+  },
+  async ({ input }) => {
+    let mod: typeof import('@kubb/adapter-oas')
+    try {
+      mod = await import('@kubb/adapter-oas')
+    } catch {
+      return tool.error('The validate tool requires @kubb/adapter-oas.\nInstall: npm install @kubb/adapter-oas')
+    }
+    try {
+      await mod.adapterOas().validate(input, { throwOnError: true })
+      return tool.text(`Validation successful: ${input}`)
+    } catch (err) {
+      const serialized = Diagnostics.serialize(Diagnostics.from(err))
+      return tool.error(`Validation failed:\n${formatDiagnostics([serialized])}\n\n\`\`\`json\n${JSON.stringify(serialized, null, 2)}\n\`\`\``)
+    }
+  },
+)

package/src/types.ts

@@ -3,10 +3,11 @@ export const NotifyTypes = {
   SUCCESS: 'SUCCESS',
   ERROR: 'ERROR',
   WARN: 'WARN',
+  DIAGNOSTIC: 'DIAGNOSTIC',
   PLUGIN_START: 'PLUGIN_START',
   PLUGIN_END: 'PLUGIN_END',
   FILES_START: 'FILES_START',
-  FILE_UPDATE: 'FILE_UPDATE',
+  FILES_UPDATE: 'FILES_UPDATE',
   FILES_END: 'FILES_END',
   GENERATION_START: 'GENERATION_START',
   GENERATION_END: 'GENERATION_END',

package/src/utils/formatDiagnostics.ts

@@ -0,0 +1,29 @@
+import type { SerializedDiagnostic } from '@kubb/core'
+
+/**
+ * Renders serialized diagnostics as a plain-text block for an AI assistant. Each entry
+ * keeps the stable `code`, the source pointer, the suggested fix, and the docs link, so
+ * the agent can act on the problem rather than parsing a bare message. No ANSI styling,
+ * unlike the CLI renderer.
+ */
+export function formatDiagnostics(diagnostics: ReadonlyArray<SerializedDiagnostic>): string {
+  return diagnostics.map((diagnostic) => formatDiagnostic(diagnostic)).join('\n\n')
+}
+
+function formatDiagnostic(diagnostic: SerializedDiagnostic): string {
+  const { code, severity, message, location, help, plugin, docsUrl } = diagnostic
+  const rule = plugin ? `${plugin}(${code})` : code
+  const lines = [`${severity} ${rule}: ${message}`]
+
+  if (location && 'pointer' in location) {
+    lines.push(`  at ${location.pointer}`)
+  }
+  if (help) {
+    lines.push(`  help: ${help}`)
+  }
+  if (docsUrl) {
+    lines.push(`  docs: ${docsUrl}`)
+  }
+
+  return lines.join('\n')
+}

package/src/utils/loadUserConfig.ts

@@ -1,12 +1,20 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { Config } from '@kubb/core'
-import { unrun } from 'unrun'
+import { createJiti } from 'jiti'
 import { ALLOWED_CONFIG_EXTENSIONS } from '../constants.ts'
 import { NotifyTypes } from '../types.ts'
 
 type NotifyFunction = (type: string, message: string, data?: Record<string, unknown>) => Promise<void>
 
+const jiti = createJiti(import.meta.url, {
+  jsx: {
+    runtime: 'automatic',
+    importSource: '@kubb/renderer-jsx',
+  },
+  moduleCache: false,
+})
+
 const loadedModules = new Map<string, unknown>()
 
 async function loadModule(filePath: string): Promise<unknown> {
@@ -17,15 +25,12 @@ async function loadModule(filePath: string): Promise<unknown> {
   if (loadedModules.has(filePath)) {
     return loadedModules.get(filePath)
   }
-  const { module } = await unrun({ path: filePath })
-  loadedModules.set(filePath, module)
-  return module
+  const mod = await jiti.import(filePath, { default: true })
+  loadedModules.set(filePath, mod)
+  return mod
 }
 
 export async function loadUserConfig(configPath: string | undefined, { notify }: { notify: NotifyFunction }): Promise<{ userConfig: Config; cwd: string }> {
-  let userConfig: Config | undefined
-  let cwd: string
-
   if (configPath) {
     const ext = path.extname(configPath)
     if (!ALLOWED_CONFIG_EXTENSIONS.has(ext)) {
@@ -41,37 +46,33 @@ export async function loadUserConfig(configPath: string | undefined, { notify }:
       await notify(NotifyTypes.CONFIG_ERROR, msg)
       throw new Error(msg)
     }
-    cwd = path.dirname(resolvedConfigPath)
-
+    const cwd = path.dirname(resolvedConfigPath)
     try {
-      userConfig = (await loadModule(resolvedConfigPath)) as Config
+      const userConfig = (await loadModule(resolvedConfigPath)) as Config
       await notify(NotifyTypes.CONFIG_LOADED, `Loaded config from ${resolvedConfigPath}`)
+      return { userConfig, cwd }
     } catch (error) {
-      await notify(NotifyTypes.CONFIG_ERROR, `Failed to load config: ${error instanceof Error ? error.message : String(error)}`)
-      throw new Error(`Failed to load config: ${error instanceof Error ? error.message : String(error)}`)
-    }
-  } else {
-    cwd = process.cwd()
-    const configFileNames = ['kubb.config.ts', 'kubb.config.mts', 'kubb.config.cts', 'kubb.config.js', 'kubb.config.cjs']
-
-    for (const configFileName of configFileNames) {
-      const configFilePath = path.resolve(process.cwd(), configFileName)
-      if (!existsSync(configFilePath)) continue
-      try {
-        userConfig = (await loadModule(configFilePath)) as Config
-        await notify(NotifyTypes.CONFIG_LOADED, `Loaded ${configFileName} from current directory`)
-        break
-      } catch {
-        // Continue trying next config file
-      }
+      const msg = `Failed to load config: ${error instanceof Error ? error.message : String(error)}`
+      await notify(NotifyTypes.CONFIG_ERROR, msg)
+      throw new Error(msg)
     }
+  }
 
-    if (!userConfig) {
-      await notify(NotifyTypes.CONFIG_ERROR, 'No config file found')
+  const cwd = process.cwd()
+  const configFileNames = ['kubb.config.ts', 'kubb.config.mts', 'kubb.config.cts', 'kubb.config.js', 'kubb.config.cjs']
 
-      throw new Error(`No config file found. Please provide a config path or create one of: ${configFileNames.join(', ')}`)
+  for (const configFileName of configFileNames) {
+    const configFilePath = path.resolve(process.cwd(), configFileName)
+    if (!existsSync(configFilePath)) continue
+    try {
+      const userConfig = (await loadModule(configFilePath)) as Config
+      await notify(NotifyTypes.CONFIG_LOADED, `Loaded ${configFileName} from current directory`)
+      return { userConfig, cwd }
+    } catch (err) {
+      await notify(NotifyTypes.CONFIG_ERROR, `Failed to load ${configFileName}: ${err instanceof Error ? err.message : String(err)}`)
     }
   }
 
-  return { userConfig: userConfig!, cwd }
+  await notify(NotifyTypes.CONFIG_ERROR, 'No config file found')
+  throw new Error(`No config file found. Please provide a config path or create one of: ${configFileNames.join(', ')}`)
 }

package/src/utils/resolveUserConfig.ts

@@ -1,28 +1,13 @@
 import { isPromise } from '@internals/utils'
-import type { CLIOptions, Config } from '@kubb/core'
+import type { CLIOptions, Config, PossibleConfig } from '@kubb/core'
 
 export type ResolveUserConfigOptions = {
   configPath?: string
   logLevel?: string
 }
 
-/**
- * Resolve the config by handling function configs and returning the final configuration
- */
-export async function resolveUserConfig(config: Config, options: ResolveUserConfigOptions): Promise<Config> {
-  let kubbUserConfig = Promise.resolve(config) as Promise<Config>
-
-  if (typeof config === 'function') {
-    const possiblePromise = (config as any)({
-      logLevel: options.logLevel,
-      config: options.configPath,
-    } as CLIOptions)
-    if (isPromise(possiblePromise)) {
-      kubbUserConfig = possiblePromise
-    } else {
-      kubbUserConfig = Promise.resolve(possiblePromise)
-    }
-  }
-
-  return (await kubbUserConfig) as Config
+export async function resolveUserConfig(config: PossibleConfig<CLIOptions>, options: ResolveUserConfigOptions): Promise<Config> {
+  const result = typeof config === 'function' ? config({ logLevel: options.logLevel as CLIOptions['logLevel'], config: options.configPath }) : config
+  const resolved = isPromise(result) ? await result : result
+  return (Array.isArray(resolved) ? resolved[0] : resolved) as Config
 }