fastmcp 1.9.0 → 1.11.0

package/src/FastMCP.ts

@@ -3,6 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import {
   CallToolRequestSchema,
   ClientCapabilities,
+  CompleteRequestSchema,
   ErrorCode,
   GetPromptRequestSchema,
   ListPromptsRequestSchema,
@@ -22,6 +23,7 @@ import { readFile } from "fs/promises";
 import { fileTypeFromBuffer } from "file-type";
 import { StrictEventEmitter } from "strict-event-emitter-types";
 import { EventEmitter } from "events";
+import Fuse from "fuse.js";
 import { startSSEServer } from "mcp-proxy";
 import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 
@@ -36,6 +38,7 @@ type FastMCPEvents = {
 
 type FastMCPSessionEvents = {
   rootsChanged: (event: { roots: Root[] }) => void;
+  error: (event: { error: Error }) => void;
 };
 
 /**
@@ -86,7 +89,7 @@ type Extra = unknown;
 
 type Extras = Record<string, Extra>;
 
-class UnexpectedStateError extends FastMCPError {
+export class UnexpectedStateError extends FastMCPError {
   public extras?: Extras;
 
   public constructor(message: string, extras?: Extras) {
@@ -185,6 +188,30 @@ const ContentResultZodSchema = z
   })
   .strict() satisfies z.ZodType<ContentResult>;
 
+type Completion = {
+  values: string[];
+  total?: number;
+  hasMore?: boolean;
+};
+
+/**
+ * https://github.com/modelcontextprotocol/typescript-sdk/blob/3164da64d085ec4e022ae881329eee7b72f208d4/src/types.ts#L983-L1003
+ */
+const CompletionZodSchema = z.object({
+  /**
+   * An array of completion values. Must not exceed 100 items.
+   */
+  values: z.array(z.string()).max(100),
+  /**
+   * 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.
+   */
+  hasMore: z.optional(z.boolean()),
+}) satisfies z.ZodType<Completion>;
+
 type Tool<Params extends ToolParameters = ToolParameters> = {
   name: string;
   description?: string;
@@ -203,13 +230,17 @@ type Resource = {
   load: () => Promise<{ text: string } | { blob: string }>;
 };
 
-type PromptArgument = Readonly<{
+type ArgumentValueCompleter = (value: string) => Promise<Completion>;
+
+type InputPromptArgument = Readonly<{
   name: string;
   description?: string;
   required?: boolean;
+  complete?: ArgumentValueCompleter;
+  enum?: string[];
 }>;
 
-type ArgumentsToObject<T extends PromptArgument[]> = {
+type ArgumentsToObject<T extends InputPromptArgument[]> = {
   [K in T[number]["name"]]: Extract<
     T[number],
     { name: K }
@@ -218,14 +249,33 @@ type ArgumentsToObject<T extends PromptArgument[]> = {
     : string | undefined;
 };
 
+type InputPrompt<
+  Arguments extends InputPromptArgument[] = InputPromptArgument[],
+  Args = ArgumentsToObject<Arguments>,
+> = {
+  name: string;
+  description?: string;
+  arguments?: InputPromptArgument[];
+  load: (args: Args) => Promise<string>;
+};
+
+type PromptArgument = Readonly<{
+  name: string;
+  description?: string;
+  required?: boolean;
+  complete?: ArgumentValueCompleter;
+  enum?: string[];
+}>;
+
 type Prompt<
   Arguments extends PromptArgument[] = PromptArgument[],
   Args = ArgumentsToObject<Arguments>,
 > = {
-  name: string;
+  arguments?: PromptArgument[];
+  complete?: (name: string, value: string) => Promise<Completion>;
   description?: string;
-  arguments?: Arguments;
   load: (args: Args) => Promise<string>;
+  name: string;
 };
 
 type ServerOptions = {
@@ -255,6 +305,7 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
   #server: Server;
   #clientCapabilities?: ClientCapabilities;
   #roots: Root[] = [];
+  #prompts: Prompt[] = [];
 
   constructor({
     name,
@@ -280,6 +331,10 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
     }
 
     if (prompts.length) {
+      for (const prompt of prompts) {
+        this.addPrompt(prompt);
+      }
+
       this.#capabilities.prompts = {};
     }
 
@@ -293,6 +348,7 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
     this.setupErrorHandling();
     this.setupLoggingHandlers();
     this.setupRootsHandlers();
+    this.setupCompleteHandlers();
 
     if (tools.length) {
       this.setupToolHandlers(tools);
@@ -307,6 +363,49 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
     }
   }
 
+  private addPrompt(inputPrompt: InputPrompt) {
+    const completers: Record<string, ArgumentValueCompleter> = {};
+    const enums: Record<string, string[]> = {};
+
+    for (const argument of inputPrompt.arguments ?? []) {
+      if (argument.complete) {
+        completers[argument.name] = argument.complete;
+      }
+
+      if (argument.enum) {
+        enums[argument.name] = argument.enum;
+      }
+    }
+
+    const prompt = {
+      ...inputPrompt,
+      complete: async (name: string, value: string) => {
+        if (completers[name]) {
+          return await completers[name](value);
+        }
+
+        if (enums[name]) {
+          const fuse = new Fuse(enums[name], {
+            keys: ["value"],
+          });
+
+          const result = fuse.search(value);
+
+          return {
+            values: result.map((item) => item.item),
+            total: result.length,
+          };
+        }
+
+        return {
+          values: [],
+        };
+      },
+    };
+
+    this.#prompts.push(prompt);
+  }
+
   public get clientCapabilities(): ClientCapabilities | null {
     return this.#clientCapabilities ?? null;
   }
@@ -315,6 +414,8 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
     return this.#server;
   }
 
+  #pingInterval: ReturnType<typeof setInterval> | null = null;
+
   public async connect(transport: Transport) {
     if (this.#server.transport) {
       throw new UnexpectedStateError("Server is already connected");
@@ -336,15 +437,25 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
       await delay(100);
     }
 
+    if (!this.#clientCapabilities) {
+      throw new UnexpectedStateError("Server did not connect");
+    }
+
     if (this.#clientCapabilities?.roots) {
       const roots = await this.#server.listRoots();
 
       this.#roots = roots.roots;
     }
 
-    if (!this.#clientCapabilities) {
-      throw new UnexpectedStateError("Server did not connect");
-    }
+    this.#pingInterval = setInterval(async () => {
+      try {
+        await this.#server.ping();
+      } catch (error) {
+        this.emit("error", {
+          error: error as Error,
+        });
+      }
+    }, 1000);
   }
 
   public get roots(): Root[] {
@@ -352,6 +463,10 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
   }
 
   public async close() {
+    if (this.#pingInterval) {
+      clearInterval(this.#pingInterval);
+    }
+
     await this.#server.close();
   }
 
@@ -365,6 +480,43 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
     return this.#loggingLevel;
   }
 
+  private setupCompleteHandlers() {
+    this.#server.setRequestHandler(CompleteRequestSchema, async (request) => {
+      if (request.params.ref.type === "ref/prompt") {
+        const prompt = this.#prompts.find(
+          (prompt) => prompt.name === request.params.ref.name,
+        );
+
+        if (!prompt) {
+          throw new UnexpectedStateError("Unknown prompt", {
+            request,
+          });
+        }
+
+        if (!prompt.complete) {
+          throw new UnexpectedStateError("Prompt does not support completion", {
+            request,
+          });
+        }
+
+        const completion = CompletionZodSchema.parse(
+          await prompt.complete(
+            request.params.argument.name,
+            request.params.argument.value,
+          ),
+        );
+
+        return {
+          completion,
+        };
+      }
+
+      throw new UnexpectedStateError("Unexpected completion request", {
+        request,
+      });
+    });
+  }
+
   private setupRootsHandlers() {
     this.#server.setNotificationHandler(
       RootsListChangedNotificationSchema,
@@ -578,6 +730,7 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
             name: prompt.name,
             description: prompt.description,
             arguments: prompt.arguments,
+            complete: prompt.complete,
           };
         }),
       };
@@ -597,14 +750,12 @@ export class FastMCPSession extends FastMCPSessionEventEmitter {
 
       const args = request.params.arguments;
 
-      if (prompt.arguments) {
-        for (const arg of prompt.arguments) {
-          if (arg.required && !(args && arg.name in args)) {
-            throw new McpError(
-              ErrorCode.InvalidRequest,
-              `Missing required argument: ${arg.name}`,
-            );
-          }
+      for (const arg of prompt.arguments ?? []) {
+        if (arg.required && !(args && arg.name in args)) {
+          throw new McpError(
+            ErrorCode.InvalidRequest,
+            `Missing required argument: ${arg.name}`,
+          );
         }
       }
 
@@ -640,7 +791,7 @@ class FastMCPEventEmitter extends FastMCPEventEmitterBase {}
 
 export class FastMCP extends FastMCPEventEmitter {
   #options: ServerOptions;
-  #prompts: Prompt[] = [];
+  #prompts: InputPrompt[] = [];
   #resources: Resource[] = [];
   #sessions: FastMCPSession[] = [];
   #sseServer: SSEServer | null = null;
@@ -673,7 +824,9 @@ export class FastMCP extends FastMCPEventEmitter {
   /**
    * Adds a prompt to the server.
    */
-  public addPrompt<const Args extends PromptArgument[]>(prompt: Prompt<Args>) {
+  public addPrompt<const Args extends InputPromptArgument[]>(
+    prompt: InputPrompt<Args>,
+  ) {
     this.#prompts.push(prompt);
   }