@ttoss/http-server-mcp-openapi 0.2.13 → 0.2.14

package/README.md

@@ -69,6 +69,11 @@ path-item one with the same `name`+`in`.
 Tool arguments are **camelCase** (`agentId`, `projectId`); the generated
 request path, query string, and body use the original **snake_case** names.
 
+Query params honour their declared `style` and `explode`. `form` (the default)
+repeats array values, `spaceDelimited`/`pipeDelimited` join them, and
+`deepObject` emits bracketed keys — including nested objects and arrays, so
+`{ documentId: { $eq: 'doc_1' } }` becomes `filters[documentId][$eq]=doc_1`.
+
 ## `registerOpenApiTools`
 
 | Field      | Description                                                                                                   |

package/dist/index.cjs

@@ -117,22 +117,108 @@ var buildPathFn = (pathTemplate, pathParams) => {
     return result;
   };
 };
+var NON_EXPLODED_DELIMITERS = {
+  form: ",",
+  spaceDelimited: " ",
+  pipeDelimited: "|"
+};
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+/**
+* Appends a `deepObject` value as bracketed keys — `filters[documentId][$eq]`.
+* OpenAPI only defines one level, but the APIs that ask for `deepObject`
+* (Strapi, Directus) nest, so nested objects and arrays recurse instead of
+* being stringified into `[object Object]`.
+*/
+var appendDeepObject = args => {
+  if (args.value === void 0 || args.value === null) return;
+  if (Array.isArray(args.value)) {
+    for (const [index, item] of args.value.entries()) appendDeepObject({
+      search: args.search,
+      key: `${args.key}[${index}]`,
+      value: item
+    });
+    return;
+  }
+  if (isRecord(args.value)) {
+    for (const [property, propertyValue] of Object.entries(args.value)) appendDeepObject({
+      search: args.search,
+      key: `${args.key}[${property}]`,
+      value: propertyValue
+    });
+    return;
+  }
+  args.search.append(args.key, String(args.value));
+};
+var appendArrayValue = args => {
+  if (args.explode) {
+    for (const item of args.value) args.search.append(args.name, String(item));
+    return;
+  }
+  args.search.append(args.name, args.value.map(String).join(args.delimiter));
+};
+var appendObjectValue = args => {
+  const entries = Object.entries(args.value).filter(([, entryValue]) => {
+    return entryValue !== void 0 && entryValue !== null;
+  });
+  if (args.explode) {
+    for (const [property, entryValue] of entries) args.search.append(property, String(entryValue));
+    return;
+  }
+  args.search.append(args.name, entries.flatMap(([property, entryValue]) => {
+    return [property, String(entryValue)];
+  }).join(args.delimiter));
+};
+var appendQueryValue = args => {
+  const style = args.param.style ?? "form";
+  if (style === "deepObject") {
+    appendDeepObject({
+      search: args.search,
+      key: args.param.name,
+      value: args.value
+    });
+    return;
+  }
+  const serialization = {
+    search: args.search,
+    name: args.param.name,
+    explode: args.param.explode ?? style === "form",
+    delimiter: NON_EXPLODED_DELIMITERS[style] ?? ","
+  };
+  if (Array.isArray(args.value)) {
+    appendArrayValue({
+      ...serialization,
+      value: args.value
+    });
+    return;
+  }
+  if (isRecord(args.value)) {
+    appendObjectValue({
+      ...serialization,
+      value: args.value
+    });
+    return;
+  }
+  args.search.append(args.param.name, String(args.value));
+};
 /**
 * Builds a function that serialises query params into a query string
-* (including the leading `?`). Returns `undefined` when the op has no query
-* params. Array values are appended once per element.
+* (including the leading `?`), honouring each param's OpenAPI `style` and
+* `explode`. Returns `undefined` when the op has no query params.
 */
 var buildQueryFn = queryParams => {
   if (queryParams.length === 0) return void 0;
   return args => {
     const search = new URLSearchParams();
-    for (const {
-      name,
-      camelName
-    } of queryParams) {
-      const value = args[camelName];
+    for (const param of queryParams) {
+      const value = args[param.camelName];
       if (value === void 0 || value === null) continue;
-      if (Array.isArray(value)) for (const item of value) search.append(name, String(item));else search.append(name, String(value));
+      appendQueryValue({
+        search,
+        param,
+        value
+      });
     }
     const qs = search.toString();
     return qs ? `?${qs}` : "";
@@ -275,7 +361,9 @@ var extractQueryParams = args => {
       camelName: snakeToCamel(p.name || ""),
       description: p.description || "",
       required: p.required || false,
-      type: p.schema?.type || "string"
+      type: p.schema?.type || "string",
+      style: p.style,
+      explode: p.explode
     };
   }));
 };

package/dist/index.d.cts

@@ -93,7 +93,9 @@ interface OperationSpec {
     name?: string;
     in?: string;
     required?: boolean;
-    description?: string;
+    description?: string; /** Query serialisation style, e.g. `form` (default) or `deepObject`. */
+    style?: string; /** Whether each value gets its own key. Defaults to `true` for `form`. */
+    explode?: boolean;
     schema?: {
       type?: string;
       items?: {
@@ -212,6 +214,8 @@ declare const resolveParameter: (param: Record<string, unknown> | undefined, spe
   in?: string;
   required?: boolean;
   description?: string;
+  style?: string;
+  explode?: boolean;
   schema?: {
     type?: string;
     items?: {
@@ -224,15 +228,19 @@ declare const buildPathFn: (pathTemplate: string, pathParams: Array<{
   name: string;
   camelName: string;
 }>) => ((args: Record<string, unknown>) => string);
+/** Query parameter with the OpenAPI serialisation rules declared for it. */
+type QueryParamSerialization = {
+  name: string;
+  camelName: string; /** OpenAPI `style` (`form`, `deepObject`, `spaceDelimited`, `pipeDelimited`). */
+  style?: string; /** OpenAPI `explode`. Defaults to `true` for `form`, `false` otherwise. */
+  explode?: boolean;
+};
 /**
  * Builds a function that serialises query params into a query string
- * (including the leading `?`). Returns `undefined` when the op has no query
- * params. Array values are appended once per element.
+ * (including the leading `?`), honouring each param's OpenAPI `style` and
+ * `explode`. Returns `undefined` when the op has no query params.
  */
-declare const buildQueryFn: (queryParams: Array<{
-  name: string;
-  camelName: string;
-}>) => ((args: Record<string, unknown>) => string) | undefined;
+declare const buildQueryFn: (queryParams: QueryParamSerialization[]) => ((args: Record<string, unknown>) => string) | undefined;
 /**
  * Builds a function that maps camelCase args back to a snake_case request
  * body, skipping `undefined` args. Returns `undefined` when the op has no body.
@@ -296,6 +304,8 @@ declare const extractQueryParams: (args: {
   description: string;
   required: boolean;
   type: string;
+  style?: string;
+  explode?: boolean;
 }>;
 /**
  * snake_case names of every top-level property an operation's request schema
@@ -360,4 +370,4 @@ declare const openApiToToolDefinitions: (args: {
   options?: OpenApiToToolsOptions;
 }) => ToolDefinition[];
 //#endregion
-export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedRequest, type ToolDefinition, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };
+export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type QueryParamSerialization, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedRequest, type ToolDefinition, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };

package/dist/index.d.mts

@@ -93,7 +93,9 @@ interface OperationSpec {
     name?: string;
     in?: string;
     required?: boolean;
-    description?: string;
+    description?: string; /** Query serialisation style, e.g. `form` (default) or `deepObject`. */
+    style?: string; /** Whether each value gets its own key. Defaults to `true` for `form`. */
+    explode?: boolean;
     schema?: {
       type?: string;
       items?: {
@@ -212,6 +214,8 @@ declare const resolveParameter: (param: Record<string, unknown> | undefined, spe
   in?: string;
   required?: boolean;
   description?: string;
+  style?: string;
+  explode?: boolean;
   schema?: {
     type?: string;
     items?: {
@@ -224,15 +228,19 @@ declare const buildPathFn: (pathTemplate: string, pathParams: Array<{
   name: string;
   camelName: string;
 }>) => ((args: Record<string, unknown>) => string);
+/** Query parameter with the OpenAPI serialisation rules declared for it. */
+type QueryParamSerialization = {
+  name: string;
+  camelName: string; /** OpenAPI `style` (`form`, `deepObject`, `spaceDelimited`, `pipeDelimited`). */
+  style?: string; /** OpenAPI `explode`. Defaults to `true` for `form`, `false` otherwise. */
+  explode?: boolean;
+};
 /**
  * Builds a function that serialises query params into a query string
- * (including the leading `?`). Returns `undefined` when the op has no query
- * params. Array values are appended once per element.
+ * (including the leading `?`), honouring each param's OpenAPI `style` and
+ * `explode`. Returns `undefined` when the op has no query params.
  */
-declare const buildQueryFn: (queryParams: Array<{
-  name: string;
-  camelName: string;
-}>) => ((args: Record<string, unknown>) => string) | undefined;
+declare const buildQueryFn: (queryParams: QueryParamSerialization[]) => ((args: Record<string, unknown>) => string) | undefined;
 /**
  * Builds a function that maps camelCase args back to a snake_case request
  * body, skipping `undefined` args. Returns `undefined` when the op has no body.
@@ -296,6 +304,8 @@ declare const extractQueryParams: (args: {
   description: string;
   required: boolean;
   type: string;
+  style?: string;
+  explode?: boolean;
 }>;
 /**
  * snake_case names of every top-level property an operation's request schema
@@ -360,4 +370,4 @@ declare const openApiToToolDefinitions: (args: {
   options?: OpenApiToToolsOptions;
 }) => ToolDefinition[];
 //#endregion
-export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedRequest, type ToolDefinition, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };
+export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type QueryParamSerialization, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedRequest, type ToolDefinition, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };

package/dist/index.mjs

@@ -114,22 +114,108 @@ var buildPathFn = (pathTemplate, pathParams) => {
     return result;
   };
 };
+var NON_EXPLODED_DELIMITERS = {
+  form: ",",
+  spaceDelimited: " ",
+  pipeDelimited: "|"
+};
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+/**
+* Appends a `deepObject` value as bracketed keys — `filters[documentId][$eq]`.
+* OpenAPI only defines one level, but the APIs that ask for `deepObject`
+* (Strapi, Directus) nest, so nested objects and arrays recurse instead of
+* being stringified into `[object Object]`.
+*/
+var appendDeepObject = args => {
+  if (args.value === void 0 || args.value === null) return;
+  if (Array.isArray(args.value)) {
+    for (const [index, item] of args.value.entries()) appendDeepObject({
+      search: args.search,
+      key: `${args.key}[${index}]`,
+      value: item
+    });
+    return;
+  }
+  if (isRecord(args.value)) {
+    for (const [property, propertyValue] of Object.entries(args.value)) appendDeepObject({
+      search: args.search,
+      key: `${args.key}[${property}]`,
+      value: propertyValue
+    });
+    return;
+  }
+  args.search.append(args.key, String(args.value));
+};
+var appendArrayValue = args => {
+  if (args.explode) {
+    for (const item of args.value) args.search.append(args.name, String(item));
+    return;
+  }
+  args.search.append(args.name, args.value.map(String).join(args.delimiter));
+};
+var appendObjectValue = args => {
+  const entries = Object.entries(args.value).filter(([, entryValue]) => {
+    return entryValue !== void 0 && entryValue !== null;
+  });
+  if (args.explode) {
+    for (const [property, entryValue] of entries) args.search.append(property, String(entryValue));
+    return;
+  }
+  args.search.append(args.name, entries.flatMap(([property, entryValue]) => {
+    return [property, String(entryValue)];
+  }).join(args.delimiter));
+};
+var appendQueryValue = args => {
+  const style = args.param.style ?? "form";
+  if (style === "deepObject") {
+    appendDeepObject({
+      search: args.search,
+      key: args.param.name,
+      value: args.value
+    });
+    return;
+  }
+  const serialization = {
+    search: args.search,
+    name: args.param.name,
+    explode: args.param.explode ?? style === "form",
+    delimiter: NON_EXPLODED_DELIMITERS[style] ?? ","
+  };
+  if (Array.isArray(args.value)) {
+    appendArrayValue({
+      ...serialization,
+      value: args.value
+    });
+    return;
+  }
+  if (isRecord(args.value)) {
+    appendObjectValue({
+      ...serialization,
+      value: args.value
+    });
+    return;
+  }
+  args.search.append(args.param.name, String(args.value));
+};
 /**
 * Builds a function that serialises query params into a query string
-* (including the leading `?`). Returns `undefined` when the op has no query
-* params. Array values are appended once per element.
+* (including the leading `?`), honouring each param's OpenAPI `style` and
+* `explode`. Returns `undefined` when the op has no query params.
 */
 var buildQueryFn = queryParams => {
   if (queryParams.length === 0) return void 0;
   return args => {
     const search = new URLSearchParams();
-    for (const {
-      name,
-      camelName
-    } of queryParams) {
-      const value = args[camelName];
+    for (const param of queryParams) {
+      const value = args[param.camelName];
       if (value === void 0 || value === null) continue;
-      if (Array.isArray(value)) for (const item of value) search.append(name, String(item));else search.append(name, String(value));
+      appendQueryValue({
+        search,
+        param,
+        value
+      });
     }
     const qs = search.toString();
     return qs ? `?${qs}` : "";
@@ -272,7 +358,9 @@ var extractQueryParams = args => {
       camelName: snakeToCamel(p.name || ""),
       description: p.description || "",
       required: p.required || false,
-      type: p.schema?.type || "string"
+      type: p.schema?.type || "string",
+      style: p.style,
+      explode: p.explode
     };
   }));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp-openapi",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "description": "Generate Model Context Protocol (MCP) tools from an OpenAPI specification for @ttoss/http-server-mcp",
   "keywords": [
     "ai",
@@ -42,8 +42,8 @@
     "jest": "^30.4.2",
     "supertest": "^7.2.2",
     "tsdown": "^0.22.2",
-    "@ttoss/http-server": "^0.8.1",
-    "@ttoss/config": "^1.38.0"
+    "@ttoss/config": "^1.38.0",
+    "@ttoss/http-server": "^0.8.1"
   },
   "publishConfig": {
     "access": "public",