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

package/package.json

@@ -1,70 +1,65 @@
 {
   "name": "@kubb/plugin-mcp",
-  "version": "5.0.0-alpha.9",
-  "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.10",
+  "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": [
-    "mcp",
-    "model-context-protocol",
     "ai",
-    "llm",
-    "claude",
     "ai-tools",
+    "code-generation",
+    "codegen",
+    "kubb",
+    "llm",
+    "mcp",
+    "model-context-protocol",
     "openapi",
     "swagger",
-    "typescript",
-    "code-generator",
-    "codegen",
-    "plugins",
-    "kubb"
+    "typescript"
   ],
+  "license": "MIT",
+  "author": "stijnvanhulle",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kubb-labs/kubb.git",
+    "url": "git+https://github.com/kubb-labs/plugins.git",
     "directory": "packages/plugin-mcp"
   },
-  "license": "MIT",
-  "author": "stijnvanhulle",
-  "sideEffects": false,
+  "files": [
+    "src",
+    "dist",
+    "extension.yaml",
+    "!/**/**.test.**",
+    "!/**/__tests__/**",
+    "!/**/__snapshots__/**"
+  ],
   "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./components": {
-      "import": "./dist/components.js",
-      "require": "./dist/components.cjs"
-    },
-    "./generators": {
-      "import": "./dist/generators.js",
-      "require": "./dist/generators.cjs"
-    },
     "./package.json": "./package.json"
   },
-  "types": "./dist/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "utils": [
-        "./dist/utils.d.ts"
-      ],
-      "hooks": [
-        "./dist/hooks.d.ts"
-      ],
-      "components": [
-        "./dist/components.d.ts"
-      ],
-      "generators": [
-        "./dist/generators.d.ts"
-      ]
-    }
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@kubb/core": "5.0.0-beta.10",
+    "@kubb/renderer-jsx": "5.0.0-beta.10",
+    "@kubb/plugin-client": "5.0.0-beta.10",
+    "@kubb/plugin-ts": "5.0.0-beta.10",
+    "@kubb/plugin-zod": "5.0.0-beta.10"
+  },
+  "devDependencies": {
+    "@internals/shared": "0.0.0",
+    "@internals/utils": "0.0.0"
+  },
+  "peerDependencies": {
+    "@kubb/renderer-jsx": "5.0.0-beta.10"
   },
-  "files": [
-    "src",
-    "dist",
-    "!/**/**.test.**",
-    "!/**/__tests__/**",
-    "!/**/__snapshots__/**"
-  ],
   "size-limit": [
     {
       "path": "./dist/*.js",
@@ -72,32 +67,14 @@
       "gzip": true
     }
   ],
-  "dependencies": {
-    "@kubb/react-fabric": "0.14.0",
-    "@kubb/core": "5.0.0-alpha.9",
-    "@kubb/oas": "5.0.0-alpha.9",
-    "@kubb/plugin-client": "5.0.0-alpha.9",
-    "@kubb/plugin-oas": "5.0.0-alpha.9",
-    "@kubb/plugin-ts": "5.0.0-alpha.9",
-    "@kubb/plugin-zod": "5.0.0-alpha.9"
-  },
-  "devDependencies": {
-    "@internals/utils": "0.0.0"
-  },
   "engines": {
     "node": ">=22"
   },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
   "scripts": {
     "build": "tsdown && size-limit",
     "clean": "npx rimraf ./dist",
-    "lint": "bun biome lint .",
-    "lint:fix": "bun biome lint --fix --unsafe .",
+    "lint": "oxlint .",
+    "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",
     "start": "tsdown --watch",

package/src/components/McpHandler.tsx

@@ -0,0 +1,167 @@
+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'
+
+type Props = {
+  /**
+   * Name of the handler function.
+   */
+  name: string
+  /**
+   * AST operation node.
+   */
+  node: ast.OperationNode
+  /**
+   * TypeScript resolver for resolving param/data/response type names.
+   */
+  resolver: ResolverTs
+  /**
+   * Base URL prepended to every generated request URL.
+   */
+  baseURL: string | undefined
+  /**
+   * Return type when calling fetch.
+   * - 'data' returns response data only.
+   * - 'full' returns the full response object.
+   * @default 'data'
+   */
+  dataReturnType: PluginMcp['resolvedOptions']['client']['dataReturnType']
+  /**
+   * How to style your params.
+   */
+  paramsCasing?: PluginMcp['resolvedOptions']['paramsCasing']
+}
+
+/**
+ * Generate a remapping statement: `const mappedX = x ? { "orig": x.camel, ... } : undefined`
+ */
+function buildRemappingCode(mapping: Record<string, string>, varName: string, sourceName: string): string {
+  const pairs = Object.entries(mapping)
+    .map(([orig, camel]) => `"${orig}": ${sourceName}.${camel}`)
+    .join(', ')
+  return `const ${varName} = ${sourceName} ? { ${pairs} } : undefined`
+}
+
+const declarationPrinter = functionPrinter({ mode: 'declaration' })
+
+export function McpHandler({ name, node, resolver, baseURL, dataReturnType, paramsCasing }: Props): KubbReactNode {
+  const urlPath = new URLPath(node.path)
+  const contentType = node.requestBody?.content?.[0]?.contentType
+  const isFormData = contentType === 'multipart/form-data'
+
+  const { query: queryParams, header: headerParams } = getOperationParameters(node, { paramsCasing })
+  const { path: originalPathParams, query: originalQueryParams, header: originalHeaderParams } = getOperationParameters(node)
+
+  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : undefined
+  const responseName = resolver.resolveResponseName(node)
+
+  const errorResponses = node.responses.filter((r) => Number(r.statusCode) >= 400).map((r) => resolver.resolveResponseStatusName(node, r.statusCode))
+  const errorType = errorResponses.length > 0 ? errorResponses.join(' | ') : 'Error'
+
+  const TError = `ResponseErrorConfig<${errorType}>`
+  const generics = [responseName, TError, requestName || 'unknown'].filter(Boolean)
+
+  const paramsNode = ast.createOperationParams(node, {
+    paramsType: 'object',
+    pathParamsType: 'inline',
+    resolver,
+    paramsCasing,
+  })
+  const baseParamsSignature = declarationPrinter.print(paramsNode) ?? ''
+  const paramsSignature = baseParamsSignature
+    ? `${baseParamsSignature}, request: RequestHandlerExtra<ServerRequest, ServerNotification>`
+    : 'request: RequestHandlerExtra<ServerRequest, ServerNotification>'
+
+  const pathParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalPathParams, camelCase) : undefined
+  const queryParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalQueryParams, camelCase) : undefined
+  const headerParamsMapping = paramsCasing ? buildTransformedParamsMapping(originalHeaderParams, camelCase) : undefined
+
+  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)
+
+  const fetchConfig: string[] = []
+  fetchConfig.push(`method: ${JSON.stringify(node.method.toUpperCase())}`)
+  fetchConfig.push(`url: ${urlPath.template}`)
+  if (baseURL) fetchConfig.push(`baseURL: \`${baseURL}\``)
+  if (queryParams.length) fetchConfig.push(queryParamsMapping ? 'params: mappedParams' : 'params')
+  if (requestName) fetchConfig.push(`data: ${isFormData ? 'formData as FormData' : 'requestData'}`)
+  if (headers.length) fetchConfig.push(`headers: { ${headers.join(', ')} }`)
+
+  const callToolResult =
+    dataReturnType === 'data'
+      ? `return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(res.data)
+              }
+            ],
+            structuredContent: { data: res.data }
+           }`
+      : `return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(res)
+              }
+            ],
+            structuredContent: { data: res.data }
+           }`
+
+  return (
+    <File.Source name={name} isExportable isIndexable>
+      <Function
+        name={name}
+        async
+        export
+        params={paramsSignature}
+        JSDoc={{
+          comments: buildOperationComments(node),
+        }}
+        returnType={'Promise<CallToolResult>'}
+      >
+        {''}
+        <br />
+        <br />
+        {pathParamsMapping &&
+          Object.entries(pathParamsMapping)
+            .filter(([originalName, camelCaseName]) => originalName !== camelCaseName && isValidVarName(originalName))
+            .map(([originalName, camelCaseName]) => `const ${originalName} = ${camelCaseName}`)
+            .join('\n')}
+        {pathParamsMapping && (
+          <>
+            <br />
+            <br />
+          </>
+        )}
+        {queryParamsMapping && queryParams.length > 0 && (
+          <>
+            {buildRemappingCode(queryParamsMapping, 'mappedParams', 'params')}
+            <br />
+            <br />
+          </>
+        )}
+        {headerParamsMapping && headerParams.length > 0 && (
+          <>
+            {buildRemappingCode(headerParamsMapping, 'mappedHeaders', 'headers')}
+            <br />
+            <br />
+          </>
+        )}
+        {requestName && 'const requestData = data'}
+        <br />
+        {isFormData && requestName && 'const formData = buildFormData(requestData)'}
+        <br />
+        {`const res = await fetch<${generics.join(', ')}>({ ${fetchConfig.join(', ')} }, request)`}
+        <br />
+        {callToolResult}
+      </Function>
+    </File.Source>
+  )
+}

package/src/components/Server.tsx

@@ -1,16 +1,33 @@
-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 type { FabricReactNode } from '@kubb/react-fabric/types'
+import { getOperationParameters } from '@internals/shared'
+import { ast } from '@kubb/core'
+import { functionPrinter } from '@kubb/plugin-ts'
+import { Const, File, Function } from '@kubb/renderer-jsx'
+import type { KubbReactNode } from '@kubb/renderer-jsx/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
@@ -19,99 +36,28 @@ type Props = {
     }
     mcp: {
       name: string
-      file: KubbFile.File
+      file: ast.FileNode
     }
     zod: {
-      name: string
-      file: KubbFile.File
-      schemas: OperationSchemas
-    }
-    type: {
-      schemas: OperationSchemas
+      pathParams: Array<ZodParam>
+      /**
+       * Query params — individual schemas to compose into `z.object({ ... })`.
+       */
+      queryParams?: string | Array<ZodParam>
+      /**
+       * Header params — individual schemas to compose into `z.object({ ... })`.
+       */
+      headerParams?: string | Array<ZodParam>
+      requestName?: string
+      responseName?: string
     }
+    node: ast.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
-}
+const keysPrinter = functionPrinter({ mode: 'keys' })
 
-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,
-      },
-    },
-  })
-}
-
-export function Server({ name, serverName, serverVersion, paramsCasing, operations }: Props): FabricReactNode {
+export function Server({ name, serverName, serverVersion, paramsCasing, operations }: Props): KubbReactNode {
   return (
     <File.Source name={name} isExportable isIndexable>
       <Const name={'server'} export>
@@ -124,9 +70,45 @@ 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 { 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 })),
+                  }),
+                ],
+              })
+            : 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 +118,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}, request) => {
+  return ${mcp.name}(${destructured}, request)
 })
           `
           }
@@ -150,25 +132,23 @@ server.registerTool(${JSON.stringify(tool.name)}, {
           return `
 server.registerTool(${JSON.stringify(tool.name)}, {
   ${config},
-}, async () => {
-  return ${mcp.name}(${paramsClient.toObject()})
+}, async (request) => {
+  return ${mcp.name}(request)
 })
           `
         })
         .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>
   )
 }