fastmcp 3.23.1 → 3.25.0

package/README.md

@@ -1311,9 +1311,50 @@ server.addTool({
 
 In this example, only clients authenticating with the `admin` role will be able to list or call the `admin-dashboard` tool. The `public-info` tool will be available to all authenticated users.
 
-#### OAuth Support
+#### OAuth Proxy
 
-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):
+FastMCP includes a built-in **OAuth Proxy** that acts as a secure intermediary between MCP clients and upstream OAuth providers. The proxy handles the complete OAuth 2.1 authorization flow, including Dynamic Client Registration (DCR), PKCE, consent management, and token management with encryption and token swap patterns enabled by default.
+
+**Key Features:**
+
+- 🔐 **Secure by Default**: Automatic encryption (AES-256-GCM) and token swap pattern
+- 🚀 **Zero Configuration**: Auto-generates keys and handles OAuth flows automatically
+- 🔌 **Pre-configured Providers**: Built-in support for Google, GitHub, and Azure
+- 🎯 **RFC Compliant**: Implements DCR (RFC 7591), PKCE, and OAuth 2.1
+- 🔑 **Optional JWKS**: Support for RS256/ES256 token verification (via optional `jose` dependency)
+
+**Quick Start:**
+
+```ts
+import { FastMCP } from "fastmcp";
+import { GoogleProvider } from "fastmcp/auth";
+
+const authProxy = new GoogleProvider({
+  clientId: process.env.GOOGLE_CLIENT_ID,
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+  baseUrl: "https://your-server.com",
+  scopes: ["openid", "profile", "email"],
+});
+
+const server = new FastMCP({
+  name: "My Server",
+  oauth: {
+    enabled: true,
+    authorizationServer: authProxy.getAuthorizationServerMetadata(),
+    proxy: authProxy, // Routes automatically registered!
+  },
+});
+```
+
+**Documentation:**
+
+- [OAuth Proxy Features](docs/oauth-proxy-features.md) - Complete feature list and capabilities
+- [OAuth Proxy Implementation Guide](docs/oauth-proxy-guide.md) - Setup and configuration
+- [Python vs TypeScript Comparison](docs/oauth-python-typescript.md) - Feature comparison
+
+#### OAuth Discovery Endpoints
+
+FastMCP also supports OAuth discovery endpoints for direct integration with OAuth providers, supporting both **MCP Specification 2025-03-26** and **MCP Specification 2025-06-18**. This provides 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, DiscoveryDocumentCache } from "fastmcp";
@@ -1413,7 +1454,18 @@ const server = new FastMCP({
 This configuration automatically exposes OAuth discovery endpoints:
 
 - `/.well-known/oauth-authorization-server` - Authorization server metadata (RFC 8414)
-- `/.well-known/oauth-protected-resource` - Protected resource metadata (RFC 9470)
+- `/.well-known/oauth-protected-resource` - Protected resource metadata (RFC 9728)
+- `/.well-known/oauth-protected-resource<endpoint>` - Protected resource metadata at sub-path (MCP 2025-11-25)
+
+**Discovery Mechanism (MCP Specification 2025-11-25):**
+
+Clients discover protected resource metadata using the following search order:
+
+1. **WWW-Authenticate header** - Primary method (handled automatically by mcp-proxy)
+2. **Sub-path well-known** - `/.well-known/oauth-protected-resource<endpoint>` (e.g., `/.well-known/oauth-protected-resource/mcp`)
+3. **Root well-known** - `/.well-known/oauth-protected-resource` (fallback)
+
+Both the sub-path and root endpoints return identical metadata, ensuring compatibility with all MCP client implementations.
 
 For JWT token validation, you can use libraries like [`get-jwks`](https://github.com/nearform/get-jwks) and [`@fastify/jwt`](https://github.com/fastify/fastify-jwt) for OAuth JWT tokens.
 

package/dist/FastMCP.d.ts

@@ -9,6 +9,7 @@ import { EventEmitter } from 'events';
 import http from 'http';
 import { StrictEventEmitter } from 'strict-event-emitter-types';
 import { z } from 'zod';
+import { O as OAuthProxy } from './OAuthProxy-BOCkkAhO.js';
 
 declare class DiscoveryDocumentCache {
     #private;
@@ -493,6 +494,16 @@ type ServerOptions<T extends FastMCPSessionAuth> = {
              */
             tlsClientCertificateBoundAccessTokens?: boolean;
         };
+        /**
+         * OAuth Proxy instance for automatic OAuth flow handling.
+         * When provided, FastMCP will automatically register OAuth endpoints:
+         * - /oauth/register (DCR)
+         * - /oauth/authorize
+         * - /oauth/token
+         * - /oauth/callback
+         * - /oauth/consent
+         */
+        proxy?: OAuthProxy;
     };
     ping?: {
         /**

package/dist/FastMCP.js

@@ -1475,7 +1475,13 @@ var FastMCP = class extends FastMCPEventEmitter {
             );
           },
           onUnhandledRequest: async (req, res) => {
-            await this.#handleUnhandledRequest(req, res, true, httpConfig.host);
+            await this.#handleUnhandledRequest(
+              req,
+              res,
+              true,
+              httpConfig.host,
+              httpConfig.endpoint
+            );
           },
           port: httpConfig.port,
           stateless: true,
@@ -1521,7 +1527,8 @@ var FastMCP = class extends FastMCPEventEmitter {
               req,
               res,
               false,
-              httpConfig.host
+              httpConfig.host,
+              httpConfig.endpoint
             );
           },
           port: httpConfig.port,
@@ -1578,7 +1585,7 @@ var FastMCP = class extends FastMCPEventEmitter {
   /**
    * Handles unhandled HTTP requests with health, readiness, and OAuth endpoints
    */
-  #handleUnhandledRequest = async (req, res, isStateless = false, host) => {
+  #handleUnhandledRequest = async (req, res, isStateless = false, host, streamEndpoint) => {
     const healthConfig = this.#options.health ?? {};
     const enabled = healthConfig.enabled === void 0 ? true : healthConfig.enabled;
     if (enabled) {
@@ -1635,13 +1642,176 @@ var FastMCP = class extends FastMCPEventEmitter {
         }).end(JSON.stringify(metadata));
         return;
       }
-      if (url.pathname === "/.well-known/oauth-protected-resource" && oauthConfig.protectedResource) {
-        const metadata = convertObjectToSnakeCase(
-          oauthConfig.protectedResource
-        );
-        res.writeHead(200, {
-          "Content-Type": "application/json"
-        }).end(JSON.stringify(metadata));
+      if (oauthConfig.protectedResource) {
+        const wellKnownBase = "/.well-known/oauth-protected-resource";
+        let shouldServeMetadata = false;
+        if (streamEndpoint && url.pathname === `${wellKnownBase}${streamEndpoint}`) {
+          shouldServeMetadata = true;
+        } else if (url.pathname === wellKnownBase) {
+          shouldServeMetadata = true;
+        }
+        if (shouldServeMetadata) {
+          const metadata = convertObjectToSnakeCase(
+            oauthConfig.protectedResource
+          );
+          res.writeHead(200, {
+            "Content-Type": "application/json"
+          }).end(JSON.stringify(metadata));
+          return;
+        }
+      }
+    }
+    const oauthProxy = oauthConfig?.proxy;
+    if (oauthProxy && oauthConfig?.enabled) {
+      const url = new URL(req.url || "", `http://${host}`);
+      try {
+        if (req.method === "POST" && url.pathname === "/oauth/register") {
+          let body = "";
+          req.on("data", (chunk) => body += chunk);
+          req.on("end", async () => {
+            try {
+              const request = JSON.parse(body);
+              const response = await oauthProxy.registerClient(request);
+              res.writeHead(201, { "Content-Type": "application/json" }).end(JSON.stringify(response));
+            } catch (error) {
+              const statusCode = error.statusCode || 400;
+              res.writeHead(statusCode, { "Content-Type": "application/json" }).end(
+                JSON.stringify(
+                  error.toJSON?.() || {
+                    error: "invalid_request"
+                  }
+                )
+              );
+            }
+          });
+          return;
+        }
+        if (req.method === "GET" && url.pathname === "/oauth/authorize") {
+          try {
+            const params = Object.fromEntries(url.searchParams.entries());
+            const response = await oauthProxy.authorize(
+              params
+            );
+            const location = response.headers.get("Location");
+            if (location) {
+              res.writeHead(response.status, { Location: location }).end();
+            } else {
+              const html = await response.text();
+              res.writeHead(response.status, { "Content-Type": "text/html" }).end(html);
+            }
+          } catch (error) {
+            res.writeHead(400, { "Content-Type": "application/json" }).end(
+              JSON.stringify(
+                error.toJSON?.() || {
+                  error: "invalid_request"
+                }
+              )
+            );
+          }
+          return;
+        }
+        if (req.method === "GET" && url.pathname === "/oauth/callback") {
+          try {
+            const mockRequest = new Request(`http://${host}${req.url}`);
+            const response = await oauthProxy.handleCallback(mockRequest);
+            const location = response.headers.get("Location");
+            if (location) {
+              res.writeHead(response.status, { Location: location }).end();
+            } else {
+              const text = await response.text();
+              res.writeHead(response.status).end(text);
+            }
+          } catch (error) {
+            res.writeHead(400, { "Content-Type": "application/json" }).end(
+              JSON.stringify(
+                error.toJSON?.() || {
+                  error: "server_error"
+                }
+              )
+            );
+          }
+          return;
+        }
+        if (req.method === "POST" && url.pathname === "/oauth/consent") {
+          let body = "";
+          req.on("data", (chunk) => body += chunk);
+          req.on("end", async () => {
+            try {
+              const mockRequest = new Request(`http://${host}/oauth/consent`, {
+                body,
+                headers: {
+                  "Content-Type": "application/x-www-form-urlencoded"
+                },
+                method: "POST"
+              });
+              const response = await oauthProxy.handleConsent(mockRequest);
+              const location = response.headers.get("Location");
+              if (location) {
+                res.writeHead(response.status, { Location: location }).end();
+              } else {
+                const text = await response.text();
+                res.writeHead(response.status).end(text);
+              }
+            } catch (error) {
+              res.writeHead(400, { "Content-Type": "application/json" }).end(
+                JSON.stringify(
+                  error.toJSON?.() || {
+                    error: "server_error"
+                  }
+                )
+              );
+            }
+          });
+          return;
+        }
+        if (req.method === "POST" && url.pathname === "/oauth/token") {
+          let body = "";
+          req.on("data", (chunk) => body += chunk);
+          req.on("end", async () => {
+            try {
+              const params = new URLSearchParams(body);
+              const grantType = params.get("grant_type");
+              let response;
+              if (grantType === "authorization_code") {
+                response = await oauthProxy.exchangeAuthorizationCode({
+                  client_id: params.get("client_id") || "",
+                  client_secret: params.get("client_secret") || void 0,
+                  code: params.get("code") || "",
+                  code_verifier: params.get("code_verifier") || void 0,
+                  grant_type: "authorization_code",
+                  redirect_uri: params.get("redirect_uri") || ""
+                });
+              } else if (grantType === "refresh_token") {
+                response = await oauthProxy.exchangeRefreshToken({
+                  client_id: params.get("client_id") || "",
+                  client_secret: params.get("client_secret") || void 0,
+                  grant_type: "refresh_token",
+                  refresh_token: params.get("refresh_token") || "",
+                  scope: params.get("scope") || void 0
+                });
+              } else {
+                throw {
+                  statusCode: 400,
+                  toJSON: () => ({ error: "unsupported_grant_type" })
+                };
+              }
+              res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify(response));
+            } catch (error) {
+              const statusCode = error.statusCode || 400;
+              res.writeHead(statusCode, { "Content-Type": "application/json" }).end(
+                JSON.stringify(
+                  error.toJSON?.() || {
+                    error: "invalid_request"
+                  }
+                )
+              );
+            }
+          });
+          return;
+        }
+      } catch (error) {
+        this.#logger.error("[FastMCP error] OAuth Proxy endpoint error", error);
+        res.writeHead(500).end();
         return;
       }
     }