@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.
- package/dist/index.cjs +3 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/docs/guides/server.md +103 -12
- package/docs/options.md +23 -43
- package/docs/overview.md +37 -10
- package/kubb-extension.json +1 -1
- package/package.json +6 -6
package/docs/guides/server.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# Run an MCP server
|
|
2
2
|
|
|
3
|
-
Generate
|
|
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
|
|
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
|
-
|
|
30
|
+
The plugin writes one handler per operation, plus `server.ts`, `start.ts`, and `.mcp.json` in `src/gen/mcp/`.
|
|
31
31
|
|
|
32
|
-
##
|
|
32
|
+
## Install the runtime
|
|
33
33
|
|
|
34
|
-
Install the
|
|
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
|
|
51
|
+
## Connect Claude Code
|
|
50
52
|
|
|
51
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
8
|
-
| ------------------------------------------------------------------------- |
|
|
9
|
-
| [`output`](#output)
|
|
10
|
-
| [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group) | Split output by tag or path
|
|
11
|
-
| [`client`](#client) |
|
|
12
|
-
| [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include) | Keep only operations that match.
|
|
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)
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
43
|
+
The handlers call [`@kubb/plugin-client`](https://kubb.dev/extensions/kubb-labs/plugin-client).
|
|
51
44
|
:::
|
|
52
45
|
|
|
53
46
|
::
|
|
54
47
|
|
|
55
|
-
|
|
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
|
-
|
|
51
|
+
See [Tool calls and results](https://kubb.dev/extensions/kubb-labs/plugin-mcp/guides/server#tool-calls-and-results).
|
|
58
52
|
|
|
59
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
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`,
|
|
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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
-
|
|
29
|
+
Operations that stream their response get no tool.
|
|
21
30
|
|
|
22
|
-
See [
|
|
31
|
+
See [Streaming operations](https://kubb.dev/extensions/kubb-labs/plugin-mcp/guides/server#streaming-operations).
|
|
23
32
|
|
|
24
33
|
## Example
|
|
25
34
|
|
|
26
|
-
|
|
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.
|
package/kubb-extension.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kubb/plugin-mcp",
|
|
3
|
-
"version": "5.5.
|
|
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.
|
|
72
|
-
"@kubb/plugin-ts": "^5.5.
|
|
73
|
-
"@kubb/plugin-zod": "^5.9.
|
|
74
|
-
"@kubb/renderer-jsx": "^5.
|
|
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.
|
|
80
|
+
"@kubb/plugin-client": "6.0.4",
|
|
81
81
|
"@modelcontextprotocol/server": "^2.4.0",
|
|
82
82
|
"zod": "^4.6.7"
|
|
83
83
|
},
|