@prefecthq/fastmcp-ts 0.0.2-alpha.0

package/dist/client.d.ts

@@ -0,0 +1,543 @@
+import { CreateMessageResult, CreateMessageResultWithTools, ContentBlock, CreateMessageRequestParams, LoggingLevel, ElicitRequestParams, ElicitResult, Tool, Resource, Prompt, ResourceTemplate, ResourceContents, GetPromptResult, Root, ModelPreferences, SamplingMessage, ToolChoice } from '@modelcontextprotocol/sdk/types';
+export { ContentBlock, CreateMessageRequestParams, CreateMessageResult, CreateMessageResultWithTools, ElicitRequestParams, ElicitResult, GetPromptResult, LoggingLevel, ModelPreferences, Prompt, PromptArgument, PromptMessage, Resource, ResourceContents, ResourceTemplate, Root, SamplingMessage, Tool, ToolChoice, ToolResultContent, ToolUseContent } from '@modelcontextprotocol/sdk/types';
+import { OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
+import { OAuthClientMetadata, OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport';
+import Anthropic from '@anthropic-ai/sdk';
+import OpenAI from 'openai';
+import { GoogleGenAI } from '@google/genai';
+
+/** Union of the two sampling result shapes the MCP protocol defines. */
+type AnySamplingResult = CreateMessageResult | CreateMessageResultWithTools;
+
+/**
+ * The SDK's CallToolResult with a typed generic for structuredContent.
+ * Use TData to get typed access to structured tool output.
+ */
+type CallToolResult<TData = unknown> = {
+    content: ContentBlock[];
+    structuredContent: TData | null;
+    isError: boolean;
+};
+type CompletionResult = {
+    values: string[];
+    total?: number;
+    hasMore?: boolean;
+};
+
+type LogMessage = {
+    level: LoggingLevel;
+    logger?: string;
+    data: unknown;
+};
+type LogHandler = (message: LogMessage) => void | Promise<void>;
+type ProgressHandler = (progress: number, total?: number, message?: string) => void | Promise<void>;
+type SamplingHandler = (params: CreateMessageRequestParams) => AnySamplingResult | Promise<AnySamplingResult>;
+type ElicitationHandler = (params: ElicitRequestParams) => ElicitResult | Promise<ElicitResult>;
+type ResourceUpdateHandler = (uri: string) => void | Promise<void>;
+/**
+ * Config for receiving server-initiated list-change notifications.
+ * Set debounceMs: 0 in tests for instant delivery.
+ */
+type ListChangedHandler<T> = {
+    onChanged: (error: Error | null, items: T[] | null) => void | Promise<void>;
+    /** Whether to auto-fetch the updated list before calling onChanged. Default: true. */
+    autoRefresh?: boolean;
+    /** Debounce window in ms. Default: 300. Set to 0 to disable. */
+    debounceMs?: number;
+};
+interface ClientHandlers {
+    log?: LogHandler;
+    progress?: ProgressHandler;
+    sampling?: SamplingHandler;
+    elicitation?: ElicitationHandler;
+    onToolsListChanged?: ListChangedHandler<Tool>;
+    onResourcesListChanged?: ListChangedHandler<Resource>;
+    onPromptsListChanged?: ListChangedHandler<Prompt>;
+}
+declare function defaultLogHandler(message: LogMessage): void;
+declare function defaultProgressHandler(progress: number, total?: number, message?: string): void;
+
+interface RequestOptions {
+    /** Per-request timeout in seconds. Overrides client-level defaultOptions. */
+    timeout?: number;
+    /** AbortSignal for caller-controlled cancellation. */
+    signal?: AbortSignal;
+}
+interface CallToolOptions extends RequestOptions {
+    /** Per-call progress handler, overrides the client-level handler for this call. */
+    onProgress?: ProgressHandler;
+}
+interface IToolsClient {
+    listTools(options?: RequestOptions): Promise<Tool[]>;
+    callTool<TData = unknown>(name: string, args?: Record<string, unknown>, options?: CallToolOptions): Promise<CallToolResult<TData>>;
+}
+interface IResourcesClient {
+    listResources(options?: RequestOptions): Promise<Resource[]>;
+    listResourceTemplates(options?: RequestOptions): Promise<ResourceTemplate[]>;
+    readResource(uri: string, options?: RequestOptions): Promise<ResourceContents[]>;
+    subscribeResource(uri: string, handler: ResourceUpdateHandler, options?: RequestOptions): Promise<void>;
+    unsubscribeResource(uri: string, options?: RequestOptions): Promise<void>;
+}
+interface IPromptsClient {
+    listPrompts(options?: RequestOptions): Promise<Prompt[]>;
+    getPrompt(name: string, args?: Record<string, string>, options?: RequestOptions): Promise<GetPromptResult>;
+}
+interface IClient extends IToolsClient, IResourcesClient, IPromptsClient {
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    ping(options?: RequestOptions): Promise<boolean>;
+    complete(ref: {
+        type: 'ref/prompt';
+        name: string;
+    } | {
+        type: 'ref/resource';
+        uri: string;
+    }, argument: {
+        name: string;
+        value: string;
+    }, context?: {
+        arguments?: Record<string, string>;
+    }, options?: RequestOptions): Promise<CompletionResult>;
+    setLogLevel(level: LoggingLevel, options?: RequestOptions): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+type OAuthToken = {
+    access_token: string;
+    token_type?: string;
+    refresh_token?: string;
+    /** Unix timestamp in milliseconds (normalized internally). */
+    expires_at?: number;
+    /** Seconds until expiry — used to compute expires_at on receipt. */
+    expires_in?: number;
+    scope?: string;
+};
+type KeyValueStore = {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+};
+declare class InMemoryStore implements KeyValueStore {
+    private readonly _map;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare class FileTokenStorage implements KeyValueStore {
+    private readonly _path;
+    constructor(path?: string);
+    private _readAll;
+    private _writeAll;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+interface OAuthOptions {
+    /** Pre-registered client ID. When set, Dynamic Client Registration is skipped. */
+    clientId?: string;
+    /** Pre-registered client secret. */
+    clientSecret?: string;
+    /** Requested OAuth scopes (space-separated string or array). */
+    scopes?: string | string[];
+    /** Client name used in Dynamic Client Registration. Default: "FastMCP Client". */
+    clientName?: string;
+    /** Persistent key-value store for tokens, client info, and discovery state. Default: in-memory. */
+    store?: KeyValueStore;
+    /**
+     * Port for the local OAuth callback server. Default: 8765.
+     * The port must be consistent across calls because it is registered as the
+     * redirect_uri during Dynamic Client Registration.
+     */
+    callbackPort?: number;
+    /**
+     * Override how the authorization URL is opened. When not provided the
+     * system browser is launched. Inject a no-op or mock here for testing.
+     */
+    onRedirect?: (url: URL) => void | Promise<void>;
+}
+declare class OAuth implements OAuthClientProvider {
+    private _serverUrl;
+    private readonly _clientId?;
+    private readonly _clientSecret?;
+    private readonly _scopes?;
+    private readonly _clientName;
+    private readonly _store;
+    private readonly _callbackPort;
+    private readonly _onRedirect?;
+    private _codeVerifier;
+    private _callbackPromise;
+    private _callbackResolve;
+    private _callbackReject;
+    private _callbackServer;
+    private _actualCallbackPort;
+    constructor(options?: OAuthOptions);
+    /**
+     * Binds the MCP server URL so that all storage keys are namespaced by it.
+     * Called by Client before connecting.
+     */
+    _bind(serverUrl: string): void;
+    get redirectUrl(): string | URL;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    saveClientInformation(info: OAuthClientInformationMixed): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    saveCodeVerifier(codeVerifier: string): void;
+    codeVerifier(): string;
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
+    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
+    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
+    /**
+     * Returns the actual port the callback server bound to.
+     * Only populated after redirectToAuthorization() has been called.
+     */
+    get callbackServerPort(): number | null;
+    /**
+     * Waits for the OAuth authorization code to arrive via the callback server,
+     * then stops the server and resolves with the code.
+     *
+     * Must be called after the UnauthorizedError thrown by connect() is caught.
+     */
+    waitForCallback(timeoutMs?: number): Promise<string>;
+    private _key;
+    private _startCallbackServer;
+    private _stopCallbackServer;
+}
+declare class BearerAuth {
+    private readonly _token;
+    constructor(token: string);
+    getHeaders(): Record<string, string>;
+}
+interface ClientCredentialsOptions {
+    tokenEndpoint: string;
+    clientId: string;
+    clientSecret: string;
+    scope?: string;
+    store?: KeyValueStore;
+    /** How many seconds before expiry to proactively re-fetch. Default: 60. */
+    refreshBufferSeconds?: number;
+}
+declare class ClientCredentials {
+    readonly kind: "client_credentials";
+    private readonly _tokenEndpoint;
+    private readonly _clientId;
+    private readonly _clientSecret;
+    private readonly _scope?;
+    private readonly _store;
+    private readonly _bufferMs;
+    private _fetchPromise;
+    constructor(options: ClientCredentialsOptions);
+    getHeaders(): Promise<Record<string, string>>;
+    private get _tokenKey();
+    private _getValidToken;
+    private _doFetch;
+}
+
+interface McpServerLike {
+    connect(transport: Transport): Promise<void>;
+}
+type McpServerEntry = {
+    url: string;
+    headers?: Record<string, string>;
+    auth?: BearerAuth | OAuth | ClientCredentials | string;
+} | {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    auth?: BearerAuth | OAuth | ClientCredentials | string;
+};
+/** Values accepted in mcpServers: either a config object or an in-process server. */
+type McpServerValue = McpServerEntry | McpServerLike;
+type McpConfig = {
+    mcpServers: Record<string, McpServerValue>;
+};
+declare class StdioTransport {
+    readonly command: string;
+    readonly args: string[];
+    readonly env?: Record<string, string>;
+    readonly cwd?: string;
+    constructor(command: string, args?: string[], options?: {
+        env?: Record<string, string>;
+        cwd?: string;
+    });
+}
+type ClientTransportInput = string | McpServerLike | McpConfig | StdioTransport | Transport;
+
+interface MultiServerOptions {
+    handlers?: ClientHandlers;
+    /** file:// URIs to advertise to all servers as accessible roots. */
+    roots?: string[];
+    defaultOptions?: ClientDefaultOptions;
+}
+declare class MultiServerClient implements IClient {
+    private _clients;
+    private _connectPromise;
+    private _connected;
+    /** URI (or namespaced template URI) → server name, populated by list calls */
+    private _uriMap;
+    private readonly _config;
+    private readonly _handlers;
+    private readonly _roots;
+    private readonly _defaultOptions;
+    private _resourceSubscriptions;
+    constructor(config: McpConfig, options?: MultiServerOptions);
+    connect(): Promise<void>;
+    private _doConnect;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    isConnected(): boolean;
+    static connect(config: McpConfig, options?: MultiServerOptions): Promise<MultiServerClient>;
+    ping(options?: RequestOptions): Promise<boolean>;
+    listTools(options?: RequestOptions): Promise<Tool[]>;
+    callTool<TData = unknown>(name: string, args?: Record<string, unknown>, options?: CallToolOptions): Promise<CallToolResult<TData>>;
+    callToolRaw<TData = unknown>(name: string, args?: Record<string, unknown>, options?: CallToolOptions): Promise<CallToolResult<TData>>;
+    listResources(options?: RequestOptions): Promise<Resource[]>;
+    listResourceTemplates(options?: RequestOptions): Promise<ResourceTemplate[]>;
+    readResource(uri: string, options?: RequestOptions): Promise<ResourceContents[]>;
+    listPrompts(options?: RequestOptions): Promise<Prompt[]>;
+    getPrompt(name: string, args?: Record<string, string>, options?: RequestOptions): Promise<GetPromptResult>;
+    subscribeResource(uri: string, handler: ResourceUpdateHandler, options?: RequestOptions): Promise<void>;
+    unsubscribeResource(uri: string, options?: RequestOptions): Promise<void>;
+    complete(ref: {
+        type: 'ref/prompt';
+        name: string;
+    } | {
+        type: 'ref/resource';
+        uri: string;
+    }, argument: {
+        name: string;
+        value: string;
+    }, context?: {
+        arguments?: Record<string, string>;
+    }, options?: RequestOptions): Promise<CompletionResult>;
+    setLogLevel(level: LoggingLevel, options?: RequestOptions): Promise<void>;
+    private _assertConnected;
+    private _parseNamespacedName;
+    private _sdkForServer;
+    private _buildSdkClient;
+    private _buildCapabilities;
+    private _registerHandlers;
+    private _toSdkOptions;
+}
+
+declare class ToolCallError extends Error {
+    readonly content: ContentBlock[];
+    constructor(message: string, content: ContentBlock[]);
+}
+interface ClientDefaultOptions {
+    /** Global fallback timeout in seconds for all requests. */
+    timeout?: number;
+    tool?: {
+        timeout?: number;
+    };
+    resource?: {
+        timeout?: number;
+    };
+    prompt?: {
+        timeout?: number;
+    };
+}
+/** A single element of the roots option: a URI string or a full Root object. */
+type RootInput = string | Root;
+/**
+ * Static list of roots, or an async callback invoked on each roots/list request.
+ * URI strings are normalised to file:// URIs automatically; relative paths are
+ * resolved against process.cwd().
+ */
+type RootsValue = RootInput[] | (() => RootInput[] | Promise<RootInput[]>);
+interface ClientOptions {
+    /**
+     * Authentication to attach to HTTP requests.
+     * A plain string is treated as a Bearer token.
+     */
+    auth?: BearerAuth | OAuth | ClientCredentials | string;
+    handlers?: ClientHandlers;
+    /**
+     * Filesystem roots to advertise to the server.
+     * Accepts a static array of strings / Root objects, or an async callback
+     * invoked on each roots/list request (useful for dynamic root sets).
+     */
+    roots?: RootsValue;
+    /**
+     * When true (default), the MCP initialize handshake is performed
+     * automatically inside connect().
+     */
+    autoInitialize?: boolean;
+    defaultOptions?: ClientDefaultOptions;
+}
+declare class Client implements IClient {
+    private _sdkClient;
+    private _refCount;
+    private _connectPromise;
+    private readonly _resourceSubscriptions;
+    private readonly _input;
+    private readonly _auth;
+    private readonly _handlers;
+    private readonly _roots;
+    private readonly _autoInitialize;
+    private readonly _defaultOptions;
+    constructor(input: ClientTransportInput, options?: ClientOptions);
+    connect(): Promise<void>;
+    private _doConnect;
+    private _extractServerUrl;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    isConnected(): boolean;
+    /** Creates a connected MultiServerClient when given a multi-entry McpConfig. */
+    static connect(input: McpConfig, options?: MultiServerOptions): Promise<MultiServerClient>;
+    /** Creates a connected Client for a single-server transport. Use with `await using` for automatic cleanup. */
+    static connect(input: ClientTransportInput, options?: ClientOptions): Promise<Client>;
+    ping(options?: RequestOptions): Promise<boolean>;
+    listTools(options?: RequestOptions): Promise<Tool[]>;
+    callTool<TData = unknown>(name: string, args?: Record<string, unknown>, options?: CallToolOptions): Promise<CallToolResult<TData>>;
+    /** Returns the full result including isError without throwing. */
+    callToolRaw<TData = unknown>(name: string, args?: Record<string, unknown>, options?: CallToolOptions): Promise<CallToolResult<TData>>;
+    listResources(options?: RequestOptions): Promise<Resource[]>;
+    listResourceTemplates(options?: RequestOptions): Promise<ResourceTemplate[]>;
+    readResource(uri: string, options?: RequestOptions): Promise<ResourceContents[]>;
+    /** Returns the raw SDK ReadResourceResult without unwrapping. */
+    readResourceRaw(uri: string, options?: RequestOptions): Promise<{
+        [x: string]: unknown;
+        contents: ({
+            uri: string;
+            text: string;
+            mimeType?: string | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            blob: string;
+            mimeType?: string | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    subscribeResource(uri: string, handler: ResourceUpdateHandler, options?: RequestOptions): Promise<void>;
+    unsubscribeResource(uri: string, options?: RequestOptions): Promise<void>;
+    listPrompts(options?: RequestOptions): Promise<Prompt[]>;
+    getPrompt(name: string, args?: Record<string, string>, options?: RequestOptions): Promise<GetPromptResult>;
+    complete(ref: {
+        type: 'ref/prompt';
+        name: string;
+    } | {
+        type: 'ref/resource';
+        uri: string;
+    }, argument: {
+        name: string;
+        value: string;
+    }, context?: {
+        arguments?: Record<string, string>;
+    }, options?: RequestOptions): Promise<CompletionResult>;
+    setLogLevel(level: LoggingLevel, options?: RequestOptions): Promise<void>;
+    private _sdk;
+    private _toSdkOptions;
+    private _buildCapabilities;
+    private _buildListChangedConfig;
+    private _registerHandlers;
+    /**
+     * Notify the connected server that the client's roots list has changed.
+     * The server should re-issue a roots/list request to get the updated list.
+     */
+    notifyRootsChanged(): Promise<void>;
+}
+
+type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+declare function toResult<T, E = Error>(fn: Promise<T> | (() => Promise<T>)): Promise<Result<T, E>>;
+
+/**
+ * Resolve a concrete model name from the server's modelPreferences.
+ * A plain string always uses that model; a function inspects the preferences.
+ */
+type ModelSelector = string | ((prefs: ModelPreferences | undefined) => string);
+/** Called with each text token as it is streamed from the provider. */
+type OnTokenCallback = (token: string) => void;
+interface SamplingAdapterOptions {
+    /** Override or replace the model selection logic. */
+    modelSelector?: ModelSelector;
+    /** Fired for each streamed text token. Tool-use deltas are not surfaced. */
+    onToken?: OnTokenCallback;
+}
+/** Implemented by all sampling adapters. */
+interface SamplingAdapter {
+    asHandler(): SamplingHandler;
+}
+
+interface GenericCompletionParams {
+    model: string;
+    messages: SamplingMessage[];
+    system?: string;
+    /** Defaulted to 1024 when absent in the original request. */
+    maxTokens: number;
+    temperature?: number;
+    stopSequences?: string[];
+    tools?: Tool[];
+    toolChoice?: ToolChoice;
+    onToken?: OnTokenCallback;
+}
+type GenericCompletionFn = (params: GenericCompletionParams) => Promise<AnySamplingResult>;
+/**
+ * Contribution template. Wraps any async function into a SamplingHandler.
+ *
+ * The adapter resolves the model from modelPreferences, defaults maxTokens,
+ * and threads onToken through. Message format conversion, tool translation,
+ * and streaming are the caller's responsibility.
+ *
+ * Example:
+ * ```ts
+ * const adapter = new GenericSamplingAdapter(async ({ model, messages }) => {
+ *   const text = await myLlm.complete(model, messages)
+ *   return { role: 'assistant', content: { type: 'text', text }, model, stopReason: 'endTurn' }
+ * })
+ * ```
+ */
+declare class GenericSamplingAdapter implements SamplingAdapter {
+    private readonly _fn;
+    private readonly _options;
+    constructor(fn: GenericCompletionFn, options?: SamplingAdapterOptions & {
+        defaultModel?: string;
+    });
+    asHandler(): SamplingHandler;
+}
+
+declare class AnthropicSamplingAdapter implements SamplingAdapter {
+    private readonly _client;
+    private readonly _options;
+    constructor(client: Anthropic, options?: SamplingAdapterOptions & {
+        defaultModel?: string;
+    });
+    asHandler(): SamplingHandler;
+}
+
+declare class OpenAISamplingAdapter implements SamplingAdapter {
+    private readonly _client;
+    private readonly _options;
+    constructor(client: OpenAI, options?: SamplingAdapterOptions & {
+        defaultModel?: string;
+    });
+    asHandler(): SamplingHandler;
+}
+
+declare class GoogleSamplingAdapter implements SamplingAdapter {
+    private readonly _client;
+    private readonly _options;
+    constructor(client: GoogleGenAI, options?: SamplingAdapterOptions & {
+        defaultModel?: string;
+    });
+    asHandler(): SamplingHandler;
+}
+
+export { AnthropicSamplingAdapter, type AnySamplingResult, BearerAuth, type CallToolOptions, type CallToolResult, Client, ClientCredentials, type ClientCredentialsOptions, type ClientDefaultOptions, type ClientHandlers, type ClientOptions, type ClientTransportInput, type CompletionResult, type ElicitationHandler, FileTokenStorage, type GenericCompletionFn, type GenericCompletionParams, GenericSamplingAdapter, GoogleSamplingAdapter, type IClient, type IPromptsClient, type IResourcesClient, type IToolsClient, InMemoryStore, type KeyValueStore, type ListChangedHandler, type LogHandler, type LogMessage, type McpConfig, type McpServerEntry, type McpServerLike, type McpServerValue, type ModelSelector, MultiServerClient, type MultiServerOptions, OAuth, type OAuthOptions, type OAuthToken, type OnTokenCallback, OpenAISamplingAdapter, type ProgressHandler, type RequestOptions, type ResourceUpdateHandler, type Result, type RootInput, type RootsValue, type SamplingAdapter, type SamplingAdapterOptions, type SamplingHandler, StdioTransport, ToolCallError, defaultLogHandler, defaultProgressHandler, toResult };