fastmcp/dist/FastMCP.js

A TypeScript framework for building MCP servers.

// src/FastMCP.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  CompleteRequestSchema,
  ErrorCode,
  GetPromptRequestSchema,
  ListPromptsRequestSchema,
  ListResourcesRequestSchema,
  ListResourceTemplatesRequestSchema,
  ListToolsRequestSchema,
  McpError,
  ReadResourceRequestSchema,
  RootsListChangedNotificationSchema,
  SetLevelRequestSchema
} from "@modelcontextprotocol/sdk/types.js";
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 { EventEmitter } from "events";
import Fuse from "fuse.js";
import { startSSEServer } from "mcp-proxy";
import parseURITemplate from "uri-templates";
import {
  fetch
} from "undici";
var imageContent = async (input) => {
  let rawData;
  if ("url" in input) {
    const response = await fetch(input.url);
    if (!response.ok) {
      throw new Error(`Failed to fetch image from URL: ${response.statusText}`);
    }
    rawData = Buffer.from(await response.arrayBuffer());
  } else if ("path" in input) {
    rawData = await readFile(input.path);
  } else if ("buffer" in input) {
    rawData = input.buffer;
  } else {
    throw new Error(
      "Invalid input: Provide a valid 'url', 'path', or 'buffer'"
    );
  }
  const mimeType = await fileTypeFromBuffer(rawData);
  const base64Data = rawData.toString("base64");
  return {
    type: "image",
    data: base64Data,
    mimeType: mimeType?.mime ?? "image/png"
  };
};
var FastMCPError = class extends Error {
  constructor(message) {
    super(message);
    this.name = new.target.name;
  }
};
var UnexpectedStateError = class extends FastMCPError {
  extras;
  constructor(message, extras) {
    super(message);
    this.name = new.target.name;
    this.extras = extras;
  }
};
var UserError = class extends UnexpectedStateError {
};
var TextContentZodSchema = z.object({
  type: z.literal("text"),
  /**
   * The text content of the message.
   */
  text: z.string()
}).strict();
var ImageContentZodSchema = z.object({
  type: z.literal("image"),
  /**
   * The base64-encoded image data.
   */
  data: z.string().base64(),
  /**
   * The MIME type of the image. Different providers may support different image types.
   */
  mimeType: z.string()
}).strict();
var ContentZodSchema = z.discriminatedUnion("type", [
  TextContentZodSchema,
  ImageContentZodSchema
]);
var ContentResultZodSchema = z.object({
  content: ContentZodSchema.array(),
  isError: z.boolean().optional()
}).strict();
var 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())
});
var FastMCPSessionEventEmitterBase = EventEmitter;
var FastMCPSessionEventEmitter = class extends FastMCPSessionEventEmitterBase {
};
var FastMCPSession = class extends FastMCPSessionEventEmitter {
  #capabilities = {};
  #clientCapabilities;
  #loggingLevel = "info";
  #prompts = [];
  #resources = [];
  #resourceTemplates = [];
  #roots = [];
  #server;
  #auth;
  constructor({
    auth,
    name,
    version,
    tools,
    resources,
    resourcesTemplates,
    prompts
  }) {
    super();
    this.#auth = auth;
    if (tools.length) {
      this.#capabilities.tools = {};
    }
    if (resources.length || resourcesTemplates.length) {
      this.#capabilities.resources = {};
    }
    if (prompts.length) {
      for (const prompt of prompts) {
        this.addPrompt(prompt);
      }
      this.#capabilities.prompts = {};
    }
    this.#capabilities.logging = {};
    this.#server = new Server(
      { name, version },
      { capabilities: this.#capabilities }
    );
    this.setupErrorHandling();
    this.setupLoggingHandlers();
    this.setupRootsHandlers();
    this.setupCompleteHandlers();
    if (tools.length) {
      this.setupToolHandlers(tools);
    }
    if (resources.length || resourcesTemplates.length) {
      for (const resource of resources) {
        this.addResource(resource);
      }
      this.setupResourceHandlers(resources);
      if (resourcesTemplates.length) {
        for (const resourceTemplate of resourcesTemplates) {
          this.addResourceTemplate(resourceTemplate);
        }
        this.setupResourceTemplateHandlers(resourcesTemplates);
      }
    }
    if (prompts.length) {
      this.setupPromptHandlers(prompts);
    }
  }
  addResource(inputResource) {
    this.#resources.push(inputResource);
  }
  addResourceTemplate(inputResourceTemplate) {
    const completers = {};
    for (const argument of inputResourceTemplate.arguments ?? []) {
      if (argument.complete) {
        completers[argument.name] = argument.complete;
      }
    }
    const resourceTemplate = {
      ...inputResourceTemplate,
      complete: async (name, value) => {
        if (completers[name]) {
          return await completers[name](value);
        }
        return {
          values: []
        };
      }
    };
    this.#resourceTemplates.push(resourceTemplate);
  }
  addPrompt(inputPrompt) {
    const completers = {};
    const enums = {};
    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, value) => {
        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);
  }
  get clientCapabilities() {
    return this.#clientCapabilities ?? null;
  }
  get server() {
    return this.#server;
  }
  #pingInterval = null;
  async requestSampling(message) {
    return this.#server.createMessage(message);
  }
  async connect(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("[warning] FastMCP could not infer client capabilities");
    }
    if (this.#clientCapabilities?.roots?.listChanged) {
      try {
        const roots = await this.#server.listRoots();
        this.#roots = roots.roots;
      } catch (e) {
        console.error(`[error] FastMCP received error listing roots.

${e instanceof Error ? e.stack : JSON.stringify(e)}`);
      }
    }
    this.#pingInterval = setInterval(async () => {
      try {
        await this.#server.ping();
      } catch (error) {
        this.emit("error", {
          error
        });
      }
    }, 1e3);
  }
  get roots() {
    return this.#roots;
  }
  async close() {
    if (this.#pingInterval) {
      clearInterval(this.#pingInterval);
    }
    try {
      await this.#server.close();
    } catch (error) {
      console.error("[MCP Error]", "could not close server", error);
    }
  }
  setupErrorHandling() {
    this.#server.onerror = (error) => {
      console.error("[MCP Error]", error);
    };
  }
  get loggingLevel() {
    return this.#loggingLevel;
  }
  setupCompleteHandlers() {
    this.#server.setRequestHandler(CompleteRequestSchema, async (request) => {
      if (request.params.ref.type === "ref/prompt") {
        const prompt = this.#prompts.find(
          (prompt2) => prompt2.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
        };
      }
      if (request.params.ref.type === "ref/resource") {
        const resource = this.#resourceTemplates.find(
          (resource2) => resource2.uriTemplate === request.params.ref.uri
        );
        if (!resource) {
          throw new UnexpectedStateError("Unknown resource", {
            request
          });
        }
        if (!("uriTemplate" in resource)) {
          throw new UnexpectedStateError("Unexpected resource");
        }
        if (!resource.complete) {
          throw new UnexpectedStateError(
            "Resource does not support completion",
            {
              request
            }
          );
        }
        const completion = CompletionZodSchema.parse(
          await resource.complete(
            request.params.argument.name,
            request.params.argument.value
          )
        );
        return {
          completion
        };
      }
      throw new UnexpectedStateError("Unexpected completion request", {
        request
      });
    });
  }
  setupRootsHandlers() {
    this.#server.setNotificationHandler(
      RootsListChangedNotificationSchema,
      () => {
        this.#server.listRoots().then((roots) => {
          this.#roots = roots.roots;
          this.emit("rootsChanged", {
            roots: roots.roots
          });
        });
      }
    );
  }
  setupLoggingHandlers() {
    this.#server.setRequestHandler(SetLevelRequestSchema, (request) => {
      this.#loggingLevel = request.params.level;
      return {};
    });
  }
  setupToolHandlers(tools) {
    this.#server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: await Promise.all(tools.map(async (tool) => {
          return {
            name: tool.name,
            description: tool.description,
            inputSchema: tool.parameters ? await toJsonSchema(tool.parameters) : void 0
          };
        }))
      };
    });
    this.#server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const tool = tools.find((tool2) => tool2.name === request.params.name);
      if (!tool) {
        throw new McpError(
          ErrorCode.MethodNotFound,
          `Unknown tool: ${request.params.name}`
        );
      }
      let args = void 0;
      if (tool.parameters) {
        const parsed = await tool.parameters["~standard"].validate(
          request.params.arguments
        );
        if (parsed.issues) {
          throw new McpError(
            ErrorCode.InvalidParams,
            `Invalid ${request.params.name} parameters`
          );
        }
        args = parsed.value;
      }
      const progressToken = request.params?._meta?.progressToken;
      let result;
      try {
        const reportProgress = async (progress) => {
          await this.#server.notification({
            method: "notifications/progress",
            params: {
              ...progress,
              progressToken
            }
          });
        };
        const log = {
          debug: (message, context) => {
            this.#server.sendLoggingMessage({
              level: "debug",
              data: {
                message,
                context
              }
            });
          },
          error: (message, context) => {
            this.#server.sendLoggingMessage({
              level: "error",
              data: {
                message,
                context
              }
            });
          },
          info: (message, context) => {
            this.#server.sendLoggingMessage({
              level: "info",
              data: {
                message,
                context
              }
            });
          },
          warn: (message, context) => {
            this.#server.sendLoggingMessage({
              level: "warning",
              data: {
                message,
                context
              }
            });
          }
        };
        const maybeStringResult = await tool.execute(args, {
          reportProgress,
          log,
          session: this.#auth
        });
        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
          };
        }
        return {
          content: [{ type: "text", text: `Error: ${error}` }],
          isError: true
        };
      }
      return result;
    });
  }
  setupResourceHandlers(resources) {
    this.#server.setRequestHandler(ListResourcesRequestSchema, async () => {
      return {
        resources: resources.map((resource) => {
          return {
            uri: resource.uri,
            name: resource.name,
            mimeType: resource.mimeType
          };
        })
      };
    });
    this.#server.setRequestHandler(
      ReadResourceRequestSchema,
      async (request) => {
        if ("uri" in request.params) {
          const resource = resources.find(
            (resource2) => "uri" in resource2 && resource2.uri === request.params.uri
          );
          if (!resource) {
            for (const resourceTemplate of this.#resourceTemplates) {
              const uriTemplate = parseURITemplate(
                resourceTemplate.uriTemplate
              );
              const match = uriTemplate.fromUri(request.params.uri);
              if (!match) {
                continue;
              }
              const uri = uriTemplate.fill(match);
              const result = await resourceTemplate.load(match);
              return {
                contents: [
                  {
                    uri,
                    mimeType: resourceTemplate.mimeType,
                    name: resourceTemplate.name,
                    ...result
                  }
                ]
              };
            }
            throw new McpError(
              ErrorCode.MethodNotFound,
              `Unknown resource: ${request.params.uri}`
            );
          }
          if (!("uri" in resource)) {
            throw new UnexpectedStateError("Resource does not support reading");
          }
          let maybeArrayResult;
          try {
            maybeArrayResult = await resource.load();
          } catch (error) {
            throw new McpError(
              ErrorCode.InternalError,
              `Error reading resource: ${error}`,
              {
                uri: resource.uri
              }
            );
          }
          if (Array.isArray(maybeArrayResult)) {
            return {
              contents: maybeArrayResult.map((result) => ({
                uri: resource.uri,
                mimeType: resource.mimeType,
                name: resource.name,
                ...result
              }))
            };
          } else {
            return {
              contents: [
                {
                  uri: resource.uri,
                  mimeType: resource.mimeType,
                  name: resource.name,
                  ...maybeArrayResult
                }
              ]
            };
          }
        }
        throw new UnexpectedStateError("Unknown resource request", {
          request
        });
      }
    );
  }
  setupResourceTemplateHandlers(resourceTemplates) {
    this.#server.setRequestHandler(
      ListResourceTemplatesRequestSchema,
      async () => {
        return {
          resourceTemplates: resourceTemplates.map((resourceTemplate) => {
            return {
              name: resourceTemplate.name,
              uriTemplate: resourceTemplate.uriTemplate
            };
          })
        };
      }
    );
  }
  setupPromptHandlers(prompts) {
    this.#server.setRequestHandler(ListPromptsRequestSchema, async () => {
      return {
        prompts: prompts.map((prompt) => {
          return {
            name: prompt.name,
            description: prompt.description,
            arguments: prompt.arguments,
            complete: prompt.complete
          };
        })
      };
    });
    this.#server.setRequestHandler(GetPromptRequestSchema, async (request) => {
      const prompt = prompts.find(
        (prompt2) => prompt2.name === request.params.name
      );
      if (!prompt) {
        throw new McpError(
          ErrorCode.MethodNotFound,
          `Unknown prompt: ${request.params.name}`
        );
      }
      const args = request.params.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}`
          );
        }
      }
      let result;
      try {
        result = await prompt.load(args);
      } catch (error) {
        throw new McpError(
          ErrorCode.InternalError,
          `Error loading prompt: ${error}`
        );
      }
      return {
        description: prompt.description,
        messages: [
          {
            role: "user",
            content: { type: "text", text: result }
          }
        ]
      };
    });
  }
};
var FastMCPEventEmitterBase = EventEmitter;
var FastMCPEventEmitter = class extends FastMCPEventEmitterBase {
};
var FastMCP = class extends FastMCPEventEmitter {
  constructor(options) {
    super();
    this.options = options;
    this.#options = options;
    this.#authenticate = options.authenticate;
  }
  #options;
  #prompts = [];
  #resources = [];
  #resourcesTemplates = [];
  #sessions = [];
  #sseServer = null;
  #tools = [];
  #authenticate;
  get sessions() {
    return this.#sessions;
  }
  /**
   * Adds a tool to the server.
   */
  addTool(tool) {
    this.#tools.push(tool);
  }
  /**
   * Adds a resource to the server.
   */
  addResource(resource) {
    this.#resources.push(resource);
  }
  /**
   * Adds a resource template to the server.
   */
  addResourceTemplate(resource) {
    this.#resourcesTemplates.push(resource);
  }
  /**
   * Adds a prompt to the server.
   */
  addPrompt(prompt) {
    this.#prompts.push(prompt);
  }
  /**
   * Starts the server.
   */
  async start(options = {
    transportType: "stdio"
  }) {
    if (options.transportType === "stdio") {
      const transport = new StdioServerTransport();
      const session = new FastMCPSession({
        name: this.#options.name,
        version: this.#options.version,
        tools: this.#tools,
        resources: this.#resources,
        resourcesTemplates: this.#resourcesTemplates,
        prompts: this.#prompts
      });
      await session.connect(transport);
      this.#sessions.push(session);
      this.emit("connect", {
        session
      });
    } else if (options.transportType === "sse") {
      this.#sseServer = await startSSEServer({
        endpoint: options.sse.endpoint,
        port: options.sse.port,
        createServer: async (request) => {
          let auth;
          if (this.#authenticate) {
            auth = await this.#authenticate(request);
          }
          return new FastMCPSession({
            auth,
            name: this.#options.name,
            version: this.#options.version,
            tools: this.#tools,
            resources: this.#resources,
            resourcesTemplates: this.#resourcesTemplates,
            prompts: this.#prompts
          });
        },
        onClose: (session) => {
          this.emit("disconnect", {
            session
          });
        },
        onConnect: async (session) => {
          this.#sessions.push(session);
          this.emit("connect", {
            session
          });
        }
      });
      console.info(
        `server is running on SSE at http://localhost:${options.sse.port}${options.sse.endpoint}`
      );
    } else {
      throw new Error("Invalid transport type");
    }
  }
  /**
   * Stops the server.
   */
  async stop() {
    if (this.#sseServer) {
      this.#sseServer.close();
    }
  }
};
export {
  FastMCP,
  FastMCPSession,
  UnexpectedStateError,
  UserError,
  imageContent
};
//# sourceMappingURL=FastMCP.js.map