@prefecthq/fastmcp-ts 1.0.0 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@ The TypeScript framework for building [Model Context Protocol](https://modelcont
 
 Built on version 2 of the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) — the scoped `@modelcontextprotocol/server` and `@modelcontextprotocol/client` packages. FastMCP handles the protocol plumbing so you can focus on what your server actually does.
 
-FastMCP 1.0 speaks both MCP protocol generations: the 2025 legacy era and the 2026-07-28 modern era. A server serves both at once, and a client negotiates one. Upgrading from 0.x keeps your existing code running — the client defaults to the legacy era until you opt into the modern one. The [migration guide](docs/migration.mdx) covers the upgrade path.
+FastMCP 1.0 speaks both MCP protocol generations: the 2025 legacy era and the 2026-07-28 modern era. A server serves both at once, and a client negotiates one. The client negotiates automatically by default: it probes once at connect, uses the modern era when the server offers it, and falls back to legacy otherwise, so upgrading from 0.x keeps your existing code running against servers of either generation. Pass `versionNegotiation: { mode: 'legacy' }` to opt out of the probe. The [migration guide](docs/migration.mdx) covers the upgrade path.
 
 ## Installation
 
@@ -289,7 +289,7 @@ fastmcp run server.ts --transport http --port 3000
 fastmcp inspect --file server.ts
 fastmcp inspect --url http://localhost:3000
 fastmcp inspect --file server.ts --json
-fastmcp inspect --file server.ts --modern       # negotiate the 2026-07-28 protocol era over stdio
+fastmcp inspect --file server.ts --legacy       # force the legacy 2025 era, no probe
 fastmcp inspect --file server.ts --pin 2026-07-28  # require that exact era
 
 # Call a tool, read a resource, or get a prompt
@@ -312,7 +312,7 @@ fastmcp install claude-desktop server.ts
 fastmcp discover
 ```
 
-`fastmcp inspect`, `fastmcp list`, and `fastmcp call` connect over stdio by default, when you pass `--file` or `--command`. Add `--modern` to negotiate the newer 2026-07-28 protocol era. A `--url` connection negotiates the protocol version automatically, so `--modern` is not needed for HTTP. `--pin <version>` works on every transport, including HTTP. It forces that exact protocol revision. The connection fails if the server does not offer it.
+`fastmcp inspect`, `fastmcp list`, and `fastmcp call` negotiate the protocol era automatically on every transport: one probe at connect, the modern 2026-07-28 era when the server offers it, and the legacy 2025 era otherwise. Add `--legacy` to skip the probe and force the legacy era. `--pin <version>` works on every transport, including HTTP. It forces that exact protocol revision. The connection fails if the server does not offer it. `--modern` is a deprecated no-op, kept for compatibility.
 
 ---
 

package/dist/cli/index.cjs

@@ -1172,8 +1172,8 @@ var init_version = __esm({
       async run({ args }) {
         if (args.json) setJsonMode(true);
         const data = {
-          fastmcp: "1.0.0",
-          "mcp-sdk": "^2.0.0",
+          fastmcp: "1.2.0",
+          "mcp-sdk": "2.0.0",
           node: process.version,
           platform: `${process.platform} ${process.arch}`
         };
@@ -28348,6 +28348,33 @@ var init_auth = __esm({
   }
 });
 
+// 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;
+}
+var init_capabilities = __esm({
+  "src/client/capabilities.ts"() {
+    "use strict";
+  }
+});
+
 // src/client/handlers.ts
 function defaultLogHandler(message) {
   const prefix = message.logger ? `[${message.logger}]` : "[server]";
@@ -29288,6 +29315,7 @@ var init_multi_server = __esm({
   "src/client/multi-server.ts"() {
     "use strict";
     init_dist4();
+    init_capabilities();
     init_handlers();
     init_transports();
     init_client();
@@ -29300,6 +29328,7 @@ var init_multi_server = __esm({
       _config;
       _handlers;
       _roots;
+      _capabilities;
       _defaultOptions;
       _versionNegotiation;
       _resourceSubscriptions = /* @__PURE__ */ new Map();
@@ -29321,8 +29350,13 @@ var init_multi_server = __esm({
           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 ?? {};
       }
       // -------------------------------------------------------------------------
@@ -29734,18 +29768,11 @@ ${errors.map(String).join("\n")}`);
         return new Client(
           { 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({
@@ -29831,6 +29858,7 @@ var init_client = __esm({
     "use strict";
     init_dist4();
     init_auth();
+    init_capabilities();
     init_handlers();
     init_transports();
     init_multi_server();
@@ -29869,6 +29897,7 @@ var init_client = __esm({
       _auth;
       _handlers;
       _roots;
+      _capabilities;
       _autoInitialize;
       _versionNegotiation;
       _prior;
@@ -29896,8 +29925,13 @@ var init_client = __esm({
           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;
@@ -29930,9 +29964,9 @@ var init_client = __esm({
         const sdkClient = new Client(
           { 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 } : {},
@@ -29956,7 +29990,10 @@ var init_client = __esm({
           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);
@@ -30037,6 +30074,35 @@ var init_client = __esm({
       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)
       // -------------------------------------------------------------------------
@@ -30370,13 +30436,6 @@ var init_client = __esm({
         }
         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;
@@ -30439,14 +30498,13 @@ var init_client = __esm({
 });
 
 // src/cli/utils/connect.ts
-function resolveVersionNegotiation2(kind, era) {
+function resolveVersionNegotiation2(era) {
   if (era?.pin) return { mode: { pin: era.pin } };
-  if (kind === "url") return { mode: "auto" };
-  if (era?.modern) return { mode: "auto" };
-  return void 0;
+  if (era?.legacy) return { mode: "legacy" };
+  return { mode: "auto" };
 }
 async function connectClient(mode, auth2, era) {
-  const versionNegotiation = resolveVersionNegotiation2(mode.kind, era);
+  const versionNegotiation = resolveVersionNegotiation2(era);
   if (mode.kind === "url") {
     const client2 = new Client2(mode.url, { auth: auth2, versionNegotiation });
     await client2.connect();
@@ -30500,6 +30558,86 @@ var init_auth2 = __esm({
   }
 });
 
+// src/cli/utils/manifest.ts
+function componentKey(prefix, identifier) {
+  return `${prefix}:${identifier}@`;
+}
+function buildFastmcpManifest(input) {
+  const { serverInfo } = input;
+  return {
+    server: {
+      name: serverInfo?.name ?? null,
+      instructions: input.instructions ?? null,
+      // Python reports an unset version as null, never ''.
+      version: serverInfo?.version || null,
+      website_url: serverInfo?.websiteUrl ?? null,
+      icons: serverInfo?.icons ?? null,
+      generation: input.generation,
+      capabilities: input.capabilities ?? {}
+    },
+    environment: {
+      fastmcp: input.fastmcpVersion,
+      mcp: input.mcpVersion
+    },
+    tools: input.tools.map((t2) => ({
+      key: componentKey("tool", t2.name),
+      name: t2.name,
+      description: t2.description ?? null,
+      input_schema: t2.inputSchema ?? {},
+      output_schema: t2.outputSchema ?? null,
+      annotations: t2.annotations ?? null,
+      tags: null,
+      title: t2.title ?? null,
+      icons: t2.icons ?? null,
+      meta: t2._meta ?? null
+    })),
+    prompts: input.prompts.map((p2) => ({
+      key: componentKey("prompt", p2.name),
+      name: p2.name,
+      description: p2.description ?? null,
+      arguments: p2.arguments?.length ? p2.arguments.map((a) => ({
+        name: a.name,
+        description: a.description ?? null,
+        required: a.required ?? null
+      })) : null,
+      tags: null,
+      title: p2.title ?? null,
+      icons: p2.icons ?? null,
+      meta: p2._meta ?? null
+    })),
+    resources: input.resources.map((r) => ({
+      key: componentKey("resource", r.uri),
+      uri: r.uri,
+      name: r.name ?? null,
+      description: r.description ?? null,
+      mime_type: r.mimeType ?? null,
+      annotations: r.annotations ?? null,
+      tags: null,
+      title: r.title ?? null,
+      icons: r.icons ?? null,
+      meta: r._meta ?? null
+    })),
+    templates: input.templates.map((t2) => ({
+      key: componentKey("template", t2.uriTemplate),
+      uri_template: t2.uriTemplate,
+      name: t2.name ?? null,
+      description: t2.description ?? null,
+      mime_type: t2.mimeType ?? null,
+      parameters: null,
+      annotations: t2.annotations ?? null,
+      tags: null,
+      title: t2.title ?? null,
+      icons: t2.icons ?? null,
+      meta: t2._meta ?? null
+    }))
+  };
+}
+var init_manifest = __esm({
+  "src/cli/utils/manifest.ts"() {
+    "use strict";
+  }
+});
+
 // node_modules/fast-string-truncated-width/dist/utils.js
 var isAmbiguous, isFullWidth, isWide;
 var init_utils = __esm({
@@ -33194,6 +33332,7 @@ var init_inspect = __esm({
     init_file_spec();
     init_connect();
     init_auth2();
+    init_manifest();
     init_spinner();
     init_format();
     init_output();
@@ -33208,11 +33347,16 @@ var init_inspect = __esm({
         export: { type: "string", description: "Named export to resolve (e.g. server); overrides file:export syntax" },
         auth: { type: "string", description: "Bearer token" },
         json: { type: "boolean", description: "Output JSON", default: false },
-        modern: { type: "boolean", description: "Turn on version negotiation for stdio and in-process connections", default: false },
+        format: { type: "string", description: "Output format: fastmcp (the snake_case manifest the Python FastMCP CLI emits for --format fastmcp). Implies JSON output." },
+        modern: { type: "boolean", description: "Deprecated no-op: auto-negotiation is the default on every transport", default: false },
+        legacy: { type: "boolean", description: "Force the legacy 2025 protocol era; skips the server/discover probe", default: false },
         pin: { type: "string", description: "Pin the protocol era to this revision (e.g. 2026-07-28)" }
       },
       async run({ args }) {
-        if (args.json) setJsonMode(true);
+        if (args.format !== void 0 && args.format !== "fastmcp") {
+          cliError(`Unknown format "${args.format}". Supported formats: fastmcp`);
+        }
+        if (args.json || args.format) setJsonMode(true);
         if (!args.url && !args.command && !args.file) {
           cliError("Provide a server URL, --command <cmd>, or --file <file>");
         }
@@ -33226,7 +33370,7 @@ var init_inspect = __esm({
           }
         }
         const mode = args.file ? { kind: "inprocess", spec: fileSpec } : args.command ? { kind: "stdio", command: args.command } : { kind: "url", url: args.url };
-        const era = { modern: args.modern, pin: args.pin };
+        const era = { modern: args.modern, legacy: args.legacy, pin: args.pin };
         let client;
         try {
           client = await withSpinner(
@@ -33237,6 +33381,32 @@ var init_inspect = __esm({
           cliError(formatError2(err), { code: EXIT.CONNECTION });
         }
         try {
+          if (args.format === "fastmcp") {
+            const [tools2, resources2, templates, prompts2] = await Promise.all([
+              client.listTools().catch(() => []),
+              client.listResources().catch(() => []),
+              client.listResourceTemplates().catch(() => []),
+              client.listPrompts().catch(() => [])
+            ]);
+            const manifest = buildFastmcpManifest({
+              serverInfo: client.getServerInfo(),
+              instructions: client.getInstructions(),
+              capabilities: client.getServerCapabilities(),
+              // A --file entrypoint is a FastMCP server (Python generation 2, the
+              // only case Python's inspect supports); over --url/--command the
+              // generation is unknowable from the wire.
+              generation: mode.kind === "inprocess" ? 2 : null,
+              fastmcpVersion: "1.2.0",
+              mcpVersion: "2.0.0",
+              tools: tools2,
+              prompts: prompts2,
+              resources: resources2,
+              templates
+            });
+            output(manifest, () => {
+            });
+            return;
+          }
           const [tools, resources, prompts] = await Promise.all([
             client.listTools().catch(() => []),
             client.listResources().catch(() => []),
@@ -33328,7 +33498,8 @@ var init_list = __esm({
         prompts: { type: "boolean", description: "Also list prompts", default: false },
         "input-schema": { type: "boolean", description: "Expand input schemas", default: false },
         json: { type: "boolean", description: "Output JSON", default: false },
-        modern: { type: "boolean", description: "Turn on version negotiation for stdio and in-process connections", default: false },
+        modern: { type: "boolean", description: "Deprecated no-op: auto-negotiation is the default on every transport", default: false },
+        legacy: { type: "boolean", description: "Force the legacy 2025 protocol era; skips the server/discover probe", default: false },
         pin: { type: "string", description: "Pin the protocol era to this revision (e.g. 2026-07-28)" }
       },
       async run({ args }) {
@@ -33346,7 +33517,7 @@ var init_list = __esm({
           }
         }
         const mode = args.file ? { kind: "inprocess", spec: fileSpec } : args.command ? { kind: "stdio", command: args.command } : { kind: "url", url: args.url };
-        const era = { modern: args.modern, pin: args.pin };
+        const era = { modern: args.modern, legacy: args.legacy, pin: args.pin };
         let client;
         try {
           client = await withSpinner(
@@ -33620,7 +33791,8 @@ var init_call = __esm({
         auth: { type: "string", description: "Bearer token" },
         "input-json": { type: "string", description: "Raw JSON input instead of key=value args" },
         json: { type: "boolean", description: "Output JSON", default: false },
-        modern: { type: "boolean", description: "Turn on version negotiation for stdio and in-process connections", default: false },
+        modern: { type: "boolean", description: "Deprecated no-op: auto-negotiation is the default on every transport", default: false },
+        legacy: { type: "boolean", description: "Force the legacy 2025 protocol era; skips the server/discover probe", default: false },
         pin: { type: "string", description: "Pin the protocol era to this revision (e.g. 2026-07-28)" }
       },
       async run({ args, rawArgs }) {
@@ -33638,7 +33810,7 @@ var init_call = __esm({
           }
         }
         const mode = args.file ? { kind: "inprocess", spec: fileSpec } : args.command ? { kind: "stdio", command: args.command } : { kind: "url", url: args.url };
-        const era = { modern: args.modern, pin: args.pin };
+        const era = { modern: args.modern, legacy: args.legacy, pin: args.pin };
         let client;
         try {
           client = await withSpinner(
@@ -46728,7 +46900,7 @@ init_format();
 var main = defineCommand({
   meta: {
     name: "fastmcp",
-    version: "1.0.0",
+    version: "1.2.0",
     description: "FastMCP CLI \u2014 build, run, and manage MCP servers"
   },
   args: {