@kubb/plugin-mcp 5.1.0-canary.20261013T083511 → 5.1.1
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/README.md +2 -2
- package/dist/index.cjs +45 -49
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +1 -5
- package/dist/index.js +46 -50
- package/dist/index.js.map +1 -1
- package/docs/guides/server.md +73 -0
- package/docs/options.md +79 -0
- package/docs/overview.md +40 -0
- package/kubb-extension.json +9 -2
- package/package.json +14 -14
- package/OVERVIEW.md +0 -15
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Run an MCP server
|
|
2
|
+
|
|
3
|
+
Generate and start an MCP server with typed tools and an HTTP client.
|
|
4
|
+
|
|
5
|
+
::steps{level="2"}
|
|
6
|
+
|
|
7
|
+
## Generate the server
|
|
8
|
+
|
|
9
|
+
Register TypeScript types, Zod schemas, and an Axios or Fetch client alongside `pluginMcp`. A single registered client is detected automatically.
|
|
10
|
+
|
|
11
|
+
```typescript [kubb.config.ts]
|
|
12
|
+
import { defineConfig } from 'kubb/config'
|
|
13
|
+
import { pluginTs } from '@kubb/plugin-ts'
|
|
14
|
+
import { pluginZod } from '@kubb/plugin-zod'
|
|
15
|
+
import { pluginAxios } from '@kubb/plugin-axios'
|
|
16
|
+
import { pluginMcp } from '@kubb/plugin-mcp'
|
|
17
|
+
|
|
18
|
+
export default defineConfig({
|
|
19
|
+
input: './petStore.yaml',
|
|
20
|
+
output: { path: './src/gen' },
|
|
21
|
+
plugins: [
|
|
22
|
+
pluginTs({ output: { path: 'types', mode: 'directory' } }),
|
|
23
|
+
pluginZod(),
|
|
24
|
+
pluginAxios({ baseURL: 'https://petstore.swagger.io/v2' }),
|
|
25
|
+
pluginMcp({ output: { path: 'mcp', mode: 'directory' } }),
|
|
26
|
+
],
|
|
27
|
+
})
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Run `kubb generate`. The plugin writes tool handlers, `server.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.
|
|
31
|
+
|
|
32
|
+
## Start the server
|
|
33
|
+
|
|
34
|
+
Install the generated server's runtime dependencies and a TypeScript runner:
|
|
35
|
+
|
|
36
|
+
```shell [Terminal]
|
|
37
|
+
npm install @modelcontextprotocol/server@^2 zod@^4.2 axios@^1
|
|
38
|
+
npm install -D tsx
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Import the generated `startServer` function.
|
|
42
|
+
|
|
43
|
+
```typescript [server.ts]
|
|
44
|
+
import { startServer } from './src/gen/mcp/server'
|
|
45
|
+
|
|
46
|
+
await startServer()
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Run the entry point:
|
|
50
|
+
|
|
51
|
+
```shell [Terminal]
|
|
52
|
+
npx tsx server.ts
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
::
|
|
56
|
+
|
|
57
|
+
## Select a client
|
|
58
|
+
|
|
59
|
+
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.
|
|
60
|
+
|
|
61
|
+
```typescript [kubb.config.ts]
|
|
62
|
+
import { pluginAxios } from '@kubb/plugin-axios'
|
|
63
|
+
import { pluginFetch } from '@kubb/plugin-fetch'
|
|
64
|
+
import { pluginMcp } from '@kubb/plugin-mcp'
|
|
65
|
+
|
|
66
|
+
const clients = [
|
|
67
|
+
pluginAxios({ output: { path: 'clients-axios', mode: 'directory' } }),
|
|
68
|
+
pluginFetch({ output: { path: 'clients-fetch', mode: 'directory' } }),
|
|
69
|
+
pluginMcp({ output: { path: 'mcp', mode: 'directory' }, client: 'axios' }),
|
|
70
|
+
]
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Add these entries alongside `pluginTs` and `pluginZod` in `defineConfig.plugins`. The handlers import operations from `clients-axios`.
|
package/docs/options.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Options
|
|
2
|
+
|
|
3
|
+
Pass these options to `pluginMcp()`. Shared options link to [Shared plugin options](https://kubb.dev/docs/5.x/reference/plugin-options).
|
|
4
|
+
|
|
5
|
+
## Options overview
|
|
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. | `[]` |
|
|
17
|
+
|
|
18
|
+
## Option details
|
|
19
|
+
|
|
20
|
+
### output
|
|
21
|
+
|
|
22
|
+
Where the generated MCP handler files are written. The plugin writes `server.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 two files. With `group`, handlers move into subfolders and the two files stay at the root.
|
|
23
|
+
|
|
24
|
+
| | |
|
|
25
|
+
| -------- | -------------------------------------------- |
|
|
26
|
+
| Type | `Output` |
|
|
27
|
+
| Required | `false` |
|
|
28
|
+
| Default | `{ path: 'mcp', barrel: { type: 'named' } }` |
|
|
29
|
+
|
|
30
|
+
### client
|
|
31
|
+
|
|
32
|
+
Selects which registered client plugin the handlers call. A single registered client is auto-detected. Set `client` when several are registered.
|
|
33
|
+
|
|
34
|
+
| | |
|
|
35
|
+
| -------- | -------------------- |
|
|
36
|
+
| Type | `'fetch' \| 'axios'` |
|
|
37
|
+
| Required | `false` |
|
|
38
|
+
|
|
39
|
+
::field-group
|
|
40
|
+
|
|
41
|
+
:::field{name="'fetch'"}
|
|
42
|
+
Calls the operations generated by [`@kubb/plugin-fetch`](https://kubb.dev/extensions/kubb-labs/plugin-fetch).
|
|
43
|
+
:::
|
|
44
|
+
|
|
45
|
+
:::field{name="'axios'"}
|
|
46
|
+
Calls the operations generated by [`@kubb/plugin-axios`](https://kubb.dev/extensions/kubb-labs/plugin-axios).
|
|
47
|
+
:::
|
|
48
|
+
|
|
49
|
+
::
|
|
50
|
+
|
|
51
|
+
Each handler passes grouped `{ path, query, headers, body }` options. Configure transport settings such as `baseURL` on the client plugin.
|
|
52
|
+
|
|
53
|
+
Generated handlers follow the client plugin's `returnType` option. With `'full'` (the client default) handlers read the success body from `res.data`, and with `'data'` they use the resolved call result directly 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`.
|
|
54
|
+
|
|
55
|
+
> [!NOTE]
|
|
56
|
+
> The handlers call a client plugin's functions, so register `@kubb/plugin-fetch` or `@kubb/plugin-axios` alongside this one.
|
|
57
|
+
|
|
58
|
+
### resolver
|
|
59
|
+
|
|
60
|
+
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).
|
|
61
|
+
|
|
62
|
+
| | |
|
|
63
|
+
| -------- | ---------------------------- |
|
|
64
|
+
| Type | `ResolverPatch<ResolverMcp>` |
|
|
65
|
+
| Required | `false` |
|
|
66
|
+
|
|
67
|
+
```typescript [Partial override]
|
|
68
|
+
type ResolverMcpPatch = {
|
|
69
|
+
name?(name: string): string
|
|
70
|
+
file?: {
|
|
71
|
+
baseName?(params: { name: string; extname: string }): string
|
|
72
|
+
path?(params: { baseName: string; output: Output }): string
|
|
73
|
+
}
|
|
74
|
+
imports?(options: ResolveImportsOptions): Array<ImportNode>
|
|
75
|
+
handler?: {
|
|
76
|
+
name?(node: OperationNode): string // → 'showPetByIdHandler'
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
package/docs/overview.md
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# MCP
|
|
2
|
+
|
|
3
|
+
Generates a Model Context Protocol (MCP) server from your OpenAPI spec. Each operation becomes a typed tool that AI assistants can call.
|
|
4
|
+
|
|
5
|
+
The tool handlers call a function generated by a client plugin, and Zod schemas from `@kubb/plugin-zod` validate the tool input. The plugin writes `server.ts` and `.mcp.json` next to the handlers.
|
|
6
|
+
|
|
7
|
+
## Setup
|
|
8
|
+
|
|
9
|
+
- Add `@kubb/plugin-ts`, `@kubb/plugin-zod`, and a client plugin: `@kubb/plugin-fetch` or `@kubb/plugin-axios`.
|
|
10
|
+
- Install `@modelcontextprotocol/server` v2 or higher and `zod` 4.2 or higher in the app that runs the server.
|
|
11
|
+
|
|
12
|
+
## Options worth knowing
|
|
13
|
+
|
|
14
|
+
- `client` picks `fetch` or `axios` when both client plugins are registered. A single client is detected automatically.
|
|
15
|
+
- Keep `output.path` a folder name, such as the default `mcp`. Single-file output has no place for `server.ts` and `.mcp.json`.
|
|
16
|
+
|
|
17
|
+
## Example
|
|
18
|
+
|
|
19
|
+
```typescript [kubb.config.ts]
|
|
20
|
+
import { defineConfig } from 'kubb/config'
|
|
21
|
+
import { pluginTs } from '@kubb/plugin-ts'
|
|
22
|
+
import { pluginZod } from '@kubb/plugin-zod'
|
|
23
|
+
import { pluginFetch } from '@kubb/plugin-fetch'
|
|
24
|
+
import { pluginMcp } from '@kubb/plugin-mcp'
|
|
25
|
+
|
|
26
|
+
export default defineConfig({
|
|
27
|
+
input: './petStore.yaml',
|
|
28
|
+
output: { path: './src/gen' },
|
|
29
|
+
plugins: [
|
|
30
|
+
pluginTs(),
|
|
31
|
+
pluginZod(),
|
|
32
|
+
pluginFetch({ baseURL: 'https://petstore.swagger.io/v2' }),
|
|
33
|
+
pluginMcp({ output: { path: 'mcp', mode: 'directory' } }),
|
|
34
|
+
],
|
|
35
|
+
})
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## See also
|
|
39
|
+
|
|
40
|
+
- [Connect Claude to a remote MCP server](https://modelcontextprotocol.io/docs/tools/claude-desktop)
|
package/kubb-extension.json
CHANGED
|
@@ -11,9 +11,16 @@
|
|
|
11
11
|
"dark": "https://kubb.dev/feature/mcp-dark.svg"
|
|
12
12
|
},
|
|
13
13
|
"tags": ["mcp", "model-context-protocol", "ai", "claude", "llm", "codegen", "openapi"],
|
|
14
|
-
"docs": "https://kubb.dev/
|
|
14
|
+
"docs": "https://kubb.dev/extensions/kubb-labs/plugin-mcp",
|
|
15
|
+
"maintainers": [
|
|
16
|
+
{
|
|
17
|
+
"name": "Stijn Van Hulle",
|
|
18
|
+
"github": "stijnvanhulle"
|
|
19
|
+
}
|
|
20
|
+
],
|
|
21
|
+
"dependencies": ["plugin-ts", "plugin-zod"],
|
|
15
22
|
"compatibility": {
|
|
16
|
-
"kubb": ">=5.8.
|
|
23
|
+
"kubb": ">=5.8.3",
|
|
17
24
|
"node": ">=22"
|
|
18
25
|
},
|
|
19
26
|
"role": "consumer",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kubb/plugin-mcp",
|
|
3
|
-
"version": "5.1.
|
|
3
|
+
"version": "5.1.1",
|
|
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",
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"model-context-protocol",
|
|
15
15
|
"typescript"
|
|
16
16
|
],
|
|
17
|
-
"homepage": "https://kubb.dev/
|
|
17
|
+
"homepage": "https://kubb.dev/extensions/kubb-labs/plugin-mcp",
|
|
18
18
|
"license": "MIT",
|
|
19
19
|
"author": "stijnvanhulle",
|
|
20
20
|
"repository": {
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
"files": [
|
|
40
40
|
"dist",
|
|
41
41
|
"kubb-extension.json",
|
|
42
|
-
"
|
|
42
|
+
"docs",
|
|
43
43
|
"!/**/**.test.**",
|
|
44
44
|
"!/**/__tests__/**",
|
|
45
45
|
"!/**/__snapshots__/**"
|
|
@@ -63,24 +63,24 @@
|
|
|
63
63
|
"registry": "https://registry.npmjs.org/"
|
|
64
64
|
},
|
|
65
65
|
"dependencies": {
|
|
66
|
-
"@kubb/plugin-ts": "^5.
|
|
67
|
-
"@kubb/plugin-zod": "^5.
|
|
66
|
+
"@kubb/plugin-ts": "^5.0.9",
|
|
67
|
+
"@kubb/plugin-zod": "^5.4.7"
|
|
68
68
|
},
|
|
69
69
|
"devDependencies": {
|
|
70
|
-
"@internals/client": "0.
|
|
71
|
-
"@internals/shared": "0.
|
|
72
|
-
"@internals/utils": "0.
|
|
73
|
-
"@modelcontextprotocol/
|
|
74
|
-
"kubb": "^5.8.
|
|
70
|
+
"@internals/client": "0.0.0",
|
|
71
|
+
"@internals/shared": "0.0.0",
|
|
72
|
+
"@internals/utils": "0.0.0",
|
|
73
|
+
"@modelcontextprotocol/server": "^2.3.1",
|
|
74
|
+
"kubb": "^5.8.3",
|
|
75
75
|
"zod": "^4.6.5"
|
|
76
76
|
},
|
|
77
77
|
"peerDependencies": {
|
|
78
|
-
"@modelcontextprotocol/
|
|
79
|
-
"kubb": "^5.8.
|
|
80
|
-
"zod": "^4.
|
|
78
|
+
"@modelcontextprotocol/server": "^2.0.0",
|
|
79
|
+
"kubb": "^5.8.3",
|
|
80
|
+
"zod": "^4.2.0"
|
|
81
81
|
},
|
|
82
82
|
"peerDependenciesMeta": {
|
|
83
|
-
"@modelcontextprotocol/
|
|
83
|
+
"@modelcontextprotocol/server": {
|
|
84
84
|
"optional": true
|
|
85
85
|
},
|
|
86
86
|
"zod": {
|
package/OVERVIEW.md
DELETED
|
@@ -1,15 +0,0 @@
|
|
|
1
|
-
# MCP
|
|
2
|
-
|
|
3
|
-
Generates a Model Context Protocol (MCP) server from your OpenAPI spec. Each operation becomes a typed tool that AI assistants can call.
|
|
4
|
-
|
|
5
|
-
The tool handlers call a function generated by a client plugin, and Zod schemas from `@kubb/plugin-zod` validate the tool input. The plugin writes `server.ts` and `.mcp.json` next to the handlers.
|
|
6
|
-
|
|
7
|
-
## Setup
|
|
8
|
-
|
|
9
|
-
- Add `@kubb/plugin-ts`, `@kubb/plugin-zod`, and a client plugin: `@kubb/plugin-fetch` or `@kubb/plugin-axios`.
|
|
10
|
-
- Install `@modelcontextprotocol/sdk` v1 or higher in the app that runs the server.
|
|
11
|
-
|
|
12
|
-
## Options worth knowing
|
|
13
|
-
|
|
14
|
-
- `client` picks `fetch` or `axios` when both client plugins are registered. A single client is detected automatically.
|
|
15
|
-
- Keep `output.path` a folder name, such as the default `mcp`. Single-file output has no place for `server.ts` and `.mcp.json`.
|