fastmcp 3.18.0 → 3.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastmcp",
-  "version": "3.18.0",
+  "version": "3.19.1",
   "main": "dist/FastMCP.js",
   "scripts": {
     "build": "tsup",
@@ -27,7 +27,7 @@
     "execa": "^9.6.0",
     "file-type": "^21.0.0",
     "fuse.js": "^7.1.0",
-    "mcp-proxy": "^5.5.4",
+    "mcp-proxy": "^5.8.0",
     "strict-event-emitter-types": "^2.0.0",
     "undici": "^7.13.0",
     "uri-templates": "^0.2.0",

package/src/FastMCP.test.ts

@@ -1052,6 +1052,238 @@ test("embedded resources work with direct resources", async () => {
   });
 });
 
+test("embedded resources work with URI templates and query parameters", async () => {
+  await runWithTestServer({
+    run: async ({ client }) => {
+      // Test case 1: Simple query parameter extraction
+      expect(
+        await client.callTool({
+          arguments: {
+            uri: "ui://search?location=a&q=b",
+          },
+          name: "get_search_resource",
+        }),
+      ).toEqual({
+        content: [
+          {
+            resource: {
+              mimeType: "application/json",
+              text: '{"location":"a","query":"b","type":"search"}',
+              uri: "ui://search?location=a&q=b",
+            },
+            type: "resource",
+          },
+        ],
+      });
+
+      // Test case 2: Query parameters with different order
+      expect(
+        await client.callTool({
+          arguments: {
+            uri: "ui://search?q=test&location=home",
+          },
+          name: "get_search_resource",
+        }),
+      ).toEqual({
+        content: [
+          {
+            resource: {
+              mimeType: "application/json",
+              text: '{"location":"home","query":"test","type":"search"}',
+              uri: "ui://search?q=test&location=home",
+            },
+            type: "resource",
+          },
+        ],
+      });
+
+      // Test case 3: Query parameters with encoded values
+      expect(
+        await client.callTool({
+          arguments: {
+            uri: "ui://search?location=new%20york&q=hello%20world",
+          },
+          name: "get_search_resource",
+        }),
+      ).toEqual({
+        content: [
+          {
+            resource: {
+              mimeType: "application/json",
+              text: '{"location":"new york","query":"hello world","type":"search"}',
+              uri: "ui://search?location=new%20york&q=hello%20world",
+            },
+            type: "resource",
+          },
+        ],
+      });
+    },
+
+    server: async () => {
+      const server = new FastMCP({
+        name: "Test",
+        version: "1.0.0",
+      });
+
+      server.addResourceTemplate({
+        arguments: [
+          {
+            name: "location",
+            required: true,
+          },
+          {
+            name: "q",
+            required: true,
+          },
+        ],
+        async load(args) {
+          return {
+            text: JSON.stringify({
+              location: args.location,
+              query: args.q,
+              type: "search",
+            }),
+          };
+        },
+        mimeType: "application/json",
+        name: "Search Resource",
+        uriTemplate: "ui://search{?location,q}",
+      });
+
+      server.addTool({
+        description:
+          "Get search resource data using embedded function with query parameters",
+        execute: async (args) => {
+          return {
+            content: [
+              {
+                resource: await server.embedded(args.uri),
+                type: "resource",
+              },
+            ],
+          };
+        },
+        name: "get_search_resource",
+        parameters: z.object({
+          uri: z.string(),
+        }),
+      });
+
+      return server;
+    },
+  });
+});
+
+test("embedded resources work with complex URI template patterns", async () => {
+  await runWithTestServer({
+    run: async ({ client }) => {
+      // Test case 1: Path and query parameters combined
+      expect(
+        await client.callTool({
+          arguments: {
+            uri: "api://users/123?fields=name,email&format=json",
+          },
+          name: "get_user_data",
+        }),
+      ).toEqual({
+        content: [
+          {
+            resource: {
+              mimeType: "application/json",
+              text: '{"userId":"123","fields":["name","email"],"format":"json"}',
+              uri: "api://users/123?fields=name,email&format=json",
+            },
+            type: "resource",
+          },
+        ],
+      });
+
+      // Test case 2: Optional query parameters (some missing)
+      expect(
+        await client.callTool({
+          arguments: {
+            uri: "api://users/456?format=xml",
+          },
+          name: "get_user_data",
+        }),
+      ).toEqual({
+        content: [
+          {
+            resource: {
+              mimeType: "application/json",
+              text: '{"userId":"456","format":"xml"}',
+              uri: "api://users/456?format=xml",
+            },
+            type: "resource",
+          },
+        ],
+      });
+    },
+
+    server: async () => {
+      const server = new FastMCP({
+        name: "Test",
+        version: "1.0.0",
+      });
+
+      server.addResourceTemplate({
+        arguments: [
+          {
+            name: "userId",
+            required: true,
+          },
+          {
+            name: "fields",
+            required: false,
+          },
+          {
+            name: "format",
+            required: false,
+          },
+        ],
+        async load(args) {
+          const result: Record<string, string> = {
+            userId: args.userId,
+          };
+          if (args.fields) {
+            result.fields = args.fields;
+          }
+          if (args.format) {
+            result.format = args.format;
+          }
+          return {
+            text: JSON.stringify(result),
+          };
+        },
+        mimeType: "application/json",
+        name: "User Data API",
+        uriTemplate: "api://users/{userId}{?fields,format}",
+      });
+
+      server.addTool({
+        description:
+          "Get user data using complex URI templates with path and query parameters",
+        execute: async (args) => {
+          return {
+            content: [
+              {
+                resource: await server.embedded(args.uri),
+                type: "resource",
+              },
+            ],
+          };
+        },
+        name: "get_user_data",
+        parameters: z.object({
+          uri: z.string(),
+        }),
+      });
+
+      return server;
+    },
+  });
+});
+
 test("adds prompts", async () => {
   await runWithTestServer({
     run: async ({ client }) => {
@@ -3293,6 +3525,359 @@ test("stateless mode health check includes mode indicator", async () => {
   }
 });
 
+test("stateless mode with valid authentication allows access", async () => {
+  const port = await getRandomPort();
+
+  const server = new FastMCP<{ userId: string }>({
+    authenticate: async () => {
+      // Always authenticate successfully for this test
+      return { userId: "123" };
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async () => {
+      return "pong";
+    },
+    name: "ping",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    const client = new Client(
+      {
+        name: "Test client",
+        version: "1.0.0",
+      },
+      {
+        capabilities: {},
+      },
+    );
+
+    const transport = new StreamableHTTPClientTransport(
+      new URL(`http://localhost:${port}/mcp`),
+    );
+
+    await client.connect(transport);
+
+    const result = await client.callTool({
+      arguments: {},
+      name: "ping",
+    });
+
+    expect(result.content).toEqual([
+      {
+        text: "pong",
+        type: "text",
+      },
+    ]);
+
+    // Server should not track sessions in stateless mode
+    expect(server.sessions.length).toBe(0);
+
+    await client.close();
+  } finally {
+    await server.stop();
+  }
+});
+
+test("stateless mode rejects missing Authorization header", async () => {
+  const port = await getRandomPort();
+
+  const server = new FastMCP<{ userId: string }>({
+    authenticate: async (req) => {
+      const authHeader = req.headers.authorization;
+
+      if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        throw new Response(null, {
+          status: 401,
+          statusText: "Unauthorized",
+        });
+      }
+
+      return { userId: "123" };
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async () => {
+      return "pong";
+    },
+    name: "ping",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    // Send a raw HTTP request without Authorization header
+    const response = await fetch(`http://localhost:${port}/mcp`, {
+      body: JSON.stringify({
+        id: 1,
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: {
+          arguments: {},
+          name: "ping",
+        },
+      }),
+      headers: {
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+    });
+
+    expect(response.status).toBe(401);
+
+    const body = (await response.json()) as { error?: { message?: string } };
+    expect(body.error?.message).toContain("Unauthorized");
+  } finally {
+    await server.stop();
+  }
+});
+
+test("stateless mode rejects invalid authentication token", async () => {
+  const port = await getRandomPort();
+  const VALID_TOKEN = "valid_jwt_token";
+  const INVALID_TOKEN = "invalid_jwt_token";
+
+  const server = new FastMCP<{ userId: string }>({
+    authenticate: async (req) => {
+      const authHeader = req.headers.authorization;
+
+      if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        throw new Response(null, {
+          status: 401,
+          statusText: "Unauthorized",
+        });
+      }
+
+      const token = authHeader.split(" ")[1];
+
+      if (token === VALID_TOKEN) {
+        return { userId: "123" };
+      }
+
+      throw new Response(null, {
+        status: 401,
+        statusText: "Unauthorized",
+      });
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async () => {
+      return "pong";
+    },
+    name: "ping",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    // Send a raw HTTP request with invalid token
+    const response = await fetch(`http://localhost:${port}/mcp`, {
+      body: JSON.stringify({
+        id: 1,
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: {
+          arguments: {},
+          name: "ping",
+        },
+      }),
+      headers: {
+        Authorization: `Bearer ${INVALID_TOKEN}`,
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+    });
+
+    expect(response.status).toBe(401);
+
+    const body = (await response.json()) as { error?: { message?: string } };
+    expect(body.error?.message).toContain("Unauthorized");
+  } finally {
+    await server.stop();
+  }
+});
+
+test("stateless mode handles authentication function throwing errors", async () => {
+  const port = await getRandomPort();
+
+  const server = new FastMCP<{ userId: string }>({
+    authenticate: async () => {
+      // Simulate an internal error during token validation
+      throw new Error("JWT validation service is down");
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async () => {
+      return "pong";
+    },
+    name: "ping",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    // Send a raw HTTP request
+    const response = await fetch(`http://localhost:${port}/mcp`, {
+      body: JSON.stringify({
+        id: 1,
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: {
+          arguments: {},
+          name: "ping",
+        },
+      }),
+      headers: {
+        Authorization: "Bearer any_token",
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+    });
+
+    expect(response.status).toBe(401);
+
+    const body = (await response.json()) as { error?: { message?: string } };
+    expect(body.error?.message).toContain("Unauthorized");
+  } finally {
+    await server.stop();
+  }
+});
+
+test("stateless mode handles concurrent requests with authentication", async () => {
+  const port = await getRandomPort();
+  let requestCount = 0;
+
+  const server = new FastMCP<{ requestId: number }>({
+    authenticate: async () => {
+      // Track each authentication request
+      requestCount++;
+      return { requestId: requestCount };
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Echo request ID",
+    execute: async (_args, context) => {
+      return `Request ${context.session?.requestId}`;
+    },
+    name: "whoami",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    // Create two clients to test concurrent stateless requests
+    const client1 = new Client(
+      {
+        name: "Client 1",
+        version: "1.0.0",
+      },
+      {
+        capabilities: {},
+      },
+    );
+
+    const client2 = new Client(
+      {
+        name: "Client 2",
+        version: "1.0.0",
+      },
+      {
+        capabilities: {},
+      },
+    );
+
+    const transport1 = new StreamableHTTPClientTransport(
+      new URL(`http://localhost:${port}/mcp`),
+    );
+
+    const transport2 = new StreamableHTTPClientTransport(
+      new URL(`http://localhost:${port}/mcp`),
+    );
+
+    await client1.connect(transport1);
+    await client2.connect(transport2);
+
+    // Both clients should work independently
+    const result1 = await client1.callTool({
+      arguments: {},
+      name: "whoami",
+    });
+
+    const result2 = await client2.callTool({
+      arguments: {},
+      name: "whoami",
+    });
+
+    // Each request should have been authenticated
+    expect((result1.content as unknown[])[0]).toHaveProperty("text");
+    expect((result2.content as unknown[])[0]).toHaveProperty("text");
+
+    // Server should not track sessions in stateless mode
+    expect(server.sessions.length).toBe(0);
+
+    await client1.close();
+    await client2.close();
+  } finally {
+    await server.stop();
+  }
+});
+
 test("host configuration works with 0.0.0.0", async () => {
   const port = await getRandomPort();
 

package/src/FastMCP.ts

@@ -1987,48 +1987,30 @@ export class FastMCP<
 
     // Try to match against resource templates
     for (const template of this.#resourcesTemplates) {
-      // Check if the URI starts with the template base
-      const templateBase = template.uriTemplate.split("{")[0];
-
-      if (uri.startsWith(templateBase)) {
-        const params: Record<string, string> = {};
-        const templateParts = template.uriTemplate.split("/");
-        const uriParts = uri.split("/");
-
-        for (let i = 0; i < templateParts.length; i++) {
-          const templatePart = templateParts[i];
-
-          if (templatePart?.startsWith("{") && templatePart.endsWith("}")) {
-            const paramName = templatePart.slice(1, -1);
-            const paramValue = uriParts[i];
-
-            if (paramValue) {
-              params[paramName] = paramValue;
-            }
-          }
-        }
-
-        const result = await template.load(
-          params as ResourceTemplateArgumentsToObject<
-            typeof template.arguments
-          >,
-        );
+      const parsedTemplate = parseURITemplate(template.uriTemplate);
+      const params = parsedTemplate.fromUri(uri);
+      if (!params) {
+        continue;
+      }
 
-        const resourceData: ResourceContent["resource"] = {
-          mimeType: template.mimeType,
-          uri,
-        };
+      const result = await template.load(
+        params as ResourceTemplateArgumentsToObject<typeof template.arguments>,
+      );
 
-        if ("text" in result) {
-          resourceData.text = result.text;
-        }
+      const resourceData: ResourceContent["resource"] = {
+        mimeType: template.mimeType,
+        uri,
+      };
 
-        if ("blob" in result) {
-          resourceData.blob = result.blob;
-        }
+      if ("text" in result) {
+        resourceData.text = result.text;
+      }
 
-        return resourceData; // The resource we're looking for
+      if ("blob" in result) {
+        resourceData.blob = result.blob;
       }
+
+      return resourceData; // The resource we're looking for
     }
 
     throw new UnexpectedStateError(`Resource not found: ${uri}`, { uri });
@@ -2127,11 +2109,18 @@ export class FastMCP<
         );
 
         this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
+          authenticate: this.#authenticate,
           createServer: async (request) => {
             let auth: T | undefined;
 
             if (this.#authenticate) {
               auth = await this.#authenticate(request);
+
+              // In stateless mode, authentication is REQUIRED
+              // mcp-proxy will catch this error and return 401
+              if (auth === undefined || auth === null) {
+                throw new Error("Authentication required");
+              }
             }
 
             // In stateless mode, create a new session for each request
@@ -2161,6 +2150,7 @@ export class FastMCP<
       } else {
         // Regular mode with session management
         this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
+          authenticate: this.#authenticate,
           createServer: async (request) => {
             let auth: T | undefined;
 
@@ -2201,6 +2191,7 @@ export class FastMCP<
             );
           },
           port: httpConfig.port,
+          stateless: httpConfig.stateless,
           streamEndpoint: httpConfig.endpoint,
         });