fastmcp 3.20.1 → 3.21.0

package/README.md

@@ -1316,10 +1316,15 @@ In this example, only clients authenticating with the `admin` role will be able
 FastMCP includes built-in support for OAuth discovery endpoints, supporting both **MCP Specification 2025-03-26** and **MCP Specification 2025-06-18** for OAuth integration. This makes it easy to integrate with OAuth authorization flows by providing standard discovery endpoints that comply with RFC 8414 (OAuth 2.0 Authorization Server Metadata) and RFC 9470 (OAuth 2.0 Protected Resource Metadata):
 
 ```ts
-import { FastMCP } from "fastmcp";
+import { FastMCP, DiscoveryDocumentCache } from "fastmcp";
 import { buildGetJwks } from "get-jwks";
 import fastJwt from "fast-jwt";
 
+// Create a cache for discovery documents (reuse across requests)
+const discoveryCache = new DiscoveryDocumentCache({
+  ttl: 3600000, // Cache for 1 hour (default)
+});
+
 const server = new FastMCP({
   name: "My Server",
   version: "1.0.0",
@@ -1351,19 +1356,16 @@ const server = new FastMCP({
 
     // Validate OAuth JWT access token using OpenID Connect discovery
     try {
-      // TODO: Cache the discovery document to avoid repeated requests
-      // Discover OAuth/OpenID configuration from well-known endpoint
+      // Fetch and cache the discovery document
       const discoveryUrl =
         "https://auth.example.com/.well-known/openid-configuration";
       // Alternative: Use OAuth authorization server metadata endpoint
       // const discoveryUrl = 'https://auth.example.com/.well-known/oauth-authorization-server';
 
-      const discoveryResponse = await fetch(discoveryUrl);
-      if (!discoveryResponse.ok) {
-        throw new Error("Failed to fetch OAuth discovery document");
-      }
-
-      const config = await discoveryResponse.json();
+      const config = (await discoveryCache.get(discoveryUrl)) as {
+        jwks_uri: string;
+        issuer: string;
+      };
       const jwksUri = config.jwks_uri;
       const issuer = config.issuer;
 

package/dist/FastMCP.d.ts

@@ -10,6 +10,37 @@ import http from 'http';
 import { StrictEventEmitter } from 'strict-event-emitter-types';
 import { z } from 'zod';
 
+declare class DiscoveryDocumentCache {
+    #private;
+    get size(): number;
+    /**
+     * @param options - configuration options
+     * @param options.ttl - time-to-live in miliseconds
+     */
+    constructor(options?: {
+        ttl?: number;
+    });
+    /**
+     * @param url - optional URL to clear. if omitted, clears all cached documents.
+     */
+    clear(url?: string): void;
+    /**
+     * fetches a discovery document from the given URL.
+     * uses cached value if available and not expired.
+     * coalesces concurrent requests for the same URL to prevent duplicate fetches.
+     *
+     * @param url - the discovery document URL (e.g., /.well-known/openid-configuration)
+     * @returns the discovery document as a JSON object
+     * @throws Error if the fetch fails or returns non-OK status
+     */
+    get(url: string): Promise<unknown>;
+    /**
+     * @param url - the URL to check
+     * @returns true if the URL is cached and nott expired
+     */
+    has(url: string): boolean;
+}
+
 interface Logger {
     debug(...args: unknown[]): void;
     error(...args: unknown[]): void;
@@ -648,4 +679,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
     stop(): Promise<void>;
 }
 
-export { type AudioContent, type Content, type ContentResult, type Context, FastMCP, type FastMCPEvents, FastMCPSession, type FastMCPSessionEvents, type ImageContent, type InputPrompt, type InputPromptArgument, type Logger, type LoggingLevel, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type SSEServer, type SerializableValue, type ServerOptions, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };
+export { type AudioContent, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, FastMCPSession, type FastMCPSessionEvents, type ImageContent, type InputPrompt, type InputPromptArgument, type Logger, type LoggingLevel, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type SSEServer, type SerializableValue, type ServerOptions, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };

package/dist/FastMCP.js

@@ -20,16 +20,104 @@ import { readFile } from "fs/promises";
 import Fuse from "fuse.js";
 import { startHTTPServer } from "mcp-proxy";
 import { setTimeout as delay } from "timers/promises";
-import { fetch } from "undici";
+import { fetch as fetch2 } from "undici";
 import parseURITemplate from "uri-templates";
 import { toJsonSchema } from "xsschema";
 import { z } from "zod";
+
+// src/DiscoveryDocumentCache.ts
+var DiscoveryDocumentCache = class {
+  get size() {
+    return this.#cache.size;
+  }
+  #cache = /* @__PURE__ */ new Map();
+  #inFlight = /* @__PURE__ */ new Map();
+  #ttl;
+  /**
+   * @param options - configuration options
+   * @param options.ttl - time-to-live in miliseconds
+   */
+  constructor(options = {}) {
+    this.#ttl = options.ttl ?? 36e5;
+  }
+  /**
+   * @param url - optional URL to clear. if omitted, clears all cached documents.
+   */
+  clear(url) {
+    if (url) {
+      this.#cache.delete(url);
+    } else {
+      this.#cache.clear();
+    }
+  }
+  /**
+   * fetches a discovery document from the given URL.
+   * uses cached value if available and not expired.
+   * coalesces concurrent requests for the same URL to prevent duplicate fetches.
+   *
+   * @param url - the discovery document URL (e.g., /.well-known/openid-configuration)
+   * @returns the discovery document as a JSON object
+   * @throws Error if the fetch fails or returns non-OK status
+   */
+  async get(url) {
+    const now = Date.now();
+    const cached = this.#cache.get(url);
+    if (cached && cached.expiresAt > now) {
+      return cached.data;
+    }
+    const inFlight = this.#inFlight.get(url);
+    if (inFlight) {
+      return inFlight;
+    }
+    const fetchPromise = this.#fetchAndCache(url);
+    this.#inFlight.set(url, fetchPromise);
+    try {
+      const data = await fetchPromise;
+      return data;
+    } finally {
+      this.#inFlight.delete(url);
+    }
+  }
+  /**
+   * @param url - the URL to check
+   * @returns true if the URL is cached and nott expired
+   */
+  has(url) {
+    const cached = this.#cache.get(url);
+    if (!cached) {
+      return false;
+    }
+    const now = Date.now();
+    if (cached.expiresAt <= now) {
+      this.#cache.delete(url);
+      return false;
+    }
+    return true;
+  }
+  async #fetchAndCache(url) {
+    const res = await fetch(url);
+    if (!res.ok) {
+      throw new Error(
+        `Failed to fetch discovery document from ${url}: ${res.status} ${res.statusText}`
+      );
+    }
+    const data = await res.json();
+    const expiresAt = Date.now() + this.#ttl;
+    this.#cache.set(url, {
+      data,
+      expiresAt
+    });
+    return data;
+  }
+};
+
+// src/FastMCP.ts
 var imageContent = async (input) => {
   let rawData;
   try {
     if ("url" in input) {
       try {
-        const response = await fetch(input.url);
+        const response = await fetch2(input.url);
         if (!response.ok) {
           throw new Error(
             `Server responded with status: ${response.status} - ${response.statusText}`
@@ -82,7 +170,7 @@ var audioContent = async (input) => {
   try {
     if ("url" in input) {
       try {
-        const response = await fetch(input.url);
+        const response = await fetch2(input.url);
         if (!response.ok) {
           throw new Error(
             `Server responded with status: ${response.status} - ${response.statusText}`
@@ -1382,6 +1470,7 @@ var FastMCP = class extends FastMCPEventEmitter {
   }
 };
 export {
+  DiscoveryDocumentCache,
   FastMCP,
   FastMCPSession,
   UnexpectedStateError,