@prefecthq/fastmcp-ts 1.5.2 → 1.7.0

package/dist/server.d.ts

@@ -6,6 +6,43 @@ import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Readable, Writable } from 'node:stream';
 import { Response as Response$1 } from 'express';
 
+/** Sink contract for FastMCPOptions.logger. `console` and Winston loggers
+ * satisfy it structurally; Pino needs a small adapter (see docs/servers/logging.mdx). */
+interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+declare const FRAMEWORK_LOG_LEVELS: readonly ["debug", "info", "warn", "error", "silent"];
+/** Framework-diagnostics level axis. Distinct from the MCP `LogLevel` union
+ * (client-facing `ctx.log` levels), which is a separate axis entirely. */
+type FrameworkLogLevel = (typeof FRAMEWORK_LOG_LEVELS)[number];
+interface BannerFields {
+    name: string;
+    version: string;
+    transport: 'stdio' | 'http';
+    url?: string;
+}
+/** Level-gated wrapper around the sink. This is what the framework holds and
+ * calls; the gate applies identically to injected and default sinks. */
+declare class ResolvedLogger {
+    private readonly sink;
+    readonly level: FrameworkLogLevel;
+    constructor(sink: Logger, level: FrameworkLogLevel);
+    private enabled;
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    /** Server-start card. Pretty DefaultSink renders a banner block;
+     * every other sink gets one plain info line. Gated as info. */
+    startupBanner(fields: BannerFields): void;
+    /** Listening confirmation. The word "listening" is load-bearing: the CLI's
+     * run command detects a successful start by sniffing stderr for it. */
+    listening(url: string): void;
+}
+
 /**
  * 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;
@@ -419,8 +456,9 @@ interface CustomRouteConfig {
     path: string;
     /**
      * HTTP methods served, compared case-insensitively. Default: `['GET']`.
-     * `OPTIONS` is rejected at registration: the global CORS preflight answers
-     * `OPTIONS` before route dispatch, so a route on it would be unreachable.
+     * `OPTIONS` is rejected at registration: it is reserved for the global
+     * CORS preflight, and never dispatches to a route even when CORS is
+     * disabled (`http.cors: false`).
      */
     methods?: string[];
 }
@@ -461,10 +499,21 @@ interface Middleware {
     onGetPrompt?(ctx: MiddlewareContext, next: Next): Promise<unknown>;
     onListPrompts?(ctx: MiddlewareContext, next: Next): Promise<unknown>;
 }
-/** Logs every request with method, outcome, and elapsed time. */
+/** Logs every request with method, outcome, and elapsed time.
+ *
+ * Output resolution, in order: an explicit `emit` (unchanged legacy behavior,
+ * `[fastmcp]`-prefixed strings); the server's framework logger when attached
+ * via FastMCPOptions.middleware or `use()`; a plain stderr write. The default
+ * was `console.log` before v-next, which corrupted the stdio protocol stream. */
 declare class LoggingMiddleware implements Middleware {
-    private readonly emit;
-    constructor(emit?: (msg: string) => void);
+    private readonly emit?;
+    private logger;
+    constructor(emit?: ((msg: string) => void) | undefined);
+    /** @internal Called by FastMCP when this middleware is attached. */
+    _bindLogger(logger: ResolvedLogger): void;
+    private emitRequest;
+    private emitResponse;
+    private emitFailure;
     onRequest(ctx: MiddlewareContext, next: Next): Promise<unknown>;
 }
 /**
@@ -791,6 +840,49 @@ declare class ResourceResult {
     }>);
 }
 
+/**
+ * Configurable CORS for the HTTP listener `run()` starts (both the plain and
+ * the OAuth serve paths). Resolution and header computation are pure
+ * functions: `resolveCors` runs once, in the FastMCP constructor, and fails
+ * loudly on malformed config (the `resolveHealth` precedent); the two header
+ * builders run per request.
+ *
+ * `fetch()` is deliberately untouched: the embedding framework owns CORS at
+ * its HTTP boundary, exactly as it owns Host/Origin validation.
+ */
+
+/** `FastMCPOptions.http.cors` object form. `true` and omitted mean the
+ * permissive defaults; `false` disables CORS handling entirely (no global
+ * preflight, no headers). */
+interface CorsOptions {
+    /**
+     * Origins allowed to call the MCP endpoint from a browser, compared
+     * against the request's `Origin` header. `'*'` (the default) allows every
+     * origin. A string or array allows exactly those `scheme://host[:port]`
+     * origins. A function receives the `Origin` value and returns whether it
+     * is allowed. A function that throws denies the origin.
+     */
+    origin?: string | string[] | ((origin: string) => boolean);
+    /** `Access-Control-Allow-Methods` value; replaces the default
+     * `GET, POST, DELETE, OPTIONS` list verbatim. */
+    methods?: string[];
+    /** Extra request headers for `Access-Control-Allow-Headers`, added to the
+     * defaults. The MCP protocol headers are never removed: silently dropping
+     * one would break browser clients in ways that only surface in
+     * production. */
+    allowedHeaders?: string[];
+    /** Extra response headers for `Access-Control-Expose-Headers`, added to
+     * the default `Mcp-Session-Id` (legacy sessionful browser clients must
+     * read it from the initialize response). */
+    exposedHeaders?: string[];
+    /** Send `Access-Control-Allow-Credentials: true`. Requires an explicit
+     * non-`'*'` `origin`: browsers reject `*` on credentialed requests, so
+     * that combination is a construction-time error. */
+    credentials?: boolean;
+    /** `Access-Control-Max-Age` for preflight caching, in seconds. */
+    maxAge?: number;
+}
+
 type CacheableResultMethod = 'tools/list' | 'prompts/list' | 'resources/list' | 'resources/templates/list' | 'resources/read' | 'server/discover';
 
 interface OAuthConfig {
@@ -826,11 +918,37 @@ interface FastMCPOptions {
      * opt-out. Withheld names are listed in `ctx.http.redactedHeaderNames`.
      * Redaction applies to `ctx.http` only; a RequestVerifier always sees the
      * full wire headers.
+     *
+     * `cors` configures the CORS posture of the HTTP listener `run()` starts
+     * (both serve paths): omitted or `true` serves the permissive defaults
+     * (`Access-Control-Allow-Origin: *`), `false` disables CORS handling
+     * entirely, and an object narrows it — see `CorsOptions`. Malformed
+     * values throw here, at construction, for every transport. `fetch()` is
+     * unaffected: the embedding framework owns CORS at its HTTP boundary.
      */
     http?: {
         redactHeaders?: string[];
         exposeHeaders?: string[];
+        cors?: boolean | CorsOptions;
     };
+    /**
+     * Sink for the framework's own diagnostic logs (lifecycle, warnings,
+     * errors). `console` and Winston loggers satisfy the shape directly; see
+     * the logging docs for a Pino adapter. Default: a built-in stderr logger
+     * (styled on a TTY, plain single-line format otherwise). Client-facing MCP
+     * logging (`ctx.log`) is a separate channel and is not affected. Do not use
+     * `logger: console` with the stdio transport: `console.info` and
+     * `console.debug` write to stdout, which carries the JSON-RPC stream on
+     * that transport.
+     */
+    logger?: Logger;
+    /**
+     * Minimum level for framework logs, applied before any logger (injected or
+     * default) is called. Precedence: this option, then the FASTMCP_LOG_LEVEL
+     * environment variable, then 'info'. 'silent' disables framework logging.
+     * Malformed values throw here, at construction, for every transport.
+     */
+    logLevel?: FrameworkLogLevel;
     /** Maximum number of tools returned per listTools page. Default: 50. */
     toolsPageSize?: number;
     /** Maximum number of resources (or templates) returned per page. Default: 50. */
@@ -1026,6 +1144,9 @@ declare class FastMCP {
     readonly name: string;
     readonly version: string;
     private _auth;
+    /** @internal Framework logger; used by same-package modules (proxy, openapi). Not public API. */
+    readonly _logger: ResolvedLogger;
+    private _cors;
     private _oauth;
     private _sensitiveHeaders;
     private _toolsPageSize;
@@ -1487,6 +1608,10 @@ type StdioTransport = {
     cwd?: string;
     /** How long (ms) before the proxy re-fetches component lists. Default 30 000. Set 0 for notifications-only. */
     cacheTtl?: number;
+    /** Framework logger for the proxy's own FastMCP instance. Defaults to the stderr sink. */
+    logger?: Logger;
+    /** Framework log level for the proxy's own FastMCP instance. */
+    logLevel?: FrameworkLogLevel;
 };
 type HttpTransport = {
     type: 'http';
@@ -1494,6 +1619,10 @@ type HttpTransport = {
     requestInit?: RequestInit;
     /** How long (ms) before the proxy re-fetches component lists. Default 30 000. Set 0 for notifications-only. */
     cacheTtl?: number;
+    /** Framework logger for the proxy's own FastMCP instance. Defaults to the stderr sink. */
+    logger?: Logger;
+    /** Framework log level for the proxy's own FastMCP instance. */
+    logLevel?: FrameworkLogLevel;
 };
 type ProxyTransport = StdioTransport | HttpTransport;
 /**
@@ -1841,4 +1970,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 ComponentFn, type CspPolicy, type CustomRouteConfig, type CustomRouteHandler, 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 HealthOptions, 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 ToolAnnotations, 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 };
+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 CorsOptions, type CspPolicy, type CustomRouteConfig, type CustomRouteHandler, 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, type FrameworkLogLevel, GenerativeUI, Grid, type HTTPRoute, type HealthOptions, type HttpMethod, type HttpRequestContext, If, type IfNode, Image, Input, Line, type LogLevel, type Logger, 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 ToolAnnotations, 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 };