@kubb/plugin-mcp 5.5.0-canary.20261111T122007 → 5.5.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/dist/index.cjs CHANGED
@@ -30,6 +30,38 @@ let _kubb_renderer_jsx = require("@kubb/renderer-jsx");
30
30
  let _kubb_renderer_jsx_jsx_runtime = require("@kubb/renderer-jsx/jsx-runtime");
31
31
  let _kubb_plugin_ts = require("@kubb/plugin-ts");
32
32
  let _kubb_plugin_zod = require("@kubb/plugin-zod");
33
+ // ../../internals/utils/src/fs.ts
34
+ function toSlash(p) {
35
+ if (p.startsWith("\\\\?\\")) return p;
36
+ return p.replaceAll("\\", "/");
37
+ }
38
+ /**
39
+ * Returns the relative path from `rootDir` to `filePath`, always using forward slashes
40
+ * and prefixed with `./` when not already traversing upward.
41
+ *
42
+ * @example
43
+ * ```ts
44
+ * getRelativePath('/src/components', '/src/components/Button.tsx') // './Button.tsx'
45
+ * getRelativePath('/src/components', '/src/utils/helpers.ts') // '../utils/helpers.ts'
46
+ * ```
47
+ */
48
+ function getRelativePath(rootDir, filePath) {
49
+ const relativePath = node_path.posix.relative(toSlash(rootDir), toSlash(filePath));
50
+ return relativePath.startsWith("../") ? relativePath : `./${relativePath}`;
51
+ }
52
+ // ../../internals/utils/src/strings.ts
53
+ /**
54
+ * Escapes an `@` at the start of a line, so a multi-line description can't start a new JSDoc tag.
55
+ * Editors render `\@` as `@` in hovers.
56
+ *
57
+ * @example
58
+ * ```ts
59
+ * jsDocEscape('intro\n@example value') // 'intro\n\\@example value'
60
+ * ```
61
+ */
62
+ function jsDocEscape(input) {
63
+ return `${input}`.replace(/^(\s*)@/gm, "$1\\@");
64
+ }
33
65
  // ../../internals/shared/src/operation.ts
34
66
  /**
35
67
  * Builds the `ResolverFileParams` every operation generator passes to
@@ -99,7 +131,7 @@ function resolveOperationFile(options) {
99
131
  * The operation's method and path as plain text, such as `` `GET /pet/{petId}` ``. A path is not a valid `{@link}` target.
100
132
  */
101
133
  function getOperationRequestLine(node) {
102
- return _kubb_kit.ast.isHttpOperationNode(node) && node.path ? `\`${node.method.toUpperCase()} ${node.path}\`` : null;
134
+ return _kubb_kit.ast.http.isOperation(node) && node.path ? `\`${node.method.toUpperCase()} ${node.path}\`` : null;
103
135
  }
104
136
  /**
105
137
  * Derives the shared `ContentTypeInfo` shape from a list of content types, tracking whether several
@@ -123,7 +155,48 @@ function getContentTypeInfo(node) {
123
155
  * whether several are present, so the client can let a caller pick which one to accept.
124
156
  */
125
157
  function getResponseContentTypeInfo(node) {
126
- return buildContentTypeInfo(getPrimarySuccessResponse(node)?.content?.map((e) => e.contentType) ?? []);
158
+ return buildContentTypeInfo(_kubb_kit.ast.http.responses.findPrimary(node)?.content?.map((e) => e.contentType) ?? []);
159
+ }
160
+ /**
161
+ * How an operation streams its primary success response item by item, when that response declares one content type:
162
+ * - `'event'` for `text/event-stream` whose `itemSchema` types the whole event with its own `event` and `data`
163
+ * - `'data'` for `text/event-stream` typed by its payload only
164
+ * - `'line'` for JSON Lines, one parsed JSON value per line
165
+ *
166
+ * Returns `null` for any other response, and for a response that also declares another content type, which stays a normal
167
+ * call with its query hooks.
168
+ */
169
+ function getEventStream(node) {
170
+ const content = _kubb_kit.ast.http.responses.findPrimary(node)?.content ?? [];
171
+ if (content.length !== 1) return null;
172
+ const entry = content[0];
173
+ const framing = getStreamFraming(entry);
174
+ if (framing === "events") return entry.stream?.shape ?? "data";
175
+ return framing === "lines" ? "line" : null;
176
+ }
177
+ /**
178
+ * How a content entry is framed as a stream: `'events'` for Server-Sent Events, `'lines'` for JSON Lines.
179
+ */
180
+ function getStreamFraming(entry) {
181
+ if (_kubb_kit.ast.mediaType.getBase(entry) === "text/event-stream") return "events";
182
+ return entry.stream && _kubb_kit.ast.mediaType.isStream(entry) ? "lines" : void 0;
183
+ }
184
+ /**
185
+ * Whether an operation streams its primary success response, as Server-Sent Events or JSON Lines. The client generator uses
186
+ * this to return a typed stream of items instead of a one-shot `RequestResult`.
187
+ */
188
+ function isEventStream(node) {
189
+ return getEventStream(node) !== null;
190
+ }
191
+ /**
192
+ * Whether a success response offers a stream media type next to other content types. The client returns that variant's
193
+ * body as a `ReadableStream`, so the stream runtime is registered and a hook's data type includes the stream.
194
+ */
195
+ function hasStreamVariant(node) {
196
+ return _kubb_kit.ast.http.responses.filterSuccess(node).some((response) => {
197
+ const variants = (response.content ?? []).filter((entry) => entry.schema);
198
+ return variants.length > 1 && variants.some((entry) => _kubb_kit.ast.mediaType.isStream(entry));
199
+ });
127
200
  }
128
201
  /**
129
202
  * Builds the `client?:` option type shared by the generated query hooks (`useQuery`,
@@ -166,11 +239,11 @@ const requestGroupOrder = [
166
239
  * Which of the grouped request options an operation carries.
167
240
  */
168
241
  function getRequestGroups(node) {
169
- const { path, query, header, cookie } = getOperationParameters(node);
242
+ const { path, query, header, cookie } = _kubb_kit.ast.http.groupParameters(node);
170
243
  return {
171
244
  path: path.length > 0,
172
245
  query: query.length > 0,
173
- body: Boolean(node.requestBody?.content?.[0]?.schema),
246
+ body: Boolean(_kubb_kit.ast.http.requestBody.getSchema(node)),
174
247
  headers: header.length > 0,
175
248
  cookies: cookie.length > 0
176
249
  };
@@ -182,7 +255,7 @@ function getRequestGroups(node) {
182
255
  */
183
256
  function getRequestGroupOptionality(node) {
184
257
  const groups = getRequestGroups(node);
185
- const { path, query, header } = getOperationParameters(node);
258
+ const { path, query, header } = _kubb_kit.ast.http.groupParameters(node);
186
259
  const hasRequiredPath = path.some((param) => param.required);
187
260
  const hasRequiredQuery = query.some((param) => param.required);
188
261
  const hasRequiredHeader = header.some((param) => param.required);
@@ -217,55 +290,12 @@ function buildOperationComments(node, options = {}) {
217
290
  getOperationRequestLine(node),
218
291
  node.description && `@description ${node.description}`,
219
292
  node.summary && `@summary ${node.summary}`,
220
- node.deprecated && "@deprecated"
293
+ node.deprecated && "@deprecated",
294
+ node.externalDocs && `@see ${jsDocEscape([node.externalDocs.url, node.externalDocs.description].filter(Boolean).join(" "))}`
221
295
  ].filter((comment) => Boolean(comment));
222
296
  if (!splitLines) return filteredComments;
223
297
  return filteredComments.flatMap((text) => text.split(/\r?\n/).map((line) => line.trim())).filter((comment) => Boolean(comment));
224
298
  }
225
- const operationParameterGroupsByNode = /* @__PURE__ */ new WeakMap();
226
- /**
227
- * An OpenAPI 3.2 `querystring` parameter is the whole query string, so a form-encoded object becomes one query parameter
228
- * per property, typed and serialized like any other.
229
- * Another content type, such as JSON, stays one parameter named after it, and the runtime sends its value as the whole query string.
230
- */
231
- function spreadQuerystring(param) {
232
- const schema = param.schema.type === "ref" ? param.schema.schema : param.schema;
233
- const formEncoded = !param.contentType || param.contentType.split(";")[0].trim().toLowerCase() === "application/x-www-form-urlencoded";
234
- if (schema?.type !== "object" || !formEncoded) return [param];
235
- return schema.properties.map((property) => _kubb_kit.ast.factory.createParameter({
236
- name: property.name,
237
- in: "query",
238
- schema: property.schema,
239
- required: param.required && property.required
240
- }));
241
- }
242
- /**
243
- * Groups an operation's parameters by location (`path`/`query`/`header`/`cookie`), deduping each
244
- * group by name. Every plugin generator visiting the same `OperationNode` shares one AST instance
245
- * (see `KubbDriver`), so the result is cached per node to avoid re-filtering and re-deduping the
246
- * same parameters once per plugin.
247
- */
248
- function getOperationParameters(node) {
249
- const cached = operationParameterGroupsByNode.get(node);
250
- if (cached) return cached;
251
- const dedupe = (params) => {
252
- const seen = /* @__PURE__ */ new Set();
253
- return params.filter((param) => {
254
- if (seen.has(param.name)) return false;
255
- seen.add(param.name);
256
- return true;
257
- });
258
- };
259
- const group = (location) => dedupe(node.parameters.filter((param) => param.in === location));
260
- const groups = {
261
- path: group("path"),
262
- query: dedupe([...group("query"), ...group("querystring").flatMap(spreadQuerystring)]),
263
- header: group("header"),
264
- cookie: group("cookie")
265
- };
266
- operationParameterGroupsByNode.set(node, groups);
267
- return groups;
268
- }
269
299
  /**
270
300
  * Whether the operation declares more than one request media type with a schema, so a caller must pick one on `contentType`.
271
301
  */
@@ -278,42 +308,6 @@ function hasRequestContentTypeChoice(node) {
278
308
  function castToClientOptions(callArg, clientName, returnType = "full") {
279
309
  return `${callArg} as Parameters<typeof ${clientName}${returnType === "plain" ? "" : "<true>"}>[0]`;
280
310
  }
281
- function getStatusCodeNumber(statusCode) {
282
- const code = Number(statusCode);
283
- return Number.isNaN(code) ? null : code;
284
- }
285
- function isSuccessStatusCode(statusCode) {
286
- const code = getStatusCodeNumber(statusCode);
287
- return code !== null && code >= 200 && code < 300;
288
- }
289
- function getSuccessResponses(responses) {
290
- return responses.filter((response) => isSuccessStatusCode(response.statusCode));
291
- }
292
- function getOperationSuccessResponses(node) {
293
- return getSuccessResponses(node.responses);
294
- }
295
- function getPrimarySuccessResponse(node) {
296
- return getOperationSuccessResponses(node)[0] ?? null;
297
- }
298
- // ../../internals/utils/src/fs.ts
299
- function toSlash(p) {
300
- if (p.startsWith("\\\\?\\")) return p;
301
- return p.replaceAll("\\", "/");
302
- }
303
- /**
304
- * Returns the relative path from `rootDir` to `filePath`, always using forward slashes
305
- * and prefixed with `./` when not already traversing upward.
306
- *
307
- * @example
308
- * ```ts
309
- * getRelativePath('/src/components', '/src/components/Button.tsx') // './Button.tsx'
310
- * getRelativePath('/src/components', '/src/utils/helpers.ts') // '../utils/helpers.ts'
311
- * ```
312
- */
313
- function getRelativePath(rootDir, filePath) {
314
- const relativePath = node_path.posix.relative(toSlash(rootDir), toSlash(filePath));
315
- return relativePath.startsWith("../") ? relativePath : `./${relativePath}`;
316
- }
317
311
  // ../../internals/shared/src/resolver.ts
318
312
  /**
319
313
  * Builds the allocation key for a declaration an operation owns. `scope` names which declaration
@@ -335,36 +329,6 @@ function operationKey(node, ...scope) {
335
329
  ...scope.map(String)
336
330
  ];
337
331
  }
338
- // ../../internals/shared/src/group.ts
339
- /**
340
- * Builds the `group` config a Kubb plugin passes to `ctx.setOptions`, applying the
341
- * shared default naming so every plugin groups output consistently:
342
- *
343
- * - `path` groups use the second path segment (`/pet/findByStatus` → `pet`).
344
- * - other groups use the camelCased group (`pet store` → `petStore`).
345
- *
346
- * A user-provided `group.name` always wins over the default namer, so callers stay in
347
- * control of their output folders. Returns `null` when grouping is disabled, matching the
348
- * per-plugin convention.
349
- *
350
- * @param group - The user-supplied group option, or `undefined` to disable grouping.
351
- *
352
- * @example
353
- * ```ts
354
- * createGroupConfig(group) // shared across every plugin
355
- * ```
356
- */
357
- function createGroupConfig(group) {
358
- if (!group) return null;
359
- const defaultName = (ctx) => {
360
- if (group.type === "path") return `${ctx.group.split("/")[1]}`;
361
- return (0, _kubb_kit.camelCase)(ctx.group);
362
- };
363
- return {
364
- ...group,
365
- name: group.name ? group.name : defaultName
366
- };
367
- }
368
332
  // src/components/McpHandler.tsx
369
333
  function McpHandler({ name, clientName, node, resolver, returnType = "full" }) {
370
334
  const { signature, names: callArgs } = buildRequestParamsSignature(node, resolver, { isConfigurable: false });
@@ -418,7 +382,7 @@ function Server({ serverName, serverVersion, operations }) {
418
382
  });
419
383
  if (zod.queryParams) entries.push({
420
384
  key: "query",
421
- value: zodObject(zod.queryParams)
385
+ value: typeof zod.queryParams === "string" ? zod.queryParams : zodObject(zod.queryParams)
422
386
  });
423
387
  if (zod.headerParams) entries.push({
424
388
  key: "headers",
@@ -433,12 +397,12 @@ function Server({ serverName, serverVersion, operations }) {
433
397
  value: zod.requestName
434
398
  });
435
399
  const destructured = `{ ${entries.map((e) => e.key).join(", ")} }`;
436
- const inputSchema = entries.length ? `z.object({ ${entries.map((e) => `${e.key}: ${e.value}`).join(", ")} })` : null;
400
+ const inputSchema = entries.length ? `toolSchema(z.object({ ${entries.map((e) => `${e.key}: ${e.value}`).join(", ")} }))` : null;
437
401
  const outputSchema = zod.responseName;
438
402
  const config = [
439
403
  tool.title ? `title: ${JSON.stringify(tool.title)}` : null,
440
404
  `description: ${JSON.stringify(tool.description)}`,
441
- outputSchema ? `outputSchema: z.object({ data: ${outputSchema} })` : null
405
+ outputSchema ? `outputSchema: toolSchema(z.object({ data: ${outputSchema} }))` : null
442
406
  ].filter(Boolean).join(",\n ");
443
407
  if (inputSchema) return `
444
408
  server.registerTool(${JSON.stringify(tool.name)}, {
@@ -457,6 +421,31 @@ server.registerTool(${JSON.stringify(tool.name)}, {
457
421
  `;
458
422
  }).filter(Boolean).join("");
459
423
  return /* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsxs)(_kubb_renderer_jsx_jsx_runtime.Fragment, { children: [
424
+ /* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsx)(_kubb_renderer_jsx.File.Source, {
425
+ name: "toolSchema",
426
+ children: /* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsx)(_kubb_renderer_jsx.Function, {
427
+ name: "toolSchema",
428
+ generics: "T extends z.ZodType",
429
+ params: "schema: T",
430
+ JSDoc: { comments: ["Converts with `unrepresentable: \"any\"`, because a `bigint` or `Blob` in one tool schema fails every `tools/list` request.", "A `bigint` is listed as an `int64` integer and a `Blob` as an unconstrained value."] },
431
+ children: `const standard = schema['~standard']
432
+ const convert = (io: 'input' | 'output') => (options: Parameters<typeof standard.jsonSchema.input>[0]) =>
433
+ standard.jsonSchema[io]({
434
+ ...options,
435
+ libraryOptions: {
436
+ unrepresentable: 'any',
437
+ override: ({ zodSchema, jsonSchema }: { zodSchema: z.core.$ZodType; jsonSchema: Record<string, unknown> }) => {
438
+ if (zodSchema._zod.def.type === 'bigint') {
439
+ jsonSchema.type = 'integer'
440
+ jsonSchema.format = 'int64'
441
+ }
442
+ },
443
+ },
444
+ })
445
+
446
+ return { '~standard': { ...standard, jsonSchema: { input: convert('input'), output: convert('output') } } }`
447
+ })
448
+ }),
460
449
  /* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsx)(_kubb_renderer_jsx.File.Source, {
461
450
  name: "getServer",
462
451
  isExportable: true,
@@ -465,8 +454,8 @@ server.registerTool(${JSON.stringify(tool.name)}, {
465
454
  name: "getServer",
466
455
  export: true,
467
456
  children: `const server = new McpServer({
468
- name: '${serverName}',
469
- version: '${serverVersion}',
457
+ name: ${_kubb_kit.text.quote(serverName)},
458
+ version: ${_kubb_kit.text.quote(serverVersion)},
470
459
  })
471
460
  ${registrations}
472
461
  return server`
@@ -666,7 +655,8 @@ function resolveClientOperation(options) {
666
655
  operationFile: file.path
667
656
  }),
668
657
  clientPathIsFile: importPath === void 0 || isRelativeImport(importPath),
669
- returnType: operationOptions.returnType ?? "full"
658
+ returnType: operationOptions.returnType ?? "full",
659
+ typedHeaders: importPath === void 0
670
660
  };
671
661
  });
672
662
  }
@@ -694,6 +684,7 @@ function toZodTypeResolver(resolver) {
694
684
  status: (node, statusCode) => type(resolver.response.status(node, statusCode)),
695
685
  response: (node) => type(resolver.response.response(node)),
696
686
  responses: (node) => type(resolver.response.responses(node)),
687
+ headers: (node, statusCode) => type(resolver.response.headers(node, statusCode)),
697
688
  options: (node) => resolver.response.options(node)
698
689
  }
699
690
  };
@@ -752,7 +743,8 @@ const mcpGenerator = (0, _kubb_kit.defineGenerator)({
752
743
  name: "mcp",
753
744
  renderer: _kubb_renderer_jsx.jsxRenderer,
754
745
  operation(node, ctx) {
755
- if (!_kubb_kit.ast.isHttpOperationNode(node)) return null;
746
+ if (!_kubb_kit.ast.http.isOperation(node)) return null;
747
+ if (isEventStream(node) || hasStreamVariant(node)) return null;
756
748
  const { resolver, driver, root, config } = ctx;
757
749
  const { output, client, group } = ctx.options;
758
750
  const types = resolveOperationTypes(driver, resolver.pluginName);
@@ -861,8 +853,8 @@ const serverGenerator = (0, _kubb_kit.defineGenerator)({
861
853
  command: "npx",
862
854
  args: ["tsx", getRelativePath(node_path.default.resolve(config.root), startFile.path)]
863
855
  } } };
864
- const operationsMapped = nodes.filter(_kubb_kit.ast.isHttpOperationNode).map((node) => {
865
- const { path: pathParams, query: queryParams, header: headerParams, cookie: cookieParams } = getOperationParameters(node);
856
+ const operationsMapped = nodes.filter(_kubb_kit.ast.http.isOperation).filter((node) => !isEventStream(node) && !hasStreamVariant(node)).map((node) => {
857
+ const { path: pathParams, query: queryParams, header: headerParams, cookie: cookieParams } = _kubb_kit.ast.http.groupParameters(node);
866
858
  const mcpFile = resolver.file({
867
859
  ...operationFileEntry(node, node.operationId),
868
860
  root,
@@ -877,13 +869,14 @@ const serverGenerator = (0, _kubb_kit.defineGenerator)({
877
869
  output: pluginZod.options?.output ?? output,
878
870
  group: pluginZod.options?.group ?? void 0
879
871
  });
880
- const requestName = node.requestBody?.content?.[0]?.schema ? zodResolver.response.body(node) : null;
881
- const successStatus = getPrimarySuccessResponse(node)?.statusCode;
872
+ const requestName = _kubb_kit.ast.http.requestBody.getSchema(node) ? zodResolver.response.body(node) : null;
873
+ const successStatus = _kubb_kit.ast.http.responses.findPrimary(node)?.statusCode;
882
874
  const responseName = successStatus ? zodResolver.response.status(node, successStatus) : null;
883
875
  const resolveParams = (params) => params.map((p) => ({
884
876
  name: p.name,
885
877
  schemaName: zodResolver.param.name(node, p)
886
878
  }));
879
+ const resolveOptional = (params) => params.length ? resolveParams(params) : null;
887
880
  return {
888
881
  tool: {
889
882
  name: node.operationId,
@@ -896,9 +889,9 @@ const serverGenerator = (0, _kubb_kit.defineGenerator)({
896
889
  },
897
890
  zod: {
898
891
  pathParams: resolveParams(pathParams),
899
- queryParams: queryParams.length ? resolveParams(queryParams) : null,
900
- headerParams: headerParams.length ? resolveParams(headerParams) : null,
901
- cookieParams: cookieParams.length ? resolveParams(cookieParams) : null,
892
+ queryParams: resolveOptional(queryParams),
893
+ headerParams: resolveOptional(headerParams),
894
+ cookieParams: resolveOptional(cookieParams),
902
895
  requestName,
903
896
  responseName,
904
897
  file: zodFile
@@ -908,7 +901,7 @@ const serverGenerator = (0, _kubb_kit.defineGenerator)({
908
901
  const imports = operationsMapped.flatMap(({ mcp, zod }) => {
909
902
  const zodNames = [
910
903
  ...zod.pathParams.map((p) => p.schemaName),
911
- ...(zod.queryParams ?? []).map((p) => p.schemaName),
904
+ ...typeof zod.queryParams === "string" ? [zod.queryParams] : (zod.queryParams ?? []).map((p) => p.schemaName),
912
905
  ...(zod.headerParams ?? []).map((p) => p.schemaName),
913
906
  ...(zod.cookieParams ?? []).map((p) => p.schemaName),
914
907
  zod.requestName,
@@ -1010,11 +1003,11 @@ const serverGenerator = (0, _kubb_kit.defineGenerator)({
1010
1003
  });
1011
1004
  // kubb-extension.json
1012
1005
  var compatibility = {
1013
- "kubb": ">=5.16.0",
1006
+ "kubb": ">=5.18.4",
1014
1007
  "node": ">=22.22"
1015
1008
  };
1016
1009
  // package.json
1017
- var version = "5.5.0-canary.20261111T122007";
1010
+ var version = "5.5.1";
1018
1011
  // src/resolvers/resolverMcp.ts
1019
1012
  /**
1020
1013
  * Default resolver used by `@kubb/plugin-mcp`. Decides the names and file
@@ -1031,7 +1024,7 @@ var version = "5.5.0-canary.20261111T122007";
1031
1024
  const resolverMcp = (0, _kubb_kit.createResolver)({
1032
1025
  pluginName: "plugin-mcp",
1033
1026
  name(name) {
1034
- return this.memo(`name:${name}`, () => (0, _kubb_kit.camelCase)(name, { suffix: "handler" }));
1027
+ return this.memo(`name:${name}`, () => _kubb_kit.casing.camel(name, { suffix: "handler" }));
1035
1028
  },
1036
1029
  handler: { name(node) {
1037
1030
  const name = this.name(node.operationId);
@@ -1100,7 +1093,7 @@ const pluginMcp = (0, _kubb_kit.defineExtension)({
1100
1093
  exclude,
1101
1094
  include,
1102
1095
  override,
1103
- group: createGroupConfig(group),
1096
+ group: group ?? null,
1104
1097
  client: resolveContractClient({
1105
1098
  plugin: pluginMcpName,
1106
1099
  client,