@prefecthq/fastmcp-ts 1.0.0 → 1.2.0

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { CreateMessageResult, CreateMessageResultWithTools, ContentBlock, CreateMessageRequestParams, LoggingLevel, ElicitRequestParams, ElicitResult, Tool, Resource, Prompt, ResourceTemplateType, TextResourceContents, BlobResourceContents, GetPromptResult, OAuthClientMetadata as OAuthClientMetadata$1, Root, ModelPreferences, SamplingMessage, ToolChoice } from '@modelcontextprotocol/server';
 export { BlobResourceContents, ContentBlock, CreateMessageRequestParams, CreateMessageResult, CreateMessageResultWithTools, ElicitRequestParams, ElicitResult, GetPromptResult, LoggingLevel, ModelPreferences, Prompt, PromptArgument, PromptMessage, Resource, ResourceContents, ResourceTemplateType as ResourceTemplate, Root, SamplingMessage, TextResourceContents, Tool, ToolChoice, ToolResultContent, ToolUseContent } from '@modelcontextprotocol/server';
-import { OAuthClientProvider, OAuthClientMetadata, OAuthClientInformationContext, StoredOAuthClientInformation, StoredOAuthTokens, OAuthDiscoveryState, ClientAuthMethod, Transport, VersionNegotiationOptions, ProtocolEra, PriorDiscovery, InputRequiredOptions, ResponseCacheStore } from '@modelcontextprotocol/client';
+import { OAuthClientProvider, OAuthClientMetadata, OAuthClientInformationContext, StoredOAuthClientInformation, StoredOAuthTokens, OAuthDiscoveryState, ClientAuthMethod, Transport, ClientCapabilities, VersionNegotiationOptions, PriorDiscovery, InputRequiredOptions, ResponseCacheStore, ProtocolEra, Implementation, ServerCapabilities } from '@modelcontextprotocol/client';
+export { ClientCapabilities } from '@modelcontextprotocol/client';
 import Anthropic from '@anthropic-ai/sdk';
 import OpenAI from 'openai';
 import { GoogleGenAI } from '@google/genai';
@@ -598,17 +599,139 @@ declare class StdioTransport {
 }
 type ClientTransportInput = string | McpServerLike | McpConfig | StdioTransport | Transport;
 
+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 | AsyncHeaderAuth | string;
+    handlers?: ClientHandlers;
+    /**
+     * Additional capabilities to advertise to the server. FastMCP preserves
+     * their settings while adding capabilities inferred from handlers and roots.
+     */
+    capabilities?: ClientCapabilities;
+    /**
+     * 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;
+    /**
+     * Protocol version negotiation (protocol revision 2026-07-28 and later).
+     * The default is `{ mode: 'auto' }`: connect() probes the server once with
+     * `server/discover` and uses the modern (2026-07-28) era on definitive
+     * modern evidence, falling back to the plain legacy `initialize` handshake
+     * on anything else (a method-not-found answer, silence on a local stdio
+     * pipe, a probe child that exits). The probe is stall-safe in the SDK: on
+     * stdio it runs against a short-lived sibling process and a timeout falls
+     * back to legacy, while on HTTP — where silence means an outage — a probe
+     * timeout rejects with a typed error instead of hanging. Pass
+     * `{ mode: 'legacy' }` to opt out: no probe, the 2025 sequence
+     * byte-identical to prior behavior. Pass `{ mode: { pin: '2026-07-28' } }`
+     * to require the modern era outright — connect() throws if the server
+     * cannot speak it. See `getProtocolEra()` to read the negotiated result
+     * after connecting.
+     */
+    versionNegotiation?: VersionNegotiationOptions;
+    /**
+     * A cached era verdict from a previous connection to the same server, so
+     * connect() can skip the `server/discover` probe entirely. Takes precedence
+     * over `versionNegotiation`. `{ kind: 'modern', discover }` adopts a prior
+     * `DiscoverResult` with zero round trips; `{ kind: 'legacy' }` skips the probe
+     * and runs the plain legacy `initialize` handshake. Freshness is the caller's
+     * responsibility — a stale modern verdict fails loudly at the first request; a
+     * stale legacy verdict succeeds silently forever. Reuse only within one
+     * authorization context.
+     */
+    prior?: PriorDiscovery;
+    /**
+     * Multi-round-trip auto-fulfilment (protocol revision 2026-07-28). On the
+     * modern era, servers obtain client input (elicitation, sampling, roots) by
+     * answering a request with an `input_required` result instead of a
+     * server→client request. By default the client fulfils these automatically
+     * through the same `handlers.sampling`/`handlers.elicitation` callbacks,
+     * retrying up to `maxRounds` times. Set `autoFulfill: false` for manual mode.
+     * Has no effect on legacy-era connections. Passed through verbatim to the SDK
+     * client.
+     */
+    inputRequired?: InputRequiredOptions;
+    /**
+     * The response-cache store backing cacheable results (SEP-2549 `ttlMs`/
+     * `cacheScope` hints on `listTools`/`listResources`/`listResourceTemplates`/
+     * `listPrompts`/`readResource`). Defaults to a fresh in-memory store per
+     * client (the SDK's own default) when omitted. Passed through verbatim.
+     */
+    responseCacheStore?: ResponseCacheStore;
+    /**
+     * Opaque per-principal identifier for response-cache writes whose
+     * server-reported `cacheScope` is `'private'`. Set this to a stable identity
+     * of the authorization context (e.g. the auth subject) when one
+     * `responseCacheStore` backs several principals. Passed through verbatim.
+     */
+    cachePartition?: string;
+    /**
+     * TTL (ms) applied when a cacheable result arrives without a `ttlMs` field.
+     * Default `0` (never served from cache, but still stored). Passed through
+     * verbatim.
+     */
+    defaultCacheTtlMs?: number;
+    /**
+     * Allow the deprecated SSE transport when a target URL's path indicates SSE
+     * (e.g. ends in `/sse`). Default `false` — such URLs throw a clear error
+     * pointing at Streamable HTTP and this flag, rather than silently connecting
+     * over a transport the MCP SDK itself marks `@deprecated`. When enabled, a
+     * one-time deprecation warning is logged via `console.warn`.
+     */
+    legacySSE?: boolean;
+}
+
 interface MultiServerOptions {
     handlers?: ClientHandlers;
+    /**
+     * Additional capabilities to advertise to every server. FastMCP combines
+     * them with capabilities inferred from handlers and roots.
+     */
+    capabilities?: ClientCapabilities;
     /** file:// URIs to advertise to all servers as accessible roots. */
     roots?: string[];
     defaultOptions?: ClientDefaultOptions;
     /**
-     * Opt-in protocol version negotiation, applied identically to every server
-     * in the config (protocol revision 2026-07-28 and later). See
+     * Protocol version negotiation, applied identically to every server in the
+     * config (protocol revision 2026-07-28 and later). See
      * `ClientOptions.versionNegotiation` on the single-server `Client` — same
      * semantics, just applied per sub-client here since each connected server
-     * negotiates its own era independently. Default `'legacy'`.
+     * negotiates its own era independently. Default `{ mode: 'auto' }`: each
+     * sub-client probes its server once and falls back to legacy when the
+     * server offers no modern era; `{ mode: 'legacy' }` opts every connection
+     * out of the probe.
      */
     versionNegotiation?: VersionNegotiationOptions;
 }
@@ -621,6 +744,7 @@ declare class MultiServerClient implements IClient {
     private readonly _config;
     private readonly _handlers;
     private readonly _roots;
+    private readonly _capabilities;
     private readonly _defaultOptions;
     private readonly _versionNegotiation;
     private _resourceSubscriptions;
@@ -691,7 +815,6 @@ declare class MultiServerClient implements IClient {
     private _parseNamespacedName;
     private _sdkForServer;
     private _buildSdkClient;
-    private _buildCapabilities;
     private _registerHandlers;
     /** See Client._metaParams's docs — the same purpose, per server name, since
      * each connected server may be on a different era and have a different
@@ -704,107 +827,6 @@ 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 | AsyncHeaderAuth | 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;
-    /**
-     * Opt-in protocol version negotiation (protocol revision 2026-07-28 and later).
-     * The default is `'legacy'`: connect() runs the plain 2025 sequence, byte-identical
-     * to today's behavior (no probe, no new headers). Pass `{ mode: 'auto' }` to probe
-     * with `server/discover` and use the modern era when the server supports it
-     * (falling back to legacy otherwise), or `{ mode: { pin: '2026-07-28' } }` to
-     * require the modern era outright. See `getProtocolEra()` to read the negotiated
-     * result after connecting.
-     */
-    versionNegotiation?: VersionNegotiationOptions;
-    /**
-     * A cached era verdict from a previous connection to the same server, so
-     * connect() can skip the `server/discover` probe entirely. Takes precedence
-     * over `versionNegotiation`. `{ kind: 'modern', discover }` adopts a prior
-     * `DiscoverResult` with zero round trips; `{ kind: 'legacy' }` skips the probe
-     * and runs the plain legacy `initialize` handshake. Freshness is the caller's
-     * responsibility — a stale modern verdict fails loudly at the first request; a
-     * stale legacy verdict succeeds silently forever. Reuse only within one
-     * authorization context.
-     */
-    prior?: PriorDiscovery;
-    /**
-     * Multi-round-trip auto-fulfilment (protocol revision 2026-07-28). On the
-     * modern era, servers obtain client input (elicitation, sampling, roots) by
-     * answering a request with an `input_required` result instead of a
-     * server→client request. By default the client fulfils these automatically
-     * through the same `handlers.sampling`/`handlers.elicitation` callbacks,
-     * retrying up to `maxRounds` times. Set `autoFulfill: false` for manual mode.
-     * Has no effect on legacy-era connections. Passed through verbatim to the SDK
-     * client.
-     */
-    inputRequired?: InputRequiredOptions;
-    /**
-     * The response-cache store backing cacheable results (SEP-2549 `ttlMs`/
-     * `cacheScope` hints on `listTools`/`listResources`/`listResourceTemplates`/
-     * `listPrompts`/`readResource`). Defaults to a fresh in-memory store per
-     * client (the SDK's own default) when omitted. Passed through verbatim.
-     */
-    responseCacheStore?: ResponseCacheStore;
-    /**
-     * Opaque per-principal identifier for response-cache writes whose
-     * server-reported `cacheScope` is `'private'`. Set this to a stable identity
-     * of the authorization context (e.g. the auth subject) when one
-     * `responseCacheStore` backs several principals. Passed through verbatim.
-     */
-    cachePartition?: string;
-    /**
-     * TTL (ms) applied when a cacheable result arrives without a `ttlMs` field.
-     * Default `0` (never served from cache, but still stored). Passed through
-     * verbatim.
-     */
-    defaultCacheTtlMs?: number;
-    /**
-     * Allow the deprecated SSE transport when a target URL's path indicates SSE
-     * (e.g. ends in `/sse`). Default `false` — such URLs throw a clear error
-     * pointing at Streamable HTTP and this flag, rather than silently connecting
-     * over a transport the MCP SDK itself marks `@deprecated`. When enabled, a
-     * one-time deprecation warning is logged via `console.warn`.
-     */
-    legacySSE?: boolean;
-}
 declare class Client implements IClient {
     private _sdkClient;
     private _refCount;
@@ -832,6 +854,7 @@ declare class Client implements IClient {
     private readonly _auth;
     private readonly _handlers;
     private readonly _roots;
+    private readonly _capabilities;
     private readonly _autoInitialize;
     private readonly _versionNegotiation;
     private readonly _prior;
@@ -874,6 +897,29 @@ declare class Client implements IClient {
      * `undefined` before connect(). See `ClientOptions.versionNegotiation`.
      */
     getProtocolEra(): ProtocolEra | undefined;
+    /**
+     * The connected server's self-reported identity (`serverInfo`: name, version,
+     * and optional title / websiteUrl / icons), when it identified itself. On a
+     * legacy connection it comes from the `initialize` result, where it is
+     * required. On a modern (2026-07-28) connection it comes from the
+     * `server/discover` result's metadata — FastMCP servers advertise it there,
+     * but an anonymous modern server may omit it, leaving this `undefined`.
+     * `undefined` before connect().
+     */
+    getServerInfo(): Implementation | undefined;
+    /**
+     * The server's `instructions` string, when the server provided one — from
+     * the legacy `initialize` result or, on a modern (2026-07-28) connection,
+     * from the `server/discover` result. `undefined` otherwise and before
+     * connect().
+     */
+    getInstructions(): string | undefined;
+    /**
+     * The capabilities the server advertised during connection — on the legacy
+     * `initialize` result, or on the `server/discover` result for a modern
+     * (2026-07-28) connection. `undefined` before connect().
+     */
+    getServerCapabilities(): ServerCapabilities | undefined;
     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. */
@@ -1052,7 +1098,6 @@ declare class Client implements IClient {
      */
     private _metaParams;
     private _toSdkOptions;
-    private _buildCapabilities;
     private _buildListChangedConfig;
     private _registerHandlers;
     /**

package/dist/client.js

@@ -916,6 +916,28 @@ async function resolveTransport(input, auth, options) {
 // src/client/client.ts
 import { UnauthorizedError, Client as SdkClient2, LOG_LEVEL_META_KEY as LOG_LEVEL_META_KEY2 } from "@modelcontextprotocol/client";
 
+// src/client/capabilities.ts
+function buildClientCapabilities(supplied, inferred) {
+  const capabilities = { ...supplied };
+  if (inferred.sampling) {
+    capabilities.sampling = {
+      ...supplied?.sampling,
+      tools: supplied?.sampling?.tools ?? {}
+    };
+  }
+  if (inferred.elicitation) {
+    const elicitation = supplied?.elicitation;
+    capabilities.elicitation = elicitation ? { ...elicitation, form: elicitation.form ?? {} } : {};
+  }
+  if (inferred.rootsListChanged !== void 0) {
+    capabilities.roots = {
+      ...supplied?.roots,
+      listChanged: inferred.rootsListChanged
+    };
+  }
+  return capabilities;
+}
+
 // src/client/multi-server.ts
 import { Client as SdkClient, LOG_LEVEL_META_KEY } from "@modelcontextprotocol/client";
 var MultiServerClient = class _MultiServerClient {
@@ -927,6 +949,7 @@ var MultiServerClient = class _MultiServerClient {
   _config;
   _handlers;
   _roots;
+  _capabilities;
   _defaultOptions;
   _versionNegotiation;
   _resourceSubscriptions = /* @__PURE__ */ new Map();
@@ -948,8 +971,13 @@ var MultiServerClient = class _MultiServerClient {
       sampling: options?.handlers?.sampling,
       elicitation: options?.handlers?.elicitation
     };
-    this._versionNegotiation = options?.versionNegotiation;
+    this._versionNegotiation = options?.versionNegotiation ?? { mode: "auto" };
     this._roots = options?.roots;
+    this._capabilities = buildClientCapabilities(options?.capabilities, {
+      sampling: this._handlers.sampling !== void 0,
+      elicitation: this._handlers.elicitation !== void 0,
+      rootsListChanged: this._roots === void 0 ? void 0 : false
+    });
     this._defaultOptions = options?.defaultOptions ?? {};
   }
   // -------------------------------------------------------------------------
@@ -1361,18 +1389,11 @@ ${errors.map(String).join("\n")}`);
     return new SdkClient(
       { name: "fastmcp-ts", version: "1.0.0" },
       {
-        capabilities: this._buildCapabilities(),
-        ...this._versionNegotiation ? { versionNegotiation: this._versionNegotiation } : {}
+        capabilities: this._capabilities,
+        versionNegotiation: this._versionNegotiation
       }
     );
   }
-  _buildCapabilities() {
-    return {
-      ...this._handlers.sampling ? { sampling: { tools: {} } } : {},
-      ...this._handlers.elicitation ? { elicitation: {} } : {},
-      ...this._roots ? { roots: { listChanged: false } } : {}
-    };
-  }
   _registerHandlers(sdk) {
     sdk.setNotificationHandler("notifications/message", (notification) => {
       void this._handlers.log({
@@ -1459,6 +1480,7 @@ var Client = class _Client {
   _auth;
   _handlers;
   _roots;
+  _capabilities;
   _autoInitialize;
   _versionNegotiation;
   _prior;
@@ -1486,8 +1508,13 @@ var Client = class _Client {
       onPromptsListChanged: options?.handlers?.onPromptsListChanged
     };
     this._roots = options?.roots ? normalizeRootsOption(options.roots) : void 0;
+    this._capabilities = buildClientCapabilities(options?.capabilities, {
+      sampling: this._handlers.sampling !== void 0,
+      elicitation: this._handlers.elicitation !== void 0,
+      rootsListChanged: this._roots === void 0 ? void 0 : true
+    });
     this._autoInitialize = options?.autoInitialize ?? true;
-    this._versionNegotiation = options?.versionNegotiation;
+    this._versionNegotiation = options?.versionNegotiation ?? { mode: "auto" };
     this._prior = options?.prior;
     this._inputRequired = options?.inputRequired;
     this._responseCacheStore = options?.responseCacheStore;
@@ -1520,9 +1547,9 @@ var Client = class _Client {
     const sdkClient = new SdkClient2(
       { name: "fastmcp-ts", version: "1.0.0" },
       {
-        capabilities: this._buildCapabilities(),
+        capabilities: this._capabilities,
         listChanged: this._buildListChangedConfig(),
-        ...this._versionNegotiation ? { versionNegotiation: this._versionNegotiation } : {},
+        versionNegotiation: this._versionNegotiation,
         ...this._inputRequired ? { inputRequired: this._inputRequired } : {},
         ...this._responseCacheStore ? { responseCacheStore: this._responseCacheStore } : {},
         ...this._cachePartition !== void 0 ? { cachePartition: this._cachePartition } : {},
@@ -1546,7 +1573,10 @@ var Client = class _Client {
       if (err instanceof UnauthorizedError && this._auth instanceof OAuth) {
         const callbackParams = await this._auth.waitForCallback();
         await this._finishAuth(transport, callbackParams);
-        const retry = await resolveTransport(this._input, this._auth);
+        const retry = await resolveTransport(this._input, this._auth, {
+          legacySSE: this._legacySSE,
+          versionNegotiation: this._versionNegotiation
+        });
         if (retry.beforeConnect) await retry.beforeConnect();
         this._transport = retry.transport;
         await sdkClient.connect(retry.transport);
@@ -1627,6 +1657,35 @@ var Client = class _Client {
   getProtocolEra() {
     return this._sdkClient?.getProtocolEra();
   }
+  /**
+   * The connected server's self-reported identity (`serverInfo`: name, version,
+   * and optional title / websiteUrl / icons), when it identified itself. On a
+   * legacy connection it comes from the `initialize` result, where it is
+   * required. On a modern (2026-07-28) connection it comes from the
+   * `server/discover` result's metadata — FastMCP servers advertise it there,
+   * but an anonymous modern server may omit it, leaving this `undefined`.
+   * `undefined` before connect().
+   */
+  getServerInfo() {
+    return this._sdkClient?.getServerVersion();
+  }
+  /**
+   * The server's `instructions` string, when the server provided one — from
+   * the legacy `initialize` result or, on a modern (2026-07-28) connection,
+   * from the `server/discover` result. `undefined` otherwise and before
+   * connect().
+   */
+  getInstructions() {
+    return this._sdkClient?.getInstructions();
+  }
+  /**
+   * The capabilities the server advertised during connection — on the legacy
+   * `initialize` result, or on the `server/discover` result for a modern
+   * (2026-07-28) connection. `undefined` before connect().
+   */
+  getServerCapabilities() {
+    return this._sdkClient?.getServerCapabilities();
+  }
   // -------------------------------------------------------------------------
   // Tools (IToolsClient)
   // -------------------------------------------------------------------------
@@ -1960,13 +2019,6 @@ var Client = class _Client {
     }
     return sdkOptions;
   }
-  _buildCapabilities() {
-    return {
-      ...this._handlers.sampling ? { sampling: { tools: {} } } : {},
-      ...this._handlers.elicitation ? { elicitation: {} } : {},
-      ...this._roots ? { roots: { listChanged: true } } : {}
-    };
-  }
   _buildListChangedConfig() {
     const { onToolsListChanged, onResourcesListChanged, onPromptsListChanged } = this._handlers;
     if (!onToolsListChanged && !onResourcesListChanged && !onPromptsListChanged) return void 0;