fastmcp 3.23.1 → 3.24.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";

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

@@ -1645,6 +1645,160 @@ var FastMCP = class extends FastMCPEventEmitter {
         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;
+      }
+    }
     res.writeHead(404).end();
   };
   #parseRuntimeConfig(overrides) {