fastmcp 1.22.4 → 1.23.1

package/README.md

@@ -432,7 +432,6 @@ server.addTool({
 });
 ```
 
-
 #### Logging
 
 Tools can log messages to the client using the `log` object in the context object:
@@ -517,6 +516,40 @@ server.addTool({
 });
 ```
 
+#### Tool Annotations
+
+As of the MCP Specification (2025-03-26), tools can include annotations that provide richer context and control by adding metadata about a tool's behavior:
+
+```typescript
+server.addTool({
+  name: "fetch-content",
+  description: "Fetch content from a URL",
+  parameters: z.object({
+    url: z.string(),
+  }),
+  annotations: {
+    title: "Web Content Fetcher", // Human-readable title for UI display
+    readOnlyHint: true, // Tool doesn't modify its environment
+    openWorldHint: true, // Tool interacts with external entities
+  },
+  execute: async (args) => {
+    return await fetchWebpageContent(args.url);
+  },
+});
+```
+
+The available annotations are:
+
+| Annotation        | Type    | Default | Description                                                                                                                          |
+| :---------------- | :------ | :------ | :----------------------------------------------------------------------------------------------------------------------------------- |
+| `title`           | string  | -       | A human-readable title for the tool, useful for UI display                                                                           |
+| `readOnlyHint`    | boolean | `false` | If true, indicates the tool does not modify its environment                                                                          |
+| `destructiveHint` | boolean | `true`  | If true, the tool may perform destructive updates (only meaningful when `readOnlyHint` is false)                                     |
+| `idempotentHint`  | boolean | `false` | If true, calling the tool repeatedly with the same arguments has no additional effect (only meaningful when `readOnlyHint` is false) |
+| `openWorldHint`   | boolean | `true`  | If true, the tool may interact with an "open world" of external entities                                                             |
+
+These annotations help clients and LLMs better understand how to use the tools and what to expect when calling them.
+
 ### Resources
 
 [Resources](https://modelcontextprotocol.io/docs/concepts/resources) represent any kind of data that an MCP server wants to make available to clients. This can include:
@@ -712,10 +745,10 @@ import { AuthError } from "fastmcp";
 const server = new FastMCP({
   name: "My Server",
   version: "1.0.0",
-  authenticate: ({request}) => {
+  authenticate: ({ request }) => {
     const apiKey = request.headers["x-api-key"];
 
-    if (apiKey !== '123') {
+    if (apiKey !== "123") {
       throw new Response(null, {
         status: 401,
         statusText: "Unauthorized",
@@ -725,7 +758,7 @@ const server = new FastMCP({
     // Whatever you return here will be accessible in the `context.session` object.
     return {
       id: 1,
-    }
+    };
   },
 });
 ```
@@ -741,6 +774,19 @@ server.addTool({
 });
 ```
 
+### Providing Instructions
+
+You can provide instructions to the server using the `instructions` option:
+
+```ts
+const server = new FastMCP({
+  name: "My Server",
+  version: "1.0.0",
+  instructions:
+    'Instructions describing how to use the server and its features.\n\nThis can be used by clients to improve the LLM\'s understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.',
+});
+```
+
 ### Sessions
 
 The `session` object is an instance of `FastMCPSession` and it describes active client sessions.
@@ -870,10 +916,7 @@ Follow the guide https://modelcontextprotocol.io/quickstart/user and add the fol
   "mcpServers": {
     "my-mcp-server": {
       "command": "npx",
-      "args": [
-        "tsx",
-        "/PATH/TO/YOUR_PROJECT/src/index.ts"
-      ],
+      "args": ["tsx", "/PATH/TO/YOUR_PROJECT/src/index.ts"],
       "env": {
         "YOUR_ENV_VAR": "value"
       }

package/dist/FastMCP.d.ts

@@ -1,11 +1,11 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { AudioContent, Root, ClientCapabilities, CreateMessageRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { z } from 'zod';
-import { StrictEventEmitter } from 'strict-event-emitter-types';
 import { EventEmitter } from 'events';
-import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import http from 'http';
+import { StrictEventEmitter } from 'strict-event-emitter-types';
+import { z } from 'zod';
 
 type SSEServer = {
     close: () => Promise<void>;
@@ -19,49 +19,43 @@ type FastMCPEvents<T extends FastMCPSessionAuth> = {
     }) => void;
 };
 type FastMCPSessionEvents = {
-    rootsChanged: (event: {
-        roots: Root[];
-    }) => void;
     error: (event: {
         error: Error;
     }) => void;
+    rootsChanged: (event: {
+        roots: Root[];
+    }) => void;
 };
 /**
  * Generates an image content object from a URL, file path, or buffer.
  */
 declare const imageContent: (input: {
-    url: string;
+    buffer: Buffer;
 } | {
     path: string;
 } | {
-    buffer: Buffer;
+    url: string;
 }) => Promise<ImageContent>;
 declare const audioContent: (input: {
-    url: string;
+    buffer: Buffer;
 } | {
     path: string;
 } | {
-    buffer: Buffer;
+    url: string;
 }) => Promise<AudioContent>;
-declare abstract class FastMCPError extends Error {
-    constructor(message?: string);
-}
+type Context<T extends FastMCPSessionAuth> = {
+    log: {
+        debug: (message: string, data?: SerializableValue) => void;
+        error: (message: string, data?: SerializableValue) => void;
+        info: (message: string, data?: SerializableValue) => void;
+        warn: (message: string, data?: SerializableValue) => void;
+    };
+    reportProgress: (progress: Progress) => Promise<void>;
+    session: T | undefined;
+};
 type Extra = unknown;
 type Extras = Record<string, Extra>;
-declare class UnexpectedStateError extends FastMCPError {
-    extras?: Extras;
-    constructor(message: string, extras?: Extras);
-}
-/**
- * An error that is meant to be surfaced to the user.
- */
-declare class UserError extends UnexpectedStateError {
-}
-type ToolParameters = StandardSchemaV1;
 type Literal = boolean | null | number | string | undefined;
-type SerializableValue = Literal | SerializableValue[] | {
-    [key: string]: SerializableValue;
-};
 type Progress = {
     /**
      * The progress thus far. This should increase every time progress is made, even if the total is unknown.
@@ -72,93 +66,82 @@ type Progress = {
      */
     total?: number;
 };
-type Context<T extends FastMCPSessionAuth> = {
-    session: T | undefined;
-    reportProgress: (progress: Progress) => Promise<void>;
-    log: {
-        debug: (message: string, data?: SerializableValue) => void;
-        error: (message: string, data?: SerializableValue) => void;
-        info: (message: string, data?: SerializableValue) => void;
-        warn: (message: string, data?: SerializableValue) => void;
-    };
-};
+type SerializableValue = {
+    [key: string]: SerializableValue;
+} | Literal | SerializableValue[];
 type TextContent = {
-    type: "text";
     text: string;
+    type: "text";
 };
+type ToolParameters = StandardSchemaV1;
+declare abstract class FastMCPError extends Error {
+    constructor(message?: string);
+}
+declare class UnexpectedStateError extends FastMCPError {
+    extras?: Extras;
+    constructor(message: string, extras?: Extras);
+}
+/**
+ * An error that is meant to be surfaced to the user.
+ */
+declare class UserError extends UnexpectedStateError {
+}
 type ImageContent = {
-    type: "image";
     data: string;
     mimeType: string;
+    type: "image";
 };
-type Content = TextContent | ImageContent;
+type Content = ImageContent | TextContent;
 type ContentResult = {
     content: Content[];
     isError?: boolean;
 };
 type Completion = {
-    values: string[];
-    total?: number;
     hasMore?: boolean;
+    total?: number;
+    values: string[];
 };
-type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolParameters> = {
-    name: string;
+type ArgumentValueCompleter = (value: string) => Promise<Completion>;
+type InputPrompt<Arguments extends InputPromptArgument[] = InputPromptArgument[], Args = PromptArgumentsToObject<Arguments>> = {
+    arguments?: InputPromptArgument[];
     description?: string;
-    parameters?: Params;
-    execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<string | ContentResult | TextContent | ImageContent | AudioContent>;
-};
-type ResourceResult = {
-    text: string;
-} | {
-    blob: string;
-};
-type InputResourceTemplateArgument = Readonly<{
+    load: (args: Args) => Promise<string>;
     name: string;
-    description?: string;
+};
+type InputPromptArgument = Readonly<{
     complete?: ArgumentValueCompleter;
-}>;
-type ResourceTemplateArgument = Readonly<{
-    name: string;
     description?: string;
-    complete?: ArgumentValueCompleter;
-}>;
-type ResourceTemplate<Arguments extends ResourceTemplateArgument[] = ResourceTemplateArgument[]> = {
-    uriTemplate: string;
+    enum?: string[];
     name: string;
-    description?: string;
-    mimeType?: string;
+    required?: boolean;
+}>;
+type InputResourceTemplate<Arguments extends ResourceTemplateArgument[] = ResourceTemplateArgument[]> = {
     arguments: Arguments;
-    complete?: (name: string, value: string) => Promise<Completion>;
+    description?: string;
     load: (args: ResourceTemplateArgumentsToObject<Arguments>) => Promise<ResourceResult>;
-};
-type ResourceTemplateArgumentsToObject<T extends {
+    mimeType?: string;
     name: string;
-}[]> = {
-    [K in T[number]["name"]]: string;
-};
-type InputResourceTemplate<Arguments extends ResourceTemplateArgument[] = ResourceTemplateArgument[]> = {
     uriTemplate: string;
-    name: string;
-    description?: string;
-    mimeType?: string;
-    arguments: Arguments;
-    load: (args: ResourceTemplateArgumentsToObject<Arguments>) => Promise<ResourceResult>;
 };
-type Resource = {
-    uri: string;
-    name: string;
+type InputResourceTemplateArgument = Readonly<{
+    complete?: ArgumentValueCompleter;
     description?: string;
-    mimeType?: string;
-    load: () => Promise<ResourceResult | ResourceResult[]>;
-    complete?: (name: string, value: string) => Promise<Completion>;
-};
-type ArgumentValueCompleter = (value: string) => Promise<Completion>;
-type InputPromptArgument = Readonly<{
     name: string;
+}>;
+type LoggingLevel = "alert" | "critical" | "debug" | "emergency" | "error" | "info" | "notice" | "warning";
+type Prompt<Arguments extends PromptArgument[] = PromptArgument[], Args = PromptArgumentsToObject<Arguments>> = {
+    arguments?: PromptArgument[];
+    complete?: (name: string, value: string) => Promise<Completion>;
     description?: string;
-    required?: boolean;
+    load: (args: Args) => Promise<string>;
+    name: string;
+};
+type PromptArgument = Readonly<{
     complete?: ArgumentValueCompleter;
+    description?: string;
     enum?: string[];
+    name: string;
+    required?: boolean;
 }>;
 type PromptArgumentsToObject<T extends {
     name: string;
@@ -168,89 +151,141 @@ type PromptArgumentsToObject<T extends {
         name: K;
     }>["required"] extends true ? string : string | undefined;
 };
-type InputPrompt<Arguments extends InputPromptArgument[] = InputPromptArgument[], Args = PromptArgumentsToObject<Arguments>> = {
-    name: string;
+type Resource = {
+    complete?: (name: string, value: string) => Promise<Completion>;
     description?: string;
-    arguments?: InputPromptArgument[];
-    load: (args: Args) => Promise<string>;
-};
-type PromptArgument = Readonly<{
+    load: () => Promise<ResourceResult | ResourceResult[]>;
+    mimeType?: string;
     name: string;
+    uri: string;
+};
+type ResourceResult = {
+    blob: string;
+} | {
+    text: string;
+};
+type ResourceTemplate<Arguments extends ResourceTemplateArgument[] = ResourceTemplateArgument[]> = {
+    arguments: Arguments;
+    complete?: (name: string, value: string) => Promise<Completion>;
     description?: string;
-    required?: boolean;
+    load: (args: ResourceTemplateArgumentsToObject<Arguments>) => Promise<ResourceResult>;
+    mimeType?: string;
+    name: string;
+    uriTemplate: string;
+};
+type ResourceTemplateArgument = Readonly<{
     complete?: ArgumentValueCompleter;
-    enum?: string[];
-}>;
-type Prompt<Arguments extends PromptArgument[] = PromptArgument[], Args = PromptArgumentsToObject<Arguments>> = {
-    arguments?: PromptArgument[];
-    complete?: (name: string, value: string) => Promise<Completion>;
     description?: string;
-    load: (args: Args) => Promise<string>;
     name: string;
+}>;
+type ResourceTemplateArgumentsToObject<T extends {
+    name: string;
+}[]> = {
+    [K in T[number]["name"]]: string;
 };
 type ServerOptions<T extends FastMCPSessionAuth> = {
+    authenticate?: Authenticate<T>;
+    instructions?: string;
     name: string;
     version: `${number}.${number}.${number}`;
-    authenticate?: Authenticate<T>;
 };
-type LoggingLevel = "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
+type Tool<T extends FastMCPSessionAuth, Params extends ToolParameters = ToolParameters> = {
+    annotations?: ToolAnnotations;
+    description?: string;
+    execute: (args: StandardSchemaV1.InferOutput<Params>, context: Context<T>) => Promise<AudioContent | ContentResult | ImageContent | string | TextContent>;
+    name: string;
+    parameters?: Params;
+};
+/**
+ * Tool annotations as defined in MCP Specification (2025-03-26)
+ * These provide hints about a tool's behavior.
+ */
+type ToolAnnotations = {
+    /**
+     * If true, the tool may perform destructive updates
+     * Only meaningful when readOnlyHint is false
+     * @default true
+     */
+    destructiveHint?: boolean;
+    /**
+     * If true, calling the tool repeatedly with the same arguments has no additional effect
+     * Only meaningful when readOnlyHint is false
+     * @default false
+     */
+    idempotentHint?: boolean;
+    /**
+     * If true, the tool may interact with an "open world" of external entities
+     * @default true
+     */
+    openWorldHint?: boolean;
+    /**
+     * If true, indicates the tool does not modify its environment
+     * @default false
+     */
+    readOnlyHint?: boolean;
+    /**
+     * A human-readable title for the tool, useful for UI display
+     */
+    title?: string;
+};
 declare const FastMCPSessionEventEmitterBase: {
     new (): StrictEventEmitter<EventEmitter, FastMCPSessionEvents>;
 };
-declare class FastMCPSessionEventEmitter extends FastMCPSessionEventEmitterBase {
-}
+type FastMCPSessionAuth = Record<string, unknown> | undefined;
 type SamplingResponse = {
+    content: AudioContent | ImageContent | TextContent;
     model: string;
-    stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string;
-    role: "user" | "assistant";
-    content: TextContent | ImageContent | AudioContent;
+    role: "assistant" | "user";
+    stopReason?: "endTurn" | "maxTokens" | "stopSequence" | string;
 };
-type FastMCPSessionAuth = Record<string, unknown> | undefined;
+declare class FastMCPSessionEventEmitter extends FastMCPSessionEventEmitterBase {
+}
 declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends FastMCPSessionEventEmitter {
     #private;
-    constructor({ auth, name, version, tools, resources, resourcesTemplates, prompts, }: {
+    get clientCapabilities(): ClientCapabilities | null;
+    get loggingLevel(): LoggingLevel;
+    get roots(): Root[];
+    get server(): Server;
+    constructor({ auth, instructions, name, prompts, resources, resourcesTemplates, tools, version, }: {
         auth?: T;
+        instructions?: string;
         name: string;
-        version: string;
-        tools: Tool<T>[];
+        prompts: Prompt[];
         resources: Resource[];
         resourcesTemplates: InputResourceTemplate[];
-        prompts: Prompt[];
+        tools: Tool<T>[];
+        version: string;
     });
+    close(): Promise<void>;
+    connect(transport: Transport): Promise<void>;
+    requestSampling(message: z.infer<typeof CreateMessageRequestSchema>["params"]): Promise<SamplingResponse>;
+    private addPrompt;
     private addResource;
     private addResourceTemplate;
-    private addPrompt;
-    get clientCapabilities(): ClientCapabilities | null;
-    get server(): Server;
-    requestSampling(message: z.infer<typeof CreateMessageRequestSchema>["params"]): Promise<SamplingResponse>;
-    connect(transport: Transport): Promise<void>;
-    get roots(): Root[];
-    close(): Promise<void>;
-    private setupErrorHandling;
-    get loggingLevel(): LoggingLevel;
     private setupCompleteHandlers;
-    private setupRootsHandlers;
+    private setupErrorHandling;
     private setupLoggingHandlers;
-    private setupToolHandlers;
+    private setupPromptHandlers;
     private setupResourceHandlers;
     private setupResourceTemplateHandlers;
-    private setupPromptHandlers;
+    private setupRootsHandlers;
+    private setupToolHandlers;
 }
 declare const FastMCPEventEmitterBase: {
     new (): StrictEventEmitter<EventEmitter, FastMCPEvents<FastMCPSessionAuth>>;
 };
+type Authenticate<T> = (request: http.IncomingMessage) => Promise<T>;
 declare class FastMCPEventEmitter extends FastMCPEventEmitterBase {
 }
-type Authenticate<T> = (request: http.IncomingMessage) => Promise<T>;
 declare class FastMCP<T extends Record<string, unknown> | undefined = undefined> extends FastMCPEventEmitter {
     #private;
     options: ServerOptions<T>;
-    constructor(options: ServerOptions<T>);
     get sessions(): FastMCPSession<T>[];
+    constructor(options: ServerOptions<T>);
     /**
-     * Adds a tool to the server.
+     * Adds a prompt to the server.
      */
-    addTool<Params extends ToolParameters>(tool: Tool<T, Params>): void;
+    addPrompt<const Args extends InputPromptArgument[]>(prompt: InputPrompt<Args>): void;
     /**
      * Adds a resource to the server.
      */
@@ -260,20 +295,20 @@ declare class FastMCP<T extends Record<string, unknown> | undefined = undefined>
      */
     addResourceTemplate<const Args extends InputResourceTemplateArgument[]>(resource: InputResourceTemplate<Args>): void;
     /**
-     * Adds a prompt to the server.
+     * Adds a tool to the server.
      */
-    addPrompt<const Args extends InputPromptArgument[]>(prompt: InputPrompt<Args>): void;
+    addTool<Params extends ToolParameters>(tool: Tool<T, Params>): void;
     /**
      * Starts the server.
      */
     start(options?: {
-        transportType: "stdio";
-    } | {
-        transportType: "sse";
         sse: {
             endpoint: `/${string}`;
             port: number;
         };
+        transportType: "sse";
+    } | {
+        transportType: "stdio";
     }): Promise<void>;
     /**
      * Stops the server.