@prefecthq/fastmcp-ts 0.0.2-alpha.0

package/dist/server.d.ts

@@ -0,0 +1,1023 @@
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport';
+import { OAuthServerProvider, AuthorizationParams } from '@modelcontextprotocol/sdk/server/auth/provider';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { Readable, Writable } from 'node:stream';
+import { Server } from '@modelcontextprotocol/sdk/server';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types';
+import { Response } from 'express';
+import { OAuthClientInformationFull } from '@modelcontextprotocol/sdk/shared/auth';
+import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types';
+
+interface AccessToken {
+    /** The raw bearer token string. */
+    token: string;
+    /** The subject/client identifier from the token. */
+    clientId?: string;
+    /** Scopes granted to the token. */
+    scopes: string[];
+    /** Unix timestamp (seconds) when the token expires. */
+    expiresAt?: number;
+    /** All claims from the token payload. */
+    claims: Record<string, unknown>;
+}
+interface TokenVerifier {
+    verify(token: string): Promise<AccessToken>;
+}
+/**
+ * Thrown by authorization checks to produce a 403 response.
+ * Any other error thrown during verification produces a 401.
+ */
+declare class AuthorizationError extends Error {
+    constructor(message: string);
+}
+
+type AuthCheck = (token: AccessToken) => void | Promise<void>;
+declare function requireScopes(...scopes: string[]): AuthCheck;
+
+interface PromptArgument {
+    name: string;
+    description?: string;
+    /** When true, the client must supply this argument. Defaults to false. */
+    required?: boolean;
+}
+interface PromptConfig {
+    /** Unique prompt identifier. Inferred from the handler function name when omitted. */
+    name?: string;
+    /** Human-readable display name shown in UIs. */
+    title?: string;
+    /** Description shown to clients and LLMs. Inferred from name when omitted. */
+    description?: string;
+    /** Declared arguments. Advertised to clients in prompts/list. */
+    arguments?: PromptArgument[];
+    /** When true the prompt is hidden from list responses and cannot be invoked. */
+    disabled?: boolean;
+    /** Execution timeout in milliseconds. No timeout by default. */
+    timeout?: number;
+    /** Arbitrary tags for server-side filtering and transforms. */
+    tags?: string[];
+    auth?: AuthCheck;
+}
+type TextContent = {
+    type: 'text';
+    text: string;
+};
+type ImageContent = {
+    type: 'image';
+    data: string;
+    mimeType: string;
+};
+type AudioContent = {
+    type: 'audio';
+    data: string;
+    mimeType: string;
+};
+type ResourceLinkContent = {
+    type: 'resource_link';
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+};
+type EmbeddedResource = {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+    } & ({
+        text: string;
+    } | {
+        blob: string;
+    });
+};
+type PromptContent = TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLinkContent;
+interface PromptMessage {
+    role: 'user' | 'assistant';
+    content: PromptContent;
+}
+/**
+ * Escape hatch for full control over the prompt response.
+ * Return this from a prompt handler to set an explicit description and/or
+ * supply a custom multi-turn message sequence.
+ */
+declare class PromptResult {
+    readonly messages: PromptMessage[];
+    readonly description?: string | undefined;
+    constructor(messages: PromptMessage[], description?: string | undefined);
+}
+
+type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+interface SamplingMessage {
+    role: 'user' | 'assistant';
+    content: {
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    };
+}
+interface SamplingParams {
+    messages: SamplingMessage[];
+    systemPrompt?: string;
+    /** Maximum tokens to generate. Defaults to 1024. */
+    maxTokens?: number;
+    temperature?: number;
+    stopSequences?: string[];
+    modelPreferences?: {
+        hints?: Array<{
+            name?: string;
+        }>;
+        costPriority?: number;
+        speedPriority?: number;
+        intelligencePriority?: number;
+    };
+}
+interface SamplingResult {
+    role: 'assistant';
+    content: {
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    };
+    model: string;
+    stopReason?: string;
+}
+/**
+ * Flat JSON Schema object describing fields to collect from the user.
+ * Only primitive property types (string, number, boolean) are allowed per the MCP spec.
+ */
+interface ElicitationSchema {
+    type: 'object';
+    properties: Record<string, {
+        type: 'string' | 'number' | 'boolean';
+        title?: string;
+        description?: string;
+    }>;
+    required?: string[];
+}
+interface ElicitationResult {
+    /** How the user responded to the elicitation. */
+    action: 'accept' | 'decline' | 'cancel';
+    /** Submitted form values. Present only when action is 'accept'. */
+    content?: Record<string, string | number | boolean>;
+}
+interface Root {
+    uri: string;
+    name?: string;
+}
+interface McpContext {
+    /** Auth token for the current request, if any. */
+    auth: AccessToken | undefined;
+    /** The MCP request ID for the current call. */
+    requestId: string | 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>;
+    info(message: string, loggerName?: string): Promise<void>;
+    notice(message: string, loggerName?: string): Promise<void>;
+    warning(message: string, loggerName?: string): Promise<void>;
+    error(message: string, loggerName?: string): Promise<void>;
+    critical(message: string, loggerName?: string): Promise<void>;
+    alert(message: string, loggerName?: string): Promise<void>;
+    emergency(message: string, loggerName?: string): Promise<void>;
+    /**
+     * Send a progress notification to the client.
+     * No-op if the request did not include a `progressToken` in its `_meta`.
+     */
+    reportProgress(progress: number, total?: number, message?: string): Promise<void>;
+    /**
+     * Ask the client to perform an LLM inference call and return the result.
+     * Throws if the client has not advertised the `sampling` capability.
+     */
+    sample(params: SamplingParams): Promise<SamplingResult>;
+    /**
+     * Ask the client to collect input from the user via a form dialog.
+     * Throws if the client has not advertised the `elicitation` capability.
+     */
+    elicit(message: string, schema: ElicitationSchema): Promise<ElicitationResult>;
+    /**
+     * Request the list of filesystem roots the client has declared.
+     * Throws if the client has not advertised the `roots` capability.
+     */
+    listRoots(): Promise<Root[]>;
+    /** Retrieve a value from session-scoped state. Returns undefined if not set. */
+    getState(key: string): unknown;
+    /** Store a value in session-scoped state. Persists for the lifetime of the session. */
+    setState(key: string, value: unknown): void;
+    /** Remove a value from session-scoped state. */
+    deleteState(key: string): void;
+    /**
+     * Resolve a logical tool name to its current external name, accounting for
+     * any namespace prefix applied when the owning FastMCPApp was mounted.
+     * Returns the name unchanged when called outside a mounted context.
+     */
+    resolveToolName(name: string): string;
+    /**
+     * Register a callback that runs when the current session closes.
+     * Useful for releasing per-session resources (e.g. uploaded files).
+     * No-op if called outside an active HTTP session.
+     */
+    onClose(callback: () => void): void;
+}
+
+interface MiddlewareContext<T = unknown> {
+    readonly method: string;
+    readonly request: T;
+    readonly mcpContext: McpContext;
+}
+type Next<R = unknown> = () => Promise<R>;
+interface Middleware {
+    /** Called once per Server instance. Use to register notification handlers or other server-level setup. */
+    setup?(server: Server): void;
+    onRequest?<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+    onCallTool?<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+    onListTools?<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+    onReadResource?<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+    onListResources?<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+    onListResourceTemplates?<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+    onGetPrompt?<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+    onListPrompts?<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+}
+/** Logs every request with method, outcome, and elapsed time. */
+declare class LoggingMiddleware implements Middleware {
+    private readonly emit;
+    constructor(emit?: (msg: string) => void);
+    onRequest<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+}
+/**
+ * Custom cache key function. Receives the full middleware context so callers can
+ * incorporate auth identity or any other dimension into the key.
+ *
+ * **Required when using per-component auth checks.** The default key is
+ * `"method:JSON(params)"`, which contains no auth information. If auth-filtered
+ * list results (tools, resources, prompts) are cached with the default key, one
+ * session's filtered results can be served to a session with different permissions.
+ * Pass a `keyFn` that includes the caller identity, e.g.:
+ *
+ * ```ts
+ * new CachingMiddleware(60_000, (ctx) =>
+ *   `${ctx.method}:${ctx.mcpContext.auth?.clientId ?? ''}:${JSON.stringify(ctx.request)}`
+ * )
+ * ```
+ */
+type CacheKeyFn = (ctx: MiddlewareContext) => string;
+/** TTL-based response cache keyed on method + serialised request params by default.
+ *  Pass a custom `keyFn` when using per-component auth so cached results are
+ *  partitioned by caller identity. */
+declare class CachingMiddleware implements Middleware {
+    readonly ttl: number;
+    private readonly _keyFn?;
+    private readonly _cache;
+    constructor(ttl?: number, _keyFn?: CacheKeyFn | undefined);
+    onRequest<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+}
+/** Fixed-window counter rate limiter. Resets to full capacity after every windowMs interval. */
+declare class RateLimitingMiddleware implements Middleware {
+    private readonly limit;
+    private readonly windowMs;
+    private _tokens;
+    private _lastRefill;
+    constructor(limit: number, windowMs?: number);
+    onRequest<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+}
+/** Rejects responses whose JSON serialisation exceeds maxBytes. */
+declare class SizeLimitingMiddleware implements Middleware {
+    private readonly maxBytes;
+    constructor(maxBytes: number);
+    onRequest<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+}
+/**
+ * Normalises errors thrown by handlers to proper MCP shapes:
+ * - tools/call plain errors → { isError: true, content: [...] }  (per MCP spec)
+ * - tools/call McpError     → re-thrown as a protocol-level error
+ * - all other methods       → McpError(InternalError, message)
+ *
+ * Re-throwing McpError from onCallTool ensures that middleware-level errors
+ * (e.g. from RateLimitingMiddleware or SizeLimitingMiddleware stacked before
+ * this middleware) always propagate as protocol errors and are never silently
+ * converted to isError:true tool responses.
+ */
+declare class ErrorNormalizationMiddleware implements Middleware {
+    onCallTool<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+    onRequest<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+}
+/**
+ * Intercepts `notifications/cancelled` from the client and aborts the matching
+ * in-flight handler via Promise.race + AbortController.
+ */
+declare class CancellationMiddleware implements Middleware {
+    private readonly _inFlight;
+    setup(server: Server): void;
+    onRequest<T, R>(ctx: MiddlewareContext<T>, next: Next<R>): Promise<R>;
+}
+
+interface ToolView {
+    readonly name: string;
+    /** Human-readable display name shown in UIs. Takes precedence over `name` for display purposes. */
+    readonly title?: string;
+    readonly description: string;
+    readonly tags: readonly string[];
+}
+interface ResourceView {
+    readonly uri: string;
+    readonly name: string;
+    readonly tags: readonly string[];
+    readonly mimeType?: string;
+    readonly title?: string;
+}
+interface PromptView {
+    readonly name: string;
+    readonly description: string;
+    readonly tags: readonly string[];
+}
+interface SynthesizedTool {
+    readonly name: string;
+    /** Human-readable display name shown in UIs. Takes precedence over `name` for display purposes. */
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema?: Record<string, unknown>;
+    readonly auth?: AuthCheck;
+    readonly timeout?: number;
+    readonly handler: (args: any) => unknown;
+}
+interface Transform {
+    /**
+     * Transform a tool view before it appears in list responses.
+     * Return a modified view to rename/redescribe; return null to hide the tool
+     * from list responses (it remains callable by its original name).
+     */
+    transformTool?(view: ToolView): ToolView | null;
+    /** Transform a static resource view. */
+    transformResource?(view: ResourceView): ResourceView | null;
+    /** Transform a URI-template resource view. */
+    transformResourceTemplate?(view: ResourceView): ResourceView | null;
+    /** Transform a prompt view. */
+    transformPrompt?(view: PromptView): PromptView | null;
+    /**
+     * Synthesize additional tools derived from the current resource and prompt lists.
+     * Called at request time so the snapshot is always fresh.
+     */
+    synthesizeTools?(resources: ResourceView[], prompts: PromptView[]): SynthesizedTool[];
+}
+/** Rename a single tool. The original name still resolves at call time. */
+declare function renameTool(originalName: string, newName: string): Transform;
+/** Rewrite the description of a single tool. */
+declare function redescribeTool(toolName: string, description: string): Transform;
+/**
+ * Hide components whose predicate returns false.
+ * Hidden items are removed from list responses but remain callable by original name.
+ */
+declare class FilterTransform implements Transform {
+    private readonly predicates;
+    constructor(predicates: {
+        tools?: (v: ToolView) => boolean;
+        resources?: (v: ResourceView) => boolean;
+        /** When omitted, falls back to the `resources` predicate. */
+        resourceTemplates?: (v: ResourceView) => boolean;
+        prompts?: (v: PromptView) => boolean;
+    });
+    transformTool(v: ToolView): ToolView | null;
+    transformResource(v: ResourceView): ResourceView | null;
+    transformResourceTemplate(v: ResourceView): ResourceView | null;
+    transformPrompt(v: PromptView): PromptView | null;
+}
+/** Prefix all tool, prompt, and resource names with a string. URIs are left unchanged. */
+declare class NamespaceTransform implements Transform {
+    private readonly prefix;
+    constructor(prefix: string);
+    transformTool(v: ToolView): ToolView;
+    transformResource(v: ResourceView): ResourceView;
+    transformResourceTemplate(v: ResourceView): ResourceView;
+    transformPrompt(v: PromptView): PromptView;
+}
+/** Expose registered resources as a `list_resources` tool. */
+declare class ResourcesAsTools implements Transform {
+    synthesizeTools(resources: ResourceView[]): SynthesizedTool[];
+}
+/** Expose registered prompts as a `list_prompts` tool. */
+declare class PromptsAsTools implements Transform {
+    synthesizeTools(_resources: ResourceView[], prompts: PromptView[]): SynthesizedTool[];
+}
+/**
+ * Expose only components whose tags include the specified version string.
+ * Components with no tags are always excluded.
+ */
+declare class VersionFilter implements Transform {
+    private readonly version;
+    constructor(version: string);
+    private _matches;
+    transformTool(v: ToolView): ToolView | null;
+    transformResource(v: ResourceView): ResourceView | null;
+    transformResourceTemplate(v: ResourceView): ResourceView | null;
+    transformPrompt(v: PromptView): PromptView | null;
+}
+
+type Visibility = 'model' | 'app';
+interface CspPolicy {
+    connectDomains?: string[];
+    /** Covers img-src, script-src, style-src, font-src, media-src. */
+    resourceDomains?: string[];
+    frameDomains?: string[];
+    baseUriDomains?: string[];
+}
+interface UiToolMeta {
+    /** Explicit resource URI. Auto-derived from tool name when omitted. */
+    resourceUri?: string;
+    /** Who can see this tool. Defaults to ['model']. */
+    visibility?: Visibility[];
+}
+interface BrowserPermissions {
+    camera?: Record<string, never>;
+    microphone?: Record<string, never>;
+    geolocation?: Record<string, never>;
+    clipboardWrite?: Record<string, never>;
+}
+interface ResourceUiMeta {
+    csp?: CspPolicy;
+    permissions?: BrowserPermissions;
+    domain?: string;
+    prefersBorder?: boolean;
+}
+
+interface ResourceAnnotations {
+    /** Intended audience(s) — 'user', 'assistant', or both. */
+    audience?: Array<'user' | 'assistant'>;
+    /** Importance hint from 0 (least) to 1 (most). */
+    priority?: number;
+    /** ISO 8601 timestamp of last modification. */
+    lastModified?: string;
+}
+interface ResourceConfig {
+    /** Static URI (e.g. `file://readme`) or RFC 6570 template (e.g. `user://{id}`). */
+    uri: string;
+    /** Programmatic identifier. Defaults to the uri. */
+    name?: string;
+    /** Human-readable display name shown in UIs. Defaults to `name`. */
+    title?: string;
+    description?: string;
+    /** MIME type of the resource content. Defaults to 'text/plain' for strings, 'application/octet-stream' for binary. */
+    mimeType?: string;
+    /**
+     * Size of the resource content in bytes, if known.
+     * Only meaningful for static resources; ignored for URI templates.
+     */
+    size?: number;
+    /** Behavioral hints for clients. */
+    annotations?: ResourceAnnotations;
+    /** Execution timeout in milliseconds. No timeout by default. */
+    timeout?: number;
+    /** When true the resource is hidden from list responses and cannot be read. */
+    disabled?: boolean;
+    /** Arbitrary tags for server-side filtering. */
+    tags?: string[];
+    auth?: AuthCheck;
+    /** Apps extension metadata. Included in _meta.ui in resources/list for UI-capable clients. */
+    ui?: ResourceUiMeta;
+}
+/**
+ * Escape hatch for full control over resource response content.
+ * Return this from a resource handler to specify content directly.
+ */
+declare class ResourceResult {
+    readonly contents: Array<{
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    }>;
+    constructor(contents: Array<{
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    }>);
+}
+
+interface OAuthConfig {
+    /** OAuth server provider implementing the authorization and token flow. */
+    provider: OAuthServerProvider;
+    /**
+     * Issuer URL for the OAuth server (used in metadata endpoints).
+     * Defaults to the HTTP server's bound address when not specified.
+     */
+    issuerUrl?: URL;
+    /** Scopes supported by this server, advertised in OAuth metadata. */
+    scopes?: string[];
+}
+interface FastMCPOptions {
+    name: string;
+    version?: string;
+    /** Simple bearer-token verifier for non-OAuth auth scenarios. */
+    auth?: TokenVerifier;
+    /** Full OAuth 2.1 server with Dynamic Client Registration support. */
+    oauth?: OAuthConfig;
+    /** Maximum number of tools returned per listTools page. Default: 50. */
+    toolsPageSize?: number;
+    /** Maximum number of resources (or templates) returned per page. Default: 50. */
+    resourcesPageSize?: number;
+    /** Maximum number of prompts returned per prompts/list page. Default: 50. */
+    promptsPageSize?: number;
+    /** Middleware applied to every request in registration order. */
+    middleware?: Middleware[];
+    /** Transforms applied to component list responses in registration order. */
+    transforms?: Transform[];
+}
+interface RunOptions {
+    transport?: 'stdio' | 'http';
+    port?: number;
+    host?: string;
+    path?: string;
+    /** Custom stdin stream for the stdio transport. Defaults to process.stdin. */
+    stdin?: Readable;
+    /** Custom stdout stream for the stdio transport. Defaults to process.stdout. */
+    stdout?: Writable;
+}
+interface ServerAddress {
+    host: string;
+    port: number;
+    path: string;
+}
+interface ToolConfig {
+    name: string;
+    /** Human-readable display name shown in UIs. Takes precedence over `name` for display purposes. */
+    title?: string;
+    description: string;
+    /** Standard Schema validator for the tool's input arguments. Used for runtime validation. */
+    input?: StandardSchemaV1;
+    /**
+     * Explicit JSON Schema advertised to clients as `inputSchema`. Overrides auto-generation from
+     * `input`. Use when you need JSON Schema features beyond what your validator auto-generates
+     * (e.g. `examples`, `$comment`, per-property descriptions, or custom annotations).
+     */
+    inputSchema?: Record<string, unknown>;
+    /** Standard Schema validator for the tool's return value. Validated before result conversion. */
+    output?: StandardSchemaV1;
+    /**
+     * Explicit JSON Schema advertised to clients as `outputSchema`. Overrides auto-generation from
+     * `output`. Use when you need JSON Schema features beyond what your validator auto-generates.
+     */
+    outputSchema?: Record<string, unknown>;
+    /** Execution timeout in milliseconds. No timeout by default. */
+    timeout?: number;
+    /** When true the tool is hidden from listTools and cannot be invoked via tools/call. */
+    disabled?: boolean;
+    /** Arbitrary tags for server-side filtering. */
+    tags?: string[];
+    auth?: AuthCheck;
+    /** Apps extension — links this tool to a UI resource and controls visibility. */
+    ui?: UiToolMeta;
+}
+declare class FastMCP {
+    readonly name: string;
+    readonly version: string;
+    private _auth;
+    private _oauth;
+    private _toolsPageSize;
+    private _resourcesPageSize;
+    private _tools;
+    private _staticResources;
+    private _templateResources;
+    private _prompts;
+    private _promptsPageSize;
+    private _middleware;
+    private _transforms;
+    private _primaryState;
+    private _httpServer;
+    private _address;
+    private _sessions;
+    private _primaryServer;
+    private _toolRegisteredCallbacks;
+    private _resourceRegisteredCallbacks;
+    private _promptRegisteredCallbacks;
+    private _proxyCloseCallbacks;
+    private _mountedChildren;
+    constructor(options: FastMCPOptions);
+    private _hasUiComponents;
+    /** Create a new Server instance with all request handlers wired up. */
+    private _makeServer;
+    private _resolveToken;
+    private _setupHandlers;
+    private _notifyToolListChanged;
+    private _notifyResourceListChanged;
+    private _notifyPromptListChanged;
+    tool<S extends StandardSchemaV1>(config: Omit<ToolConfig, 'input'> & {
+        input: S;
+    }, handler: (args: StandardSchemaV1.InferOutput<S>) => unknown): void;
+    tool(config: ToolConfig, handler: (args: Record<string, unknown>) => unknown): void;
+    prompt(config: PromptConfig, handler: (args?: Record<string, string>) => unknown): void;
+    resource(config: ResourceConfig, handler: (params?: Record<string, string>) => unknown): void;
+    _removeTool(name: string): boolean;
+    _removeResource(uri: string): boolean;
+    _removePrompt(name: string): boolean;
+    /** Add a transform to the pipeline. Applied to list responses in registration order. */
+    transform(t: Transform): this;
+    /**
+     * Dispatch a tool call through this server's middleware chain using an inherited context.
+     * Used by parent servers to honour child-level middleware when routing mounted tool calls.
+     */
+    _dispatchTool(name: string, rawArgs: unknown, ctx: McpContext): Promise<{
+        [x: string]: unknown;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                text: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            } | {
+                uri: string;
+                blob: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        structuredContent?: {
+            [x: string]: unknown;
+        } | undefined;
+        isError?: boolean | undefined;
+    }>;
+    /**
+     * Run a resource read through this server's middleware chain using an inherited context.
+     * Returns the raw handler result so the parent can apply convertResourceResult with the
+     * actual requested URI (important for template resources).
+     */
+    _dispatchResource(uri: string, params: Record<string, string> | undefined, ctx: McpContext): Promise<unknown>;
+    /**
+     * Dispatch a prompt render through this server's middleware chain using an inherited context.
+     */
+    _dispatchPrompt(name: string, args: Record<string, string>, ctx: McpContext): Promise<{
+        description?: string;
+        messages: PromptMessage[];
+    }>;
+    private _mirrorTool;
+    private _mirrorResource;
+    private _mirrorPrompt;
+    /** Mount a child server onto this server. All tools, resources, and prompts from the child become accessible via this server. Pass a prefix to namespace names and prevent collisions. */
+    mount(child: FastMCP, prefix?: string): this;
+    /** Register a callback invoked when this server is closed — used by proxy connections. */
+    _addCloseCallback(cb: () => Promise<void>): void;
+    /**
+     * Register a provider (FastMCPApp or FastMCP) on this server.
+     * All tools, resources, and prompts from the provider are mounted without a prefix.
+     * For FastMCPApp, pass provider.server; for FastMCP, pass directly.
+     */
+    addProvider(provider: FastMCP | {
+        server: FastMCP;
+    }): this;
+    private _applyTransformsToTools;
+    private _applyTransformsToResources;
+    private _applyTransformsToResourceTemplates;
+    private _applyTransformsToPrompts;
+    private _buildSynthesizedTools;
+    private _getVisibleViews;
+    /**
+     * Add a middleware to the pipeline.
+     *
+     * Can be called at any point before the first request arrives. `setup()` is
+     * called immediately on the primary server so that notification handlers and
+     * other server-level side-effects are active before `connect()` / `run()` is
+     * called. HTTP sessions created after `use()` will also have `setup()` called
+     * via `_makeServer()`.
+     */
+    use(mw: Middleware): this;
+    getContext(): McpContext;
+    /** The bound address after run() resolves for the http transport. Null for stdio or before run(). */
+    get address(): ServerAddress | null;
+    connect(transport: Transport): Promise<void>;
+    run(options?: RunOptions): Promise<void>;
+    private _runHttpOAuth;
+    private _runHttpSimple;
+    close(): Promise<void>;
+}
+
+declare class Image {
+    readonly buffer: Buffer | Uint8Array;
+    readonly mimeType: string;
+    constructor(buffer: Buffer | Uint8Array, mimeType: string);
+}
+declare class File {
+    readonly buffer: Buffer | Uint8Array;
+    readonly name: string;
+    readonly mimeType: string;
+    constructor(buffer: Buffer | Uint8Array, name: string, mimeType: string);
+}
+declare class ToolResult {
+    readonly result: CallToolResult;
+    constructor(result: CallToolResult);
+}
+
+declare function multiAuth(...verifiers: TokenVerifier[]): TokenVerifier;
+
+interface JwtVerifierOptions {
+    jwksUri: string;
+    issuer?: string;
+    audience?: string | string[];
+    /** Clock skew tolerance in seconds. Default: 0. */
+    leeway?: number;
+}
+declare function jwtVerifier(options: JwtVerifierOptions): TokenVerifier;
+
+interface IntrospectionVerifierOptions {
+    endpoint: string;
+    credentials: {
+        clientId: string;
+        clientSecret: string;
+    };
+    /** Cache TTL in seconds. Omit or set to 0 to disable caching. */
+    cacheTtl?: number;
+}
+declare function introspectionVerifier(options: IntrospectionVerifierOptions): TokenVerifier;
+
+declare function staticTokenVerifier(map: Record<string, Partial<Omit<AccessToken, 'token'>>>): TokenVerifier;
+declare function debugTokenVerifier(): TokenVerifier;
+
+interface OAuthProviderOptions {
+    /**
+     * Called during the authorization step. Implementations must eventually redirect
+     * to `params.redirectUri` with a `code` query parameter (and `state` if present).
+     *
+     * If omitted, all authorization requests are auto-approved immediately — suitable
+     * for testing and development only.
+     */
+    onAuthorize?: (client: OAuthClientInformationFull, params: AuthorizationParams, res: Response) => Promise<void>;
+    /** Scopes supported by this server, advertised in OAuth metadata. */
+    scopes?: string[];
+    /** Access token lifetime in seconds. Default: 3600. */
+    tokenTtl?: number;
+}
+/**
+ * Creates an in-memory OAuth 2.1 server provider with Dynamic Client Registration support.
+ *
+ * Suitable for development, testing, and simple deployments where persistence is not required.
+ * All state (clients, codes, tokens) is held in memory and lost on restart.
+ */
+declare function oauthProvider(options?: OAuthProviderOptions): OAuthServerProvider;
+
+interface OAuthProxyOptions {
+    /** Pre-registered credentials this proxy uses when talking to the upstream server. */
+    upstreamCredentials: {
+        clientId: string;
+        clientSecret?: string;
+    };
+    /** Upstream OAuth server endpoint URLs. */
+    endpoints: {
+        authorizationUrl: string;
+        tokenUrl: string;
+        revocationUrl?: string;
+    };
+    /**
+     * Verifies an access token issued by the upstream and returns information about it.
+     * Called for every MCP request to validate the bearer token.
+     */
+    verifyAccessToken: (token: string) => Promise<AuthInfo>;
+}
+/**
+ * Creates an OAuth provider that proxies to an existing upstream OAuth server using
+ * pre-registered credentials.
+ *
+ * MCP clients interact with this proxy using Dynamic Client Registration. The proxy
+ * presents a DCR-compliant interface while internally using its own fixed credentials
+ * (`upstreamCredentials`) when communicating with the upstream authorization server.
+ */
+declare function oauthProxy(options: OAuthProxyOptions): OAuthServerProvider;
+
+type StdioTransport = {
+    type: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** How long (ms) before the proxy re-fetches component lists. Default 30 000. Set 0 for notifications-only. */
+    cacheTtl?: number;
+};
+type HttpTransport = {
+    type: 'http';
+    url: string;
+    requestInit?: RequestInit;
+    /** How long (ms) before the proxy re-fetches component lists. Default 30 000. Set 0 for notifications-only. */
+    cacheTtl?: number;
+};
+type ProxyTransport = StdioTransport | HttpTransport;
+/**
+ * Create a FastMCP instance that proxies all requests to a remote MCP server.
+ * The returned instance can be mounted onto a parent server via `parent.mount(proxy)`.
+ *
+ * Component lists (tools, resources, prompts) are kept in sync via:
+ *  - Change notifications from the backend (immediate resync)
+ *  - TTL-based lazy resync on each list request (configurable via `cacheTtl`, default 30 s)
+ */
+declare function createProxy(config: ProxyTransport, name?: string): Promise<FastMCP>;
+
+interface Component {
+    type: string;
+    props?: Record<string, unknown>;
+    children?: Component[];
+}
+interface IfNode extends Component {
+    type: 'if';
+    branches: Array<{
+        condition: string;
+        node: Component;
+    }>;
+    fallback?: Component;
+    elif(condition: string, node: Component): IfNode;
+    else(node: Component): Component;
+}
+interface CatalogEntry {
+    type: string;
+    description: string;
+}
+declare function Column(props?: Record<string, unknown>, children?: Component[]): Component;
+declare function Row(props?: Record<string, unknown>, children?: Component[]): Component;
+declare function Grid(props?: Record<string, unknown>, children?: Component[]): Component;
+declare function Text(content: string | Component, extraProps?: Record<string, unknown>): Component;
+declare function Badge(text: string, extraProps?: Record<string, unknown>): Component;
+declare function Table(props: {
+    columns: string[];
+    rows: string[][];
+    [key: string]: unknown;
+}): Component;
+declare function Bar(props: Record<string, unknown>): Component;
+declare function Line(props: Record<string, unknown>): Component;
+declare function Area(props: Record<string, unknown>): Component;
+declare function Pie(props: Record<string, unknown>): Component;
+declare function Input(props: Record<string, unknown>): Component;
+declare function Select(props: Record<string, unknown>): Component;
+declare function Button(props: Record<string, unknown>): Component;
+declare function If(condition: string, then: Component, fallback?: Component): IfNode;
+declare function ForEach(items: string, template: Component): Component;
+declare function Rx(expression: string): Component;
+
+interface EntrypointConfig {
+    name: string;
+    description: string;
+    title?: string;
+}
+interface BackendToolConfig {
+    name: string;
+    description: string;
+    title?: string;
+    /** Defaults to ['app']. Pass ['model', 'app'] to also expose to the LLM. */
+    visibility?: Visibility[];
+}
+interface FastMCPAppOptions {
+    name: string;
+    version?: string;
+}
+declare class FastMCPApp {
+    readonly server: FastMCP;
+    constructor(options: FastMCPAppOptions);
+    /**
+     * Register an entry-point tool.
+     * Entry-points are visible to the LLM (visibility: ['model', 'app']) and
+     * automatically linked to a generated ui:// resource URI.
+     */
+    entrypoint(config: EntrypointConfig, handler: (args?: any) => Component): void;
+    /**
+     * Register a backend tool.
+     * Backend tools are hidden from listTools by default (visibility: ['app']).
+     */
+    backendTool(config: BackendToolConfig, handler: (args: any) => unknown): void;
+    /**
+     * Returns a reference to a tool that resolves to the correct external name
+     * (including any mount prefix) when evaluated inside a request handler.
+     * Call inside a handler function — not at definition time.
+     */
+    toolRef(name: string): string;
+}
+
+/**
+ * Resolve a logical tool name to its current external name inside a request
+ * handler, accounting for any mount prefix applied by a parent server.
+ *
+ * Use this in providers that are built on bare FastMCP (not FastMCPApp) to
+ * produce mount-prefix–aware action strings for Button components.
+ */
+declare function actionRef(name: string): string;
+
+declare class GenerativeUI {
+    readonly server: FastMCP;
+    constructor();
+}
+
+declare class Approval {
+    readonly server: FastMCP;
+    constructor();
+}
+
+declare class Choice {
+    readonly server: FastMCP;
+    constructor();
+}
+
+interface FileHandle {
+    handle: string;
+    name: string;
+    mimeType: string;
+    data: Buffer;
+}
+interface FileStorageAdapter {
+    save(handle: string, file: FileHandle): void;
+    load(handle: string): FileHandle | undefined;
+    delete(handle: string): void;
+}
+interface FileUploadOptions {
+    storage?: FileStorageAdapter;
+}
+declare class FileUpload {
+    readonly server: FastMCP;
+    private readonly _storage;
+    constructor(options?: FileUploadOptions);
+}
+
+interface FormInputOptions {
+    name: string;
+    description: string;
+    schema: StandardSchemaV1;
+}
+declare class FormInput {
+    readonly server: FastMCP;
+    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 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 };