@kubb/plugin-mcp 5.5.2 → 5.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,12 +1,12 @@
1
1
  # Run an MCP server
2
2
 
3
- Generate and start an MCP server with typed tools and an HTTP client.
3
+ Generate an MCP server from your OpenAPI spec, start it, and connect Claude Code or Claude Desktop to its tools.
4
4
 
5
5
  ::steps{level="2"}
6
6
 
7
7
  ## Generate the server
8
8
 
9
- Register TypeScript types, Zod schemas, and an Axios or Fetch client alongside `pluginMcp`. A single registered client is detected automatically.
9
+ Register `pluginTs`, `pluginZod`, and one client plugin next to `pluginMcp`, then run `kubb generate`. When only one client plugin is registered, Kubb detects it.
10
10
 
11
11
  ```typescript [kubb.config.ts]
12
12
  import { defineConfig } from 'kubb/config'
@@ -27,28 +27,30 @@ export default defineConfig({
27
27
  })
28
28
  ```
29
29
 
30
- Run `kubb generate`. The plugin writes tool handlers, `server.ts`, `start.ts`, and `.mcp.json`. Each generated handler calls its HTTP operation, forwards the cancellation signal, and throws for non-2xx responses. Tool results include text content and structured response data. `server.ts` registers tools with Zod input and output schemas, and `start.ts` calls its `startServer()` to serve them over stdio. The tool list shows an `int64` field as an integer and a binary field as a value without a type, because `bigint` and `Blob` have no JSON Schema form. Operations that stream their response, such as `text/event-stream` or JSON Lines, get no tool, because a tool returns one JSON result.
30
+ The plugin writes one handler per operation, plus `server.ts`, `start.ts`, and `.mcp.json` in `src/gen/mcp/`.
31
31
 
32
- ## Start the server
32
+ ## Install the runtime
33
33
 
34
- Install the generated server's runtime dependencies and a TypeScript runner:
34
+ Install the runtime dependencies and a TypeScript runner:
35
35
 
36
36
  ```shell [Terminal]
37
37
  npm install @modelcontextprotocol/server@^2 zod@^4.2 axios@^1.20.0
38
38
  npm install -D tsx
39
39
  ```
40
40
 
41
+ ## Start the server
42
+
41
43
  Run the generated entry from the project root:
42
44
 
43
45
  ```shell [Terminal]
44
46
  npx tsx src/gen/mcp/start.ts
45
47
  ```
46
48
 
47
- The server reads MCP messages from stdin, prints nothing on startup, and logs transport errors to stderr. Press `Ctrl+C` to stop it.
49
+ The server reads MCP messages from stdin, prints nothing on startup, and logs transport errors to stderr. Press `Ctrl+C` to stop it. You do not need to keep it running, because an MCP client starts it.
48
50
 
49
- ## Connect a client
51
+ ## Connect Claude Code
50
52
 
51
- The generated `.mcp.json` runs the same command:
53
+ Claude Code reads `.mcp.json` from the project root. Copy the `mcpServers` entry from the generated file into it.
52
54
 
53
55
  ```json [src/gen/mcp/.mcp.json]
54
56
  {
@@ -62,13 +64,77 @@ The generated `.mcp.json` runs the same command:
62
64
  }
63
65
  ```
64
66
 
65
- The server name comes from `info.title` in your OpenAPI spec. MCP clients start the command from their own working directory, so the `args` path is relative to the Kubb `root`, not to the `.mcp.json` folder. Claude Code reads `.mcp.json` from the project root, so copy the entry under `mcpServers` into that file. For a client that starts in another folder, such as Claude Desktop, use an absolute path to `start.ts`.
67
+ The server name comes from `info.title` in your spec. The `args` path is relative to the Kubb `root`, not to the `.mcp.json` folder, because MCP clients start the command from their own working directory.
68
+
69
+ ::
70
+
71
+ ## What the tools look like
72
+
73
+ `server.ts` registers one tool per operation:
74
+
75
+ | Tool field | Comes from |
76
+ | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
77
+ | Name | The `operationId` |
78
+ | Title | The operation `summary` |
79
+ | Description | The operation `description`, or one built from the method and path: `Make a GET request to /pets/{petId}` |
80
+ | Input | The Zod schemas of the parameters and the request body |
81
+ | Output | The success body, as `{ data: body }` structured content and as the JSON text of `body`. A success with no body gives empty text. |
82
+
83
+ Each handler forwards the MCP cancellation signal to the client and throws for a non-2xx response, which the assistant sees as a tool error. Operations that stream their response get no tool.
84
+
85
+ See [Tool calls and results](#tool-calls-and-results).
86
+
87
+ ## Claude Desktop
88
+
89
+ Claude Desktop does not start servers from your project folder, so its entry needs an absolute path to `start.ts`. First generate the server and install the runtime, as in the steps above.
90
+
91
+ ::steps{level="3"}
92
+
93
+ ### Register the server
94
+
95
+ Open Claude Desktop's `Settings → Developer → Edit Config`. This opens `claude_desktop_config.json`, on macOS under `~/Library/Application Support/Claude/` and on Windows under `%APPDATA%\Claude\`.
96
+
97
+ Copy the entry from `src/gen/mcp/.mcp.json` into its `mcpServers` object, next to any existing servers. Change the `args` path to the absolute path of `start.ts`:
98
+
99
+ :::code-group
100
+
101
+ ```json [macOS]
102
+ {
103
+ "mcpServers": {
104
+ "Swagger Petstore": {
105
+ "type": "stdio",
106
+ "command": "npx",
107
+ "args": ["tsx", "/absolute/path/to/project/src/gen/mcp/start.ts"]
108
+ }
109
+ }
110
+ }
111
+ ```
112
+
113
+ ```json [Windows]
114
+ {
115
+ "mcpServers": {
116
+ "Swagger Petstore": {
117
+ "type": "stdio",
118
+ "command": "npx",
119
+ "args": ["tsx", "C:\\path\\to\\project\\src\\gen\\mcp\\start.ts"]
120
+ }
121
+ }
122
+ }
123
+ ```
124
+
125
+ :::
126
+
127
+ In Windows JSON paths, escape each backslash as `\\`.
128
+
129
+ ### Use the generated tools
130
+
131
+ Quit Claude Desktop completely and reopen it. Open `Manage connectors`, select your server, and check that the tools match your operations. Ask Claude to run one operation, and review its request before you approve the API call.
66
132
 
67
133
  ::
68
134
 
69
135
  ## Use your own entry file
70
136
 
71
- To run setup code first, such as loading environment variables, import `startServer` from the generated `server.ts` in your own entry file and point `args` at that file instead of `start.ts`.
137
+ To run setup code first, such as loading environment variables, import `startServer` from `server.ts` in your own entry file. Point `args` at that file instead of `start.ts`.
72
138
 
73
139
  ```typescript [mcp.ts]
74
140
  import { startServer } from './src/gen/mcp/server'
@@ -78,7 +144,7 @@ startServer()
78
144
 
79
145
  ## Select a client
80
146
 
81
- When both HTTP plugins are registered, set [`client`](https://kubb.dev/extensions/kubb-labs/plugin-mcp/options#client) explicitly. Give each client a different output directory so their generated files do not overwrite each other.
147
+ When several client plugins are registered, set [`client`](https://kubb.dev/extensions/kubb-labs/plugin-mcp/options#client). Give each client plugin its own output folder, so their files do not overwrite each other.
82
148
 
83
149
  ```typescript [kubb.config.ts]
84
150
  import { pluginAxios } from '@kubb/plugin-axios'
@@ -92,4 +158,29 @@ const clients = [
92
158
  ]
93
159
  ```
94
160
 
95
- Add these entries alongside `pluginTs` and `pluginZod` in `defineConfig.plugins`. The handlers import operations from `clients-axios`.
161
+ Add these entries next to `pluginTs` and `pluginZod` in `plugins`. The handlers then import from `clients-axios`.
162
+
163
+ ## Less common cases
164
+
165
+ ### Tool calls and results
166
+
167
+ Configure transport settings such as `baseURL` on the client plugin. With `client: 'client'`, set them in your own client module, because `pluginClient` takes no `baseURL`.
168
+
169
+ Each handler calls the client function with:
170
+
171
+ - The grouped `path`, `query`, `headers`, `body`, and `cookies` options that the operation has.
172
+ - The MCP cancellation signal.
173
+ - `throwOnError: true`, so a non-2xx response throws and surfaces as a tool error, whatever the client's `throwOnErrorDefault`.
174
+
175
+ The tool response body depends on the client's `returnType`:
176
+
177
+ | Client `returnType` | Tool response body |
178
+ | --------------------------------------------------------------------------- | ------------------------ |
179
+ | `'full'` (the client default), or the plain result of `@kubb/plugin-client` | `res.data` |
180
+ | `'data'` | The resolved call result |
181
+
182
+ In the tool list, an `int64` field shows as an integer and a binary field as a value without a type, because `bigint` and `Blob` have no JSON Schema form.
183
+
184
+ ### Streaming operations
185
+
186
+ Operations that stream their response, such as `text/event-stream` or JSON Lines, get no tool, because a tool returns one JSON result.
package/docs/options.md CHANGED
@@ -1,35 +1,28 @@
1
1
  # Options
2
2
 
3
- Pass these options to `pluginMcp()`. Shared options link to [Shared plugin options](https://kubb.dev/docs/5.x/reference/plugin-options).
3
+ Pass these options to `pluginMcp()`. Shared options link to [Shared plugin options](https://kubb.dev/docs/5.x/reference/plugin-options), and this page gives only their default here.
4
4
 
5
5
  ## Options overview
6
6
 
7
- | Option | Purpose | Default |
8
- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------- |
9
- | [`output`](#output) | Where handlers are written: `path`, `mode`, `barrel`, `banner`, `footer`. | `{ path: 'mcp', barrel: { type: 'named' } }` |
10
- | [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group) | Split output by tag or path: `type`, `name`. | None |
11
- | [`client`](#client) | Which registered client plugin the handlers call. | Auto-detected |
12
- | [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include) | Keep only operations that match. | None |
13
- | [`exclude`](https://kubb.dev/docs/5.x/reference/plugin-options#exclude) | Skip operations that match. | `[]` |
14
- | [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override) | Apply different options per pattern. | `[]` |
15
- | [`resolver`](#resolver) | Customize generated names and file paths. | `resolverMcp` |
16
- | [`macros`](https://kubb.dev/docs/5.x/reference/plugin-options#macros) | Rewrite AST nodes before printing. | `[]` |
7
+ | Option | Purpose | Default |
8
+ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------- |
9
+ | [`output`](https://kubb.dev/docs/5.x/reference/plugin-options#output) | Where handlers are written. | `{ path: 'mcp', barrel: { type: 'named' } }` |
10
+ | [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group) | Split output by tag or path. | None |
11
+ | [`client`](#client) | Registered client plugin the handlers call. | Detected |
12
+ | [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include) | Keep only operations that match. | None |
13
+ | [`exclude`](https://kubb.dev/docs/5.x/reference/plugin-options#exclude) | Skip operations that match. | `[]` |
14
+ | [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override) | Apply different options per pattern. | `[]` |
15
+ | [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver) | Customize generated names and file paths. See [resolver members](#resolver-members). | `resolverMcp` |
16
+ | [`macros`](https://kubb.dev/docs/5.x/reference/plugin-options#macros) | Rewrite AST nodes before printing. | `[]` |
17
17
 
18
- ## Option details
19
-
20
- ### output
18
+ > [!IMPORTANT]
19
+ > Keep `output.path` a folder name, such as the default `'mcp'`. The plugin writes `server.ts`, `start.ts`, and `.mcp.json` at its root, and single-file output (`output.mode: 'file'`, or a `path` with an extension) has no room for them. With `group`, only the handlers move into subfolders.
21
20
 
22
- Where the generated MCP handler files are written. The plugin writes `server.ts`, `start.ts`, and `.mcp.json` at the root of `output.path`, next to the handlers. Keep `output.path` a folder name such as the default `'mcp'`. Single-file output (`output.mode: 'file'`, or a `path` with an extension) has no room for those files. With `group`, handlers move into subfolders and those files stay at the root.
23
-
24
- | | |
25
- | -------- | -------------------------------------------- |
26
- | Type | `Output` |
27
- | Required | `false` |
28
- | Default | `{ path: 'mcp', barrel: { type: 'named' } }` |
21
+ ## Option details
29
22
 
30
23
  ### client
31
24
 
32
- Selects which registered client plugin the handlers call. A single registered client is auto-detected. Set `client` when several are registered.
25
+ Selects the registered client plugin that the handlers call. When `client` is unset, the handlers call the only registered client plugin. Set transport options such as `baseURL` on that plugin, or in your own client module with `'client'`.
33
26
 
34
27
  | | |
35
28
  | -------- | -------------------------------- |
@@ -39,43 +32,30 @@ Selects which registered client plugin the handlers call. A single registered cl
39
32
  ::field-group
40
33
 
41
34
  :::field{name="'fetch'"}
42
- Calls the operations generated by [`@kubb/plugin-fetch`](https://kubb.dev/extensions/kubb-labs/plugin-fetch).
35
+ The handlers call [`@kubb/plugin-fetch`](https://kubb.dev/extensions/kubb-labs/plugin-fetch).
43
36
  :::
44
37
 
45
38
  :::field{name="'axios'"}
46
- Calls the operations generated by [`@kubb/plugin-axios`](https://kubb.dev/extensions/kubb-labs/plugin-axios).
39
+ The handlers call [`@kubb/plugin-axios`](https://kubb.dev/extensions/kubb-labs/plugin-axios).
47
40
  :::
48
41
 
49
42
  :::field{name="'client'"}
50
- Calls the operations generated by [`@kubb/plugin-client`](https://kubb.dev/extensions/kubb-labs/plugin-client).
43
+ The handlers call [`@kubb/plugin-client`](https://kubb.dev/extensions/kubb-labs/plugin-client).
51
44
  :::
52
45
 
53
46
  ::
54
47
 
55
- Each handler passes grouped `{ path, query, headers, body }` options. Configure transport settings such as `baseURL` on the client plugin.
48
+ > [!WARNING]
49
+ > The build fails when no client plugin is registered, when several are registered and `client` is unset, or when `client` names a plugin that is not registered.
56
50
 
57
- Generated handlers follow the client plugin's `returnType` option. With `'full'` (the client default) or `@kubb/plugin-client`'s plain result, handlers read the success body from `res.data`. With `'data'`, they use the resolved call result as the tool response body. Handlers always pass `throwOnError: true` so non-2xx responses throw and surface as tool errors, regardless of the client's `throwOnErrorDefault`.
51
+ See [Tool calls and results](https://kubb.dev/extensions/kubb-labs/plugin-mcp/guides/server#tool-calls-and-results).
58
52
 
59
- > [!NOTE]
60
- > The handlers call a client plugin's functions, so register `@kubb/plugin-fetch`, `@kubb/plugin-axios`, or `@kubb/plugin-client` alongside this one.
53
+ ## Resolver members
61
54
 
62
- ### resolver
63
-
64
- Overrides generated file and symbol names. Omitted members keep `resolverMcp`. The shared members (`name`, `file`, `imports`) and the `this` context are described under [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver).
65
-
66
- | | |
67
- | -------- | ---------------------------- |
68
- | Type | `ResolverPatch<ResolverMcp>` |
69
- | Required | `false` |
55
+ Members you leave out of a `resolver` patch keep `resolverMcp`. Besides the shared `name`, `file`, and `imports` members of [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver), `resolverMcp` has these:
70
56
 
71
57
  ```typescript [Partial override]
72
58
  type ResolverMcpPatch = {
73
- name?(name: string): string
74
- file?: {
75
- baseName?(params: { name: string; extname: string }): string
76
- path?(params: { baseName: string; output: Output }): string
77
- }
78
- imports?(options: ResolveImportsOptions): Array<ImportNode>
79
59
  handler?: {
80
60
  name?(node: OperationNode): string // → 'showPetByIdHandler'
81
61
  }
package/docs/overview.md CHANGED
@@ -1,29 +1,40 @@
1
1
  # MCP
2
2
 
3
- The MCP plugin turns each operation into a typed MCP tool that AI assistants can call. Each tool uses Zod schemas from `@kubb/plugin-zod` for its input and output.
3
+ The MCP plugin turns each operation in your OpenAPI spec into a typed MCP tool that AI assistants can call, validated with `@kubb/plugin-zod` schemas.
4
4
 
5
- Each tool handler calls the function a client plugin generates for that operation. The plugin writes `server.ts`, `start.ts`, and `.mcp.json` at the root of its `output.path`. `start.ts` calls the `startServer()` that `server.ts` exports, and `.mcp.json` runs `start.ts` to start a stdio server.
5
+ Each tool handler calls the function a client plugin generates for that operation.
6
+
7
+ Next to the handlers, the plugin writes three files at the root of its `output.path`:
8
+
9
+ | File | Role |
10
+ | ----------- | ------------------------------------------------------------------------------- |
11
+ | `server.ts` | Registers one tool per operation and exports `startServer()`. |
12
+ | `start.ts` | Calls `startServer()` to serve the tools over stdio. |
13
+ | `.mcp.json` | A server entry that runs `start.ts`, ready to copy into your MCP client config. |
6
14
 
7
15
  ## Setup
8
16
 
9
- - Add `@kubb/plugin-zod`, `@kubb/plugin-ts` (optional with `pluginZod({ inferred: 'codec' })`), and a client plugin: `@kubb/plugin-fetch`, `@kubb/plugin-axios`, or `@kubb/plugin-client`. Leave `sdk` unset on the client plugin.
17
+ - Add `@kubb/plugin-zod`, one client plugin (`@kubb/plugin-fetch`, `@kubb/plugin-axios`, or `@kubb/plugin-client`), and `@kubb/plugin-ts`. `@kubb/plugin-ts` is optional with `pluginZod({ inferred: 'codec' })`. Leave `sdk` unset on the client plugin.
10
18
  - Install `@modelcontextprotocol/server` v2 and `zod` 4.2 or a later v4 release in the app that runs the server. Add `axios` too when you use `@kubb/plugin-axios`.
11
19
  - Install a TypeScript runner such as `tsx`. The generated `.mcp.json` runs `npx tsx`, which downloads `tsx` from npm when it is missing.
12
- - Copy the server entry from the generated `.mcp.json` into the `.mcp.json` your MCP client reads, such as the one at the project root for Claude Code.
13
20
 
14
21
  ## Options worth knowing
15
22
 
16
- - `client` picks `fetch`, `axios`, or `client` when several client plugins are registered. A single client is detected automatically.
17
- - `exclude` skips operations. Use it for operations with a binary request body, because an MCP client sends JSON and cannot send a file.
18
- - `output.path` must be a folder name, such as the default `mcp`, because single-file output has no place for `server.ts`, `start.ts`, and `.mcp.json`.
23
+ | Option | Default | What it does |
24
+ | --------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
25
+ | [`client`](https://kubb.dev/extensions/kubb-labs/plugin-mcp/options#client) | Detected | Picks `'fetch'`, `'axios'`, or `'client'` when several client plugins are registered. |
26
+ | [`exclude`](https://kubb.dev/docs/5.x/reference/plugin-options#exclude) | `[]` | Skips operations, such as one with a binary request body. An MCP client sends JSON and cannot send a file. |
27
+ | [`output.path`](https://kubb.dev/docs/5.x/reference/plugin-options#output) | `'mcp'` | Must name a folder for `server.ts`, `start.ts`, and `.mcp.json`. |
19
28
 
20
- The `args` path in `.mcp.json` points at `start.ts` relative to the Kubb `root`, because MCP clients start the command from their own working directory. Use an absolute path for a client that starts in another folder, or point it at your own entry file to run setup code before `startServer()`.
29
+ Operations that stream their response get no tool.
21
30
 
22
- See [Options](https://kubb.dev/extensions/kubb-labs/plugin-mcp/options) for every option and its default.
31
+ See [Streaming operations](https://kubb.dev/extensions/kubb-labs/plugin-mcp/guides/server#streaming-operations).
23
32
 
24
33
  ## Example
25
34
 
26
- The config below generates an MCP server whose tools call the Petstore API through `@kubb/plugin-fetch`.
35
+ This config generates an MCP server whose tools call the Petstore API through `@kubb/plugin-fetch`. The `.mcp.json` names the server after the spec's `info.title`:
36
+
37
+ ::code-group
27
38
 
28
39
  ```typescript [kubb.config.ts]
29
40
  import { defineConfig } from 'kubb/config'
@@ -43,3 +54,19 @@ export default defineConfig({
43
54
  ],
44
55
  })
45
56
  ```
57
+
58
+ ```json [src/gen/mcp/.mcp.json]
59
+ {
60
+ "mcpServers": {
61
+ "Swagger Petstore": {
62
+ "type": "stdio",
63
+ "command": "npx",
64
+ "args": ["tsx", "./src/gen/mcp/start.ts"]
65
+ }
66
+ }
67
+ }
68
+ ```
69
+
70
+ ::
71
+
72
+ Next, [run the server](https://kubb.dev/extensions/kubb-labs/plugin-mcp/guides/server) and connect Claude Code or Claude Desktop.
@@ -21,7 +21,7 @@
21
21
  "dependencies": ["plugin-zod"],
22
22
  "optionalDependencies": ["plugin-ts"],
23
23
  "compatibility": {
24
- "kubb": ">=5.18.4",
24
+ "kubb": ">=5.19.0",
25
25
  "node": ">=22.22"
26
26
  },
27
27
  "role": "consumer",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubb/plugin-mcp",
3
- "version": "5.5.2",
3
+ "version": "5.5.4",
4
4
  "description": "Generate Model Context Protocol (MCP) tool definitions with Kubb. Expose your REST APIs as AI-callable tools for LLMs, Claude, ChatGPT, and other AI assistants.",
5
5
  "keywords": [
6
6
  "ai",
@@ -68,16 +68,16 @@
68
68
  "registry": "https://registry.npmjs.org/"
69
69
  },
70
70
  "dependencies": {
71
- "@kubb/kit": "^5.19.0",
72
- "@kubb/plugin-ts": "^5.5.2",
73
- "@kubb/plugin-zod": "^5.9.2",
74
- "@kubb/renderer-jsx": "^5.19.0"
71
+ "@kubb/kit": "^5.20.1",
72
+ "@kubb/plugin-ts": "^5.5.4",
73
+ "@kubb/plugin-zod": "^5.9.4",
74
+ "@kubb/renderer-jsx": "^5.20.1"
75
75
  },
76
76
  "devDependencies": {
77
77
  "@internals/client": "0.0.0",
78
78
  "@internals/shared": "0.0.0",
79
79
  "@internals/utils": "0.0.0",
80
- "@kubb/plugin-client": "6.0.2",
80
+ "@kubb/plugin-client": "6.0.4",
81
81
  "@modelcontextprotocol/server": "^2.4.0",
82
82
  "zod": "^4.6.7"
83
83
  },