mcp-proxy 5.11.2 → 5.12.1

package/src/authentication.ts

@@ -17,6 +17,51 @@ export interface AuthConfig {
 export class AuthenticationMiddleware {
   constructor(private config: AuthConfig = {}) {}
 
+  getScopeChallengeResponse(
+    requiredScopes: string[],
+    errorDescription?: string,
+    requestId?: unknown,
+  ): { body: string; headers: Record<string, string>; statusCode: number } {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    // Build WWW-Authenticate header with all required parameters
+    if (this.config.oauth?.protectedResource?.resource) {
+      const parts = [
+        "Bearer",
+        'error="insufficient_scope"',
+        `scope="${requiredScopes.join(" ")}"`,
+        `resource_metadata="${this.config.oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`,
+      ];
+
+      if (errorDescription) {
+        // Escape quotes in description
+        const escaped = errorDescription.replace(/"/g, '\\"');
+        parts.push(`error_description="${escaped}"`);
+      }
+
+      headers["WWW-Authenticate"] = parts.join(", ");
+    }
+
+    return {
+      body: JSON.stringify({
+        error: {
+          code: -32001, // Custom error code for insufficient scope
+          data: {
+            error: "insufficient_scope",
+            required_scopes: requiredScopes,
+          },
+          message: errorDescription || "Insufficient scope",
+        },
+        id: requestId ?? null,
+        jsonrpc: "2.0",
+      }),
+      headers,
+      statusCode: 403,
+    };
+  }
+
   getUnauthorizedResponse(options?: {
     error?: string;
     error_description?: string;
@@ -38,15 +83,21 @@ export class AuthenticationMiddleware {
 
       // Add resource_metadata if configured
       if (this.config.oauth.protectedResource?.resource) {
-        params.push(`resource_metadata="${this.config.oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`);
+        params.push(
+          `resource_metadata="${this.config.oauth.protectedResource.resource}/.well-known/oauth-protected-resource"`,
+        );
       }
 
       // Add error from options or config (options takes precedence)
-      const error = options?.error || this.config.oauth.error || "invalid_token";
+      const error =
+        options?.error || this.config.oauth.error || "invalid_token";
       params.push(`error="${error}"`);
 
       // Add error_description from options or config (options takes precedence)
-      const error_description = options?.error_description || this.config.oauth.error_description || "Unauthorized: Invalid or missing API key";
+      const error_description =
+        options?.error_description ||
+        this.config.oauth.error_description ||
+        "Unauthorized: Invalid or missing API key";
       // Escape quotes in error description
       const escaped = error_description.replace(/"/g, '\\"');
       params.push(`error_description="${escaped}"`);
@@ -72,7 +123,9 @@ export class AuthenticationMiddleware {
       body: JSON.stringify({
         error: {
           code: 401,
-          message: options?.error_description || "Unauthorized: Invalid or missing API key",
+          message:
+            options?.error_description ||
+            "Unauthorized: Invalid or missing API key",
         },
         id: null,
         jsonrpc: "2.0",
@@ -98,4 +151,3 @@ export class AuthenticationMiddleware {
     return apiKey === this.config.apiKey;
   }
 }
-

package/src/bin/mcp-proxy.ts

@@ -68,7 +68,8 @@ const argv = await yargs(hideBin(process.argv))
     },
     requestTimeout: {
       default: 300000,
-      describe: "The timeout (in milliseconds) for requests to the MCP server (default: 5 minutes)",
+      describe:
+        "The timeout (in milliseconds) for requests to the MCP server (default: 5 minutes)",
       type: "number",
     },
     server: {

package/src/proxyServer.test.ts

@@ -28,33 +28,47 @@ interface TestEnvironment {
   streamClient: Client;
 }
 
-async function createTestEnvironment(config: TestConfig = {}): Promise<TestEnvironment> {
-  const { 
-    requestTimeout, 
-    serverDelay, 
-    serverFixture = "simple-stdio-server.ts" 
+async function createTestEnvironment(
+  config: TestConfig = {},
+): Promise<TestEnvironment> {
+  const {
+    requestTimeout,
+    serverDelay,
+    serverFixture = "simple-stdio-server.ts",
   } = config;
-  
+
   const stdioTransport = new StdioClientTransport({
     args: [`src/fixtures/${serverFixture}`],
     command: "tsx",
-    env: serverDelay ? { ...process.env, RESPONSE_DELAY: serverDelay } as Record<string, string> : process.env as Record<string, string>,
+    env: serverDelay
+      ? ({ ...process.env, RESPONSE_DELAY: serverDelay } as Record<
+          string,
+          string
+        >)
+      : (process.env as Record<string, string>),
   });
 
   const stdioClient = new Client(
     { name: "mcp-proxy-test", version: "1.0.0" },
-    { capabilities: {} }
+    { capabilities: {} },
   );
 
   await stdioClient.connect(stdioTransport);
 
-  const serverVersion = stdioClient.getServerVersion() as { name: string; version: string };
-  const serverCapabilities = stdioClient.getServerCapabilities() as { capabilities: Record<string, unknown> };
+  const serverVersion = stdioClient.getServerVersion() as {
+    name: string;
+    version: string;
+  };
+  const serverCapabilities = stdioClient.getServerCapabilities() as {
+    capabilities: Record<string, unknown>;
+  };
   const port = await getRandomPort();
 
   const httpServer = await startHTTPServer({
     createServer: async () => {
-      const mcpServer = new Server(serverVersion, { capabilities: serverCapabilities });
+      const mcpServer = new Server(serverVersion, {
+        capabilities: serverCapabilities,
+      });
       await proxyServer({
         client: stdioClient,
         requestTimeout,
@@ -68,20 +82,22 @@ async function createTestEnvironment(config: TestConfig = {}): Promise<TestEnvir
 
   const streamClient = new Client(
     { name: "stream-client", version: "1.0.0" },
-    { capabilities: {} }
+    { capabilities: {} },
   );
 
-  const transport = new StreamableHTTPClientTransport(new URL(`http://localhost:${port}/mcp`));
+  const transport = new StreamableHTTPClientTransport(
+    new URL(`http://localhost:${port}/mcp`),
+  );
   await streamClient.connect(transport);
 
-  return { 
+  return {
     cleanup: async () => {
       await streamClient.close();
       await stdioClient.close();
-    }, 
-    httpServer, 
-    stdioClient, 
-    streamClient
+    },
+    httpServer,
+    stdioClient,
+    streamClient,
   };
 }
 
@@ -90,7 +106,7 @@ describe("proxyServer timeout functionality", () => {
     const { cleanup, streamClient } = await createTestEnvironment({
       requestTimeout: 1000,
       serverDelay: "500",
-      serverFixture: "slow-stdio-server.ts"
+      serverFixture: "slow-stdio-server.ts",
     });
 
     // This should succeed as timeout (1s) > delay (500ms)
@@ -105,7 +121,7 @@ describe("proxyServer timeout functionality", () => {
     const { cleanup, streamClient } = await createTestEnvironment({
       requestTimeout: 500,
       serverDelay: "1000",
-      serverFixture: "slow-stdio-server.ts"
+      serverFixture: "slow-stdio-server.ts",
     });
 
     // This should throw a timeout error as delay (1s) > timeout (500ms)
@@ -128,7 +144,7 @@ describe("proxyServer timeout functionality", () => {
     const { cleanup, streamClient } = await createTestEnvironment({
       requestTimeout: 600,
       serverDelay: "300",
-      serverFixture: "slow-stdio-server.ts"
+      serverFixture: "slow-stdio-server.ts",
     });
 
     // First get the resources
@@ -141,7 +157,9 @@ describe("proxyServer timeout functionality", () => {
     });
 
     expect(resourceContent.contents).toBeDefined();
-    expect(resourceContent.contents[0].text).toContain("300ms delay");
+    expect((resourceContent.contents[0] as { text: string }).text).toContain(
+      "300ms delay",
+    );
 
     await cleanup();
   }, 10000);

package/src/startHTTPServer.test.ts

@@ -1339,8 +1339,8 @@ it("returns 401 with custom error message when { authenticated: false, error: '.
       },
     }),
     headers: {
-      "Accept": "application/json, text/event-stream",
-      "Authorization": "Bearer expired-token",
+      Accept: "application/json, text/event-stream",
+      Authorization: "Bearer expired-token",
       "Content-Type": "application/json",
     },
     method: "POST",
@@ -1408,8 +1408,8 @@ it("returns 401 when createServer throws authentication error", async () => {
       },
     }),
     headers: {
-      "Accept": "application/json, text/event-stream",
-      "Authorization": "Bearer test-token",
+      Accept: "application/json, text/event-stream",
+      Authorization: "Bearer test-token",
       "Content-Type": "application/json",
     },
     method: "POST",
@@ -1451,7 +1451,7 @@ it("returns 401 when createServer throws JWT-related error", async () => {
       },
     }),
     headers: {
-      "Accept": "application/json, text/event-stream",
+      Accept: "application/json, text/event-stream",
       "Content-Type": "application/json",
     },
     method: "POST",
@@ -1492,7 +1492,7 @@ it("returns 401 when createServer throws Token-related error", async () => {
       },
     }),
     headers: {
-      "Accept": "application/json, text/event-stream",
+      Accept: "application/json, text/event-stream",
       "Content-Type": "application/json",
     },
     method: "POST",
@@ -1533,7 +1533,7 @@ it("returns 401 when createServer throws Unauthorized error", async () => {
       },
     }),
     headers: {
-      "Accept": "application/json, text/event-stream",
+      Accept: "application/json, text/event-stream",
       "Content-Type": "application/json",
     },
     method: "POST",
@@ -1574,7 +1574,7 @@ it("returns 500 when createServer throws non-auth error", async () => {
       },
     }),
     headers: {
-      "Accept": "application/json, text/event-stream",
+      Accept: "application/json, text/event-stream",
       "Content-Type": "application/json",
     },
     method: "POST",
@@ -1614,7 +1614,7 @@ it("includes WWW-Authenticate header in 401 response with OAuth config", async (
       },
     }),
     headers: {
-      "Accept": "application/json, text/event-stream",
+      Accept: "application/json, text/event-stream",
       "Content-Type": "application/json",
     },
     method: "POST",
@@ -1624,9 +1624,11 @@ it("includes WWW-Authenticate header in 401 response with OAuth config", async (
 
   const wwwAuthHeader = response.headers.get("WWW-Authenticate");
   expect(wwwAuthHeader).toBeTruthy();
-  expect(wwwAuthHeader).toContain('Bearer');
+  expect(wwwAuthHeader).toContain("Bearer");
   expect(wwwAuthHeader).toContain('realm="mcp-server"');
-  expect(wwwAuthHeader).toContain('resource_metadata="https://example.com/.well-known/oauth-protected-resource"');
+  expect(wwwAuthHeader).toContain(
+    'resource_metadata="https://example.com/.well-known/oauth-protected-resource"',
+  );
   expect(wwwAuthHeader).toContain('error="invalid_token"');
   expect(wwwAuthHeader).toContain('error_description="Invalid JWT token"');
 
@@ -1636,7 +1638,9 @@ it("includes WWW-Authenticate header in 401 response with OAuth config", async (
 it("includes WWW-Authenticate header when authenticate callback fails with OAuth", async () => {
   const port = await getRandomPort();
 
-  const authenticate = vi.fn().mockRejectedValue(new Error("Token signature verification failed"));
+  const authenticate = vi
+    .fn()
+    .mockRejectedValue(new Error("Token signature verification failed"));
 
   const httpServer = await startHTTPServer({
     authenticate,
@@ -1670,8 +1674,8 @@ it("includes WWW-Authenticate header when authenticate callback fails with OAuth
       },
     }),
     headers: {
-      "Accept": "application/json, text/event-stream",
-      "Authorization": "Bearer expired-token",
+      Accept: "application/json, text/event-stream",
+      Authorization: "Bearer expired-token",
       "Content-Type": "application/json",
     },
     method: "POST",
@@ -1682,12 +1686,18 @@ it("includes WWW-Authenticate header when authenticate callback fails with OAuth
 
   const wwwAuthHeader = response.headers.get("WWW-Authenticate");
   expect(wwwAuthHeader).toBeTruthy();
-  expect(wwwAuthHeader).toContain('Bearer');
+  expect(wwwAuthHeader).toContain("Bearer");
   expect(wwwAuthHeader).toContain('realm="example-api"');
-  expect(wwwAuthHeader).toContain('resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"');
+  expect(wwwAuthHeader).toContain(
+    'resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"',
+  );
   expect(wwwAuthHeader).toContain('error="invalid_token"');
-  expect(wwwAuthHeader).toContain('error_description="Token signature verification failed"');
-  expect(wwwAuthHeader).toContain('error_uri="https://example.com/docs/errors"');
+  expect(wwwAuthHeader).toContain(
+    'error_description="Token signature verification failed"',
+  );
+  expect(wwwAuthHeader).toContain(
+    'error_uri="https://example.com/docs/errors"',
+  );
 
   await httpServer.close();
 });
@@ -1715,7 +1725,7 @@ it("does not include WWW-Authenticate header in 401 response without OAuth confi
       },
     }),
     headers: {
-      "Accept": "application/json, text/event-stream",
+      Accept: "application/json, text/event-stream",
       "Content-Type": "application/json",
     },
     method: "POST",
@@ -1916,7 +1926,9 @@ it("supports origin validation with array", async () => {
   });
 
   expect(response1.status).toBe(204);
-  expect(response1.headers.get("Access-Control-Allow-Origin")).toBe("https://app.example.com");
+  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`, {
@@ -1958,7 +1970,9 @@ it("supports origin validation with function", async () => {
   });
 
   expect(response1.status).toBe(204);
-  expect(response1.headers.get("Access-Control-Allow-Origin")).toBe("https://subdomain.example.com");
+  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`, {
@@ -2029,7 +2043,9 @@ it("uses default CORS settings when cors: true", async () => {
 
   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-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();
@@ -2062,7 +2078,9 @@ it("supports custom methods and maxAge", async () => {
   });
 
   expect(response.status).toBe(204);
-  expect(response.headers.get("Access-Control-Allow-Methods")).toBe("GET, POST, PUT, DELETE");
+  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();