@prefecthq/fastmcp-ts 0.0.6 → 1.0.0-rc.0

package/README.md

@@ -2,7 +2,9 @@
 
 The TypeScript framework for building [Model Context Protocol](https://modelcontextprotocol.io) servers, clients, and apps. The official TypeScript counterpart to [FastMCP for Python](https://github.com/PrefectHQ/fastmcp) - built and maintained with 💙 by the same team at [Prefect](https://prefect.io).
 
-Built on the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk).
+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.
 
 ## Installation
 
@@ -58,6 +60,13 @@ await server.run()                              // stdio (default)
 // await server.run({ transport: 'http', port: 3000 })
 ```
 
+Save this file as `server.ts`. Installing `@prefecthq/fastmcp-ts` also installs the `fastmcp` CLI. Use it to inspect the server and call a tool, with no build step:
+
+```bash
+npx fastmcp inspect --file server.ts
+npx fastmcp call add --file server.ts a=1 b=2
+```
+
 ### Context
 
 Handlers access logging, progress, LLM sampling, user elicitation, and per-session state through an ambient context with no prop-drilling.
@@ -85,7 +94,7 @@ server.tool(
       maxTokens: 512,
     })
 
-    return content.text
+    return content.type === 'text' ? content.text : ''
   }
 )
 ```
@@ -121,7 +130,7 @@ const weather = new FastMCP({ name: 'weather' })
 weather.tool({ name: 'forecast', description: 'Get a forecast', input: z.object({ city: z.string() }) }, ({ city }) => `Forecast for ${city}`)
 
 // Wrap a remote server as a mountable instance
-const maps = await createProxy({ transport: 'http', url: 'http://maps-service/mcp' })
+const maps = await createProxy({ type: 'http', url: 'http://maps-service/mcp' })
 
 const gateway = new FastMCP({ name: 'gateway' })
 gateway.mount(weather, 'weather')   // → weather_forecast
@@ -168,7 +177,7 @@ import Anthropic from '@anthropic-ai/sdk'
 
 const client = await Client.connect('http://localhost:3000', {
   handlers: {
-    sampling: (params) => new AnthropicSamplingAdapter(new Anthropic()).handleSampling(params),
+    sampling: new AnthropicSamplingAdapter(new Anthropic()).asHandler(),
   },
 })
 ```
@@ -201,7 +210,6 @@ FastMCP ships a server-side component library for building interactive UIs rende
 
 ```typescript
 import { FastMCPApp, Column, Row, Text, Input, Button, Table } from '@prefecthq/fastmcp-ts/server'
-import { z } from 'zod'
 
 const app = new FastMCPApp({ name: 'search-app', version: '1.0.0' })
 
@@ -213,19 +221,15 @@ app.entrypoint(
       Text('Product Search'),
       Row({}, [
         Input({ name: 'query', placeholder: 'Search products…' }),
-        Button({ label: 'Search', actionRef: 'run_search' }),
+        Button({ label: 'Search', action: app.toolRef('run_search') }),
       ]),
     ])
 )
 
 // Backend tool: hidden from the LLM, callable only from within the rendered UI
 app.backendTool(
-  {
-    name: 'run_search',
-    description: 'Execute the search query',
-    input: z.object({ query: z.string() }),
-  },
-  async ({ query }) => {
+  { name: 'run_search', description: 'Execute the search query' },
+  async ({ query }: { query: string }) => {
     const rows = await db.search(query)
     return Table({ columns: ['Name', 'Price', 'Stock'], rows })
   }
@@ -247,7 +251,15 @@ const server = new FastMCP({ name: 'my-server' })
 server.addProvider(new Approval())    // confirm/deny card injected back into the conversation
 server.addProvider(new Choice())      // clickable option list
 server.addProvider(new FileUpload())  // drag-and-drop file picker; file bytes never pass through the LLM
-server.addProvider(new FormInput())   // auto-generated validated form from any Standard Schema
+
+// Auto-generated, validated form from any Standard Schema
+server.addProvider(
+  new FormInput({
+    name: 'contact_form',
+    description: 'Contact form',
+    schema: z.object({ name: z.string(), email: z.string() }),
+  }),
+)
 ```
 
 ### Generative UI
@@ -277,6 +289,8 @@ 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 --pin 2026-07-28  # require that exact era
 
 # Call a tool, read a resource, or get a prompt
 fastmcp call add --file server.ts a=1 b=2
@@ -298,12 +312,15 @@ 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.
+
 ---
 
 ## Ecosystem
 
 | Package | Role |
 |---|---|
-| [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) | Official low-level MCP protocol implementation — this library's foundation |
+| [`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server) | Official MCP TypeScript SDK v2 — the server-side protocol implementation FastMCP builds on |
+| [`@modelcontextprotocol/client`](https://www.npmjs.com/package/@modelcontextprotocol/client) | Official MCP TypeScript SDK v2 — the client-side protocol implementation FastMCP builds on |
 | [`fastmcp` (PyPI)](https://github.com/PrefectHQ/fastmcp) | The Python original this project models its API after |
 | [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) | Official MCP Apps extension — foundation for the Apps pillar |

package/dist/cli/entrypoint-runtime.cjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli/entrypoint-runtime.ts
+var import_node_url = require("url");
+var AUTO_DETECT_NAMES = ["default", "mcp", "server", "app"];
+function isFastMCPInstance(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  return typeof obj["run"] === "function" && typeof obj["tool"] === "function" && typeof obj["resource"] === "function" && typeof obj["prompt"] === "function" && typeof obj["connect"] === "function";
+}
+function describe(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return `a ${typeof value}`;
+}
+function fail(message) {
+  console.error(`fastmcp: ${message}`);
+  process.exit(1);
+}
+async function resolveFactory(value, exportName, filePath) {
+  if (typeof value !== "function") return value;
+  try {
+    return await value();
+  } catch (err) {
+    fail(
+      `Failed to call entrypoint factory "${exportName}" in ${filePath}: ` + (err instanceof Error ? err.message : String(err))
+    );
+  }
+}
+async function main() {
+  const filePath = process.env["FASTMCP_ENTRYPOINT_FILE"];
+  if (!filePath) {
+    fail("internal error: FASTMCP_ENTRYPOINT_FILE was not set for the entrypoint bootstrap");
+  }
+  const explicitExport = process.env["FASTMCP_ENTRYPOINT_EXPORT"];
+  let mod;
+  try {
+    mod = await import((0, import_node_url.pathToFileURL)(filePath).href);
+  } catch (err) {
+    fail(
+      `Failed to load entrypoint file "${filePath}": ` + (err instanceof Error ? err.stack ?? err.message : String(err))
+    );
+  }
+  let resolved;
+  if (explicitExport) {
+    if (!(explicitExport in mod)) {
+      const available = Object.keys(mod).filter((k) => k !== "__esModule");
+      fail(
+        `Entrypoint export "${explicitExport}" not found in ${filePath}.` + (available.length > 0 ? ` Available exports: ${available.join(", ")}.` : " The file has no exports.")
+      );
+    }
+    const target = await resolveFactory(mod[explicitExport], explicitExport, filePath);
+    if (!isFastMCPInstance(target)) {
+      fail(
+        `Entrypoint export "${explicitExport}" in ${filePath} is not a FastMCP server (or a function that returns one). Got ${describe(target)}.`
+      );
+    }
+    resolved = target;
+  } else {
+    for (const name of AUTO_DETECT_NAMES) {
+      if (!(name in mod)) continue;
+      const candidate = mod[name];
+      if (isFastMCPInstance(candidate)) {
+        resolved = candidate;
+        break;
+      }
+    }
+    if (resolved === void 0) {
+      return;
+    }
+  }
+  if (resolved.isRunning) {
+    return;
+  }
+  await resolved.run();
+  if (resolved.address) {
+    const { host, port, path } = resolved.address;
+    process.stderr.write(`listening on http://${host}:${port}${path}
+`);
+  }
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+//# sourceMappingURL=entrypoint-runtime.cjs.map

package/dist/cli/entrypoint-runtime.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/entrypoint-runtime.ts"],"sourcesContent":["/**\n * Entrypoint bootstrap — spawned by the CLI (`run`, `inspect`, `list`, `call`,\n * `dev inspector`) instead of the user's server file directly.\n *\n * This mirrors Python FastMCP's `FileSystemSource` entrypoint resolution\n * (`fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py`): import the\n * user's file, resolve a named export (or a factory function that returns a\n * server), and start it. Keeping this in a spawned subprocess (rather than\n * importing the user's file in the CLI's own process) preserves two things the\n * existing CLI already relies on: `tsx` transpilation for TypeScript files, and\n * process isolation so a crashing user server doesn't take down the CLI.\n *\n * Contract (set by the parent CLI process via environment variables):\n *   - FASTMCP_ENTRYPOINT_FILE: absolute path to the user's server file (required)\n *   - FASTMCP_ENTRYPOINT_EXPORT: export name to resolve. Omitted when the user\n *     didn't specify one, in which case a conventional name is auto-detected.\n *\n * Resolution order when FASTMCP_ENTRYPOINT_EXPORT is not set:\n *   `default`, `mcp`, `server`, `app` — the first of these that is already a\n *   FastMCP instance wins. Auto-detection deliberately does NOT call factory\n *   functions (mirroring Python FastMCP's `_find_server_object`, which only\n *   resolves factories for an explicit entrypoint) — invoking an arbitrary\n *   exported function as a side effect of guessing a name would be surprising,\n *   and a name match that isn't a FastMCP instance is skipped in favor of the\n *   next candidate rather than committing to it. Factory functions are only\n *   resolved when the export name is given explicitly (`file:export` or\n *   `--export`).\n *\n * Backwards compatibility: if no explicit export was requested and none of the\n * conventional names resolve to a valid entrypoint, this script assumes the\n * file already started its own server via top-level side effects (the\n * historical fastmcp-ts contract, e.g. `server.run()` at module scope) and\n * exits without error. An explicit export request that can't be resolved is\n * always a hard error.\n */\n\nimport { pathToFileURL } from 'node:url'\n\nconst AUTO_DETECT_NAMES = ['default', 'mcp', 'server', 'app']\n\ninterface RunnableFastMCP {\n  run(): Promise<void>\n  isRunning: boolean\n  address: { host: string; port: number; path: string } | null\n}\n\nfunction isFastMCPInstance(value: unknown): value is RunnableFastMCP {\n  if (!value || typeof value !== 'object') return false\n  const obj = value as Record<string, unknown>\n  return (\n    typeof obj['run'] === 'function' &&\n    typeof obj['tool'] === 'function' &&\n    typeof obj['resource'] === 'function' &&\n    typeof obj['prompt'] === 'function' &&\n    typeof obj['connect'] === 'function'\n  )\n}\n\nfunction describe(value: unknown): string {\n  if (value === null) return 'null'\n  if (Array.isArray(value)) return 'an array'\n  return `a ${typeof value}`\n}\n\nfunction fail(message: string): never {\n  console.error(`fastmcp: ${message}`)\n  process.exit(1)\n}\n\nasync function resolveFactory(\n  value: unknown,\n  exportName: string,\n  filePath: string,\n): Promise<unknown> {\n  if (typeof value !== 'function') return value\n  try {\n    return await (value as () => unknown)()\n  } catch (err) {\n    fail(\n      `Failed to call entrypoint factory \"${exportName}\" in ${filePath}: ` +\n        (err instanceof Error ? err.message : String(err)),\n    )\n  }\n}\n\nasync function main(): Promise<void> {\n  const filePath = process.env['FASTMCP_ENTRYPOINT_FILE']\n  if (!filePath) {\n    fail('internal error: FASTMCP_ENTRYPOINT_FILE was not set for the entrypoint bootstrap')\n  }\n\n  const explicitExport = process.env['FASTMCP_ENTRYPOINT_EXPORT']\n\n  let mod: Record<string, unknown>\n  try {\n    mod = (await import(pathToFileURL(filePath).href)) as Record<string, unknown>\n  } catch (err) {\n    fail(\n      `Failed to load entrypoint file \"${filePath}\": ` +\n        (err instanceof Error ? (err.stack ?? err.message) : String(err)),\n    )\n  }\n\n  let resolved: RunnableFastMCP | undefined\n\n  if (explicitExport) {\n    if (!(explicitExport in mod)) {\n      const available = Object.keys(mod).filter((k) => k !== '__esModule')\n      fail(\n        `Entrypoint export \"${explicitExport}\" not found in ${filePath}.` +\n          (available.length > 0\n            ? ` Available exports: ${available.join(', ')}.`\n            : ' The file has no exports.'),\n      )\n    }\n    const target = await resolveFactory(mod[explicitExport], explicitExport, filePath)\n    if (!isFastMCPInstance(target)) {\n      fail(\n        `Entrypoint export \"${explicitExport}\" in ${filePath} is not a FastMCP server ` +\n          `(or a function that returns one). Got ${describe(target)}.`,\n      )\n    }\n    resolved = target\n  } else {\n    for (const name of AUTO_DETECT_NAMES) {\n      if (!(name in mod)) continue\n      const candidate = mod[name]\n      // Only a direct FastMCP instance is auto-detected — a name match that\n      // isn't one (including a function, which would require calling it) is\n      // skipped in favor of the next conventional name rather than erroring\n      // or invoking it speculatively.\n      if (isFastMCPInstance(candidate)) {\n        resolved = candidate\n        break\n      }\n    }\n    if (resolved === undefined) {\n      // No conventional export resolved to a FastMCP instance. Assume this is\n      // a legacy self-running file (it started its own server via top-level\n      // side effects when imported above) and exit quietly.\n      return\n    }\n  }\n\n  if (resolved.isRunning) {\n    // The file already started this server itself (e.g. a top-level\n    // `server.run()` call) before we got a chance to. Don't start it twice.\n    return\n  }\n\n  await resolved.run()\n\n  // Mirrors the \"listening on <url>\" line the raw-SDK CLI test fixtures print\n  // themselves — FastMCP's own run() doesn't emit a startup banner, but the\n  // CLI's `run` command watches stderr for this text to detect a successful\n  // HTTP start (see spawnServer()'s \"started\" detection in commands/run.ts).\n  if (resolved.address) {\n    const { host, port, path } = resolved.address\n    process.stderr.write(`listening on http://${host}:${port}${path}\\n`)\n  }\n}\n\nmain().catch((err) => {\n  console.error(err)\n  process.exit(1)\n})\n"],"mappings":";;;;AAoCA,sBAA8B;AAE9B,IAAM,oBAAoB,CAAC,WAAW,OAAO,UAAU,KAAK;AAQ5D,SAAS,kBAAkB,OAA0C;AACnE,MAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO;AAChD,QAAM,MAAM;AACZ,SACE,OAAO,IAAI,KAAK,MAAM,cACtB,OAAO,IAAI,MAAM,MAAM,cACvB,OAAO,IAAI,UAAU,MAAM,cAC3B,OAAO,IAAI,QAAQ,MAAM,cACzB,OAAO,IAAI,SAAS,MAAM;AAE9B;AAEA,SAAS,SAAS,OAAwB;AACxC,MAAI,UAAU,KAAM,QAAO;AAC3B,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO;AACjC,SAAO,KAAK,OAAO,KAAK;AAC1B;AAEA,SAAS,KAAK,SAAwB;AACpC,UAAQ,MAAM,YAAY,OAAO,EAAE;AACnC,UAAQ,KAAK,CAAC;AAChB;AAEA,eAAe,eACb,OACA,YACA,UACkB;AAClB,MAAI,OAAO,UAAU,WAAY,QAAO;AACxC,MAAI;AACF,WAAO,MAAO,MAAwB;AAAA,EACxC,SAAS,KAAK;AACZ;AAAA,MACE,sCAAsC,UAAU,QAAQ,QAAQ,QAC7D,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,IACpD;AAAA,EACF;AACF;AAEA,eAAe,OAAsB;AACnC,QAAM,WAAW,QAAQ,IAAI,yBAAyB;AACtD,MAAI,CAAC,UAAU;AACb,SAAK,kFAAkF;AAAA,EACzF;AAEA,QAAM,iBAAiB,QAAQ,IAAI,2BAA2B;AAE9D,MAAI;AACJ,MAAI;AACF,UAAO,MAAM,WAAO,+BAAc,QAAQ,EAAE;AAAA,EAC9C,SAAS,KAAK;AACZ;AAAA,MACE,mCAAmC,QAAQ,SACxC,eAAe,QAAS,IAAI,SAAS,IAAI,UAAW,OAAO,GAAG;AAAA,IACnE;AAAA,EACF;AAEA,MAAI;AAEJ,MAAI,gBAAgB;AAClB,QAAI,EAAE,kBAAkB,MAAM;AAC5B,YAAM,YAAY,OAAO,KAAK,GAAG,EAAE,OAAO,CAAC,MAAM,MAAM,YAAY;AACnE;AAAA,QACE,sBAAsB,cAAc,kBAAkB,QAAQ,OAC3D,UAAU,SAAS,IAChB,uBAAuB,UAAU,KAAK,IAAI,CAAC,MAC3C;AAAA,MACR;AAAA,IACF;AACA,UAAM,SAAS,MAAM,eAAe,IAAI,cAAc,GAAG,gBAAgB,QAAQ;AACjF,QAAI,CAAC,kBAAkB,MAAM,GAAG;AAC9B;AAAA,QACE,sBAAsB,cAAc,QAAQ,QAAQ,kEACT,SAAS,MAAM,CAAC;AAAA,MAC7D;AAAA,IACF;AACA,eAAW;AAAA,EACb,OAAO;AACL,eAAW,QAAQ,mBAAmB;AACpC,UAAI,EAAE,QAAQ,KAAM;AACpB,YAAM,YAAY,IAAI,IAAI;AAK1B,UAAI,kBAAkB,SAAS,GAAG;AAChC,mBAAW;AACX;AAAA,MACF;AAAA,IACF;AACA,QAAI,aAAa,QAAW;AAI1B;AAAA,IACF;AAAA,EACF;AAEA,MAAI,SAAS,WAAW;AAGtB;AAAA,EACF;AAEA,QAAM,SAAS,IAAI;AAMnB,MAAI,SAAS,SAAS;AACpB,UAAM,EAAE,MAAM,MAAM,KAAK,IAAI,SAAS;AACtC,YAAQ,OAAO,MAAM,uBAAuB,IAAI,IAAI,IAAI,GAAG,IAAI;AAAA,CAAI;AAAA,EACrE;AACF;AAEA,KAAK,EAAE,MAAM,CAAC,QAAQ;AACpB,UAAQ,MAAM,GAAG;AACjB,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}