@ttoss/http-server-mcp-openapi 0.5.7 → 0.7.0

package/dist/index.mjs

@@ -1,8 +1,9 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { dispatchInProcess } from "@ttoss/http-server";
 import { getApiHeaders, registerToolFromSchema } from "@ttoss/http-server-mcp";
 
 //#region src/schema.ts
-var isRecord = value => {
+var isRecord$1 = value => {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 };
 var getAlternativeSchemas = schema => {
@@ -39,7 +40,7 @@ var followPointer = args => {
   const tokens = args.pointer.split("/").slice(1);
   let current = args.root;
   for (const rawToken of tokens) {
-    if (!isRecord(current) && !Array.isArray(current)) return void 0;
+    if (!isRecord$1(current) && !Array.isArray(current)) return void 0;
     const token = decodeURIComponent(rawToken).replace(/~1/g, "/").replace(/~0/g, "~");
     current = current[token];
   }
@@ -98,7 +99,7 @@ var dereferenceValue = args => {
       seenRefs
     });
   });
-  if (isRecord(value)) {
+  if (isRecord$1(value)) {
     if (typeof value.$ref === "string") {
       const target = resolveRef({
         ref: value.$ref,
@@ -178,7 +179,7 @@ var resolveParameter = (param, spec, documents) => {
         documents
       }
     });
-    return isRecord(target?.value) ? target.value : {};
+    return isRecord$1(target?.value) ? target.value : {};
   }
   return param;
 };
@@ -217,7 +218,7 @@ var appendDeepObject = args => {
     });
     return;
   }
-  if (isRecord(args.value)) {
+  if (isRecord$1(args.value)) {
     for (const [property, propertyValue] of Object.entries(args.value)) appendDeepObject({
       search: args.search,
       key: `${args.key}[${property}]`,
@@ -269,7 +270,7 @@ var appendQueryValue = args => {
     });
     return;
   }
-  if (isRecord(args.value)) {
+  if (isRecord$1(args.value)) {
     appendObjectValue({
       ...serialization,
       value: args.value
@@ -498,6 +499,8 @@ var extractPathParams = args => {
     return {
       name: p.name || "",
       argName: toArgName(p.name || ""),
+      description: p.description,
+      schema: dereferenceSchema(p.schema, args.spec, args.documents),
       ...managedFields(readServerManaged({
         node: p,
         extension: flag
@@ -519,6 +522,7 @@ var extractQueryParams = args => {
       description: p.description || "",
       required: p.required || false,
       type: p.schema?.type || "string",
+      schema: dereferenceSchema(p.schema, args.spec, args.documents),
       style: p.style,
       explode: p.explode,
       ...managedFields(readServerManaged({
@@ -611,7 +615,8 @@ var extractBodyProps = args => {
       nullable: val.nullable === true,
       oneOf: Array.isArray(val.oneOf) ? val.oneOf : void 0,
       anyOf: Array.isArray(val.anyOf) ? val.anyOf : void 0,
-      allOf: Array.isArray(val.allOf) ? val.allOf : void 0
+      allOf: Array.isArray(val.allOf) ? val.allOf : void 0,
+      schema: value
     };
   });
 };
@@ -641,6 +646,209 @@ var extractPinnedBody = args => {
   return pinned;
 };
 
+//#endregion
+//#region src/fullSchema.ts
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var OPENAPI_ONLY_KEYWORDS = new Set(["discriminator", "example", "externalDocs", "xml"]);
+var SCHEMA_MAPS = new Set(["$defs", "definitions", "dependentSchemas", "patternProperties", "properties"]);
+var SCHEMA_VALUES = new Set(["additionalProperties", "contains", "else", "if", "items", "not", "propertyNames", "then", "unevaluatedItems", "unevaluatedProperties"]);
+var SCHEMA_LISTS = new Set(["anyOf", "oneOf", "prefixItems"]);
+/**
+* OpenAPI 3.0's `nullable: true` in JSON Schema: `'null'` joins the `type`,
+* and `null` joins an `enum`, which would otherwise still refuse it.
+*/
+var withNull = schema => {
+  const result = {
+    ...schema
+  };
+  if (typeof result.type === "string") result.type = [result.type, "null"];else if (Array.isArray(result.type) && !result.type.includes("null")) result.type = [...result.type, "null"];
+  if (Array.isArray(result.enum) && !result.enum.includes(null)) result.enum = [...result.enum, null];
+  return result;
+};
+/**
+* Merges an `allOf` into one schema, the shape a tool argument needs.
+*
+* Members that declare `properties` are an object composition — a write body
+* that is a patch plus two fields — and merge their properties and `required`.
+* Otherwise the `allOf` only wraps a referenced scalar so it can carry its own
+* `description` (the one way OpenAPI 3.0 allows beside a `$ref`), and the
+* members are merged as they are. Sibling keys win in both, because the
+* wrapper exists to say something the referenced schema does not.
+*/
+var mergeAllOf = args => {
+  const {
+    members,
+    siblings
+  } = args;
+  if (!members.some(member => {
+    return member.properties !== void 0;
+  })) return Object.assign({}, ...members, siblings);
+  const properties = {};
+  const required = [];
+  for (const member of members) {
+    Object.assign(properties, member.properties);
+    if (Array.isArray(member.required)) required.push(...member.required);
+  }
+  return {
+    ...siblings,
+    type: "object",
+    properties,
+    ...(required.length > 0 ? {
+      required: [...new Set(required)]
+    } : {})
+  };
+};
+var normalizeChildren = args => {
+  const {
+    schema,
+    next
+  } = args;
+  const result = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (OPENAPI_ONLY_KEYWORDS.has(key) || key.startsWith("x-")) continue;
+    if (SCHEMA_MAPS.has(key) && isRecord(value)) result[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => {
+      return [name, next(child)];
+    }));else if (SCHEMA_VALUES.has(key) && isRecord(value)) result[key] = next(value);else if (SCHEMA_LISTS.has(key) && Array.isArray(value)) result[key] = value.map(next);else result[key] = value;
+  }
+  return result;
+};
+/**
+* Turns an already-dereferenced OpenAPI schema into the JSON Schema a tool
+* argument carries, keeping every constraint it declares — `enum`, `format`,
+* `pattern`, `minimum`, `default`, nested `properties` and `required`,
+* `oneOf` — and changing only what JSON Schema cannot express: `allOf` is
+* merged, `nullable` becomes a `'null'` type, and OpenAPI-only keywords and
+* `x-` extensions are dropped. Descriptions are kept verbatim.
+*/
+var toToolSchema = value => {
+  if (!isRecord(value)) return value;
+  const {
+    allOf,
+    nullable,
+    ...rest
+  } = value;
+  const own = normalizeChildren({
+    schema: rest,
+    next: toToolSchema
+  });
+  const merged = Array.isArray(allOf) ? mergeAllOf({
+    members: allOf.filter(isRecord).map(member => {
+      return toToolSchema(member);
+    }),
+    siblings: own
+  }) : own;
+  return nullable === true ? withNull(merged) : merged;
+};
+/** A path or query parameter's schema, with the parameter's own description. */
+var paramProperty = param => {
+  return {
+    ...(toToolSchema(param.schema) ?? {}),
+    ...(param.description ? {
+      description: param.description
+    } : {})
+  };
+};
+/**
+* The `inputSchema` of a tool under `schemaDetail: 'full'`: every parameter
+* and body property with its whole schema. `properties` is always present,
+* even when empty, because some clients refuse an object schema without it.
+*/
+var buildFullInputSchema = args => {
+  const params = [...args.pathParams, ...args.queryParams].filter(param => {
+    return !param.serverManaged;
+  });
+  const properties = {};
+  const required = [];
+  for (const param of params) {
+    properties[param.argName] = paramProperty(param);
+    if (param.required) required.push(param.argName);
+  }
+  for (const prop of args.bodyProps) {
+    properties[prop.argName] = toToolSchema(prop.schema);
+    if (prop.required) required.push(prop.argName);
+  }
+  return {
+    type: "object",
+    properties,
+    ...(required.length > 0 ? {
+      required: [...new Set(required)]
+    } : {})
+  };
+};
+
+//#endregion
+//#region src/inProcessCallApi.ts
+var nestedMessageOf = error => {
+  if (!error || typeof error !== "object") return null;
+  const {
+    code,
+    message
+  } = error;
+  if (typeof message !== "string") return null;
+  return typeof code === "string" ? `${code}: ${message}` : message;
+};
+/**
+* The message an error response carries, read from the envelopes REST APIs
+* commonly answer with: a plain string, `{ error: '…' }`,
+* `{ error: { code, message } }` (as `code: message`) or `{ message: '…' }`.
+* `null` when the body is none of them.
+*/
+var errorMessageOf = body => {
+  if (typeof body === "string") return body || null;
+  if (!body || typeof body !== "object") return null;
+  const {
+    error,
+    message
+  } = body;
+  if (typeof error === "string") return error;
+  return nestedMessageOf(error) ?? (typeof message === "string" ? message : null);
+};
+var defaultToError = response => {
+  return new Error(errorMessageOf(response.body) ?? `HTTP ${response.status}`);
+};
+/**
+* A `callApi` for {@link registerOpenApiTools} that serves each tool call
+* against the REST app in this same process, with no socket: validation,
+* authorization and error handling run once, in the routes, for both
+* surfaces.
+*
+* The MCP request's headers (what `createMcpRouter`'s `getApiHeaders`
+* produced — typically the caller's `Authorization`) are forwarded onto the
+* dispatched request. A 2xx answers its body; anything else throws, so the
+* client sees a tool error rather than an error body rendered as a result.
+*
+* @example
+* ```typescript
+* registerOpenApiTools({
+*   server,
+*   spec,
+*   callApi: createInProcessCallApi({ app }),
+* });
+* ```
+*/
+var createInProcessCallApi = ({
+  app,
+  headers,
+  toError = defaultToError
+}) => {
+  return async request => {
+    const response = await dispatchInProcess({
+      app: typeof app === "function" ? await app() : app,
+      method: request.method,
+      path: request.url,
+      headers: {
+        ...request.headers,
+        ...headers?.(request)
+      },
+      body: request.body
+    });
+    if (response.status < 200 || response.status >= 300) throw toError(response, request);
+    return response.body;
+  };
+};
+
 //#endregion
 //#region src/toolDefinitions.ts
 /** Converts a camelCase `operationId` to a kebab-case tool name. */
@@ -657,6 +865,11 @@ var getJsonSchemaType = schemaType => {
 var sanitizeDescription = description => {
   return (description || "").replace(/'/g, "\\'").replace(/\n/g, " ").trim();
 };
+var defaultDescribe = ({
+  operation
+}) => {
+  return sanitizeDescription(operation.description);
+};
 /**
 * Forwards a property's `oneOf` / `anyOf` / multi-entry `allOf` verbatim, or
 * returns `undefined` when it declares none.
@@ -713,8 +926,7 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
   const modelQueryParams = queryParams.filter(p => {
     return !p.serverManaged;
   });
-  const allParams = [...modelPathParams, ...modelQueryParams, ...bodyProps];
-  if (allParams.length === 0) return {
+  if ([...modelPathParams, ...modelQueryParams, ...bodyProps].length === 0) return {
     type: "object"
   };
   const requiredFields = [...modelPathParams.map(p => {
@@ -729,10 +941,11 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     return p.argName;
   })];
   const properties = {};
-  for (const param of allParams) properties[param.argName] = "description" in param ? normalizeNullable(buildTypedProperty(param)) : {
+  for (const param of modelPathParams) properties[param.argName] = {
     type: "string",
     description: ""
   };
+  for (const param of [...modelQueryParams, ...bodyProps]) properties[param.argName] = normalizeNullable(buildTypedProperty(param));
   return {
     type: "object",
     properties,
@@ -741,6 +954,35 @@ var buildInputSchema = (pathParams, queryParams, bodyProps) => {
     } : {})
   };
 };
+var SUPPORTED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+/** The tool description, from `options.describe` or the default. */
+var describeOperation = args => {
+  const {
+    options,
+    operation,
+    method,
+    pathTemplate
+  } = args;
+  return (options.describe ?? defaultDescribe)({
+    operation,
+    method,
+    pathTemplate
+  });
+};
+/** The `inputSchema` at the detail {@link OpenApiToToolsOptions.schemaDetail} asks for. */
+var selectInputSchema = args => {
+  if (args.schemaDetail !== "full") return buildInputSchema(args.pathParams, args.queryParams, args.bodyProps);
+  return buildFullInputSchema({
+    pathParams: args.pathParams.map(param => {
+      return {
+        ...param,
+        required: true
+      };
+    }),
+    queryParams: args.queryParams,
+    bodyProps: args.bodyProps
+  });
+};
 /** Collects every `x-` prefixed extension declared on the operation. */
 var extractExtensions = operation => {
   const extensions = {};
@@ -749,9 +991,7 @@ var extractExtensions = operation => {
 };
 var processOperation = args => {
   const httpMethod = args.method.toUpperCase();
-  if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(httpMethod)) return null;
-  if (!args.operation.operationId) return null;
-  if (args.operation[args.options.excludeExtension]) return null;
+  if (!SUPPORTED_METHODS.includes(httpMethod) || !args.operation.operationId || args.operation[args.options.excludeExtension]) return null;
   const toolName = operationIdToToolName(args.operation.operationId);
   const parameters = [...(args.pathItemParameters ?? []), ...(args.operation.parameters ?? [])];
   const {
@@ -759,20 +999,15 @@ var processOperation = args => {
     serverManagedExtension
   } = args.options;
   const toArgName = argNameMapper(args.options.argumentNames);
-  const pathParams = extractPathParams({
+  const paramArgs = {
     parameters,
     spec: args.spec,
     documents,
     toArgName,
     serverManagedExtension
-  });
-  const queryParams = extractQueryParams({
-    parameters,
-    spec: args.spec,
-    documents,
-    toArgName,
-    serverManagedExtension
-  });
+  };
+  const pathParams = extractPathParams(paramArgs);
+  const queryParams = extractQueryParams(paramArgs);
   const bodyArgs = {
     requestBody: args.operation.requestBody,
     spec: args.spec,
@@ -783,7 +1018,12 @@ var processOperation = args => {
     ...bodyArgs,
     toArgName
   });
-  const inputSchema = buildInputSchema(pathParams, queryParams, bodyProps);
+  const inputSchema = selectInputSchema({
+    schemaDetail: args.options.schemaDetail,
+    pathParams,
+    queryParams,
+    bodyProps
+  });
   const serverManagedParameters = collectServerManagedParameters({
     pathParams,
     queryParams
@@ -791,7 +1031,10 @@ var processOperation = args => {
   const pinned = pinnedArgs(serverManagedParameters);
   return {
     name: toolName,
-    description: sanitizeDescription(args.operation.description),
+    description: describeOperation({
+      ...args,
+      method: httpMethod
+    }),
     inputSchema,
     method: httpMethod,
     pathTemplate: args.pathTemplate,
@@ -840,6 +1083,8 @@ var resolveOptions = (options = {}) => {
     excludeExtension: options.excludeExtension ?? "x-mcp-exclude",
     serverManagedExtension: options.serverManagedExtension ?? "x-mcp-server-managed",
     argumentNames: options.argumentNames ?? "camelCase",
+    schemaDetail: options.schemaDetail,
+    describe: options.describe,
     documents: options.documents
   };
 };
@@ -935,6 +1180,9 @@ var registerOpenApiTools = args => {
     name: tool.name,
     description: tool.description,
     inputSchema: tool.inputSchema,
+    _meta: args.toolMeta?.({
+      tool
+    }),
     handler: async rawArgs => {
       const headers = getApiHeaders();
       const handlerArgs = await applyServerParameters({
@@ -944,17 +1192,25 @@ var registerOpenApiTools = args => {
         serverParameters: args.serverParameters
       });
       const url = tool.path(handlerArgs) + (tool.query ? tool.query(handlerArgs) : "");
+      const data = await args.callApi({
+        method: tool.method,
+        url,
+        body: tool.body ? tool.body(handlerArgs) : void 0,
+        tool,
+        headers
+      });
+      const structuredContent = args.toStructuredContent?.({
+        data,
+        tool
+      });
       return {
         content: [{
           type: "text",
-          text: toText(await args.callApi({
-            method: tool.method,
-            url,
-            body: tool.body ? tool.body(handlerArgs) : void 0,
-            tool,
-            headers
-          }))
-        }]
+          text: toText(data)
+        }],
+        ...(structuredContent === void 0 ? {} : {
+          structuredContent
+        })
       };
     }
   });
@@ -962,4 +1218,4 @@ var registerOpenApiTools = args => {
 };
 
 //#endregion
-export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, NO_CONTENT_TEXT, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };
+export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, NO_CONTENT_TEXT, buildBodyFn, buildFullInputSchema, buildInputSchema, buildPathFn, buildQueryFn, createInProcessCallApi, dereferenceSchema, errorMessageOf, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel, toToolSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp-openapi",
-  "version": "0.5.7",
+  "version": "0.7.0",
   "description": "Generate Model Context Protocol (MCP) tools from an OpenAPI specification for @ttoss/http-server-mcp",
   "keywords": [
     "ai",
@@ -35,15 +35,15 @@
     "dist"
   ],
   "dependencies": {
-    "@ttoss/http-server-mcp": "^0.31.1"
+    "@ttoss/http-server": "^0.11.0",
+    "@ttoss/http-server-mcp": "^0.32.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
     "jest": "^30.4.2",
     "supertest": "^7.2.2",
     "tsdown": "^0.22.2",
-    "@ttoss/http-server": "^0.10.4",
-    "@ttoss/config": "^1.39.1"
+    "@ttoss/config": "^1.40.0"
   },
   "publishConfig": {
     "access": "public",