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

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 
 import { JsonObjectSchema, McpServer } from "@ttoss/http-server-mcp";
+import { App, InProcessResponse } from "@ttoss/http-server";
 
 //#region src/types.d.ts
 /** The JSON Schema primitive types this generator can derive from an OpenAPI `type`. */
@@ -121,6 +122,7 @@ type RequestBodySpec = {
 };
 interface OperationSpec {
   operationId?: string;
+  summary?: string;
   description?: string;
   parameters?: Array<{
     name?: string;
@@ -183,9 +185,39 @@ interface OpenApiToToolsOptions {
    * to an empty schema, which accepts any value.
    */
   documents?: OpenApiDocuments;
+  /**
+   * How much of each parameter's and body property's schema reaches the
+   * tool's `inputSchema`.
+   *
+   * - `'compact'` keeps the `type`, `items` and `description` of each
+   *   top-level argument, with descriptions flattened to one line.
+   * - `'full'` keeps the whole schema — `enum`, `format`, `pattern`,
+   *   `minimum`, `default`, nested `properties` and `required`, `oneOf` — and
+   *   changes only what JSON Schema cannot say: `allOf` is merged, `nullable`
+   *   becomes a `'null'` type (and joins an `enum`), and OpenAPI-only keywords
+   *   and `x-` extensions are dropped. Descriptions stay verbatim.
+   *
+   * @default 'compact'
+   */
+  schemaDetail?: 'compact' | 'full';
+  /**
+   * Builds each tool's description from its operation. The default is the
+   * operation's `description`, flattened to one line.
+   *
+   * @example
+   * ```typescript
+   * describe: ({ operation, method, pathTemplate }) =>
+   *   `${operation.summary}\n\n${operation.description}\n\n(${method} ${pathTemplate})`,
+   * ```
+   */
+  describe?: (args: {
+    operation: OperationSpec; /** Uppercase HTTP method. */
+    method: string;
+    pathTemplate: string;
+  }) => string;
 }
 /** {@link OpenApiToToolsOptions} with every default applied. */
-type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents'>> & Pick<OpenApiToToolsOptions, 'documents'>;
+type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents' | 'describe' | 'schemaDetail'>> & Pick<OpenApiToToolsOptions, 'documents' | 'describe' | 'schemaDetail'>;
 declare const DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
 declare const DEFAULT_SERVER_MANAGED_EXTENSION = "x-mcp-server-managed";
 //#endregion
@@ -217,6 +249,8 @@ type ExtractParamsArgs = {
 declare const extractPathParams: (args: ExtractParamsArgs) => Array<{
   name: string;
   argName: string;
+  description?: string; /** The parameter's schema with every `$ref` inlined. */
+  schema?: Record<string, unknown>;
   serverManaged: boolean;
   pinnedValue?: string;
 }>;
@@ -225,7 +259,8 @@ declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   argName: string;
   description: string;
   required: boolean;
-  type: string;
+  type: string; /** The parameter's schema with every `$ref` inlined. */
+  schema?: Record<string, unknown>;
   style?: string;
   explode?: boolean;
   serverManaged: boolean;
@@ -258,7 +293,8 @@ declare const extractBodyProps: (args: {
   nullable: boolean;
   oneOf?: unknown[];
   anyOf?: unknown[];
-  allOf?: unknown[];
+  allOf?: unknown[]; /** The property's whole schema, with every `$ref` inlined. */
+  schema: Record<string, unknown>;
 }>;
 /**
  * The value each server-managed body property pins, typed by its schema and
@@ -273,6 +309,39 @@ declare const extractPinnedBody: (args: {
   operationId: string;
 }) => Record<string, string | number | boolean>;
 //#endregion
+//#region src/fullSchema.d.ts
+/**
+ * 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.
+ */
+declare const toToolSchema: (value: unknown) => unknown;
+type FullParam = {
+  argName: string;
+  required?: boolean;
+  description?: string;
+  schema?: unknown;
+  serverManaged?: boolean;
+};
+type FullBodyProp = {
+  argName: string;
+  required: boolean;
+  schema: Record<string, unknown>;
+};
+/**
+ * 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.
+ */
+declare const buildFullInputSchema: (args: {
+  pathParams: FullParam[];
+  queryParams: FullParam[];
+  bodyProps: FullBodyProp[];
+}) => JsonObjectSchema;
+//#endregion
 //#region src/registerOpenApiTools.d.ts
 /** The resolved HTTP request a tool call maps to, before transport concerns. */
 interface ResolvedRequest {
@@ -310,6 +379,37 @@ interface RegisterOpenApiToolsArgs {
    * {@link NO_CONTENT_TEXT} for an empty body (e.g. a `204`).
    */
   toText?: (data: unknown) => string;
+  /**
+   * Builds the tool result's `structuredContent` from the raw API data, sent
+   * beside the text payload. Return `undefined` to keep a result text-only,
+   * which is every result when this is unset.
+   *
+   * @example
+   * ```typescript
+   * toStructuredContent: ({ data }) =>
+   *   typeof data === 'object' && data !== null && !Array.isArray(data)
+   *     ? (data as Record<string, unknown>)
+   *     : undefined,
+   * ```
+   */
+  toStructuredContent?: (args: {
+    data: unknown;
+    tool: ToolDefinition;
+  }) => Record<string, unknown> | undefined;
+  /**
+   * Builds each tool's `_meta`, advertised on `tools/list`. This is how a
+   * generated tool links to an MCP Apps view: return the bag from
+   * `registerAppResource(...).toolMeta()`. `undefined` registers no `_meta`.
+   *
+   * @example
+   * ```typescript
+   * toolMeta: ({ tool }) =>
+   *   tool.name === 'get-agent' ? agentCard.toolMeta() : undefined,
+   * ```
+   */
+  toolMeta?: (args: {
+    tool: ToolDefinition;
+  }) => Record<string, unknown> | undefined;
   /**
    * Supplies the values of the tool's server-managed path and query
    * parameters (`tool.serverManagedParameters`), keyed by their spec name.
@@ -360,6 +460,58 @@ declare const NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
  */
 declare const registerOpenApiTools: (args: RegisterOpenApiToolsArgs) => ToolDefinition[];
 //#endregion
+//#region src/inProcessCallApi.d.ts
+interface CreateInProcessCallApiArgs {
+  /**
+   * The Koa app serving the REST API the tools were generated from, or a
+   * function returning it — for an app that mounts the MCP router itself and
+   * so is not built yet when the tools are registered.
+   */
+  app: App | (() => App | Promise<App>);
+  /**
+   * Headers added to every dispatched request, after the ones the MCP request
+   * carried — e.g. a marker that tells a request log the call came from a tool.
+   */
+  headers?: (request: ResolvedRequest) => Record<string, string | undefined>;
+  /**
+   * Builds the error a non-2xx response throws. The default reads the message
+   * out of the common error envelopes (see {@link errorMessageOf}).
+   */
+  toError?: (response: InProcessResponse, request: ResolvedRequest) => Error;
+}
+/**
+ * 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.
+ */
+declare const errorMessageOf: (body: unknown) => string | null;
+/**
+ * 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 }),
+ * });
+ * ```
+ */
+declare const createInProcessCallApi: ({
+  app,
+  headers,
+  toError
+}: CreateInProcessCallApiArgs) => ((request: ResolvedRequest) => Promise<unknown>);
+//#endregion
 //#region src/schema.d.ts
 type ResolvedSchema = {
   type?: string;
@@ -498,4 +650,4 @@ declare const openApiToToolDefinitions: (args: {
   options?: OpenApiToToolsOptions;
 }) => ToolDefinition[];
 //#endregion
-export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, NO_CONTENT_TEXT, type OpenApiDocuments, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type QueryParamSerialization, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedParameter, type ResolvedRequest, type ResolvedToolOptions, type ServerManagedParameter, type ToolDefinition, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };
+export { type CreateInProcessCallApiArgs, DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, NO_CONTENT_TEXT, type OpenApiDocuments, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type QueryParamSerialization, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedParameter, type ResolvedRequest, type ResolvedToolOptions, type ServerManagedParameter, type ToolDefinition, buildBodyFn, buildFullInputSchema, buildInputSchema, buildPathFn, buildQueryFn, createInProcessCallApi, dereferenceSchema, errorMessageOf, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel, toToolSchema };

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 
+import { App, InProcessResponse } from "@ttoss/http-server";
 import { JsonObjectSchema, McpServer } from "@ttoss/http-server-mcp";
 
 //#region src/types.d.ts
@@ -121,6 +122,7 @@ type RequestBodySpec = {
 };
 interface OperationSpec {
   operationId?: string;
+  summary?: string;
   description?: string;
   parameters?: Array<{
     name?: string;
@@ -183,9 +185,39 @@ interface OpenApiToToolsOptions {
    * to an empty schema, which accepts any value.
    */
   documents?: OpenApiDocuments;
+  /**
+   * How much of each parameter's and body property's schema reaches the
+   * tool's `inputSchema`.
+   *
+   * - `'compact'` keeps the `type`, `items` and `description` of each
+   *   top-level argument, with descriptions flattened to one line.
+   * - `'full'` keeps the whole schema — `enum`, `format`, `pattern`,
+   *   `minimum`, `default`, nested `properties` and `required`, `oneOf` — and
+   *   changes only what JSON Schema cannot say: `allOf` is merged, `nullable`
+   *   becomes a `'null'` type (and joins an `enum`), and OpenAPI-only keywords
+   *   and `x-` extensions are dropped. Descriptions stay verbatim.
+   *
+   * @default 'compact'
+   */
+  schemaDetail?: 'compact' | 'full';
+  /**
+   * Builds each tool's description from its operation. The default is the
+   * operation's `description`, flattened to one line.
+   *
+   * @example
+   * ```typescript
+   * describe: ({ operation, method, pathTemplate }) =>
+   *   `${operation.summary}\n\n${operation.description}\n\n(${method} ${pathTemplate})`,
+   * ```
+   */
+  describe?: (args: {
+    operation: OperationSpec; /** Uppercase HTTP method. */
+    method: string;
+    pathTemplate: string;
+  }) => string;
 }
 /** {@link OpenApiToToolsOptions} with every default applied. */
-type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents'>> & Pick<OpenApiToToolsOptions, 'documents'>;
+type ResolvedToolOptions = Required<Omit<OpenApiToToolsOptions, 'documents' | 'describe' | 'schemaDetail'>> & Pick<OpenApiToToolsOptions, 'documents' | 'describe' | 'schemaDetail'>;
 declare const DEFAULT_EXCLUDE_EXTENSION = "x-mcp-exclude";
 declare const DEFAULT_SERVER_MANAGED_EXTENSION = "x-mcp-server-managed";
 //#endregion
@@ -217,6 +249,8 @@ type ExtractParamsArgs = {
 declare const extractPathParams: (args: ExtractParamsArgs) => Array<{
   name: string;
   argName: string;
+  description?: string; /** The parameter's schema with every `$ref` inlined. */
+  schema?: Record<string, unknown>;
   serverManaged: boolean;
   pinnedValue?: string;
 }>;
@@ -225,7 +259,8 @@ declare const extractQueryParams: (args: ExtractParamsArgs) => Array<{
   argName: string;
   description: string;
   required: boolean;
-  type: string;
+  type: string; /** The parameter's schema with every `$ref` inlined. */
+  schema?: Record<string, unknown>;
   style?: string;
   explode?: boolean;
   serverManaged: boolean;
@@ -258,7 +293,8 @@ declare const extractBodyProps: (args: {
   nullable: boolean;
   oneOf?: unknown[];
   anyOf?: unknown[];
-  allOf?: unknown[];
+  allOf?: unknown[]; /** The property's whole schema, with every `$ref` inlined. */
+  schema: Record<string, unknown>;
 }>;
 /**
  * The value each server-managed body property pins, typed by its schema and
@@ -273,6 +309,39 @@ declare const extractPinnedBody: (args: {
   operationId: string;
 }) => Record<string, string | number | boolean>;
 //#endregion
+//#region src/fullSchema.d.ts
+/**
+ * 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.
+ */
+declare const toToolSchema: (value: unknown) => unknown;
+type FullParam = {
+  argName: string;
+  required?: boolean;
+  description?: string;
+  schema?: unknown;
+  serverManaged?: boolean;
+};
+type FullBodyProp = {
+  argName: string;
+  required: boolean;
+  schema: Record<string, unknown>;
+};
+/**
+ * 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.
+ */
+declare const buildFullInputSchema: (args: {
+  pathParams: FullParam[];
+  queryParams: FullParam[];
+  bodyProps: FullBodyProp[];
+}) => JsonObjectSchema;
+//#endregion
 //#region src/registerOpenApiTools.d.ts
 /** The resolved HTTP request a tool call maps to, before transport concerns. */
 interface ResolvedRequest {
@@ -310,6 +379,37 @@ interface RegisterOpenApiToolsArgs {
    * {@link NO_CONTENT_TEXT} for an empty body (e.g. a `204`).
    */
   toText?: (data: unknown) => string;
+  /**
+   * Builds the tool result's `structuredContent` from the raw API data, sent
+   * beside the text payload. Return `undefined` to keep a result text-only,
+   * which is every result when this is unset.
+   *
+   * @example
+   * ```typescript
+   * toStructuredContent: ({ data }) =>
+   *   typeof data === 'object' && data !== null && !Array.isArray(data)
+   *     ? (data as Record<string, unknown>)
+   *     : undefined,
+   * ```
+   */
+  toStructuredContent?: (args: {
+    data: unknown;
+    tool: ToolDefinition;
+  }) => Record<string, unknown> | undefined;
+  /**
+   * Builds each tool's `_meta`, advertised on `tools/list`. This is how a
+   * generated tool links to an MCP Apps view: return the bag from
+   * `registerAppResource(...).toolMeta()`. `undefined` registers no `_meta`.
+   *
+   * @example
+   * ```typescript
+   * toolMeta: ({ tool }) =>
+   *   tool.name === 'get-agent' ? agentCard.toolMeta() : undefined,
+   * ```
+   */
+  toolMeta?: (args: {
+    tool: ToolDefinition;
+  }) => Record<string, unknown> | undefined;
   /**
    * Supplies the values of the tool's server-managed path and query
    * parameters (`tool.serverManagedParameters`), keyed by their spec name.
@@ -360,6 +460,58 @@ declare const NO_CONTENT_TEXT = "Succeeded. The operation returned no content.";
  */
 declare const registerOpenApiTools: (args: RegisterOpenApiToolsArgs) => ToolDefinition[];
 //#endregion
+//#region src/inProcessCallApi.d.ts
+interface CreateInProcessCallApiArgs {
+  /**
+   * The Koa app serving the REST API the tools were generated from, or a
+   * function returning it — for an app that mounts the MCP router itself and
+   * so is not built yet when the tools are registered.
+   */
+  app: App | (() => App | Promise<App>);
+  /**
+   * Headers added to every dispatched request, after the ones the MCP request
+   * carried — e.g. a marker that tells a request log the call came from a tool.
+   */
+  headers?: (request: ResolvedRequest) => Record<string, string | undefined>;
+  /**
+   * Builds the error a non-2xx response throws. The default reads the message
+   * out of the common error envelopes (see {@link errorMessageOf}).
+   */
+  toError?: (response: InProcessResponse, request: ResolvedRequest) => Error;
+}
+/**
+ * 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.
+ */
+declare const errorMessageOf: (body: unknown) => string | null;
+/**
+ * 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 }),
+ * });
+ * ```
+ */
+declare const createInProcessCallApi: ({
+  app,
+  headers,
+  toError
+}: CreateInProcessCallApiArgs) => ((request: ResolvedRequest) => Promise<unknown>);
+//#endregion
 //#region src/schema.d.ts
 type ResolvedSchema = {
   type?: string;
@@ -498,4 +650,4 @@ declare const openApiToToolDefinitions: (args: {
   options?: OpenApiToToolsOptions;
 }) => ToolDefinition[];
 //#endregion
-export { DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, NO_CONTENT_TEXT, type OpenApiDocuments, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type QueryParamSerialization, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedParameter, type ResolvedRequest, type ResolvedToolOptions, type ServerManagedParameter, type ToolDefinition, buildBodyFn, buildInputSchema, buildPathFn, buildQueryFn, dereferenceSchema, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel };
+export { type CreateInProcessCallApiArgs, DEFAULT_EXCLUDE_EXTENSION, DEFAULT_SERVER_MANAGED_EXTENSION, type JsonSchemaProperty, NO_CONTENT_TEXT, type OpenApiDocuments, type OpenApiSpec, type OpenApiToToolsOptions, type OperationSpec, type QueryParamSerialization, type RegisterOpenApiToolsArgs, type RequestBodySpec, type ResolvedParameter, type ResolvedRequest, type ResolvedToolOptions, type ServerManagedParameter, type ToolDefinition, buildBodyFn, buildFullInputSchema, buildInputSchema, buildPathFn, buildQueryFn, createInProcessCallApi, dereferenceSchema, errorMessageOf, extractAcceptedBodyFields, extractBodyProps, extractPathParams, extractPinnedBody, extractQueryParams, getJsonSchemaType, openApiToToolDefinitions, operationIdToToolName, processOperation, processPath, registerOpenApiTools, resolveParameter, resolveSchema, snakeToCamel, toToolSchema };