fastmcp 4.17.1 → 4.18.0

package/dist/openapi/index.d.cts

@@ -0,0 +1,171 @@
+import { FastMCP, FastMCPSessionAuth } from '../FastMCP.cjs';
+import '@modelcontextprotocol/sdk/server/index.js';
+import '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import '@modelcontextprotocol/sdk/shared/protocol.js';
+import '@modelcontextprotocol/sdk/shared/transport.js';
+import '@modelcontextprotocol/sdk/types.js';
+import '@standard-schema/spec';
+import 'events';
+import 'hono';
+import 'http';
+import 'mcp-proxy';
+import 'strict-event-emitter-types';
+import 'zod';
+import '../OAuthProvider-Dy1PbWAT.cjs';
+import 'node:http';
+
+/**
+ * A minimal, hand-typed slice of a bundled OpenAPI 3.x document — just the
+ * parts this module reads. Deliberately not the full `openapi-types` shape,
+ * to avoid taking on that dependency for typing alone.
+ */
+interface BundledOpenApiDocument {
+    components?: {
+        schemas?: Record<string, OpenApiSchema>;
+    };
+    info?: {
+        title?: string;
+    };
+    openapi?: string;
+    paths?: Record<string, RawPathItem>;
+    servers?: OpenApiServer[];
+    swagger?: string;
+}
+interface FromOpenAPIOptions {
+    /**
+     * Overrides the resolved `servers[0].url`. Required when the spec has no
+     * `servers` entry, or has a relative `servers[0].url` and was not loaded
+     * from an http(s) URL.
+     */
+    baseUrl?: string;
+    /**
+     * Excludes operations for which this returns `true`. Applied after
+     * `include`.
+     */
+    exclude?: (operation: OperationSummary) => boolean;
+    /**
+     * HTTP client used to execute generated tool calls. Defaults to the global
+     * `fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Static or dynamically-resolved headers (e.g. an auth token) sent with
+     * every generated tool call.
+     */
+    headers?: (() => Promise<Record<string, string>> | Record<string, string>) | Record<string, string>;
+    /**
+     * Only keeps operations for which this returns `true`.
+     */
+    include?: (operation: OperationSummary) => boolean;
+    /**
+     * Hard cap on the number of generated tools. `fromOpenAPI` throws rather
+     * than silently truncating if the operation count (after `include`/
+     * `exclude`) exceeds this — or a default threshold, if neither this nor
+     * `include`/`exclude` was provided.
+     */
+    maxTools?: number;
+    /**
+     * Overrides the generated tool name for a given `operationId`.
+     */
+    mcpNames?: Record<string, string>;
+    /**
+     * Name for a newly-created server. Ignored when `server` is provided.
+     * @default the spec's `info.title`, or "OpenAPI Server"
+     */
+    name?: string;
+    /**
+     * An existing `FastMCP` server to register the generated tools onto,
+     * instead of creating a new one.
+     */
+    server?: FastMCP<FastMCPSessionAuth>;
+    /**
+     * A URL, a file path, or an already-parsed OpenAPI document.
+     *
+     * Passing a URL or file path (rather than a parsed object) is what lets
+     * external `$ref`s and a relative `servers[0].url` resolve correctly — both
+     * are resolved relative to this value.
+     */
+    spec: Record<string, unknown> | string;
+    /**
+     * Version for a newly-created server. Ignored when `server` is provided.
+     * @default "1.0.0"
+     */
+    version?: `${number}.${number}.${number}`;
+}
+type HttpMethod = "delete" | "get" | "patch" | "post" | "put";
+interface HttpRoute {
+    deprecated: boolean;
+    method: HttpMethod;
+    operationId?: string;
+    parameters: OpenApiParameter[];
+    path: string;
+    requestBody?: OpenApiRequestBody;
+    summary?: string;
+    tags: string[];
+}
+interface OpenApiParameter {
+    deprecated?: boolean;
+    description?: string;
+    in: ParameterLocation;
+    name: string;
+    required?: boolean;
+    schema?: OpenApiSchema;
+}
+interface OpenApiParameterRef {
+    $ref: string;
+}
+interface OpenApiRequestBody {
+    content?: Record<string, {
+        schema?: OpenApiSchema;
+    }>;
+    required?: boolean;
+}
+/**
+ * A raw OpenAPI/JSON Schema fragment as it appears inside the document
+ * (a parameter's `schema`, a `components.schemas` entry, etc.). Unlike
+ * `JsonSchemaObject` (jsonSchemaAdapter.ts), these are not required to carry
+ * a top-level `type` — a bare `$ref`, `allOf`, or `enum`-only node is valid
+ * JSON Schema and shows up constantly in real specs. Only the final,
+ * assembled per-tool schema needs to satisfy `JsonSchemaObject` (see
+ * `schemas.ts`).
+ */
+type OpenApiSchema = Record<string, unknown>;
+interface OpenApiServer {
+    url: string;
+    variables?: Record<string, OpenApiServerVariable>;
+}
+interface OpenApiServerVariable {
+    default: string;
+}
+/**
+ * The subset of a route's shape exposed to `include`/`exclude` predicates.
+ */
+interface OperationSummary {
+    deprecated: boolean;
+    method: HttpMethod;
+    operationId?: string;
+    path: string;
+    tags: string[];
+}
+type ParameterLocation = "cookie" | "header" | "path" | "query";
+interface RawOperation {
+    deprecated?: boolean;
+    operationId?: string;
+    parameters?: (OpenApiParameter | OpenApiParameterRef)[];
+    requestBody?: OpenApiParameterRef | OpenApiRequestBody;
+    summary?: string;
+    tags?: string[];
+}
+type RawPathItem = {
+    parameters?: (OpenApiParameter | OpenApiParameterRef)[];
+} & Partial<Record<HttpMethod, RawOperation>>;
+
+/**
+ * Converts an OpenAPI 3.x document into an MCP server, one tool per
+ * operation.
+ *
+ * See docs/openapi.md for the full option reference and known limitations.
+ */
+declare function fromOpenAPI(options: FromOpenAPIOptions): Promise<FastMCP>;
+
+export { type BundledOpenApiDocument, type FromOpenAPIOptions, type HttpMethod, type HttpRoute, type OperationSummary, fromOpenAPI };

package/dist/openapi/index.d.ts

@@ -0,0 +1,171 @@
+import { FastMCP, FastMCPSessionAuth } from '../FastMCP.js';
+import '@modelcontextprotocol/sdk/server/index.js';
+import '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import '@modelcontextprotocol/sdk/shared/protocol.js';
+import '@modelcontextprotocol/sdk/shared/transport.js';
+import '@modelcontextprotocol/sdk/types.js';
+import '@standard-schema/spec';
+import 'events';
+import 'hono';
+import 'http';
+import 'mcp-proxy';
+import 'strict-event-emitter-types';
+import 'zod';
+import '../OAuthProvider-Dy1PbWAT.js';
+import 'node:http';
+
+/**
+ * A minimal, hand-typed slice of a bundled OpenAPI 3.x document — just the
+ * parts this module reads. Deliberately not the full `openapi-types` shape,
+ * to avoid taking on that dependency for typing alone.
+ */
+interface BundledOpenApiDocument {
+    components?: {
+        schemas?: Record<string, OpenApiSchema>;
+    };
+    info?: {
+        title?: string;
+    };
+    openapi?: string;
+    paths?: Record<string, RawPathItem>;
+    servers?: OpenApiServer[];
+    swagger?: string;
+}
+interface FromOpenAPIOptions {
+    /**
+     * Overrides the resolved `servers[0].url`. Required when the spec has no
+     * `servers` entry, or has a relative `servers[0].url` and was not loaded
+     * from an http(s) URL.
+     */
+    baseUrl?: string;
+    /**
+     * Excludes operations for which this returns `true`. Applied after
+     * `include`.
+     */
+    exclude?: (operation: OperationSummary) => boolean;
+    /**
+     * HTTP client used to execute generated tool calls. Defaults to the global
+     * `fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Static or dynamically-resolved headers (e.g. an auth token) sent with
+     * every generated tool call.
+     */
+    headers?: (() => Promise<Record<string, string>> | Record<string, string>) | Record<string, string>;
+    /**
+     * Only keeps operations for which this returns `true`.
+     */
+    include?: (operation: OperationSummary) => boolean;
+    /**
+     * Hard cap on the number of generated tools. `fromOpenAPI` throws rather
+     * than silently truncating if the operation count (after `include`/
+     * `exclude`) exceeds this — or a default threshold, if neither this nor
+     * `include`/`exclude` was provided.
+     */
+    maxTools?: number;
+    /**
+     * Overrides the generated tool name for a given `operationId`.
+     */
+    mcpNames?: Record<string, string>;
+    /**
+     * Name for a newly-created server. Ignored when `server` is provided.
+     * @default the spec's `info.title`, or "OpenAPI Server"
+     */
+    name?: string;
+    /**
+     * An existing `FastMCP` server to register the generated tools onto,
+     * instead of creating a new one.
+     */
+    server?: FastMCP<FastMCPSessionAuth>;
+    /**
+     * A URL, a file path, or an already-parsed OpenAPI document.
+     *
+     * Passing a URL or file path (rather than a parsed object) is what lets
+     * external `$ref`s and a relative `servers[0].url` resolve correctly — both
+     * are resolved relative to this value.
+     */
+    spec: Record<string, unknown> | string;
+    /**
+     * Version for a newly-created server. Ignored when `server` is provided.
+     * @default "1.0.0"
+     */
+    version?: `${number}.${number}.${number}`;
+}
+type HttpMethod = "delete" | "get" | "patch" | "post" | "put";
+interface HttpRoute {
+    deprecated: boolean;
+    method: HttpMethod;
+    operationId?: string;
+    parameters: OpenApiParameter[];
+    path: string;
+    requestBody?: OpenApiRequestBody;
+    summary?: string;
+    tags: string[];
+}
+interface OpenApiParameter {
+    deprecated?: boolean;
+    description?: string;
+    in: ParameterLocation;
+    name: string;
+    required?: boolean;
+    schema?: OpenApiSchema;
+}
+interface OpenApiParameterRef {
+    $ref: string;
+}
+interface OpenApiRequestBody {
+    content?: Record<string, {
+        schema?: OpenApiSchema;
+    }>;
+    required?: boolean;
+}
+/**
+ * A raw OpenAPI/JSON Schema fragment as it appears inside the document
+ * (a parameter's `schema`, a `components.schemas` entry, etc.). Unlike
+ * `JsonSchemaObject` (jsonSchemaAdapter.ts), these are not required to carry
+ * a top-level `type` — a bare `$ref`, `allOf`, or `enum`-only node is valid
+ * JSON Schema and shows up constantly in real specs. Only the final,
+ * assembled per-tool schema needs to satisfy `JsonSchemaObject` (see
+ * `schemas.ts`).
+ */
+type OpenApiSchema = Record<string, unknown>;
+interface OpenApiServer {
+    url: string;
+    variables?: Record<string, OpenApiServerVariable>;
+}
+interface OpenApiServerVariable {
+    default: string;
+}
+/**
+ * The subset of a route's shape exposed to `include`/`exclude` predicates.
+ */
+interface OperationSummary {
+    deprecated: boolean;
+    method: HttpMethod;
+    operationId?: string;
+    path: string;
+    tags: string[];
+}
+type ParameterLocation = "cookie" | "header" | "path" | "query";
+interface RawOperation {
+    deprecated?: boolean;
+    operationId?: string;
+    parameters?: (OpenApiParameter | OpenApiParameterRef)[];
+    requestBody?: OpenApiParameterRef | OpenApiRequestBody;
+    summary?: string;
+    tags?: string[];
+}
+type RawPathItem = {
+    parameters?: (OpenApiParameter | OpenApiParameterRef)[];
+} & Partial<Record<HttpMethod, RawOperation>>;
+
+/**
+ * Converts an OpenAPI 3.x document into an MCP server, one tool per
+ * operation.
+ *
+ * See docs/openapi.md for the full option reference and known limitations.
+ */
+declare function fromOpenAPI(options: FromOpenAPIOptions): Promise<FastMCP>;
+
+export { type BundledOpenApiDocument, type FromOpenAPIOptions, type HttpMethod, type HttpRoute, type OperationSummary, fromOpenAPI };