npm - fastmcp - Versions diffs - 4.7.0 → 4.7.2 - Mend

fastmcp 4.7.0 → 4.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +68 -47
package/dist/FastMCP.cjs +2 -2
package/dist/FastMCP.js +1 -1
package/dist/{chunk-MLFG3TOK.cjs → chunk-553XY3CA.cjs} +67 -25
package/dist/chunk-553XY3CA.cjs.map +1 -0
package/dist/{chunk-YMUXVDGJ.js → chunk-KAGSBU3Z.js} +45 -3
package/dist/{chunk-YMUXVDGJ.js.map → chunk-KAGSBU3Z.js.map} +1 -1
package/dist/examples/custom-routes.cjs +2 -2
package/dist/examples/custom-routes.js +1 -1
package/package.json +2 -2
package/dist/chunk-MLFG3TOK.cjs.map +0 -1

package/README.md CHANGED Viewed

@@ -267,87 +267,108 @@ The `CorsOptions` type is exported from `fastmcp` for convenience.
 FastMCP allows you to add custom HTTP routes alongside MCP endpoints, enabling you to build comprehensive HTTP services that include REST APIs, webhooks, admin interfaces, and more - all within the same server process.
 ```ts
-// Add REST API endpoints
-server.addRoute("GET", "/api/users", async (req, res) => {
-  res.json({ users: [] });
+const app = server.getApp();
+// Add REST API endpoints with Hono's native API
+app.get("/api/users", async (c) => {
+  return c.json({ users: [] });
 });
 // Handle path parameters
-server.addRoute("GET", "/api/users/:id", async (req, res) => {
-  res.json({
-    userId: req.params.id,
-    query: req.query, // Access query parameters
+app.get("/api/users/:id", async (c) => {
+  return c.json({
+    userId: c.req.param("id"),
+    query: c.req.query(), // Access query parameters
   });
 });
 // Handle POST requests with body parsing
-server.addRoute("POST", "/api/users", async (req, res) => {
-  const body = await req.json();
-  res.status(201).json({ created: body });
+app.post("/api/users", async (c) => {
+  const body = await c.req.json();
+  return c.json({ created: body }, 201);
 });
 // Serve HTML content
-server.addRoute("GET", "/admin", async (req, res) => {
-  res.send("<html><body><h1>Admin Panel</h1></body></html>");
+app.get("/admin", async (c) => {
+  return c.html("<html><body><h1>Admin Panel</h1></body></html>");
 });
 // Handle webhooks
-server.addRoute("POST", "/webhook/github", async (req, res) => {
-  const payload = await req.json();
-  const event = req.headers["x-github-event"];
+app.post("/webhook/github", async (c) => {
+  const payload = await c.req.json();
+  const event = c.req.header("x-github-event");
   // Process webhook...
-  res.json({ received: true });
+  return c.json({ received: true });
 });
 ```
-Custom routes support:
+Custom routes use the underlying [Hono](https://hono.dev/) app returned by `server.getApp()` and support:
-- All HTTP methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
+- Hono's HTTP methods: `get`, `post`, `put`, `delete`, `patch`, `options`, and more
 - Path parameters (`:param`) and wildcards (`*`)
 - Query string parsing
-- JSON and text body parsing
+- JSON, text, form, and other body helpers from `c.req`
 - Custom status codes and headers
-- Authentication via the same `authenticate` function as MCP
-- **Public routes** that bypass authentication
+- Middleware and route groups through Hono
 Routes are matched in the order they are registered, allowing you to define specific routes before catch-all patterns.
-##### Public Routes
+##### Public and Protected Routes
-By default, custom routes require authentication (if configured). You can make routes public by adding the `{ public: true }` option:
+Custom Hono routes are public unless you add your own route middleware or authentication checks. For protected custom routes, put your auth logic in a reusable helper and call it from both FastMCP's `authenticate` option and your Hono route handlers:
 ```ts
+import type { IncomingMessage } from "node:http";
+import type { Context } from "hono";
+import { FastMCP } from "fastmcp";
+async function authenticateRequest(request: IncomingMessage) {
+  const apiKey = request.headers["x-api-key"];
+  return apiKey === "123" ? { userId: "123" } : undefined;
+}
+const server = new FastMCP({
+  name: "My Server",
+  version: "1.0.0",
+  authenticate: authenticateRequest,
+});
+const app = server.getApp();
+async function requireAuth(c: Context) {
+  const auth = await authenticateRequest(c.env.incoming);
+  if (!auth) {
+    return c.json({ error: "Authentication required" }, 401);
+  }
+  return auth;
+}
 // Public route - no authentication required
-server.addRoute(
-  "GET",
-  "/.well-known/openid-configuration",
-  async (req, res) => {
-    res.json({
-      issuer: "https://example.com",
-      authorization_endpoint: "https://example.com/auth",
-      token_endpoint: "https://example.com/token",
-    });
-  },
-  { public: true },
-);
+app.get("/.well-known/openid-configuration", async (c) => {
+  return c.json({
+    issuer: "https://example.com",
+    authorization_endpoint: "https://example.com/auth",
+    token_endpoint: "https://example.com/token",
+  });
+});
 // Private route - requires authentication
-server.addRoute("GET", "/api/users", async (req, res) => {
-  // req.auth contains authenticated user data
-  res.json({ users: [] });
+app.get("/api/users", async (c) => {
+  const auth = await requireAuth(c);
+  if (auth instanceof Response) {
+    return auth;
+  }
+  return c.json({ users: [] });
 });
 // Public static files
-server.addRoute(
-  "GET",
-  "/public/*",
-  async (req, res) => {
-    // Serve static files without authentication
-    res.send(`File: ${req.url}`);
-  },
-  { public: true },
-);
+app.get("/public/*", async (c) => {
+  return c.text(`File: ${c.req.path}`);
+});
 ```
 Public routes are perfect for:

package/dist/FastMCP.cjs CHANGED Viewed

@@ -7,7 +7,7 @@
-var _chunkMLFG3TOKcjs = require('./chunk-MLFG3TOK.cjs');
+var _chunk553XY3CAcjs = require('./chunk-553XY3CA.cjs');
@@ -41,5 +41,5 @@ var _chunkIX3HKAX4cjs = require('./chunk-IX3HKAX4.cjs');
-exports.AuthProvider = _chunkIX3HKAX4cjs.AuthProvider; exports.AzureProvider = _chunkIX3HKAX4cjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkMLFG3TOKcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkMLFG3TOKcjs.FastMCP; exports.FastMCPSession = _chunkMLFG3TOKcjs.FastMCPSession; exports.GitHubProvider = _chunkIX3HKAX4cjs.GitHubProvider; exports.GoogleProvider = _chunkIX3HKAX4cjs.GoogleProvider; exports.OAuthProvider = _chunkIX3HKAX4cjs.OAuthProvider; exports.ServerState = _chunkMLFG3TOKcjs.ServerState; exports.UnexpectedStateError = _chunkMLFG3TOKcjs.UnexpectedStateError; exports.UserError = _chunkMLFG3TOKcjs.UserError; exports.audioContent = _chunkMLFG3TOKcjs.audioContent; exports.getAuthSession = _chunkIX3HKAX4cjs.getAuthSession; exports.imageContent = _chunkMLFG3TOKcjs.imageContent; exports.requireAll = _chunkIX3HKAX4cjs.requireAll; exports.requireAny = _chunkIX3HKAX4cjs.requireAny; exports.requireAuth = _chunkIX3HKAX4cjs.requireAuth; exports.requireRole = _chunkIX3HKAX4cjs.requireRole; exports.requireScopes = _chunkIX3HKAX4cjs.requireScopes;
+exports.AuthProvider = _chunkIX3HKAX4cjs.AuthProvider; exports.AzureProvider = _chunkIX3HKAX4cjs.AzureProvider; exports.DiscoveryDocumentCache = _chunk553XY3CAcjs.DiscoveryDocumentCache; exports.FastMCP = _chunk553XY3CAcjs.FastMCP; exports.FastMCPSession = _chunk553XY3CAcjs.FastMCPSession; exports.GitHubProvider = _chunkIX3HKAX4cjs.GitHubProvider; exports.GoogleProvider = _chunkIX3HKAX4cjs.GoogleProvider; exports.OAuthProvider = _chunkIX3HKAX4cjs.OAuthProvider; exports.ServerState = _chunk553XY3CAcjs.ServerState; exports.UnexpectedStateError = _chunk553XY3CAcjs.UnexpectedStateError; exports.UserError = _chunk553XY3CAcjs.UserError; exports.audioContent = _chunk553XY3CAcjs.audioContent; exports.getAuthSession = _chunkIX3HKAX4cjs.getAuthSession; exports.imageContent = _chunk553XY3CAcjs.imageContent; exports.requireAll = _chunkIX3HKAX4cjs.requireAll; exports.requireAny = _chunkIX3HKAX4cjs.requireAny; exports.requireAuth = _chunkIX3HKAX4cjs.requireAuth; exports.requireRole = _chunkIX3HKAX4cjs.requireRole; exports.requireScopes = _chunkIX3HKAX4cjs.requireScopes;
 //# sourceMappingURL=FastMCP.cjs.map

package/dist/FastMCP.js CHANGED Viewed

@@ -7,7 +7,7 @@ import {
   UserError,
   audioContent,
   imageContent
-} from "./chunk-YMUXVDGJ.js";
+} from "./chunk-KAGSBU3Z.js";
 import {
   AuthProvider,
   AzureProvider,

package/dist/{chunk-MLFG3TOK.cjs → chunk-553XY3CA.cjs} RENAMED Viewed

@@ -1676,7 +1676,9 @@ var FastMCP = class extends FastMCPEventEmitter {
             if (this.#authenticate) {
               auth = await this.#authenticate(request);
               if (auth === void 0 || auth === null) {
-                throw new Error("Authentication required");
+                throw this.#createUnauthorizedResponse(
+                  "Authentication required"
+                );
               }
             }
             const sessionId = Array.isArray(request.headers["mcp-session-id"]) ? request.headers["mcp-session-id"][0] : request.headers["mcp-session-id"];
@@ -1795,7 +1797,7 @@ var FastMCP = class extends FastMCPEventEmitter {
   #createSession(auth, sessionId) {
     if (auth && typeof auth === "object" && "authenticated" in auth && !auth.authenticated) {
       const errorMessage = "error" in auth && typeof auth.error === "string" ? auth.error : "Authentication failed";
-      throw new Error(errorMessage);
+      throw this.#createUnauthorizedResponse(errorMessage);
     }
     const allowedTools = auth ? this.#tools.filter(
       (tool) => tool.canAccess ? tool.canAccess(auth) : true
@@ -1818,6 +1820,46 @@ var FastMCP = class extends FastMCPEventEmitter {
       version: this.#options.version
     });
   }
+  /**
+   * Builds a 401 Unauthorized HTTP Response for authentication failures.
+   *
+   * Throwing a `Response` (rather than a plain `Error`) guarantees that the
+   * transport (e.g. mcp-proxy) surfaces the correct status code directly,
+   * instead of relying on heuristics that infer the status code from the
+   * error message's text (see https://github.com/punkpeye/fastmcp/issues/180).
+   *
+   * The response body matches the JSON-RPC error envelope FastMCP otherwise
+   * produces, and a `WWW-Authenticate` header is included per RFC 7235 (and
+   * RFC 9728 when protected-resource metadata is configured), so HTTP-aware
+   * clients can distinguish "unauthenticated" from a malformed request.
+   */
+  #createUnauthorizedResponse(message) {
+    const oauth = this.#options.oauth;
+    const resource = _optionalChain([oauth, 'optionalAccess', _48 => _48.enabled]) ? _optionalChain([oauth, 'access', _49 => _49.protectedResource, 'optionalAccess', _50 => _50.resource]) : void 0;
+    const wwwAuthenticateParts = [
+      'error="invalid_token"',
+      `error_description="${message.replace(/"/g, '\\"')}"`
+    ];
+    if (resource) {
+      wwwAuthenticateParts.push(
+        `resource_metadata="${resource}/.well-known/oauth-protected-resource"`
+      );
+    }
+    return new Response(
+      JSON.stringify({
+        error: { code: -32e3, message },
+        id: null,
+        jsonrpc: "2.0"
+      }),
+      {
+        headers: {
+          "Content-Type": "application/json",
+          "WWW-Authenticate": `Bearer ${wwwAuthenticateParts.join(", ")}`
+        },
+        status: 401
+      }
+    );
+  }
   /**
    * Handles unhandled HTTP requests with health, readiness, OAuth endpoints, and custom routes
    */
@@ -1905,7 +1947,7 @@ var FastMCP = class extends FastMCPEventEmitter {
       }
     }
     const oauthConfig = this.#options.oauth;
-    if (_optionalChain([oauthConfig, 'optionalAccess', _48 => _48.enabled]) && req.method === "GET") {
+    if (_optionalChain([oauthConfig, 'optionalAccess', _51 => _51.enabled]) && req.method === "GET") {
       const url2 = new URL(req.url || "", `http://${host}`);
       const authorizationServerMetadataPath = joinPaths(
         "",
@@ -1939,8 +1981,8 @@ var FastMCP = class extends FastMCPEventEmitter {
         }
       }
     }
-    const oauthProxy = _optionalChain([oauthConfig, 'optionalAccess', _49 => _49.proxy]);
-    if (oauthProxy && _optionalChain([oauthConfig, 'optionalAccess', _50 => _50.enabled])) {
+    const oauthProxy = _optionalChain([oauthConfig, 'optionalAccess', _52 => _52.proxy]);
+    if (oauthProxy && _optionalChain([oauthConfig, 'optionalAccess', _53 => _53.enabled])) {
       const url2 = new URL(req.url || "", `http://${host}`);
       const oauthPath = basePathRelativePath;
       try {
@@ -1957,7 +1999,7 @@ var FastMCP = class extends FastMCPEventEmitter {
                 const statusCode = error.statusCode || 400;
                 res.writeHead(statusCode, { "Content-Type": "application/json" }).end(
                   JSON.stringify(
-                    _optionalChain([error, 'access', _51 => _51.toJSON, 'optionalCall', _52 => _52()]) || {
+                    _optionalChain([error, 'access', _54 => _54.toJSON, 'optionalCall', _55 => _55()]) || {
                       error: "invalid_request"
                     }
                   )
@@ -1984,7 +2026,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           } catch (error) {
             res.writeHead(400, { "Content-Type": "application/json" }).end(
               JSON.stringify(
-                _optionalChain([error, 'access', _53 => _53.toJSON, 'optionalCall', _54 => _54()]) || {
+                _optionalChain([error, 'access', _56 => _56.toJSON, 'optionalCall', _57 => _57()]) || {
                   error: "invalid_request"
                 }
               )
@@ -2006,7 +2048,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           } catch (error) {
             res.writeHead(400, { "Content-Type": "application/json" }).end(
               JSON.stringify(
-                _optionalChain([error, 'access', _55 => _55.toJSON, 'optionalCall', _56 => _56()]) || {
+                _optionalChain([error, 'access', _58 => _58.toJSON, 'optionalCall', _59 => _59()]) || {
                   error: "server_error"
                 }
               )
@@ -2041,7 +2083,7 @@ var FastMCP = class extends FastMCPEventEmitter {
               } catch (error) {
                 res.writeHead(400, { "Content-Type": "application/json" }).end(
                   JSON.stringify(
-                    _optionalChain([error, 'access', _57 => _57.toJSON, 'optionalCall', _58 => _58()]) || {
+                    _optionalChain([error, 'access', _60 => _60.toJSON, 'optionalCall', _61 => _61()]) || {
                       error: "server_error"
                     }
                   )
@@ -2063,8 +2105,8 @@ var FastMCP = class extends FastMCPEventEmitter {
                 const basicAuth = parseBasicAuthHeader(
                   req.headers.authorization
                 );
-                const clientId = _optionalChain([basicAuth, 'optionalAccess', _59 => _59.clientId]) || params.get("client_id") || "";
-                const clientSecret = _nullishCoalesce(_nullishCoalesce(_optionalChain([basicAuth, 'optionalAccess', _60 => _60.clientSecret]), () => ( params.get("client_secret"))), () => ( void 0));
+                const clientId = _optionalChain([basicAuth, 'optionalAccess', _62 => _62.clientId]) || params.get("client_id") || "";
+                const clientSecret = _nullishCoalesce(_nullishCoalesce(_optionalChain([basicAuth, 'optionalAccess', _63 => _63.clientSecret]), () => ( params.get("client_secret"))), () => ( void 0));
                 let response;
                 if (grantType === "authorization_code") {
                   response = await oauthProxy.exchangeAuthorizationCode({
@@ -2094,7 +2136,7 @@ var FastMCP = class extends FastMCPEventEmitter {
                 const statusCode = error.statusCode || 400;
                 res.writeHead(statusCode, { "Content-Type": "application/json" }).end(
                   JSON.stringify(
-                    _optionalChain([error, 'access', _61 => _61.toJSON, 'optionalCall', _62 => _62()]) || {
+                    _optionalChain([error, 'access', _64 => _64.toJSON, 'optionalCall', _65 => _65()]) || {
                       error: "invalid_request"
                     }
                   )
@@ -2165,23 +2207,23 @@ var FastMCP = class extends FastMCPEventEmitter {
     const envBasePath = process.env.FASTMCP_BASE_PATH;
     const envStateless = process.env.FASTMCP_STATELESS;
     const envHost = process.env.FASTMCP_HOST;
-    const transportType = _optionalChain([overrides, 'optionalAccess', _63 => _63.transportType]) || (transportArg === "http-stream" ? "httpStream" : transportArg) || envTransport || "stdio";
+    const transportType = _optionalChain([overrides, 'optionalAccess', _66 => _66.transportType]) || (transportArg === "http-stream" ? "httpStream" : transportArg) || envTransport || "stdio";
     if (transportType === "httpStream") {
       const port = parseInt(
-        _optionalChain([overrides, 'optionalAccess', _64 => _64.httpStream, 'optionalAccess', _65 => _65.port, 'optionalAccess', _66 => _66.toString, 'call', _67 => _67()]) || portArg || envPort || "8080"
+        _optionalChain([overrides, 'optionalAccess', _67 => _67.httpStream, 'optionalAccess', _68 => _68.port, 'optionalAccess', _69 => _69.toString, 'call', _70 => _70()]) || portArg || envPort || "8080"
       );
-      const host = _optionalChain([overrides, 'optionalAccess', _68 => _68.httpStream, 'optionalAccess', _69 => _69.host]) || hostArg || envHost || "localhost";
-      const endpoint = _optionalChain([overrides, 'optionalAccess', _70 => _70.httpStream, 'optionalAccess', _71 => _71.endpoint]) || endpointArg || envEndpoint || "/mcp";
+      const host = _optionalChain([overrides, 'optionalAccess', _71 => _71.httpStream, 'optionalAccess', _72 => _72.host]) || hostArg || envHost || "localhost";
+      const endpoint = _optionalChain([overrides, 'optionalAccess', _73 => _73.httpStream, 'optionalAccess', _74 => _74.endpoint]) || endpointArg || envEndpoint || "/mcp";
       const basePath = normalizeBasePath(
-        _optionalChain([overrides, 'optionalAccess', _72 => _72.httpStream, 'optionalAccess', _73 => _73.basePath]) || basePathArg || envBasePath
+        _optionalChain([overrides, 'optionalAccess', _75 => _75.httpStream, 'optionalAccess', _76 => _76.basePath]) || basePathArg || envBasePath
       );
-      const enableJsonResponse = _optionalChain([overrides, 'optionalAccess', _74 => _74.httpStream, 'optionalAccess', _75 => _75.enableJsonResponse]) || false;
-      const stateless = _optionalChain([overrides, 'optionalAccess', _76 => _76.httpStream, 'optionalAccess', _77 => _77.stateless]) || statelessArg === "true" || envStateless === "true" || false;
-      const cors = _optionalChain([overrides, 'optionalAccess', _78 => _78.httpStream, 'optionalAccess', _79 => _79.cors]);
-      const eventStore = _optionalChain([overrides, 'optionalAccess', _80 => _80.httpStream, 'optionalAccess', _81 => _81.eventStore]);
-      const sslCa = _optionalChain([overrides, 'optionalAccess', _82 => _82.httpStream, 'optionalAccess', _83 => _83.sslCa]);
-      const sslCert = _optionalChain([overrides, 'optionalAccess', _84 => _84.httpStream, 'optionalAccess', _85 => _85.sslCert]);
-      const sslKey = _optionalChain([overrides, 'optionalAccess', _86 => _86.httpStream, 'optionalAccess', _87 => _87.sslKey]);
+      const enableJsonResponse = _optionalChain([overrides, 'optionalAccess', _77 => _77.httpStream, 'optionalAccess', _78 => _78.enableJsonResponse]) || false;
+      const stateless = _optionalChain([overrides, 'optionalAccess', _79 => _79.httpStream, 'optionalAccess', _80 => _80.stateless]) || statelessArg === "true" || envStateless === "true" || false;
+      const cors = _optionalChain([overrides, 'optionalAccess', _81 => _81.httpStream, 'optionalAccess', _82 => _82.cors]);
+      const eventStore = _optionalChain([overrides, 'optionalAccess', _83 => _83.httpStream, 'optionalAccess', _84 => _84.eventStore]);
+      const sslCa = _optionalChain([overrides, 'optionalAccess', _85 => _85.httpStream, 'optionalAccess', _86 => _86.sslCa]);
+      const sslCert = _optionalChain([overrides, 'optionalAccess', _87 => _87.httpStream, 'optionalAccess', _88 => _88.sslCert]);
+      const sslKey = _optionalChain([overrides, 'optionalAccess', _89 => _89.httpStream, 'optionalAccess', _90 => _90.sslKey]);
       return {
         httpStream: {
           basePath,
@@ -2254,4 +2296,4 @@ var FastMCP = class extends FastMCPEventEmitter {
 exports.DiscoveryDocumentCache = DiscoveryDocumentCache; exports.imageContent = imageContent; exports.audioContent = audioContent; exports.UnexpectedStateError = UnexpectedStateError; exports.UserError = UserError; exports.ServerState = ServerState; exports.FastMCPSession = FastMCPSession; exports.FastMCP = FastMCP;
-//# sourceMappingURL=chunk-MLFG3TOK.cjs.map
+//# sourceMappingURL=chunk-553XY3CA.cjs.map