mcp-proxy 5.8.1 → 5.10.0

package/jsr.json

@@ -3,5 +3,5 @@
   "include": ["src/index.ts", "src/bin/mcp-proxy.ts"],
   "license": "MIT",
   "name": "@punkpeye/mcp-proxy",
-  "version": "5.8.1"
+  "version": "5.10.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-proxy",
-  "version": "5.8.1",
+  "version": "5.10.0",
   "main": "dist/index.js",
   "scripts": {
     "build": "tsdown",

package/src/authentication.test.ts

@@ -103,15 +103,90 @@ describe("AuthenticationMiddleware", () => {
       expect(body.id).toBe(null);
     });
 
-    it("should have consistent format regardless of configuration", () => {
+    it("should have consistent body format regardless of configuration", () => {
       const middleware1 = new AuthenticationMiddleware({});
       const middleware2 = new AuthenticationMiddleware({ apiKey: "test" });
 
       const response1 = middleware1.getUnauthorizedResponse();
       const response2 = middleware2.getUnauthorizedResponse();
 
-      expect(response1.headers).toEqual(response2.headers);
       expect(response1.body).toEqual(response2.body);
     });
+
+    it("should not include WWW-Authenticate header without OAuth config", () => {
+      const middleware = new AuthenticationMiddleware({ apiKey: "test" });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBeUndefined();
+    });
+
+    it("should include WWW-Authenticate header with OAuth config", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBe(
+        'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"',
+      );
+    });
+
+    it("should handle OAuth config with trailing slash in resource URL", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com/",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBe(
+        'Bearer resource_metadata="https://example.com//.well-known/oauth-protected-resource"',
+      );
+    });
+
+    it("should not include WWW-Authenticate header when OAuth config is empty", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {},
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBeUndefined();
+    });
+
+    it("should not include WWW-Authenticate header when protectedResource is empty", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {},
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBeUndefined();
+    });
+
+    it("should include WWW-Authenticate header with OAuth config but no apiKey", () => {
+      const middleware = new AuthenticationMiddleware({
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toBe(
+        'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"',
+      );
+    });
   });
 });

package/src/authentication.ts

@@ -2,12 +2,26 @@ import type { IncomingMessage } from "http";
 
 export interface AuthConfig {
   apiKey?: string;
+  oauth?: {
+    protectedResource?: {
+      resource?: string;
+    };
+  };
 }
 
 export class AuthenticationMiddleware {
   constructor(private config: AuthConfig = {}) {}
 
-  getUnauthorizedResponse() {
+  getUnauthorizedResponse(): { body: string; headers: Record<string, string> } {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    // Add WWW-Authenticate header if OAuth config is available
+    if (this.config.oauth?.protectedResource?.resource) {
+      headers["WWW-Authenticate"] = `Bearer resource_metadata="${this.config.oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`;
+    }
+
     return {
       body: JSON.stringify({
         error: {
@@ -17,9 +31,7 @@ export class AuthenticationMiddleware {
         id: null,
         jsonrpc: "2.0",
       }),
-      headers: {
-        "Content-Type": "application/json",
-      },
+      headers,
     };
   }
 

package/src/index.ts

@@ -1,5 +1,8 @@
+export type { AuthConfig } from "./authentication.js";
+export { AuthenticationMiddleware } from "./authentication.js";
 export { InMemoryEventStore } from "./InMemoryEventStore.js";
 export { proxyServer } from "./proxyServer.js";
+export type { CorsOptions } from "./startHTTPServer.js";
 export { startHTTPServer } from "./startHTTPServer.js";
 export { ServerType, startStdioServer } from "./startStdioServer.js";
 export { tapTransport } from "./tapTransport.js";

package/src/startHTTPServer.test.ts

@@ -1675,3 +1675,251 @@ it("succeeds when authenticate returns { authenticated: true } in stateless mode
   await httpServer.close();
   await stdioClient.close();
 });
+
+// CORS Configuration Tests
+
+it("supports wildcard CORS headers", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    cors: {
+      allowedHeaders: "*",
+    },
+    createServer: async () => {
+      const mcpServer = new Server(
+        { name: "test", version: "1.0.0" },
+        { capabilities: {} },
+      );
+      return mcpServer;
+    },
+    port,
+  });
+
+  // Test OPTIONS request to verify CORS headers
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    headers: {
+      Origin: "https://example.com",
+    },
+    method: "OPTIONS",
+  });
+
+  expect(response.status).toBe(204);
+
+  // Verify wildcard is used for allowed headers
+  const allowedHeaders = response.headers.get("Access-Control-Allow-Headers");
+  expect(allowedHeaders).toBe("*");
+
+  await httpServer.close();
+});
+
+it("supports custom CORS headers array", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    cors: {
+      allowedHeaders: ["Content-Type", "X-Custom-Header", "X-API-Key"],
+    },
+    createServer: async () => {
+      const mcpServer = new Server(
+        { name: "test", version: "1.0.0" },
+        { capabilities: {} },
+      );
+      return mcpServer;
+    },
+    port,
+  });
+
+  // Test OPTIONS request to verify CORS headers
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    headers: {
+      Origin: "https://example.com",
+    },
+    method: "OPTIONS",
+  });
+
+  expect(response.status).toBe(204);
+
+  // Verify custom headers are used
+  const allowedHeaders = response.headers.get("Access-Control-Allow-Headers");
+  expect(allowedHeaders).toBe("Content-Type, X-Custom-Header, X-API-Key");
+
+  await httpServer.close();
+});
+
+it("supports origin validation with array", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    cors: {
+      origin: ["https://app.example.com", "https://admin.example.com"],
+    },
+    createServer: async () => {
+      const mcpServer = new Server(
+        { name: "test", version: "1.0.0" },
+        { capabilities: {} },
+      );
+      return mcpServer;
+    },
+    port,
+  });
+
+  // Test with allowed origin
+  const response1 = await fetch(`http://localhost:${port}/mcp`, {
+    headers: {
+      Origin: "https://app.example.com",
+    },
+    method: "OPTIONS",
+  });
+
+  expect(response1.status).toBe(204);
+  expect(response1.headers.get("Access-Control-Allow-Origin")).toBe("https://app.example.com");
+
+  // Test with disallowed origin
+  const response2 = await fetch(`http://localhost:${port}/mcp`, {
+    headers: {
+      Origin: "https://malicious.com",
+    },
+    method: "OPTIONS",
+  });
+
+  expect(response2.status).toBe(204);
+  expect(response2.headers.get("Access-Control-Allow-Origin")).toBeNull();
+
+  await httpServer.close();
+});
+
+it("supports origin validation with function", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    cors: {
+      origin: (origin: string) => origin.endsWith(".example.com"),
+    },
+    createServer: async () => {
+      const mcpServer = new Server(
+        { name: "test", version: "1.0.0" },
+        { capabilities: {} },
+      );
+      return mcpServer;
+    },
+    port,
+  });
+
+  // Test with allowed origin
+  const response1 = await fetch(`http://localhost:${port}/mcp`, {
+    headers: {
+      Origin: "https://subdomain.example.com",
+    },
+    method: "OPTIONS",
+  });
+
+  expect(response1.status).toBe(204);
+  expect(response1.headers.get("Access-Control-Allow-Origin")).toBe("https://subdomain.example.com");
+
+  // Test with disallowed origin
+  const response2 = await fetch(`http://localhost:${port}/mcp`, {
+    headers: {
+      Origin: "https://malicious.com",
+    },
+    method: "OPTIONS",
+  });
+
+  expect(response2.status).toBe(204);
+  expect(response2.headers.get("Access-Control-Allow-Origin")).toBeNull();
+
+  await httpServer.close();
+});
+
+it("disables CORS when cors: false", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    cors: false,
+    createServer: async () => {
+      const mcpServer = new Server(
+        { name: "test", version: "1.0.0" },
+        { capabilities: {} },
+      );
+      return mcpServer;
+    },
+    port,
+  });
+
+  // Test OPTIONS request - should not have CORS headers
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    headers: {
+      Origin: "https://example.com",
+    },
+    method: "OPTIONS",
+  });
+
+  expect(response.status).toBe(204);
+  expect(response.headers.get("Access-Control-Allow-Origin")).toBeNull();
+  expect(response.headers.get("Access-Control-Allow-Headers")).toBeNull();
+
+  await httpServer.close();
+});
+
+it("uses default CORS settings when cors: true", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    cors: true,
+    createServer: async () => {
+      const mcpServer = new Server(
+        { name: "test", version: "1.0.0" },
+        { capabilities: {} },
+      );
+      return mcpServer;
+    },
+    port,
+  });
+
+  // Test OPTIONS request to verify default CORS headers
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    headers: {
+      Origin: "https://example.com",
+    },
+    method: "OPTIONS",
+  });
+
+  expect(response.status).toBe(204);
+  expect(response.headers.get("Access-Control-Allow-Origin")).toBe("*");
+  expect(response.headers.get("Access-Control-Allow-Headers")).toBe("Content-Type, Authorization, Accept, Mcp-Session-Id, Last-Event-Id");
+  expect(response.headers.get("Access-Control-Allow-Credentials")).toBe("true");
+
+  await httpServer.close();
+});
+
+it("supports custom methods and maxAge", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    cors: {
+      maxAge: 86400,
+      methods: ["GET", "POST", "PUT", "DELETE"],
+    },
+    createServer: async () => {
+      const mcpServer = new Server(
+        { name: "test", version: "1.0.0" },
+        { capabilities: {} },
+      );
+      return mcpServer;
+    },
+    port,
+  });
+
+  // Test OPTIONS request to verify custom settings
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    headers: {
+      Origin: "https://example.com",
+    },
+    method: "OPTIONS",
+  });
+
+  expect(response.status).toBe(204);
+  expect(response.headers.get("Access-Control-Allow-Methods")).toBe("GET, POST, PUT, DELETE");
+  expect(response.headers.get("Access-Control-Max-Age")).toBe("86400");
+
+  await httpServer.close();
+});

package/src/startHTTPServer.ts

@@ -8,9 +8,18 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import http from "http";
 import { randomUUID } from "node:crypto";
 
-import { AuthenticationMiddleware } from "./authentication.js";
+import { AuthConfig, AuthenticationMiddleware } from "./authentication.js";
 import { InMemoryEventStore } from "./InMemoryEventStore.js";
 
+export interface CorsOptions {
+  allowedHeaders?: string | string[]; // Allow string[] or '*' for wildcard
+  credentials?: boolean;
+  exposedHeaders?: string[];
+  maxAge?: number;
+  methods?: string[];
+  origin?: ((origin: string) => boolean) | string | string[];
+}
+
 export type SSEServer = {
   close: () => Promise<void>;
 };
@@ -49,6 +58,17 @@ const createJsonRpcErrorResponse = (code: number, message: string) => {
   });
 };
 
+// Helper function to get WWW-Authenticate header value
+const getWWWAuthenticateHeader = (
+  oauth?: AuthConfig["oauth"],
+): string | undefined => {
+  if (!oauth?.protectedResource?.resource) {
+    return undefined;
+  }
+
+  return `Bearer resource_metadata="${oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`;
+};
+
 // Helper function to handle Response errors and send appropriate HTTP response
 const handleResponseError = (
   error: unknown,
@@ -91,6 +111,94 @@ const cleanupServer = async <T extends ServerLike>(
   }
 };
 
+// Helper function to apply CORS headers
+const applyCorsHeaders = (
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  corsOptions?: boolean | CorsOptions,
+) => {
+  if (!req.headers.origin) {
+    return;
+  }
+
+  // Default CORS configuration for backward compatibility
+  const defaultCorsOptions: CorsOptions = {
+    allowedHeaders: "Content-Type, Authorization, Accept, Mcp-Session-Id, Last-Event-Id",
+    credentials: true,
+    exposedHeaders: ["Mcp-Session-Id"],
+    methods: ["GET", "POST", "OPTIONS"],
+    origin: "*",
+  };
+
+  let finalCorsOptions: CorsOptions;
+
+  if (corsOptions === false) {
+    // CORS disabled
+    return;
+  } else if (corsOptions === true || corsOptions === undefined) {
+    // Use default CORS settings
+    finalCorsOptions = defaultCorsOptions;
+  } else {
+    // Merge user options with defaults
+    finalCorsOptions = {
+      ...defaultCorsOptions,
+      ...corsOptions,
+    };
+  }
+
+  try {
+    const origin = new URL(req.headers.origin);
+
+    // Handle origin
+    let allowedOrigin = "*";
+    if (finalCorsOptions.origin) {
+      if (typeof finalCorsOptions.origin === "string") {
+        allowedOrigin = finalCorsOptions.origin;
+      } else if (Array.isArray(finalCorsOptions.origin)) {
+        allowedOrigin = finalCorsOptions.origin.includes(origin.origin)
+          ? origin.origin
+          : "false";
+      } else if (typeof finalCorsOptions.origin === "function") {
+        allowedOrigin = finalCorsOptions.origin(origin.origin) ? origin.origin : "false";
+      }
+    }
+
+    if (allowedOrigin !== "false") {
+      res.setHeader("Access-Control-Allow-Origin", allowedOrigin);
+    }
+
+    // Handle credentials
+    if (finalCorsOptions.credentials !== undefined) {
+      res.setHeader("Access-Control-Allow-Credentials", finalCorsOptions.credentials.toString());
+    }
+
+    // Handle methods
+    if (finalCorsOptions.methods) {
+      res.setHeader("Access-Control-Allow-Methods", finalCorsOptions.methods.join(", "));
+    }
+
+    // Handle allowed headers
+    if (finalCorsOptions.allowedHeaders) {
+      const allowedHeaders = typeof finalCorsOptions.allowedHeaders === "string"
+        ? finalCorsOptions.allowedHeaders
+        : finalCorsOptions.allowedHeaders.join(", ");
+      res.setHeader("Access-Control-Allow-Headers", allowedHeaders);
+    }
+
+    // Handle exposed headers
+    if (finalCorsOptions.exposedHeaders) {
+      res.setHeader("Access-Control-Expose-Headers", finalCorsOptions.exposedHeaders.join(", "));
+    }
+
+    // Handle max age
+    if (finalCorsOptions.maxAge !== undefined) {
+      res.setHeader("Access-Control-Max-Age", finalCorsOptions.maxAge.toString());
+    }
+  } catch (error) {
+    console.error("[mcp-proxy] error parsing origin", error);
+  }
+};
+
 const handleStreamRequest = async <T extends ServerLike>({
   activeTransports,
   authenticate,
@@ -98,6 +206,7 @@ const handleStreamRequest = async <T extends ServerLike>({
   enableJsonResponse,
   endpoint,
   eventStore,
+  oauth,
   onClose,
   onConnect,
   req,
@@ -113,6 +222,7 @@ const handleStreamRequest = async <T extends ServerLike>({
   enableJsonResponse?: boolean;
   endpoint: string;
   eventStore?: EventStore;
+  oauth?: AuthConfig["oauth"];
   onClose?: (server: T) => Promise<void>;
   onConnect?: (server: T) => Promise<void>;
   req: http.IncomingMessage;
@@ -148,6 +258,13 @@ const handleStreamRequest = async <T extends ServerLike>({
                 : "Unauthorized: Authentication failed";
 
             res.setHeader("Content-Type", "application/json");
+
+            // Add WWW-Authenticate header if OAuth config is available
+            const wwwAuthHeader = getWWWAuthenticateHeader(oauth);
+            if (wwwAuthHeader) {
+              res.setHeader("WWW-Authenticate", wwwAuthHeader);
+            }
+
             res.writeHead(401).end(
               JSON.stringify({
                 error: {
@@ -165,6 +282,13 @@ const handleStreamRequest = async <T extends ServerLike>({
           const errorMessage = error instanceof Error ? error.message : "Unauthorized: Authentication error";
           console.error("Authentication error:", error);
           res.setHeader("Content-Type", "application/json");
+
+          // Add WWW-Authenticate header if OAuth config is available
+          const wwwAuthHeader = getWWWAuthenticateHeader(oauth);
+          if (wwwAuthHeader) {
+            res.setHeader("WWW-Authenticate", wwwAuthHeader);
+          }
+
           res.writeHead(401).end(
             JSON.stringify({
               error: {
@@ -242,6 +366,13 @@ const handleStreamRequest = async <T extends ServerLike>({
 
           if (isAuthError) {
             res.setHeader("Content-Type", "application/json");
+
+            // Add WWW-Authenticate header if OAuth config is available
+            const wwwAuthHeader = getWWWAuthenticateHeader(oauth);
+            if (wwwAuthHeader) {
+              res.setHeader("WWW-Authenticate", wwwAuthHeader);
+            }
+
             res.writeHead(401).end(JSON.stringify({
               error: {
                 code: -32000,
@@ -294,6 +425,13 @@ const handleStreamRequest = async <T extends ServerLike>({
 
           if (isAuthError) {
             res.setHeader("Content-Type", "application/json");
+
+            // Add WWW-Authenticate header if OAuth config is available
+            const wwwAuthHeader = getWWWAuthenticateHeader(oauth);
+            if (wwwAuthHeader) {
+              res.setHeader("WWW-Authenticate", wwwAuthHeader);
+            }
+
             res.writeHead(401).end(JSON.stringify({
               error: {
                 code: -32000,
@@ -545,10 +683,12 @@ const handleSSERequest = async <T extends ServerLike>({
 export const startHTTPServer = async <T extends ServerLike>({
   apiKey,
   authenticate,
+  cors,
   createServer,
   enableJsonResponse,
   eventStore,
   host = "::",
+  oauth,
   onClose,
   onConnect,
   onUnhandledRequest,
@@ -559,10 +699,12 @@ export const startHTTPServer = async <T extends ServerLike>({
 }: {
   apiKey?: string;
   authenticate?: (request: http.IncomingMessage) => Promise<unknown>;
+  cors?: boolean | CorsOptions;
   createServer: (request: http.IncomingMessage) => Promise<T>;
   enableJsonResponse?: boolean;
   eventStore?: EventStore;
   host?: string;
+  oauth?: AuthConfig["oauth"];
   onClose?: (server: T) => Promise<void>;
   onConnect?: (server: T) => Promise<void>;
   onUnhandledRequest?: (
@@ -584,25 +726,14 @@ export const startHTTPServer = async <T extends ServerLike>({
     }
   > = {};
 
-  const authMiddleware = new AuthenticationMiddleware({ apiKey });
+  const authMiddleware = new AuthenticationMiddleware({ apiKey, oauth });
 
   /**
    * @author https://dev.classmethod.jp/articles/mcp-sse/
    */
   const httpServer = http.createServer(async (req, res) => {
-    if (req.headers.origin) {
-      try {
-        const origin = new URL(req.headers.origin);
-
-        res.setHeader("Access-Control-Allow-Origin", origin.origin);
-        res.setHeader("Access-Control-Allow-Credentials", "true");
-        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, Accept, Mcp-Session-Id, Last-Event-Id");
-        res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
-      } catch (error) {
-        console.error("[mcp-proxy] error parsing origin", error);
-      }
-    }
+    // Apply CORS headers
+    applyCorsHeaders(req, res, cors);
 
     if (req.method === "OPTIONS") {
       res.writeHead(204);
@@ -647,6 +778,7 @@ export const startHTTPServer = async <T extends ServerLike>({
         enableJsonResponse,
         endpoint: streamEndpoint,
         eventStore,
+        oauth,
         onClose,
         onConnect,
         req,