@prefecthq/fastmcp-ts 0.1.0 → 1.0.0-rc.1

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 |