fastmcp 1.22.4 → 1.23.1

package/src/FastMCP.ts

@@ -1,5 +1,6 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import {
   AudioContent,
   CallToolRequestSchema,
@@ -20,21 +21,18 @@ import {
   SetLevelRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-import { toJsonSchema } from "xsschema";
-import { z } from "zod";
-import { setTimeout as delay } from "timers/promises";
-import { readFile } from "fs/promises";
-import { fileTypeFromBuffer } from "file-type";
-import { StrictEventEmitter } from "strict-event-emitter-types";
 import { EventEmitter } from "events";
+import { fileTypeFromBuffer } from "file-type";
+import { readFile } from "fs/promises";
 import Fuse from "fuse.js";
+import http from "http";
 import { startSSEServer } from "mcp-proxy";
-import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { StrictEventEmitter } from "strict-event-emitter-types";
+import { setTimeout as delay } from "timers/promises";
+import { fetch } from "undici";
 import parseURITemplate from "uri-templates";
-import http from "http";
-import {
-  fetch
-} from "undici";
+import { toJsonSchema } from "xsschema";
+import { z } from "zod";
 
 export type SSEServer = {
   close: () => Promise<void>;
@@ -46,15 +44,15 @@ type FastMCPEvents<T extends FastMCPSessionAuth> = {
 };
 
 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.
  */
 export const imageContent = async (
-  input: { url: string } | { path: string } | { buffer: Buffer },
+  input: { buffer: Buffer } | { path: string } | { url: string },
 ): Promise<ImageContent> => {
   let rawData: Buffer;
 
@@ -81,13 +79,15 @@ export const imageContent = async (
   const base64Data = rawData.toString("base64");
 
   return {
-    type: "image",
     data: base64Data,
     mimeType: mimeType?.mime ?? "image/png",
+    type: "image",
   } as const;
 };
 
-export const audioContent = async (input: { url: string } | { path: string } | { buffer: Buffer }): Promise<AudioContent> => {
+export const audioContent = async (
+  input: { buffer: Buffer } | { path: string } | { url: string },
+): Promise<AudioContent> => {
   let rawData: Buffer;
 
   if ("url" in input) {
@@ -103,7 +103,9 @@ export const audioContent = async (input: { url: string } | { path: string } | {
   } else if ("buffer" in input) {
     rawData = input.buffer;
   } else {
-    throw new Error("Invalid input: Provide a valid 'url', 'path', or 'buffer'");
+    throw new Error(
+      "Invalid input: Provide a valid 'url', 'path', or 'buffer'",
+    );
   }
 
   const mimeType = await fileTypeFromBuffer(rawData);
@@ -111,47 +113,29 @@ export const audioContent = async (input: { url: string } | { path: string } | {
   const base64Data = rawData.toString("base64");
 
   return {
-    type: "audio",
     data: base64Data,
     mimeType: mimeType?.mime ?? "audio/mpeg",
+    type: "audio",
   } as const;
 };
 
-abstract class FastMCPError extends Error {
-  public constructor(message?: string) {
-    super(message);
-    this.name = new.target.name;
-  }
-}
+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>;
 
-export class UnexpectedStateError extends FastMCPError {
-  public extras?: Extras;
-
-  public constructor(message: string, extras?: Extras) {
-    super(message);
-    this.name = new.target.name;
-    this.extras = extras;
-  }
-}
-
-/**
- * An error that is meant to be surfaced to the user.
- */
-export 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.
@@ -163,41 +147,58 @@ 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;
+
+abstract class FastMCPError extends Error {
+  public constructor(message?: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+export class UnexpectedStateError extends FastMCPError {
+  public extras?: Extras;
+
+  public constructor(message: string, extras?: Extras) {
+    super(message);
+    this.name = new.target.name;
+    this.extras = extras;
+  }
+}
+
+/**
+ * An error that is meant to be surfaced to the user.
+ */
+export class UserError extends UnexpectedStateError {}
+
 const TextContentZodSchema = z
   .object({
-    type: z.literal("text"),
     /**
      * The text content of the message.
      */
     text: z.string(),
+    type: z.literal("text"),
   })
   .strict() satisfies z.ZodType<TextContent>;
 
 type ImageContent = {
-  type: "image";
   data: string;
   mimeType: string;
+  type: "image";
 };
 
 const ImageContentZodSchema = z
   .object({
-    type: z.literal("image"),
     /**
      * The base64-encoded image data.
      */
@@ -206,10 +207,11 @@ const ImageContentZodSchema = z
      * The MIME type of the image. Different providers may support different image types.
      */
     mimeType: z.string(),
+    type: z.literal("image"),
   })
   .strict() satisfies z.ZodType<ImageContent>;
 
-type Content = TextContent | ImageContent;
+type Content = ImageContent | TextContent;
 
 const ContentZodSchema = z.discriminatedUnion("type", [
   TextContentZodSchema,
@@ -229,9 +231,9 @@ const ContentResultZodSchema = z
   .strict() satisfies z.ZodType<ContentResult>;
 
 type Completion = {
-  values: string[];
-  total?: number;
   hasMore?: boolean;
+  total?: number;
+  values: string[];
 };
 
 /**
@@ -239,97 +241,85 @@ type Completion = {
  */
 const CompletionZodSchema = z.object({
   /**
-   * An array of completion values. Must not exceed 100 items.
+   * Indicates whether there are additional completion options beyond those provided in the current response, even if the exact total is unknown.
    */
-  values: z.array(z.string()).max(100),
+  hasMore: z.optional(z.boolean()),
   /**
    * The total number of completion options available. This can exceed the number of values actually sent in the response.
    */
   total: z.optional(z.number().int()),
   /**
-   * Indicates whether there are additional completion options beyond those provided in the current response, even if the exact total is unknown.
+   * An array of completion values. Must not exceed 100 items.
    */
-  hasMore: z.optional(z.boolean()),
+  values: z.array(z.string()).max(100),
 }) satisfies z.ZodType<Completion>;
 
-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>;
+  load: (args: Args) => Promise<string>;
+  name: string;
 };
 
-type ResourceResult =
-  | {
-      text: string;
-    }
-  | {
-      blob: string;
-    };
-
-type InputResourceTemplateArgument = Readonly<{
-  name: string;
-  description?: string;
+type InputPromptArgument = Readonly<{
   complete?: ArgumentValueCompleter;
-}>;
-
-type ResourceTemplateArgument = Readonly<{
-  name: string;
   description?: string;
-  complete?: ArgumentValueCompleter;
+  enum?: string[];
+  name: string;
+  required?: boolean;
 }>;
 
-type ResourceTemplate<
+type InputResourceTemplate<
   Arguments extends ResourceTemplateArgument[] = ResourceTemplateArgument[],
 > = {
-  uriTemplate: string;
-  name: string;
-  description?: string;
-  mimeType?: string;
   arguments: Arguments;
-  complete?: (name: string, value: string) => Promise<Completion>;
+  description?: string;
   load: (
     args: ResourceTemplateArgumentsToObject<Arguments>,
   ) => Promise<ResourceResult>;
+  mimeType?: string;
+  name: string;
+  uriTemplate: string;
 };
 
-type ResourceTemplateArgumentsToObject<T extends { name: string }[]> = {
-  [K in T[number]["name"]]: string;
-};
+type InputResourceTemplateArgument = Readonly<{
+  complete?: ArgumentValueCompleter;
+  description?: string;
+  name: string;
+}>;
 
-type InputResourceTemplate<
-  Arguments extends ResourceTemplateArgument[] = ResourceTemplateArgument[],
+type LoggingLevel =
+  | "alert"
+  | "critical"
+  | "debug"
+  | "emergency"
+  | "error"
+  | "info"
+  | "notice"
+  | "warning";
+
+type Prompt<
+  Arguments extends PromptArgument[] = PromptArgument[],
+  Args = PromptArgumentsToObject<Arguments>,
 > = {
-  uriTemplate: string;
-  name: string;
+  arguments?: PromptArgument[];
+  complete?: (name: string, value: string) => Promise<Completion>;
   description?: string;
-  mimeType?: string;
-  arguments: Arguments;
-  load: (
-    args: ResourceTemplateArgumentsToObject<Arguments>,
-  ) => Promise<ResourceResult>;
-};
-
-type Resource = {
-  uri: string;
+  load: (args: Args) => Promise<string>;
   name: string;
-  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;
-  description?: string;
-  required?: boolean;
+type PromptArgument = Readonly<{
   complete?: ArgumentValueCompleter;
+  description?: string;
   enum?: string[];
+  name: string;
+  required?: boolean;
 }>;
 
 type PromptArgumentsToObject<T extends { name: string; required?: boolean }[]> =
@@ -342,93 +332,171 @@ type PromptArgumentsToObject<T extends { name: string; required?: boolean }[]> =
       : 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>;
+  load: () => Promise<ResourceResult | ResourceResult[]>;
+  mimeType?: string;
+  name: string;
+  uri: string;
 };
 
-type PromptArgument = Readonly<{
-  name: string;
-  description?: string;
-  required?: boolean;
-  complete?: ArgumentValueCompleter;
-  enum?: string[];
-}>;
+type ResourceResult =
+  | {
+      blob: string;
+    }
+  | {
+      text: string;
+    };
 
-type Prompt<
-  Arguments extends PromptArgument[] = PromptArgument[],
-  Args = PromptArgumentsToObject<Arguments>,
+type ResourceTemplate<
+  Arguments extends ResourceTemplateArgument[] = ResourceTemplateArgument[],
 > = {
-  arguments?: PromptArgument[];
+  arguments: Arguments;
   complete?: (name: string, value: string) => Promise<Completion>;
   description?: string;
-  load: (args: Args) => Promise<string>;
+  load: (
+    args: ResourceTemplateArgumentsToObject<Arguments>,
+  ) => Promise<ResourceResult>;
+  mimeType?: string;
   name: string;
+  uriTemplate: string;
 };
 
-type ServerOptions<T extends FastMCPSessionAuth> = {
+type ResourceTemplateArgument = Readonly<{
+  complete?: ArgumentValueCompleter;
+  description?: string;
   name: string;
-  version: `${number}.${number}.${number}`;
+}>;
+
+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}`;
 };
 
-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;
+};
 
 const FastMCPSessionEventEmitterBase: {
   new (): StrictEventEmitter<EventEmitter, FastMCPSessionEvents>;
 } = EventEmitter;
 
-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;
+class FastMCPSessionEventEmitter extends FastMCPSessionEventEmitterBase {}
 
-export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends FastMCPSessionEventEmitter {
+export class FastMCPSession<
+  T extends FastMCPSessionAuth = FastMCPSessionAuth,
+> extends FastMCPSessionEventEmitter {
+  public get clientCapabilities(): ClientCapabilities | null {
+    return this.#clientCapabilities ?? null;
+  }
+  public get loggingLevel(): LoggingLevel {
+    return this.#loggingLevel;
+  }
+  public get roots(): Root[] {
+    return this.#roots;
+  }
+  public get server(): Server {
+    return this.#server;
+  }
+  #auth: T | undefined;
   #capabilities: ServerCapabilities = {};
   #clientCapabilities?: ClientCapabilities;
   #loggingLevel: LoggingLevel = "info";
+  #pingInterval: null | ReturnType<typeof setInterval> = null;
+
   #prompts: Prompt[] = [];
+
   #resources: Resource[] = [];
+
   #resourceTemplates: ResourceTemplate[] = [];
+
   #roots: Root[] = [];
+
   #server: Server;
-  #auth: T | undefined;
 
   constructor({
     auth,
+    instructions,
     name,
-    version,
-    tools,
+    prompts,
     resources,
     resourcesTemplates,
-    prompts,
+    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;
   }) {
     super();
 
@@ -454,7 +522,7 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
 
     this.#server = new Server(
       { name: name, version: version },
-      { capabilities: this.#capabilities },
+      { capabilities: this.#capabilities, instructions: instructions },
     );
 
     this.setupErrorHandling();
@@ -487,33 +555,72 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
     }
   }
 
-  private addResource(inputResource: Resource) {
-    this.#resources.push(inputResource);
+  public async close() {
+    if (this.#pingInterval) {
+      clearInterval(this.#pingInterval);
+    }
+
+    try {
+      await this.#server.close();
+    } catch (error) {
+      console.error("[FastMCP error]", "could not close server", error);
+    }
   }
 
-  private addResourceTemplate(inputResourceTemplate: InputResourceTemplate) {
-    const completers: Record<string, ArgumentValueCompleter> = {};
+  public async connect(transport: Transport) {
+    if (this.#server.transport) {
+      throw new UnexpectedStateError("Server is already connected");
+    }
 
-    for (const argument of inputResourceTemplate.arguments ?? []) {
-      if (argument.complete) {
-        completers[argument.name] = argument.complete;
+    await this.#server.connect(transport);
+
+    let attempt = 0;
+
+    while (attempt++ < 10) {
+      const capabilities = await this.#server.getClientCapabilities();
+
+      if (capabilities) {
+        this.#clientCapabilities = capabilities;
+
+        break;
       }
+
+      await delay(100);
     }
 
-    const resourceTemplate = {
-      ...inputResourceTemplate,
-      complete: async (name: string, value: string) => {
-        if (completers[name]) {
-          return await completers[name](value);
-        }
+    if (!this.#clientCapabilities) {
+      console.warn("[FastMCP warning] could not infer client capabilities");
+    }
 
-        return {
-          values: [],
-        };
-      },
-    };
+    if (this.#clientCapabilities?.roots?.listChanged) {
+      try {
+        const roots = await this.#server.listRoots();
+        this.#roots = roots.roots;
+      } catch (e) {
+        console.error(
+          `[FastMCP error] received error listing roots.\n\n${e instanceof Error ? e.stack : JSON.stringify(e)}`,
+        );
+      }
+    }
 
-    this.#resourceTemplates.push(resourceTemplate);
+    if (this.#clientCapabilities) {
+      this.#pingInterval = setInterval(async () => {
+        try {
+          await this.#server.ping();
+        } catch {
+          // The reason we are not emitting an error here is because some clients
+          // seem to not respond to the ping request, and we don't want to crash the server,
+          // e.g., https://github.com/punkpeye/fastmcp/issues/38.
+          console.warn("[FastMCP warning] server is not responding to ping");
+        }
+      }, 1000);
+    }
+  }
+
+  public async requestSampling(
+    message: z.infer<typeof CreateMessageRequestSchema>["params"],
+  ): Promise<SamplingResponse> {
+    return this.#server.createMessage(message);
   }
 
   private addPrompt(inputPrompt: InputPrompt) {
@@ -545,8 +652,8 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
           const result = fuse.search(value);
 
           return {
-            values: result.map((item) => item.item),
             total: result.length,
+            values: result.map((item) => item.item),
           };
         }
 
@@ -559,94 +666,33 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
     this.#prompts.push(prompt);
   }
 
-  public get clientCapabilities(): ClientCapabilities | null {
-    return this.#clientCapabilities ?? null;
-  }
-
-  public get server(): Server {
-    return this.#server;
-  }
-
-  #pingInterval: ReturnType<typeof setInterval> | null = null;
-
-  public async requestSampling(
-    message: z.infer<typeof CreateMessageRequestSchema>["params"],
-  ): Promise<SamplingResponse> {
-    return this.#server.createMessage(message);
+  private addResource(inputResource: Resource) {
+    this.#resources.push(inputResource);
   }
 
-  public async connect(transport: Transport) {
-    if (this.#server.transport) {
-      throw new UnexpectedStateError("Server is already connected");
-    }
-
-    await this.#server.connect(transport);
-
-    let attempt = 0;
-
-    while (attempt++ < 10) {
-      const capabilities = await this.#server.getClientCapabilities();
-
-      if (capabilities) {
-        this.#clientCapabilities = capabilities;
-
-        break;
-      }
-
-      await delay(100);
-    }
-
-    if (!this.#clientCapabilities) {
-      console.warn('[FastMCP warning] could not infer client capabilities')
-    }
+  private addResourceTemplate(inputResourceTemplate: InputResourceTemplate) {
+    const completers: Record<string, ArgumentValueCompleter> = {};
 
-    if (this.#clientCapabilities?.roots?.listChanged) {
-      try {
-        const roots = await this.#server.listRoots();
-        this.#roots = roots.roots;
-      } catch(e) {
-        console.error(`[FastMCP error] received error listing roots.\n\n${e instanceof Error ? e.stack : JSON.stringify(e)}`)
+    for (const argument of inputResourceTemplate.arguments ?? []) {
+      if (argument.complete) {
+        completers[argument.name] = argument.complete;
       }
     }
 
-    if (this.#clientCapabilities) {
-      this.#pingInterval = setInterval(async () => {
-        try {
-          await this.#server.ping();
-        } catch {
-          // The reason we are not emitting an error here is because some clients
-          // seem to not respond to the ping request, and we don't want to crash the server,
-          // e.g., https://github.com/punkpeye/fastmcp/issues/38. 
-          console.warn("[FastMCP warning] server is not responding to ping")
+    const resourceTemplate = {
+      ...inputResourceTemplate,
+      complete: async (name: string, value: string) => {
+        if (completers[name]) {
+          return await completers[name](value);
         }
-      }, 1000);
-    }
-  }
 
-  public get roots(): Root[] {
-    return this.#roots;
-  }
-
-  public async close() {
-    if (this.#pingInterval) {
-      clearInterval(this.#pingInterval);
-    }
-
-    try {
-      await this.#server.close();
-    } catch (error) {
-      console.error("[FastMCP error]", "could not close server", error);
-    }
-  }
-
-  private setupErrorHandling() {
-    this.#server.onerror = (error) => {
-      console.error("[FastMCP error]", error);
+        return {
+          values: [],
+        };
+      },
     };
-  }
 
-  public get loggingLevel(): LoggingLevel {
-    return this.#loggingLevel;
+    this.#resourceTemplates.push(resourceTemplate);
   }
 
   private setupCompleteHandlers() {
@@ -722,19 +768,10 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
     });
   }
 
-  private setupRootsHandlers() {
-    this.#server.setNotificationHandler(
-      RootsListChangedNotificationSchema,
-      () => {
-        this.#server.listRoots().then((roots) => {
-          this.#roots = roots.roots;
-
-          this.emit("rootsChanged", {
-            roots: roots.roots,
-          });
-        });
-      },
-    );
+  private setupErrorHandling() {
+    this.#server.onerror = (error) => {
+      console.error("[FastMCP error]", error);
+    };
   }
 
   private setupLoggingHandlers() {
@@ -745,134 +782,63 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
     });
   }
 
-  private setupToolHandlers(tools: Tool<T>[]) {
-    this.#server.setRequestHandler(ListToolsRequestSchema, async () => {
+  private setupPromptHandlers(prompts: Prompt[]) {
+    this.#server.setRequestHandler(ListPromptsRequestSchema, async () => {
       return {
-        tools: await Promise.all(tools.map(async (tool) => {
+        prompts: prompts.map((prompt) => {
           return {
-            name: tool.name,
-            description: tool.description,
-            inputSchema: tool.parameters
-              ? await toJsonSchema(tool.parameters)
-              : undefined,
+            arguments: prompt.arguments,
+            complete: prompt.complete,
+            description: prompt.description,
+            name: prompt.name,
           };
-        })),
+        }),
       };
     });
 
-    this.#server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      const tool = tools.find((tool) => tool.name === request.params.name);
+    this.#server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const prompt = prompts.find(
+        (prompt) => prompt.name === request.params.name,
+      );
 
-      if (!tool) {
+      if (!prompt) {
         throw new McpError(
           ErrorCode.MethodNotFound,
-          `Unknown tool: ${request.params.name}`,
-        );
-      }
-
-      let args: any = undefined;
-
-      if (tool.parameters) {
-        const parsed = await tool.parameters["~standard"].validate(
-          request.params.arguments
+          `Unknown prompt: ${request.params.name}`,
         );
+      }
 
-        if (parsed.issues) {
-          throw new McpError(
-            ErrorCode.InvalidParams,
-            `Invalid ${request.params.name} parameters`,
-          );
-        }
-
-        args = parsed.value;
-      }
-
-      const progressToken = request.params?._meta?.progressToken;
-
-      let result: ContentResult;
-
-      try {
-        const reportProgress = async (progress: Progress) => {
-          await this.#server.notification({
-            method: "notifications/progress",
-            params: {
-              ...progress,
-              progressToken,
-            },
-          });
-        };
-
-        const log = {
-          debug: (message: string, context?: SerializableValue) => {
-            this.#server.sendLoggingMessage({
-              level: "debug",
-              data: {
-                message,
-                context,
-              },
-            });
-          },
-          error: (message: string, context?: SerializableValue) => {
-            this.#server.sendLoggingMessage({
-              level: "error",
-              data: {
-                message,
-                context,
-              },
-            });
-          },
-          info: (message: string, context?: SerializableValue) => {
-            this.#server.sendLoggingMessage({
-              level: "info",
-              data: {
-                message,
-                context,
-              },
-            });
-          },
-          warn: (message: string, context?: SerializableValue) => {
-            this.#server.sendLoggingMessage({
-              level: "warning",
-              data: {
-                message,
-                context,
-              },
-            });
-          },
-        };
-
-        const maybeStringResult = await tool.execute(args, {
-          reportProgress,
-          log,
-          session: this.#auth,
-        });
+      const args = request.params.arguments;
 
-        if (typeof maybeStringResult === "string") {
-          result = ContentResultZodSchema.parse({
-            content: [{ type: "text", text: maybeStringResult }],
-          });
-        } else if ("type" in maybeStringResult) {
-          result = ContentResultZodSchema.parse({
-            content: [maybeStringResult],
-          });
-        } else {
-          result = ContentResultZodSchema.parse(maybeStringResult);
-        }
-      } catch (error) {
-        if (error instanceof UserError) {
-          return {
-            content: [{ type: "text", text: error.message }],
-            isError: true,
-          };
+      for (const arg of prompt.arguments ?? []) {
+        if (arg.required && !(args && arg.name in args)) {
+          throw new McpError(
+            ErrorCode.InvalidRequest,
+            `Missing required argument: ${arg.name}`,
+          );
         }
+      }
 
-        return {
-          content: [{ type: "text", text: `Error: ${error}` }],
-          isError: true,
-        };
+      let result: Awaited<ReturnType<Prompt["load"]>>;
+
+      try {
+        result = await prompt.load(args as Record<string, string | undefined>);
+      } catch (error) {
+        throw new McpError(
+          ErrorCode.InternalError,
+          `Error loading prompt: ${error}`,
+        );
       }
 
-      return result;
+      return {
+        description: prompt.description,
+        messages: [
+          {
+            content: { text: result, type: "text" },
+            role: "user",
+          },
+        ],
+      };
     });
   }
 
@@ -881,9 +847,9 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
       return {
         resources: resources.map((resource) => {
           return {
-            uri: resource.uri,
-            name: resource.name,
             mimeType: resource.mimeType,
+            name: resource.name,
+            uri: resource.uri,
           };
         }),
       };
@@ -917,9 +883,9 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
               return {
                 contents: [
                   {
-                    uri: uri,
                     mimeType: resourceTemplate.mimeType,
                     name: resourceTemplate.name,
+                    uri: uri,
                     ...result,
                   },
                 ],
@@ -953,9 +919,9 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
           if (Array.isArray(maybeArrayResult)) {
             return {
               contents: maybeArrayResult.map((result) => ({
-                uri: resource.uri,
                 mimeType: resource.mimeType,
                 name: resource.name,
+                uri: resource.uri,
                 ...result,
               })),
             };
@@ -963,9 +929,9 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
             return {
               contents: [
                 {
-                  uri: resource.uri,
                   mimeType: resource.mimeType,
                   name: resource.name,
+                  uri: resource.uri,
                   ...maybeArrayResult,
                 },
               ],
@@ -996,63 +962,152 @@ export class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth> e
     );
   }
 
-  private setupPromptHandlers(prompts: Prompt[]) {
-    this.#server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  private setupRootsHandlers() {
+    this.#server.setNotificationHandler(
+      RootsListChangedNotificationSchema,
+      () => {
+        this.#server.listRoots().then((roots) => {
+          this.#roots = roots.roots;
+
+          this.emit("rootsChanged", {
+            roots: roots.roots,
+          });
+        });
+      },
+    );
+  }
+
+  private setupToolHandlers(tools: Tool<T>[]) {
+    this.#server.setRequestHandler(ListToolsRequestSchema, async () => {
       return {
-        prompts: prompts.map((prompt) => {
-          return {
-            name: prompt.name,
-            description: prompt.description,
-            arguments: prompt.arguments,
-            complete: prompt.complete,
-          };
-        }),
+        tools: await Promise.all(
+          tools.map(async (tool) => {
+            return {
+              annotations: tool.annotations,
+              description: tool.description,
+              inputSchema: tool.parameters
+                ? await toJsonSchema(tool.parameters)
+                : undefined,
+              name: tool.name,
+            };
+          }),
+        ),
       };
     });
 
-    this.#server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      const prompt = prompts.find(
-        (prompt) => prompt.name === request.params.name,
-      );
+    this.#server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const tool = tools.find((tool) => tool.name === request.params.name);
 
-      if (!prompt) {
+      if (!tool) {
         throw new McpError(
           ErrorCode.MethodNotFound,
-          `Unknown prompt: ${request.params.name}`,
+          `Unknown tool: ${request.params.name}`,
         );
       }
 
-      const args = request.params.arguments;
+      let args: unknown = undefined;
 
-      for (const arg of prompt.arguments ?? []) {
-        if (arg.required && !(args && arg.name in args)) {
+      if (tool.parameters) {
+        const parsed = await tool.parameters["~standard"].validate(
+          request.params.arguments,
+        );
+
+        if (parsed.issues) {
           throw new McpError(
-            ErrorCode.InvalidRequest,
-            `Missing required argument: ${arg.name}`,
+            ErrorCode.InvalidParams,
+            `Invalid ${request.params.name} parameters`,
           );
         }
+
+        args = parsed.value;
       }
 
-      let result: Awaited<ReturnType<Prompt["load"]>>;
+      const progressToken = request.params?._meta?.progressToken;
+
+      let result: ContentResult;
 
       try {
-        result = await prompt.load(args as Record<string, string | undefined>);
+        const reportProgress = async (progress: Progress) => {
+          await this.#server.notification({
+            method: "notifications/progress",
+            params: {
+              ...progress,
+              progressToken,
+            },
+          });
+        };
+
+        const log = {
+          debug: (message: string, context?: SerializableValue) => {
+            this.#server.sendLoggingMessage({
+              data: {
+                context,
+                message,
+              },
+              level: "debug",
+            });
+          },
+          error: (message: string, context?: SerializableValue) => {
+            this.#server.sendLoggingMessage({
+              data: {
+                context,
+                message,
+              },
+              level: "error",
+            });
+          },
+          info: (message: string, context?: SerializableValue) => {
+            this.#server.sendLoggingMessage({
+              data: {
+                context,
+                message,
+              },
+              level: "info",
+            });
+          },
+          warn: (message: string, context?: SerializableValue) => {
+            this.#server.sendLoggingMessage({
+              data: {
+                context,
+                message,
+              },
+              level: "warning",
+            });
+          },
+        };
+
+        const maybeStringResult = await tool.execute(args, {
+          log,
+          reportProgress,
+          session: this.#auth,
+        });
+
+        if (typeof maybeStringResult === "string") {
+          result = ContentResultZodSchema.parse({
+            content: [{ text: maybeStringResult, type: "text" }],
+          });
+        } else if ("type" in maybeStringResult) {
+          result = ContentResultZodSchema.parse({
+            content: [maybeStringResult],
+          });
+        } else {
+          result = ContentResultZodSchema.parse(maybeStringResult);
+        }
       } catch (error) {
-        throw new McpError(
-          ErrorCode.InternalError,
-          `Error loading prompt: ${error}`,
-        );
+        if (error instanceof UserError) {
+          return {
+            content: [{ text: error.message, type: "text" }],
+            isError: true,
+          };
+        }
+
+        return {
+          content: [{ text: `Error: ${error}`, type: "text" }],
+          isError: true,
+        };
       }
 
-      return {
-        description: prompt.description,
-        messages: [
-          {
-            role: "user",
-            content: { type: "text", text: result },
-          },
-        ],
-      };
+      return result;
     });
   }
 }
@@ -1061,19 +1116,25 @@ const FastMCPEventEmitterBase: {
   new (): StrictEventEmitter<EventEmitter, FastMCPEvents<FastMCPSessionAuth>>;
 } = EventEmitter;
 
-class FastMCPEventEmitter extends FastMCPEventEmitterBase {}
-
 type Authenticate<T> = (request: http.IncomingMessage) => Promise<T>;
 
-export class FastMCP<T extends Record<string, unknown> | undefined = undefined> extends FastMCPEventEmitter {
+class FastMCPEventEmitter extends FastMCPEventEmitterBase {}
+
+export class FastMCP<
+  T extends Record<string, unknown> | undefined = undefined,
+> extends FastMCPEventEmitter {
+  public get sessions(): FastMCPSession<T>[] {
+    return this.#sessions;
+  }
+  #authenticate: Authenticate<T> | undefined;
   #options: ServerOptions<T>;
   #prompts: InputPrompt[] = [];
   #resources: Resource[] = [];
   #resourcesTemplates: InputResourceTemplate[] = [];
   #sessions: FastMCPSession<T>[] = [];
-  #sseServer: SSEServer | null = null;
+  #sseServer: null | SSEServer = null;
+
   #tools: Tool<T>[] = [];
-  #authenticate: Authenticate<T> | undefined;
 
   constructor(public options: ServerOptions<T>) {
     super();
@@ -1082,15 +1143,13 @@ export class FastMCP<T extends Record<string, unknown> | undefined = undefined>
     this.#authenticate = options.authenticate;
   }
 
-  public get sessions(): FastMCPSession<T>[] {
-    return this.#sessions;
-  }
-
   /**
-   * Adds a tool to the server.
+   * Adds a prompt to the server.
    */
-  public addTool<Params extends ToolParameters>(tool: Tool<T, Params>) {
-    this.#tools.push(tool as unknown as Tool<T>);
+  public addPrompt<const Args extends InputPromptArgument[]>(
+    prompt: InputPrompt<Args>,
+  ) {
+    this.#prompts.push(prompt);
   }
 
   /**
@@ -1110,12 +1169,10 @@ export class FastMCP<T extends Record<string, unknown> | undefined = undefined>
   }
 
   /**
-   * Adds a prompt to the server.
+   * Adds a tool to the server.
    */
-  public addPrompt<const Args extends InputPromptArgument[]>(
-    prompt: InputPrompt<Args>,
-  ) {
-    this.#prompts.push(prompt);
+  public addTool<Params extends ToolParameters>(tool: Tool<T, Params>) {
+    this.#tools.push(tool as unknown as Tool<T>);
   }
 
   /**
@@ -1123,11 +1180,11 @@ export class FastMCP<T extends Record<string, unknown> | undefined = undefined>
    */
   public async start(
     options:
-      | { transportType: "stdio" }
       | {
-          transportType: "sse";
           sse: { endpoint: `/${string}`; port: number };
-        } = {
+          transportType: "sse";
+        }
+      | { transportType: "stdio" } = {
       transportType: "stdio",
     },
   ) {
@@ -1135,12 +1192,13 @@ export class FastMCP<T extends Record<string, unknown> | undefined = undefined>
       const transport = new StdioServerTransport();
 
       const session = new FastMCPSession<T>({
+        instructions: this.#options.instructions,
         name: this.#options.name,
-        version: this.#options.version,
-        tools: this.#tools,
+        prompts: this.#prompts,
         resources: this.#resources,
         resourcesTemplates: this.#resourcesTemplates,
-        prompts: this.#prompts,
+        tools: this.#tools,
+        version: this.#options.version,
       });
 
       await session.connect(transport);
@@ -1150,11 +1208,8 @@ export class FastMCP<T extends Record<string, unknown> | undefined = undefined>
       this.emit("connect", {
         session,
       });
-
     } else if (options.transportType === "sse") {
       this.#sseServer = await startSSEServer<FastMCPSession<T>>({
-        endpoint: options.sse.endpoint as `/${string}`,
-        port: options.sse.port,
         createServer: async (request) => {
           let auth: T | undefined;
 
@@ -1165,13 +1220,14 @@ export class FastMCP<T extends Record<string, unknown> | undefined = undefined>
           return new FastMCPSession<T>({
             auth,
             name: this.#options.name,
-            version: this.#options.version,
-            tools: this.#tools,
+            prompts: this.#prompts,
             resources: this.#resources,
             resourcesTemplates: this.#resourcesTemplates,
-            prompts: this.#prompts,
+            tools: this.#tools,
+            version: this.#options.version,
           });
         },
+        endpoint: options.sse.endpoint as `/${string}`,
         onClose: (session) => {
           this.emit("disconnect", {
             session,
@@ -1184,6 +1240,7 @@ export class FastMCP<T extends Record<string, unknown> | undefined = undefined>
             session,
           });
         },
+        port: options.sse.port,
       });
 
       console.info(
@@ -1206,11 +1263,11 @@ export class FastMCP<T extends Record<string, unknown> | undefined = undefined>
 
 export type { Context };
 export type { Tool, ToolParameters };
-export type { Content, TextContent, ImageContent, ContentResult };
+export type { Content, ContentResult, ImageContent, TextContent };
 export type { Progress, SerializableValue };
 export type { Resource, ResourceResult };
 export type { ResourceTemplate, ResourceTemplateArgument };
 export type { Prompt, PromptArgument };
 export type { InputPrompt, InputPromptArgument };
-export type { ServerOptions, LoggingLevel };
+export type { LoggingLevel, ServerOptions };
 export type { FastMCPEvents, FastMCPSessionEvents };