@prefecthq/fastmcp-ts 1.2.1 → 1.3.0

package/dist/cli/index.cjs

@@ -1172,7 +1172,7 @@ var init_version = __esm({
       async run({ args }) {
         if (args.json) setJsonMode(true);
         const data = {
-          fastmcp: "1.2.1",
+          fastmcp: "1.3.0",
           "mcp-sdk": "2.0.0",
           node: process.version,
           platform: `${process.platform} ${process.arch}`
@@ -33404,7 +33404,7 @@ var init_inspect = __esm({
               // only case Python's inspect supports); over --url/--command the
               // generation is unknowable from the wire.
               generation: mode.kind === "inprocess" ? 2 : null,
-              fastmcpVersion: "1.2.1",
+              fastmcpVersion: "1.3.0",
               mcpVersion: "2.0.0",
               tools: tools2,
               prompts: prompts2,
@@ -46908,7 +46908,7 @@ init_format();
 var main = defineCommand({
   meta: {
     name: "fastmcp",
-    version: "1.2.1",
+    version: "1.3.0",
     description: "FastMCP CLI \u2014 build, run, and manage MCP servers"
   },
   args: {

package/dist/server.d.ts

@@ -6,6 +6,56 @@ import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Readable, Writable } from 'node:stream';
 import { Response as Response$1 } from 'express';
 
+/**
+ * Read-only, per-request snapshot of the HTTP request that carried the current
+ * MCP message. Present wherever the server is reached over an HTTP transport;
+ * `undefined` on stdio.
+ *
+ * REDACTION: credential headers (see {@link DEFAULT_SENSITIVE_HEADERS}, tuned
+ * by `FastMCPOptions.http`) are withheld from `headers` and listed in
+ * `redactedHeaderNames`, so a `null` lookup is never silent. The redaction
+ * guards accidental egress: tool results and logs flow into model context by
+ * design. A `RequestVerifier` receives the FULL wire headers instead (its
+ * `redactedHeaderNames` is empty): the verifier is the credential-handling
+ * code.
+ *
+ * TRUST: every value here is client-controlled input. Nothing in this object
+ * is authenticated. Do not derive authorization from it in handlers. For
+ * header-established identity (trusted reverse proxy), configure
+ * `FastMCPOptions.auth` with a `RequestVerifier` so identity flows through
+ * `ctx.auth` like every other authenticated request. See docs:
+ * servers/auth/trusted-proxy.
+ */
+interface HttpRequestContext {
+    /** Headers of the carrying HTTP request, minus the sensitive set. A per-request copy; mutations affect nothing. */
+    readonly headers: Headers;
+    /** Names (lowercase, sorted) that were present on the wire but withheld from `headers`. */
+    readonly redactedHeaderNames: readonly string[];
+    /** HTTP method of the carrying request (e.g. 'POST'). */
+    readonly method: string;
+    /**
+     * Origin-form request target (path + query, e.g. '/mcp?tenant=a'). Scheme and
+     * authority are deliberately absent: behind a proxy this server cannot know
+     * the external URL. Reconstruct it from your proxy's forwarded headers if you
+     * need it.
+     */
+    readonly url: string;
+}
+/**
+ * Copy of `headers` that is safe to attach to an outbound request to another
+ * service. Drops credentials (authorization, cookie, proxy-*), hop-by-hop
+ * headers, message-framing headers (host, content-length, content-type,
+ * expect), and every `mcp-*` protocol header. Deployment-specific credential
+ * headers are covered by `FastMCPOptions.http.redactHeaders`: they are already
+ * absent from `ctx.http.headers`. `include` re-admits specific names.
+ * Re-admitting 'authorization' forwards the caller's credential; the MCP spec
+ * forbids passing the inbound token to upstream APIs, so mint your own
+ * upstream credential instead.
+ */
+declare function forwardableHeaders(headers: Headers, options?: {
+    include?: string[];
+}): Headers;
+
 interface AccessToken {
     /** The raw bearer token string. */
     token: string;
@@ -21,6 +71,34 @@ interface AccessToken {
 interface TokenVerifier {
     verify(token: string): Promise<AccessToken>;
 }
+/**
+ * Request-level verifier for HTTP deployments where identity does not arrive
+ * as a bearer token. The typical case is a trusted reverse proxy that
+ * authenticates the caller and forwards the resolved identity as request
+ * headers.
+ *
+ * Called once per HTTP request, before dispatch, with that request's own FULL
+ * wire headers (no redaction; `request.redactedHeaderNames` is empty here —
+ * the verifier is the credential-handling code). Return an AccessToken to
+ * admit the request. The result becomes `ctx.auth`, feeds per-item `auth`
+ * checks and list filtering, and its `token` (hashed) keys response-cache
+ * partitioning. `token` MUST therefore be a stable, non-empty, per-identity
+ * value, such as the verified user id. The server rejects an empty `token`
+ * with HTTP 500. Throw `AuthorizationError` to produce 403; any other throw
+ * produces 401.
+ *
+ * SECURITY: request headers are forgeable by anyone who can reach this server
+ * directly. Trust them only after verifying provenance: a shared secret the
+ * proxy injects, mTLS, or network isolation. Add your provenance-secret
+ * header to `FastMCPOptions.http.redactHeaders` so it never surfaces in
+ * `ctx.http`. See docs: servers/auth/trusted-proxy.
+ *
+ * HTTP transports only. On stdio there is no HTTP request; configure a
+ * TokenVerifier if you need `FASTMCP_CLI_AUTH_TOKEN` support.
+ */
+interface RequestVerifier {
+    verifyRequest(request: HttpRequestContext): Promise<AccessToken>;
+}
 /**
  * Thrown by authorization checks to produce a 403 response.
  * Any other error thrown during verification produces a 401.
@@ -225,6 +303,16 @@ interface McpContext {
     auth: AccessToken | undefined;
     /** The MCP request ID for the current call. */
     requestId: string | undefined;
+    /**
+     * The HTTP request carrying the current MCP message, when serving over an
+     * HTTP transport; `undefined` on stdio. Fresh per request: on a sessionful
+     * connection each request's own headers appear here, never the
+     * initialize-time ones. Credential headers are withheld by default and
+     * listed in `http.redactedHeaderNames` (tune with `FastMCPOptions.http`).
+     * Untrusted input; see HttpRequestContext's docs before deriving any
+     * authorization from it.
+     */
+    http: HttpRequestContext | undefined;
     /** Send a log message to the client at the specified RFC 5424 severity level. */
     log(level: LogLevel, message: string, loggerName?: string): Promise<void>;
     debug(message: string, loggerName?: string): Promise<void>;
@@ -642,7 +730,7 @@ interface ResourceConfig {
     /** Arbitrary tags for server-side filtering. */
     tags?: string[];
     auth?: AuthCheck;
-    /** Apps extension metadata. Included in _meta.ui in resources/list for UI-capable clients. */
+    /** Apps extension metadata. Included as `_meta.ui` on resources/list entries and on every resources/read content item for UI-capable clients. */
     ui?: ResourceUiMeta;
     /**
      * Autocompletion callbacks for this resource template's RFC 6570 variables,
@@ -663,12 +751,14 @@ declare class ResourceResult {
         mimeType?: string;
         text?: string;
         blob?: string;
+        _meta?: Record<string, unknown>;
     }>;
     constructor(contents: Array<{
         uri: string;
         mimeType?: string;
         text?: string;
         blob?: string;
+        _meta?: Record<string, unknown>;
     }>);
 }
 
@@ -688,10 +778,30 @@ interface OAuthConfig {
 interface FastMCPOptions {
     name: string;
     version?: string;
-    /** Simple bearer-token verifier for non-OAuth auth scenarios. */
-    auth?: TokenVerifier;
+    /**
+     * Bearer-token verifier, or a RequestVerifier for header-based
+     * (trusted-proxy) deployments. See each type's docs. A RequestVerifier
+     * applies to HTTP transports only; stdio's FASTMCP_CLI_AUTH_TOKEN needs a
+     * TokenVerifier. When both `oauth` and `auth` are set, `oauth` serves the
+     * endpoint and `auth` is ignored.
+     */
+    auth?: TokenVerifier | RequestVerifier;
     /** Full OAuth 2.1 server with Dynamic Client Registration support. */
     oauth?: OAuthConfig;
+    /**
+     * HTTP request context tuning for `ctx.http`. `redactHeaders` adds names to
+     * the sensitive set withheld from `ctx.http.headers` (defaults:
+     * authorization, cookie, proxy-authorization, mcp-session-id); use it for
+     * deployment-specific credentials such as a proxy shared-secret header.
+     * `exposeHeaders` removes names from the set; it is the explicit, greppable
+     * opt-out. Withheld names are listed in `ctx.http.redactedHeaderNames`.
+     * Redaction applies to `ctx.http` only; a RequestVerifier always sees the
+     * full wire headers.
+     */
+    http?: {
+        redactHeaders?: string[];
+        exposeHeaders?: string[];
+    };
     /** Maximum number of tools returned per listTools page. Default: 50. */
     toolsPageSize?: number;
     /** Maximum number of resources (or templates) returned per page. Default: 50. */
@@ -853,6 +963,7 @@ declare class FastMCP {
     readonly version: string;
     private _auth;
     private _oauth;
+    private _sensitiveHeaders;
     private _toolsPageSize;
     private _resourcesPageSize;
     private _tools;
@@ -1307,6 +1418,203 @@ type ProxyTransport = StdioTransport | HttpTransport;
  */
 declare function createProxy(config: ProxyTransport, name?: string): Promise<FastMCP>;
 
+/**
+ * Shared types for the OpenAPI integration.
+ *
+ * The intermediate representation (HTTPRoute and friends) is a direct port of
+ * Python FastMCP's `fastmcp.utilities.openapi.models` so the two
+ * implementations generate identical MCP components from the same spec. The
+ * parity contract is pinned by the snapshots in `tests/fixtures/openapi/`.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | 'TRACE';
+type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
+type JsonSchema = Record<string, unknown>;
+/** A single parameter of an HTTP operation. */
+interface ParameterInfo {
+    name: string;
+    location: ParameterLocation;
+    required: boolean;
+    schema: JsonSchema;
+    description?: string;
+    /** OpenAPI explode property for array/object serialization. */
+    explode?: boolean;
+    /** OpenAPI style property (form, spaceDelimited, pipeDelimited, deepObject, ...). */
+    style?: string;
+}
+/** The request body of an HTTP operation, keyed by media type. */
+interface RequestBodyInfo {
+    required: boolean;
+    contentSchema: Record<string, JsonSchema>;
+    description?: string;
+}
+/** The primary success response of an HTTP operation, keyed by media type. */
+interface ResponseInfo {
+    description?: string;
+    contentSchema: Record<string, JsonSchema>;
+}
+/** Where a flattened tool argument goes when the HTTP request is built. */
+interface ParameterMapping {
+    location: ParameterLocation | 'body';
+    openapiName: string;
+}
+/** Intermediate representation of a single OpenAPI operation. */
+interface HTTPRoute {
+    path: string;
+    method: HttpMethod;
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    parameters: ParameterInfo[];
+    requestBody?: RequestBodyInfo;
+    /** Only the primary success response, keyed by its status code string. */
+    responses: Record<string, ResponseInfo>;
+    /** Schema definitions needed by the input (parameters + request body). */
+    requestSchemas: Record<string, JsonSchema>;
+    /** Schema definitions needed by the output (responses). */
+    responseSchemas: Record<string, JsonSchema>;
+    /** `x-` extension fields found on the operation. */
+    extensions: Record<string, unknown>;
+    openapiVersion?: string;
+    /** Pre-calculated flat input schema advertised on the MCP tool. */
+    flatParamSchema: JsonSchema;
+    /** Maps flat argument names back to their OpenAPI locations. */
+    parameterMap: Record<string, ParameterMapping>;
+}
+/** Type of FastMCP component to create from a route. */
+type MCPType = 'tool' | 'resource' | 'resourceTemplate' | 'exclude';
+/** Mapping rule from HTTP routes to FastMCP component types. */
+interface RouteMap {
+    /** HTTP methods to match. `'*'` (default) matches every method. */
+    methods?: HttpMethod[] | '*';
+    /** Pattern searched (unanchored) against the route path. Default matches all. */
+    pattern?: RegExp | string;
+    /** Tags that must ALL be present on the route for the map to match. */
+    tags?: string[];
+    /** The component type to create for matching routes. */
+    mcpType: MCPType;
+    /** Extra tags applied to components created by this map. */
+    mcpTags?: string[];
+}
+/**
+ * Advanced route-type hook, run after the route maps on every non-excluded
+ * route. Return a new MCPType to override, or null/undefined to keep the
+ * mapped type. Exceptions are swallowed with a warning.
+ */
+type RouteMapFn = (route: HTTPRoute, mcpType: MCPType) => MCPType | null | undefined;
+/** Mutable pre-registration view of a generated tool. */
+interface OpenAPIToolComponent {
+    kind: 'tool';
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    tags: string[];
+}
+/** Mutable pre-registration view of a generated resource. */
+interface OpenAPIResourceComponent {
+    kind: 'resource';
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    tags: string[];
+}
+/** Mutable pre-registration view of a generated resource template. */
+interface OpenAPIResourceTemplateComponent {
+    kind: 'resourceTemplate';
+    uriTemplate: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    parameters: JsonSchema;
+    tags: string[];
+}
+type OpenAPIComponent = OpenAPIToolComponent | OpenAPIResourceComponent | OpenAPIResourceTemplateComponent;
+/**
+ * Component customization hook, called with each generated component before
+ * registration. Mutate the component in place (rename, edit description,
+ * adjust tags or schemas). Exceptions are swallowed with a warning.
+ */
+type ComponentFn = (route: HTTPRoute, component: OpenAPIComponent) => void;
+
+/**
+ * HTTP execution for generated components.
+ *
+ * Port of Python FastMCP's `OpenAPITool.run` / `OpenAPIResource.read`
+ * (`fastmcp.server.providers.openapi.components`): bare fetch with a timeout,
+ * Python-compatible error messages (they surface as tool errors, so clients
+ * may match on them), JSON responses as structuredContent with the
+ * `x-fastmcp-wrap-result` unwrap applied, non-JSON as text.
+ */
+
+/** HTTP client configuration for a generated OpenAPI server. */
+interface OpenAPIClientOptions {
+    /**
+     * Base URL for requests. Defaults to the spec's first `servers` entry
+     * (with server variables filled from their defaults). Required when the
+     * spec has no absolute server URL.
+     */
+    baseUrl?: string;
+    /** Default headers sent on every request. Request-specific headers win. */
+    headers?: Record<string, string>;
+    /** Async header provider, resolved per request (e.g. a token refresher). */
+    auth?: {
+        getHeaders(): Promise<Record<string, string>>;
+    };
+    /** Custom fetch implementation. Defaults to the global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout in milliseconds. Default 30 000. */
+    timeoutMs?: number;
+}
+
+/**
+ * createOpenAPIServer: build a FastMCP server from an OpenAPI 3.x spec.
+ *
+ * TypeScript port of Python FastMCP's `FastMCP.from_openapi` /
+ * `OpenAPIProvider`. Components are generated eagerly: parse the spec into
+ * routes, map each route to a component type, name it, derive its schemas,
+ * and register it on a plain FastMCP with a forwarding handler that calls the
+ * described HTTP API. Generated names and schemas match the Python
+ * implementation byte for byte; the snapshots under `tests/fixtures/openapi/`
+ * pin that contract.
+ */
+
+interface OpenAPIServerOptions {
+    /** The OpenAPI 3.0/3.1 spec: a parsed object, or YAML/JSON text. */
+    spec: Record<string, unknown> | string;
+    /** Server name. Default 'OpenAPI Server'. */
+    name?: string;
+    /** Server version. Defaults to FastMCP's own default. */
+    version?: string;
+    /** HTTP client configuration (base URL, headers, auth, fetch, timeout). */
+    client?: OpenAPIClientOptions;
+    /** Route maps checked in order before the default (everything → tool). */
+    routeMaps?: RouteMap[];
+    /** Route-type hook, run after the route maps on every route. */
+    routeMapFn?: RouteMapFn;
+    /** Component customization hook, called before each registration. */
+    componentFn?: ComponentFn;
+    /** Overrides mapping operationId → component name. */
+    names?: Record<string, string>;
+    /** Tags added to every generated component. */
+    tags?: string[];
+    /**
+     * When true (default), tools advertise the output schema extracted from
+     * the spec. When false, a permissive schema is advertised instead (the
+     * wrap-result marker is preserved).
+     */
+    validateOutput?: boolean;
+    /** Remaining FastMCP options (auth, middleware, page sizes, ...). */
+    serverOptions?: Omit<FastMCPOptions, 'name' | 'version'>;
+}
+/**
+ * Create a FastMCP server from an OpenAPI 3.0/3.1 specification. Every
+ * operation becomes an MCP component (tool by default; see `routeMaps`)
+ * whose handler calls the described HTTP endpoint.
+ */
+declare function createOpenAPIServer(options: OpenAPIServerOptions): FastMCP;
+
 interface Component {
     type: string;
     props?: Record<string, unknown>;
@@ -1445,4 +1753,4 @@ declare class FormInput {
     constructor(options: FormInputOptions);
 }
 
-export { type AccessToken, Approval, Area, type AuthCheck, AuthorizationError, type BackendToolConfig, Badge, Bar, type BrowserPermissions, Button, type CacheKeyFn, CachingMiddleware, CancellationMiddleware, type CatalogEntry, Choice, Column, type CompleteCallback, type CompletionContext, type CompletionResult, type Component, type CspPolicy, type ElicitationResult, type ElicitationSchema, type EntrypointConfig, ErrorNormalizationMiddleware, FastMCP, FastMCPApp, type FastMCPAppOptions, type FastMCPOptions, File, type FileHandle, type FileStorageAdapter, FileUpload, type FileUploadOptions, FilterTransform, ForEach, FormInput, type FormInputOptions, GenerativeUI, Grid, If, type IfNode, Image, Input, Line, type LogLevel, LoggingMiddleware, type McpContext, type Middleware, type MiddlewareContext, NamespaceTransform, type Next, type OAuthConfig, type OAuthProviderOptions, type OAuthProxyOptions, Pie, type PromptArgument, type PromptConfig, type PromptContent, type PromptMessage, PromptResult, type PromptView, PromptsAsTools, type ProxyTransport, RateLimitingMiddleware, type ResourceAnnotations, type ResourceConfig, ResourceResult, type ResourceUiMeta, type ResourceView, ResourcesAsTools, type Root, Row, type RunOptions, Rx, type SamplingMessage, type SamplingParams, type SamplingResult, Select, type ServerAddress, SizeLimitingMiddleware, type SynthesizedTool, Table, Text, type TokenVerifier, type ToolConfig, ToolResult, type ToolView, type Transform, type UiToolMeta, VersionFilter, type Visibility, actionRef, createProxy, debugTokenVerifier, introspectionVerifier, jwtVerifier, multiAuth, oauthProvider, oauthProxy, redescribeTool, renameTool, requireScopes, staticTokenVerifier };
+export { type AccessToken, Approval, Area, type AuthCheck, AuthorizationError, type BackendToolConfig, Badge, Bar, type BrowserPermissions, Button, type CacheKeyFn, CachingMiddleware, CancellationMiddleware, type CatalogEntry, Choice, Column, type CompleteCallback, type CompletionContext, type CompletionResult, type Component, type ComponentFn, type CspPolicy, type ElicitationResult, type ElicitationSchema, type EntrypointConfig, ErrorNormalizationMiddleware, FastMCP, FastMCPApp, type FastMCPAppOptions, type FastMCPOptions, File, type FileHandle, type FileStorageAdapter, FileUpload, type FileUploadOptions, FilterTransform, ForEach, FormInput, type FormInputOptions, GenerativeUI, Grid, type HTTPRoute, type HttpMethod, type HttpRequestContext, If, type IfNode, Image, Input, Line, type LogLevel, LoggingMiddleware, type MCPType, type McpContext, type Middleware, type MiddlewareContext, NamespaceTransform, type Next, type OAuthConfig, type OAuthProviderOptions, type OAuthProxyOptions, type OpenAPIClientOptions, type OpenAPIComponent, type OpenAPIResourceComponent, type OpenAPIResourceTemplateComponent, type OpenAPIServerOptions, type OpenAPIToolComponent, type ParameterInfo, Pie, type PromptArgument, type PromptConfig, type PromptContent, type PromptMessage, PromptResult, type PromptView, PromptsAsTools, type ProxyTransport, RateLimitingMiddleware, type RequestBodyInfo, type RequestVerifier, type ResourceAnnotations, type ResourceConfig, ResourceResult, type ResourceUiMeta, type ResourceView, ResourcesAsTools, type ResponseInfo, type Root, type RouteMap, type RouteMapFn, Row, type RunOptions, Rx, type SamplingMessage, type SamplingParams, type SamplingResult, Select, type ServerAddress, SizeLimitingMiddleware, type SynthesizedTool, Table, Text, type TokenVerifier, type ToolConfig, ToolResult, type ToolView, type Transform, type UiToolMeta, VersionFilter, type Visibility, actionRef, createOpenAPIServer, createProxy, debugTokenVerifier, forwardableHeaders, introspectionVerifier, jwtVerifier, multiAuth, oauthProvider, oauthProxy, redescribeTool, renameTool, requireScopes, staticTokenVerifier };