fastmcp 4.9.2 → 4.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -14
- package/dist/FastMCP.cjs +4 -2
- package/dist/FastMCP.cjs.map +1 -1
- package/dist/FastMCP.d.cts +94 -3
- package/dist/FastMCP.d.ts +94 -3
- package/dist/FastMCP.js +4 -2
- package/dist/{chunk-ENLYR3QM.cjs → chunk-ISO2WPB5.cjs} +113 -45
- package/dist/chunk-ISO2WPB5.cjs.map +1 -0
- package/dist/{chunk-JIPRWP6F.js → chunk-JOZJUFKE.js} +69 -1
- package/dist/chunk-JOZJUFKE.js.map +1 -0
- package/dist/examples/custom-routes.cjs +2 -2
- package/dist/examples/custom-routes.js +1 -1
- package/package.json +11 -1
- package/dist/chunk-ENLYR3QM.cjs.map +0 -1
- package/dist/chunk-JIPRWP6F.js.map +0 -1
package/README.md
CHANGED
|
@@ -594,6 +594,48 @@ server.addTool({
|
|
|
594
594
|
});
|
|
595
595
|
```
|
|
596
596
|
|
|
597
|
+
**Plain JSON Schema Example:**
|
|
598
|
+
|
|
599
|
+
If you already have a JSON Schema — from an OpenAPI document, a config file, or
|
|
600
|
+
another server — `jsonSchemaAdapter` wraps it so it can be used directly, with
|
|
601
|
+
no schema library in between.
|
|
602
|
+
|
|
603
|
+
It requires the peer dependency `ajv`, which does the validation, plus
|
|
604
|
+
`ajv-formats` if your schema uses `format` keywords such as `email` or `uri`.
|
|
605
|
+
Both are imported the first time a tool is called, so servers that don't use
|
|
606
|
+
this pay nothing for it.
|
|
607
|
+
|
|
608
|
+
```bash
|
|
609
|
+
npm install ajv ajv-formats
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
```typescript
|
|
613
|
+
import { jsonSchemaAdapter } from "fastmcp";
|
|
614
|
+
|
|
615
|
+
server.addTool({
|
|
616
|
+
name: "fetch-json-schema",
|
|
617
|
+
description: "Fetch the content of a url (using plain JSON Schema)",
|
|
618
|
+
parameters: jsonSchemaAdapter({
|
|
619
|
+
type: "object",
|
|
620
|
+
properties: {
|
|
621
|
+
url: { type: "string", format: "uri" },
|
|
622
|
+
},
|
|
623
|
+
required: ["url"],
|
|
624
|
+
}),
|
|
625
|
+
execute: async (args) => {
|
|
626
|
+
const { url } = args as { url: string };
|
|
627
|
+
return await fetchWebpageContent(url);
|
|
628
|
+
},
|
|
629
|
+
});
|
|
630
|
+
```
|
|
631
|
+
|
|
632
|
+
Works for `outputSchema` too. Note that FastMCP advertises every tool schema
|
|
633
|
+
with `additionalProperties: false`, whatever your schema said — the same
|
|
634
|
+
treatment Zod and Valibot schemas get.
|
|
635
|
+
|
|
636
|
+
Unlike the schema libraries above, a plain JSON Schema carries no TypeScript
|
|
637
|
+
types, so `execute` receives `unknown` arguments. Cast or narrow them yourself.
|
|
638
|
+
|
|
597
639
|
#### Tools Without Parameters
|
|
598
640
|
|
|
599
641
|
When creating tools that don't require parameters, you have two options:
|
|
@@ -1186,15 +1228,32 @@ server.addTool({
|
|
|
1186
1228
|
});
|
|
1187
1229
|
```
|
|
1188
1230
|
|
|
1231
|
+
`reportProgress` accepts an optional human-readable `message` alongside the numeric fields, which clients can display next to the progress indicator:
|
|
1232
|
+
|
|
1233
|
+
```js
|
|
1234
|
+
await reportProgress({
|
|
1235
|
+
progress: 40,
|
|
1236
|
+
total: 100,
|
|
1237
|
+
message: "Downloading chunk 4 of 10…",
|
|
1238
|
+
});
|
|
1239
|
+
```
|
|
1240
|
+
|
|
1241
|
+
Progress notifications are only emitted when the client opts in by supplying a `progressToken` on the tool call; otherwise `reportProgress` is a no-op. Because `notifications/progress` is part of the MCP specification (the `message` field since revision 2025-03-26), this is the portable way to send incremental updates during a long-running tool call — see [Streaming Output](#streaming-output) below for the difference.
|
|
1242
|
+
|
|
1189
1243
|
#### Streaming Output
|
|
1190
1244
|
|
|
1191
|
-
FastMCP
|
|
1245
|
+
FastMCP can stream partial results from tools while they're still executing, enabling responsive UIs and real-time feedback. This is particularly useful for:
|
|
1192
1246
|
|
|
1193
1247
|
- Long-running operations that generate content incrementally
|
|
1194
1248
|
- Progressive generation of text, images, or other media
|
|
1195
1249
|
- Operations where users benefit from seeing immediate partial results
|
|
1196
1250
|
|
|
1197
|
-
|
|
1251
|
+
> [!IMPORTANT]
|
|
1252
|
+
> `streamContent` is a **FastMCP extension, not part of the MCP specification**. It emits a `notifications/tool/streamContent` notification, which the MCP specification does not define — as of revision `2025-11-25` there is no standard mechanism for streaming tool output ([SEP-2998](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2998) is the in-progress proposal to add one).
|
|
1253
|
+
>
|
|
1254
|
+
> Clients discard notifications they have no handler registered for, silently and without error. A client only sees streamed content if it registers a handler for the method (or sets a `fallbackNotificationHandler`), and **no client is known to render it as tool output** — MCP Inspector, for example, logs it in its notifications pane via a fallback handler, but the tool result itself still shows only what `execute` returned. Streaming is therefore mainly useful when you also control the client — see [Consuming streamed content](#consuming-streamed-content) below. If you need incremental updates that work on any client, use [`reportProgress`](#progress) with a `message` instead.
|
|
1255
|
+
|
|
1256
|
+
To stream from a tool, use the `streamContent` method:
|
|
1198
1257
|
|
|
1199
1258
|
```js
|
|
1200
1259
|
server.addTool({
|
|
@@ -1204,7 +1263,7 @@ server.addTool({
|
|
|
1204
1263
|
prompt: z.string(),
|
|
1205
1264
|
}),
|
|
1206
1265
|
annotations: {
|
|
1207
|
-
streamingHint: true, //
|
|
1266
|
+
streamingHint: true, // Advisory only; see below
|
|
1208
1267
|
readOnlyHint: true,
|
|
1209
1268
|
},
|
|
1210
1269
|
execute: async (args, { streamContent }) => {
|
|
@@ -1218,19 +1277,45 @@ server.addTool({
|
|
|
1218
1277
|
await new Promise((resolve) => setTimeout(resolve, 300)); // Simulate delay
|
|
1219
1278
|
}
|
|
1220
1279
|
|
|
1221
|
-
//
|
|
1222
|
-
//
|
|
1223
|
-
//
|
|
1280
|
+
// Always return a final result. Returning nothing sends an empty tool
|
|
1281
|
+
// result, so clients that ignore the streamed notifications see no output
|
|
1282
|
+
// at all.
|
|
1283
|
+
return "The quick brown fox jumps over the lazy dog.";
|
|
1284
|
+
},
|
|
1285
|
+
});
|
|
1286
|
+
```
|
|
1224
1287
|
|
|
1225
|
-
|
|
1226
|
-
|
|
1288
|
+
> [!WARNING]
|
|
1289
|
+
> Returning `undefined` from `execute` produces a tool result with empty `content`. If you stream everything and return nothing, the tool call resolves to an empty result with no indication that anything was lost — including on clients that do log the notification. Return the complete result as well, and treat streamed content purely as a progressive-rendering enhancement.
|
|
1227
1290
|
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1291
|
+
The `streamingHint` annotation is advisory metadata. It is forwarded verbatim to clients in `tools/list`, but it does not enable or gate `streamContent`, and FastMCP itself never reads it. No client is known to act on it today, though [SEP-2998](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2998) proposes standardizing the same annotation name.
|
|
1292
|
+
|
|
1293
|
+
##### Consuming streamed content
|
|
1294
|
+
|
|
1295
|
+
A client sees these notifications only if it registers a handler for the method (or sets a `fallbackNotificationHandler`):
|
|
1296
|
+
|
|
1297
|
+
```ts
|
|
1298
|
+
import { z } from "zod";
|
|
1299
|
+
|
|
1300
|
+
const StreamContentNotificationSchema = z.object({
|
|
1301
|
+
method: z.literal("notifications/tool/streamContent"),
|
|
1302
|
+
params: z.object({
|
|
1303
|
+
content: z.array(z.any()),
|
|
1304
|
+
toolName: z.string(),
|
|
1305
|
+
}),
|
|
1231
1306
|
});
|
|
1307
|
+
|
|
1308
|
+
client.setNotificationHandler(
|
|
1309
|
+
StreamContentNotificationSchema,
|
|
1310
|
+
(notification) => {
|
|
1311
|
+
const { content, toolName } = notification.params;
|
|
1312
|
+
// Render the partial content however you like.
|
|
1313
|
+
},
|
|
1314
|
+
);
|
|
1232
1315
|
```
|
|
1233
1316
|
|
|
1317
|
+
Note that notifications carry only `toolName`, not a request or progress token, so concurrent calls to the same tool on one session cannot be told apart.
|
|
1318
|
+
|
|
1234
1319
|
Streaming works with all content types (text, image, audio) and can be combined with progress reporting:
|
|
1235
1320
|
|
|
1236
1321
|
```js
|
|
@@ -1247,10 +1332,14 @@ server.addTool({
|
|
|
1247
1332
|
const total = args.datasetSize;
|
|
1248
1333
|
|
|
1249
1334
|
for (let i = 0; i < total; i++) {
|
|
1250
|
-
//
|
|
1251
|
-
await reportProgress({
|
|
1335
|
+
// Standard progress notification: reaches every spec-compliant client
|
|
1336
|
+
await reportProgress({
|
|
1337
|
+
progress: i,
|
|
1338
|
+
total,
|
|
1339
|
+
message: `Processed ${i} of ${total} items`,
|
|
1340
|
+
});
|
|
1252
1341
|
|
|
1253
|
-
//
|
|
1342
|
+
// Richer partial content: only reaches clients that opt in
|
|
1254
1343
|
if (i % 10 === 0) {
|
|
1255
1344
|
await streamContent({
|
|
1256
1345
|
type: "text",
|
package/dist/FastMCP.cjs
CHANGED
|
@@ -7,7 +7,8 @@
|
|
|
7
7
|
|
|
8
8
|
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
|
|
11
|
+
var _chunkISO2WPB5cjs = require('./chunk-ISO2WPB5.cjs');
|
|
11
12
|
|
|
12
13
|
|
|
13
14
|
|
|
@@ -41,5 +42,6 @@ var _chunkDZYT6QAHcjs = require('./chunk-DZYT6QAH.cjs');
|
|
|
41
42
|
|
|
42
43
|
|
|
43
44
|
|
|
44
|
-
|
|
45
|
+
|
|
46
|
+
exports.AuthProvider = _chunkDZYT6QAHcjs.AuthProvider; exports.AzureProvider = _chunkDZYT6QAHcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkISO2WPB5cjs.DiscoveryDocumentCache; exports.FastMCP = _chunkISO2WPB5cjs.FastMCP; exports.FastMCPSession = _chunkISO2WPB5cjs.FastMCPSession; exports.GitHubProvider = _chunkDZYT6QAHcjs.GitHubProvider; exports.GoogleProvider = _chunkDZYT6QAHcjs.GoogleProvider; exports.OAuthProvider = _chunkDZYT6QAHcjs.OAuthProvider; exports.ServerState = _chunkISO2WPB5cjs.ServerState; exports.UnexpectedStateError = _chunkISO2WPB5cjs.UnexpectedStateError; exports.UserError = _chunkISO2WPB5cjs.UserError; exports.audioContent = _chunkISO2WPB5cjs.audioContent; exports.getAuthSession = _chunkDZYT6QAHcjs.getAuthSession; exports.imageContent = _chunkISO2WPB5cjs.imageContent; exports.jsonSchemaAdapter = _chunkISO2WPB5cjs.jsonSchemaAdapter; exports.requireAll = _chunkDZYT6QAHcjs.requireAll; exports.requireAny = _chunkDZYT6QAHcjs.requireAny; exports.requireAuth = _chunkDZYT6QAHcjs.requireAuth; exports.requireRole = _chunkDZYT6QAHcjs.requireRole; exports.requireScopes = _chunkDZYT6QAHcjs.requireScopes;
|
|
45
47
|
//# sourceMappingURL=FastMCP.cjs.map
|
package/dist/FastMCP.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["/home/runner/work/fastmcp/fastmcp/dist/FastMCP.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,
|
|
1
|
+
{"version":3,"sources":["/home/runner/work/fastmcp/fastmcp/dist/FastMCP.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,inCAAC","file":"/home/runner/work/fastmcp/fastmcp/dist/FastMCP.cjs"}
|
package/dist/FastMCP.d.cts
CHANGED
|
@@ -47,6 +47,71 @@ declare class DiscoveryDocumentCache {
|
|
|
47
47
|
has(url: string): boolean;
|
|
48
48
|
}
|
|
49
49
|
|
|
50
|
+
/**
|
|
51
|
+
* A plain JSON Schema object descriptor.
|
|
52
|
+
*/
|
|
53
|
+
type JsonSchemaObject = {
|
|
54
|
+
[key: string]: unknown;
|
|
55
|
+
$schema?: string;
|
|
56
|
+
additionalProperties?: boolean;
|
|
57
|
+
properties?: Record<string, unknown>;
|
|
58
|
+
required?: string[];
|
|
59
|
+
type: string;
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* A Standard Schema that also carries the JSON Schema it was built from.
|
|
63
|
+
*
|
|
64
|
+
* `~standard.jsonSchema` is the Standard JSON Schema extension. Anything that
|
|
65
|
+
* knows about it — including the `xsschema` conversion FastMCP uses to build
|
|
66
|
+
* `tools/list` — reads the schema straight off the object instead of trying to
|
|
67
|
+
* derive one from a validation library it does not recognise.
|
|
68
|
+
*/
|
|
69
|
+
interface JsonSchemaStandardSchema extends StandardSchemaV1 {
|
|
70
|
+
readonly "~standard": {
|
|
71
|
+
readonly jsonSchema: {
|
|
72
|
+
readonly input: () => JsonSchemaObject;
|
|
73
|
+
readonly output: () => JsonSchemaObject;
|
|
74
|
+
};
|
|
75
|
+
} & StandardSchemaV1.Props;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Wraps a plain JSON Schema object so it can be used as a tool's `parameters`
|
|
79
|
+
* or `outputSchema`, without pulling in Zod, Valibot, or another validation
|
|
80
|
+
* library.
|
|
81
|
+
*
|
|
82
|
+
* Validation uses AJV, which is an optional peer dependency — install `ajv`
|
|
83
|
+
* (and `ajv-formats` if you use `format` keywords) to use this. It is imported
|
|
84
|
+
* on first validation, so servers that never call this pay nothing for it.
|
|
85
|
+
*
|
|
86
|
+
* Note that FastMCP applies the same strictness to every tool schema: objects
|
|
87
|
+
* are advertised with `additionalProperties: false`, whatever the input schema
|
|
88
|
+
* said.
|
|
89
|
+
*
|
|
90
|
+
* @example
|
|
91
|
+
* ```ts
|
|
92
|
+
* import { FastMCP, jsonSchemaAdapter } from "fastmcp";
|
|
93
|
+
*
|
|
94
|
+
* const server = new FastMCP({ name: "Example", version: "1.0.0" });
|
|
95
|
+
*
|
|
96
|
+
* server.addTool({
|
|
97
|
+
* name: "greet",
|
|
98
|
+
* description: "Greet a user",
|
|
99
|
+
* parameters: jsonSchemaAdapter({
|
|
100
|
+
* type: "object",
|
|
101
|
+
* properties: {
|
|
102
|
+
* name: { type: "string" },
|
|
103
|
+
* },
|
|
104
|
+
* required: ["name"],
|
|
105
|
+
* }),
|
|
106
|
+
* execute: async ({ name }) => `Hello, ${name}!`,
|
|
107
|
+
* });
|
|
108
|
+
* ```
|
|
109
|
+
*
|
|
110
|
+
* @param schema - A plain JSON Schema object
|
|
111
|
+
* @returns A Standard Schema that validates against `schema`
|
|
112
|
+
*/
|
|
113
|
+
declare function jsonSchemaAdapter(schema: JsonSchemaObject): JsonSchemaStandardSchema;
|
|
114
|
+
|
|
50
115
|
interface Logger {
|
|
51
116
|
debug(...args: unknown[]): void;
|
|
52
117
|
error(...args: unknown[]): void;
|
|
@@ -120,6 +185,22 @@ type Context<T extends FastMCPSessionAuth> = {
|
|
|
120
185
|
* counters, or maintain user-specific data across multiple requests.
|
|
121
186
|
*/
|
|
122
187
|
sessionId?: string;
|
|
188
|
+
/**
|
|
189
|
+
* Streams incremental content while the tool is still executing, by emitting
|
|
190
|
+
* a `notifications/tool/streamContent` notification.
|
|
191
|
+
*
|
|
192
|
+
* NOTE: this is a FastMCP extension, not part of the MCP specification. As of
|
|
193
|
+
* revision 2025-11-25 the spec has no streaming tool output primitive (see
|
|
194
|
+
* SEP-2998 for the in-progress proposal). A client only receives these
|
|
195
|
+
* notifications if it registers a handler for the method or sets a
|
|
196
|
+
* `fallbackNotificationHandler`; otherwise the SDK drops them silently. No
|
|
197
|
+
* client is known to render them as tool output.
|
|
198
|
+
*
|
|
199
|
+
* Always return a final result from `execute` rather than relying on streamed
|
|
200
|
+
* content alone, otherwise clients that ignore the notification see an empty
|
|
201
|
+
* tool result. For incremental status that works everywhere, prefer
|
|
202
|
+
* {@link Context.reportProgress} with a `message`.
|
|
203
|
+
*/
|
|
123
204
|
streamContent: (content: Content | Content[]) => Promise<void>;
|
|
124
205
|
};
|
|
125
206
|
type Extra = unknown;
|
|
@@ -134,6 +215,13 @@ type Literal = boolean | null | number | string | undefined;
|
|
|
134
215
|
*/
|
|
135
216
|
type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "streamContent">;
|
|
136
217
|
type Progress = {
|
|
218
|
+
/**
|
|
219
|
+
* An optional human-readable message describing the current progress.
|
|
220
|
+
*
|
|
221
|
+
* Part of `notifications/progress` since MCP revision 2025-03-26, so unlike
|
|
222
|
+
* `streamContent` this reaches any spec-compliant client.
|
|
223
|
+
*/
|
|
224
|
+
message?: string;
|
|
137
225
|
/**
|
|
138
226
|
* The progress thus far. This should increase every time progress is made, even if the total is unknown.
|
|
139
227
|
*/
|
|
@@ -616,8 +704,11 @@ type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolPara
|
|
|
616
704
|
};
|
|
617
705
|
annotations?: {
|
|
618
706
|
/**
|
|
619
|
-
*
|
|
620
|
-
*
|
|
707
|
+
* Advisory metadata signalling that the tool streams incremental content
|
|
708
|
+
* via {@link Context.streamContent}. Forwarded verbatim in `tools/list`.
|
|
709
|
+
*
|
|
710
|
+
* This has no effect on FastMCP's behavior: it neither enables nor is
|
|
711
|
+
* required by `streamContent`. No known client interprets it today.
|
|
621
712
|
*/
|
|
622
713
|
streamingHint?: boolean;
|
|
623
714
|
} & ToolAnnotations;
|
|
@@ -920,4 +1011,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
|
|
|
920
1011
|
stop(): Promise<void>;
|
|
921
1012
|
}
|
|
922
1013
|
|
|
923
|
-
export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };
|
|
1014
|
+
export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type JsonSchemaObject, type JsonSchemaStandardSchema, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent, jsonSchemaAdapter };
|
package/dist/FastMCP.d.ts
CHANGED
|
@@ -47,6 +47,71 @@ declare class DiscoveryDocumentCache {
|
|
|
47
47
|
has(url: string): boolean;
|
|
48
48
|
}
|
|
49
49
|
|
|
50
|
+
/**
|
|
51
|
+
* A plain JSON Schema object descriptor.
|
|
52
|
+
*/
|
|
53
|
+
type JsonSchemaObject = {
|
|
54
|
+
[key: string]: unknown;
|
|
55
|
+
$schema?: string;
|
|
56
|
+
additionalProperties?: boolean;
|
|
57
|
+
properties?: Record<string, unknown>;
|
|
58
|
+
required?: string[];
|
|
59
|
+
type: string;
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* A Standard Schema that also carries the JSON Schema it was built from.
|
|
63
|
+
*
|
|
64
|
+
* `~standard.jsonSchema` is the Standard JSON Schema extension. Anything that
|
|
65
|
+
* knows about it — including the `xsschema` conversion FastMCP uses to build
|
|
66
|
+
* `tools/list` — reads the schema straight off the object instead of trying to
|
|
67
|
+
* derive one from a validation library it does not recognise.
|
|
68
|
+
*/
|
|
69
|
+
interface JsonSchemaStandardSchema extends StandardSchemaV1 {
|
|
70
|
+
readonly "~standard": {
|
|
71
|
+
readonly jsonSchema: {
|
|
72
|
+
readonly input: () => JsonSchemaObject;
|
|
73
|
+
readonly output: () => JsonSchemaObject;
|
|
74
|
+
};
|
|
75
|
+
} & StandardSchemaV1.Props;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Wraps a plain JSON Schema object so it can be used as a tool's `parameters`
|
|
79
|
+
* or `outputSchema`, without pulling in Zod, Valibot, or another validation
|
|
80
|
+
* library.
|
|
81
|
+
*
|
|
82
|
+
* Validation uses AJV, which is an optional peer dependency — install `ajv`
|
|
83
|
+
* (and `ajv-formats` if you use `format` keywords) to use this. It is imported
|
|
84
|
+
* on first validation, so servers that never call this pay nothing for it.
|
|
85
|
+
*
|
|
86
|
+
* Note that FastMCP applies the same strictness to every tool schema: objects
|
|
87
|
+
* are advertised with `additionalProperties: false`, whatever the input schema
|
|
88
|
+
* said.
|
|
89
|
+
*
|
|
90
|
+
* @example
|
|
91
|
+
* ```ts
|
|
92
|
+
* import { FastMCP, jsonSchemaAdapter } from "fastmcp";
|
|
93
|
+
*
|
|
94
|
+
* const server = new FastMCP({ name: "Example", version: "1.0.0" });
|
|
95
|
+
*
|
|
96
|
+
* server.addTool({
|
|
97
|
+
* name: "greet",
|
|
98
|
+
* description: "Greet a user",
|
|
99
|
+
* parameters: jsonSchemaAdapter({
|
|
100
|
+
* type: "object",
|
|
101
|
+
* properties: {
|
|
102
|
+
* name: { type: "string" },
|
|
103
|
+
* },
|
|
104
|
+
* required: ["name"],
|
|
105
|
+
* }),
|
|
106
|
+
* execute: async ({ name }) => `Hello, ${name}!`,
|
|
107
|
+
* });
|
|
108
|
+
* ```
|
|
109
|
+
*
|
|
110
|
+
* @param schema - A plain JSON Schema object
|
|
111
|
+
* @returns A Standard Schema that validates against `schema`
|
|
112
|
+
*/
|
|
113
|
+
declare function jsonSchemaAdapter(schema: JsonSchemaObject): JsonSchemaStandardSchema;
|
|
114
|
+
|
|
50
115
|
interface Logger {
|
|
51
116
|
debug(...args: unknown[]): void;
|
|
52
117
|
error(...args: unknown[]): void;
|
|
@@ -120,6 +185,22 @@ type Context<T extends FastMCPSessionAuth> = {
|
|
|
120
185
|
* counters, or maintain user-specific data across multiple requests.
|
|
121
186
|
*/
|
|
122
187
|
sessionId?: string;
|
|
188
|
+
/**
|
|
189
|
+
* Streams incremental content while the tool is still executing, by emitting
|
|
190
|
+
* a `notifications/tool/streamContent` notification.
|
|
191
|
+
*
|
|
192
|
+
* NOTE: this is a FastMCP extension, not part of the MCP specification. As of
|
|
193
|
+
* revision 2025-11-25 the spec has no streaming tool output primitive (see
|
|
194
|
+
* SEP-2998 for the in-progress proposal). A client only receives these
|
|
195
|
+
* notifications if it registers a handler for the method or sets a
|
|
196
|
+
* `fallbackNotificationHandler`; otherwise the SDK drops them silently. No
|
|
197
|
+
* client is known to render them as tool output.
|
|
198
|
+
*
|
|
199
|
+
* Always return a final result from `execute` rather than relying on streamed
|
|
200
|
+
* content alone, otherwise clients that ignore the notification see an empty
|
|
201
|
+
* tool result. For incremental status that works everywhere, prefer
|
|
202
|
+
* {@link Context.reportProgress} with a `message`.
|
|
203
|
+
*/
|
|
123
204
|
streamContent: (content: Content | Content[]) => Promise<void>;
|
|
124
205
|
};
|
|
125
206
|
type Extra = unknown;
|
|
@@ -134,6 +215,13 @@ type Literal = boolean | null | number | string | undefined;
|
|
|
134
215
|
*/
|
|
135
216
|
type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "streamContent">;
|
|
136
217
|
type Progress = {
|
|
218
|
+
/**
|
|
219
|
+
* An optional human-readable message describing the current progress.
|
|
220
|
+
*
|
|
221
|
+
* Part of `notifications/progress` since MCP revision 2025-03-26, so unlike
|
|
222
|
+
* `streamContent` this reaches any spec-compliant client.
|
|
223
|
+
*/
|
|
224
|
+
message?: string;
|
|
137
225
|
/**
|
|
138
226
|
* The progress thus far. This should increase every time progress is made, even if the total is unknown.
|
|
139
227
|
*/
|
|
@@ -616,8 +704,11 @@ type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolPara
|
|
|
616
704
|
};
|
|
617
705
|
annotations?: {
|
|
618
706
|
/**
|
|
619
|
-
*
|
|
620
|
-
*
|
|
707
|
+
* Advisory metadata signalling that the tool streams incremental content
|
|
708
|
+
* via {@link Context.streamContent}. Forwarded verbatim in `tools/list`.
|
|
709
|
+
*
|
|
710
|
+
* This has no effect on FastMCP's behavior: it neither enables nor is
|
|
711
|
+
* required by `streamContent`. No known client interprets it today.
|
|
621
712
|
*/
|
|
622
713
|
streamingHint?: boolean;
|
|
623
714
|
} & ToolAnnotations;
|
|
@@ -920,4 +1011,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
|
|
|
920
1011
|
stop(): Promise<void>;
|
|
921
1012
|
}
|
|
922
1013
|
|
|
923
|
-
export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };
|
|
1014
|
+
export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type JsonSchemaObject, type JsonSchemaStandardSchema, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent, jsonSchemaAdapter };
|
package/dist/FastMCP.js
CHANGED
|
@@ -6,8 +6,9 @@ import {
|
|
|
6
6
|
UnexpectedStateError,
|
|
7
7
|
UserError,
|
|
8
8
|
audioContent,
|
|
9
|
-
imageContent
|
|
10
|
-
|
|
9
|
+
imageContent,
|
|
10
|
+
jsonSchemaAdapter
|
|
11
|
+
} from "./chunk-JOZJUFKE.js";
|
|
11
12
|
import {
|
|
12
13
|
AuthProvider,
|
|
13
14
|
AzureProvider,
|
|
@@ -36,6 +37,7 @@ export {
|
|
|
36
37
|
audioContent,
|
|
37
38
|
getAuthSession,
|
|
38
39
|
imageContent,
|
|
40
|
+
jsonSchemaAdapter,
|
|
39
41
|
requireAll,
|
|
40
42
|
requireAny,
|
|
41
43
|
requireAuth,
|