fastmcp 4.9.1 → 4.10.0

package/README.md

@@ -594,6 +594,48 @@ server.addTool({
 });
 ```
 
+**Plain JSON Schema Example:**
+
+If you already have a JSON Schema — from an OpenAPI document, a config file, or
+another server — `jsonSchemaAdapter` wraps it so it can be used directly, with
+no schema library in between.
+
+It requires the peer dependency `ajv`, which does the validation, plus
+`ajv-formats` if your schema uses `format` keywords such as `email` or `uri`.
+Both are imported the first time a tool is called, so servers that don't use
+this pay nothing for it.
+
+```bash
+npm install ajv ajv-formats
+```
+
+```typescript
+import { jsonSchemaAdapter } from "fastmcp";
+
+server.addTool({
+  name: "fetch-json-schema",
+  description: "Fetch the content of a url (using plain JSON Schema)",
+  parameters: jsonSchemaAdapter({
+    type: "object",
+    properties: {
+      url: { type: "string", format: "uri" },
+    },
+    required: ["url"],
+  }),
+  execute: async (args) => {
+    const { url } = args as { url: string };
+    return await fetchWebpageContent(url);
+  },
+});
+```
+
+Works for `outputSchema` too. Note that FastMCP advertises every tool schema
+with `additionalProperties: false`, whatever your schema said — the same
+treatment Zod and Valibot schemas get.
+
+Unlike the schema libraries above, a plain JSON Schema carries no TypeScript
+types, so `execute` receives `unknown` arguments. Cast or narrow them yourself.
+
 #### Tools Without Parameters
 
 When creating tools that don't require parameters, you have two options:

package/dist/FastMCP.cjs

@@ -7,7 +7,8 @@
 
 
 
-var _chunkMJCWKCHZcjs = require('./chunk-MJCWKCHZ.cjs');
+
+var _chunkGF4ORBWZcjs = require('./chunk-GF4ORBWZ.cjs');
 
 
 
@@ -41,5 +42,6 @@ var _chunkDZYT6QAHcjs = require('./chunk-DZYT6QAH.cjs');
 
 
 
-exports.AuthProvider = _chunkDZYT6QAHcjs.AuthProvider; exports.AzureProvider = _chunkDZYT6QAHcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkMJCWKCHZcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkMJCWKCHZcjs.FastMCP; exports.FastMCPSession = _chunkMJCWKCHZcjs.FastMCPSession; exports.GitHubProvider = _chunkDZYT6QAHcjs.GitHubProvider; exports.GoogleProvider = _chunkDZYT6QAHcjs.GoogleProvider; exports.OAuthProvider = _chunkDZYT6QAHcjs.OAuthProvider; exports.ServerState = _chunkMJCWKCHZcjs.ServerState; exports.UnexpectedStateError = _chunkMJCWKCHZcjs.UnexpectedStateError; exports.UserError = _chunkMJCWKCHZcjs.UserError; exports.audioContent = _chunkMJCWKCHZcjs.audioContent; exports.getAuthSession = _chunkDZYT6QAHcjs.getAuthSession; exports.imageContent = _chunkMJCWKCHZcjs.imageContent; exports.requireAll = _chunkDZYT6QAHcjs.requireAll; exports.requireAny = _chunkDZYT6QAHcjs.requireAny; exports.requireAuth = _chunkDZYT6QAHcjs.requireAuth; exports.requireRole = _chunkDZYT6QAHcjs.requireRole; exports.requireScopes = _chunkDZYT6QAHcjs.requireScopes;
+
+exports.AuthProvider = _chunkDZYT6QAHcjs.AuthProvider; exports.AzureProvider = _chunkDZYT6QAHcjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkGF4ORBWZcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkGF4ORBWZcjs.FastMCP; exports.FastMCPSession = _chunkGF4ORBWZcjs.FastMCPSession; exports.GitHubProvider = _chunkDZYT6QAHcjs.GitHubProvider; exports.GoogleProvider = _chunkDZYT6QAHcjs.GoogleProvider; exports.OAuthProvider = _chunkDZYT6QAHcjs.OAuthProvider; exports.ServerState = _chunkGF4ORBWZcjs.ServerState; exports.UnexpectedStateError = _chunkGF4ORBWZcjs.UnexpectedStateError; exports.UserError = _chunkGF4ORBWZcjs.UserError; exports.audioContent = _chunkGF4ORBWZcjs.audioContent; exports.getAuthSession = _chunkDZYT6QAHcjs.getAuthSession; exports.imageContent = _chunkGF4ORBWZcjs.imageContent; exports.jsonSchemaAdapter = _chunkGF4ORBWZcjs.jsonSchemaAdapter; exports.requireAll = _chunkDZYT6QAHcjs.requireAll; exports.requireAny = _chunkDZYT6QAHcjs.requireAny; exports.requireAuth = _chunkDZYT6QAHcjs.requireAuth; exports.requireRole = _chunkDZYT6QAHcjs.requireRole; exports.requireScopes = _chunkDZYT6QAHcjs.requireScopes;
 //# sourceMappingURL=FastMCP.cjs.map

package/dist/FastMCP.cjs.map

@@ -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,gjCAAC","file":"/home/runner/work/fastmcp/fastmcp/dist/FastMCP.cjs"}
+{"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

@@ -47,6 +47,71 @@ declare class DiscoveryDocumentCache {
     has(url: string): boolean;
 }
 
+/**
+ * A plain JSON Schema object descriptor.
+ */
+type JsonSchemaObject = {
+    [key: string]: unknown;
+    $schema?: string;
+    additionalProperties?: boolean;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    type: string;
+};
+/**
+ * A Standard Schema that also carries the JSON Schema it was built from.
+ *
+ * `~standard.jsonSchema` is the Standard JSON Schema extension. Anything that
+ * knows about it — including the `xsschema` conversion FastMCP uses to build
+ * `tools/list` — reads the schema straight off the object instead of trying to
+ * derive one from a validation library it does not recognise.
+ */
+interface JsonSchemaStandardSchema extends StandardSchemaV1 {
+    readonly "~standard": {
+        readonly jsonSchema: {
+            readonly input: () => JsonSchemaObject;
+            readonly output: () => JsonSchemaObject;
+        };
+    } & StandardSchemaV1.Props;
+}
+/**
+ * Wraps a plain JSON Schema object so it can be used as a tool's `parameters`
+ * or `outputSchema`, without pulling in Zod, Valibot, or another validation
+ * library.
+ *
+ * Validation uses AJV, which is an optional peer dependency — install `ajv`
+ * (and `ajv-formats` if you use `format` keywords) to use this. It is imported
+ * on first validation, so servers that never call this pay nothing for it.
+ *
+ * Note that FastMCP applies the same strictness to every tool schema: objects
+ * are advertised with `additionalProperties: false`, whatever the input schema
+ * said.
+ *
+ * @example
+ * ```ts
+ * import { FastMCP, jsonSchemaAdapter } from "fastmcp";
+ *
+ * const server = new FastMCP({ name: "Example", version: "1.0.0" });
+ *
+ * server.addTool({
+ *   name: "greet",
+ *   description: "Greet a user",
+ *   parameters: jsonSchemaAdapter({
+ *     type: "object",
+ *     properties: {
+ *       name: { type: "string" },
+ *     },
+ *     required: ["name"],
+ *   }),
+ *   execute: async ({ name }) => `Hello, ${name}!`,
+ * });
+ * ```
+ *
+ * @param schema - A plain JSON Schema object
+ * @returns A Standard Schema that validates against `schema`
+ */
+declare function jsonSchemaAdapter(schema: JsonSchemaObject): JsonSchemaStandardSchema;
+
 interface Logger {
     debug(...args: unknown[]): void;
     error(...args: unknown[]): void;
@@ -726,7 +791,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
     get server(): Server;
     get sessionId(): string | undefined;
     set sessionId(value: string | undefined);
-    constructor({ auth, instructions, logger, name, onToolCall, ping, prompts, resources, resourcesTemplates, roots, sessionId, tools, transportType, utils, version, }: {
+    constructor({ auth, instructions, logger, name, onToolCall, ping, prompts, resources, resourcesTemplates, roots, sessionId, stateless, tools, transportType, utils, version, }: {
         auth?: T;
         instructions?: string;
         logger: Logger;
@@ -738,6 +803,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
         resourcesTemplates: InputResourceTemplate<T>[];
         roots?: ServerOptions<T>["roots"];
         sessionId?: string;
+        stateless?: boolean;
         tools: Tool<T>[];
         transportType?: "httpStream" | "stdio";
         utils?: ServerOptions<T>["utils"];
@@ -919,4 +985,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
     stop(): Promise<void>;
 }
 
-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 };
+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

@@ -47,6 +47,71 @@ declare class DiscoveryDocumentCache {
     has(url: string): boolean;
 }
 
+/**
+ * A plain JSON Schema object descriptor.
+ */
+type JsonSchemaObject = {
+    [key: string]: unknown;
+    $schema?: string;
+    additionalProperties?: boolean;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    type: string;
+};
+/**
+ * A Standard Schema that also carries the JSON Schema it was built from.
+ *
+ * `~standard.jsonSchema` is the Standard JSON Schema extension. Anything that
+ * knows about it — including the `xsschema` conversion FastMCP uses to build
+ * `tools/list` — reads the schema straight off the object instead of trying to
+ * derive one from a validation library it does not recognise.
+ */
+interface JsonSchemaStandardSchema extends StandardSchemaV1 {
+    readonly "~standard": {
+        readonly jsonSchema: {
+            readonly input: () => JsonSchemaObject;
+            readonly output: () => JsonSchemaObject;
+        };
+    } & StandardSchemaV1.Props;
+}
+/**
+ * Wraps a plain JSON Schema object so it can be used as a tool's `parameters`
+ * or `outputSchema`, without pulling in Zod, Valibot, or another validation
+ * library.
+ *
+ * Validation uses AJV, which is an optional peer dependency — install `ajv`
+ * (and `ajv-formats` if you use `format` keywords) to use this. It is imported
+ * on first validation, so servers that never call this pay nothing for it.
+ *
+ * Note that FastMCP applies the same strictness to every tool schema: objects
+ * are advertised with `additionalProperties: false`, whatever the input schema
+ * said.
+ *
+ * @example
+ * ```ts
+ * import { FastMCP, jsonSchemaAdapter } from "fastmcp";
+ *
+ * const server = new FastMCP({ name: "Example", version: "1.0.0" });
+ *
+ * server.addTool({
+ *   name: "greet",
+ *   description: "Greet a user",
+ *   parameters: jsonSchemaAdapter({
+ *     type: "object",
+ *     properties: {
+ *       name: { type: "string" },
+ *     },
+ *     required: ["name"],
+ *   }),
+ *   execute: async ({ name }) => `Hello, ${name}!`,
+ * });
+ * ```
+ *
+ * @param schema - A plain JSON Schema object
+ * @returns A Standard Schema that validates against `schema`
+ */
+declare function jsonSchemaAdapter(schema: JsonSchemaObject): JsonSchemaStandardSchema;
+
 interface Logger {
     debug(...args: unknown[]): void;
     error(...args: unknown[]): void;
@@ -726,7 +791,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
     get server(): Server;
     get sessionId(): string | undefined;
     set sessionId(value: string | undefined);
-    constructor({ auth, instructions, logger, name, onToolCall, ping, prompts, resources, resourcesTemplates, roots, sessionId, tools, transportType, utils, version, }: {
+    constructor({ auth, instructions, logger, name, onToolCall, ping, prompts, resources, resourcesTemplates, roots, sessionId, stateless, tools, transportType, utils, version, }: {
         auth?: T;
         instructions?: string;
         logger: Logger;
@@ -738,6 +803,7 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
         resourcesTemplates: InputResourceTemplate<T>[];
         roots?: ServerOptions<T>["roots"];
         sessionId?: string;
+        stateless?: boolean;
         tools: Tool<T>[];
         transportType?: "httpStream" | "stdio";
         utils?: ServerOptions<T>["utils"];
@@ -919,4 +985,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
     stop(): Promise<void>;
 }
 
-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 };
+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

@@ -6,8 +6,9 @@ import {
   UnexpectedStateError,
   UserError,
   audioContent,
-  imageContent
-} from "./chunk-2PFUZL7I.js";
+  imageContent,
+  jsonSchemaAdapter
+} from "./chunk-MGP2FVUH.js";
 import {
   AuthProvider,
   AzureProvider,
@@ -36,6 +37,7 @@ export {
   audioContent,
   getAuthSession,
   imageContent,
+  jsonSchemaAdapter,
   requireAll,
   requireAny,
   requireAuth,