mcp-proxy 5.10.0 → 5.11.1

package/jsr.json

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

package/package.json

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

package/src/InMemoryEventStore.test.ts

@@ -157,4 +157,76 @@ describe("InMemoryEventStore", () => {
     );
     expect(emptyResult).toBe("");
   });
+
+  it("keeps deterministic ordering even when events share the same timestamp", async () => {
+    const store = new InMemoryEventStore();
+    const streamId = "deterministic-stream";
+
+    const messages: JSONRPCMessage[] = [
+      { id: 1, jsonrpc: "2.0", method: "step/one" },
+      { id: 2, jsonrpc: "2.0", method: "step/two" },
+      { id: 3, jsonrpc: "2.0", method: "step/three" },
+      { id: 4, jsonrpc: "2.0", method: "step/four" },
+    ];
+
+    const fixedTimestamp = 1_730_000_000_000;
+    const nowSpy = vi.spyOn(Date, "now").mockReturnValue(fixedTimestamp);
+
+    const eventIds: string[] = [];
+    try {
+      for (const message of messages) {
+        eventIds.push(await store.storeEvent(streamId, message));
+      }
+    } finally {
+      nowSpy.mockRestore();
+    }
+
+    // Ensure IDs already arrive sorted since we stored sequentially
+    expect(eventIds).toEqual([...eventIds].sort());
+
+    const parts = eventIds.map((eventId) => eventId.split("_"));
+
+    const timestampParts = parts.map(([, timestamp]) => timestamp);
+    expect(timestampParts).toEqual(
+      Array(messages.length).fill(fixedTimestamp.toString())
+    );
+
+    const counterSuffixes = parts.map(([, , counter]) => counter);
+    expect(counterSuffixes).toEqual(
+      messages.map((_, index) => (index).toString(36).padStart(4, "0"))
+    );
+
+    // Random parts should be 3 base36 characters each (due to substring(2, 5))
+    const randomParts = parts.map(([, , , random]) => random);
+    for (const random of randomParts) {
+      expect(random).toMatch(/^[0-9a-z]{3}$/);
+    }
+
+    // Replay after the first event and ensure the remainder flow in order
+    const replayedMessages: JSONRPCMessage[] = [];
+    const returnedStreamId = await store.replayEventsAfter(eventIds[0], {
+      send: async (_eventId: string, message: JSONRPCMessage) => {
+        replayedMessages.push(message);
+      },
+    });
+
+    expect(returnedStreamId).toBe(streamId);
+    expect(replayedMessages).toEqual(messages.slice(1));
+
+    // Now allow timestamp to advance to ensure counter resets
+    const nextTimestamp = fixedTimestamp + 1;
+    const secondSpy = vi.spyOn(Date, "now").mockReturnValue(nextTimestamp);
+    try {
+      const nextId = await store.storeEvent(streamId, {
+        id: 5,
+        jsonrpc: "2.0",
+        method: "step/five",
+      });
+      const [, , counter, random] = nextId.split("_");
+      expect(counter).toBe("0000");
+      expect(random).toMatch(/^[0-9a-z]{3}$/);
+    } finally {
+      secondSpy.mockRestore();
+    }
+  });
 });

package/src/InMemoryEventStore.ts

@@ -14,6 +14,8 @@ import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
 export class InMemoryEventStore implements EventStore {
   private events: Map<string, { message: JSONRPCMessage; streamId: string }> =
     new Map();
+  private lastTimestamp = 0;
+  private lastTimestampCounter = 0;
 
   /**
    * Replays events that occurred after a specific event ID
@@ -79,10 +81,25 @@ export class InMemoryEventStore implements EventStore {
   }
 
   /**
-   * Generates a unique event ID for a given stream ID
+   * Generates a monotonic unique event ID in 
+   * `${streamId}_${timestamp}_${counter}_${random}` format.
    */
   private generateEventId(streamId: string): string {
-    return `${streamId}_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
+
+    const now = Date.now();
+    
+    if (now === this.lastTimestamp) {
+      this.lastTimestampCounter++;
+    } else {
+      this.lastTimestampCounter = 0;
+      this.lastTimestamp = now;
+    }
+
+    const timestamp = now.toString();
+    const counter = this.lastTimestampCounter.toString(36).padStart(4, "0");
+    const random = Math.random().toString(36).substring(2, 5);
+
+    return `${streamId}_${timestamp}_${counter}_${random}`;
   }
 
   /**

package/src/authentication.test.ts

@@ -132,7 +132,7 @@ describe("AuthenticationMiddleware", () => {
       const response = middleware.getUnauthorizedResponse();
 
       expect(response.headers["WWW-Authenticate"]).toBe(
-        'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"',
+        'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource", error="invalid_token", error_description="Unauthorized: Invalid or missing API key"',
       );
     });
 
@@ -148,21 +148,24 @@ describe("AuthenticationMiddleware", () => {
       const response = middleware.getUnauthorizedResponse();
 
       expect(response.headers["WWW-Authenticate"]).toBe(
-        'Bearer resource_metadata="https://example.com//.well-known/oauth-protected-resource"',
+        'Bearer resource_metadata="https://example.com//.well-known/oauth-protected-resource", error="invalid_token", error_description="Unauthorized: Invalid or missing API key"',
       );
     });
 
-    it("should not include WWW-Authenticate header when OAuth config is empty", () => {
+    it("should include minimal WWW-Authenticate header when OAuth config is empty object", () => {
       const middleware = new AuthenticationMiddleware({
         apiKey: "test",
         oauth: {},
       });
       const response = middleware.getUnauthorizedResponse();
 
-      expect(response.headers["WWW-Authenticate"]).toBeUndefined();
+      // Even with empty oauth object, default error and error_description are added
+      expect(response.headers["WWW-Authenticate"]).toBe(
+        'Bearer error="invalid_token", error_description="Unauthorized: Invalid or missing API key"',
+      );
     });
 
-    it("should not include WWW-Authenticate header when protectedResource is empty", () => {
+    it("should include minimal WWW-Authenticate header when protectedResource is empty", () => {
       const middleware = new AuthenticationMiddleware({
         apiKey: "test",
         oauth: {
@@ -171,7 +174,10 @@ describe("AuthenticationMiddleware", () => {
       });
       const response = middleware.getUnauthorizedResponse();
 
-      expect(response.headers["WWW-Authenticate"]).toBeUndefined();
+      // Even without resource_metadata, default error and error_description are added
+      expect(response.headers["WWW-Authenticate"]).toBe(
+        'Bearer error="invalid_token", error_description="Unauthorized: Invalid or missing API key"',
+      );
     });
 
     it("should include WWW-Authenticate header with OAuth config but no apiKey", () => {
@@ -185,8 +191,140 @@ describe("AuthenticationMiddleware", () => {
       const response = middleware.getUnauthorizedResponse();
 
       expect(response.headers["WWW-Authenticate"]).toBe(
-        'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"',
+        'Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource", error="invalid_token", error_description="Unauthorized: Invalid or missing API key"',
       );
     });
+
+    it("should include realm in WWW-Authenticate header when configured", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com",
+          },
+          realm: "example-realm",
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toContain('realm="example-realm"');
+      expect(response.headers["WWW-Authenticate"]).toContain('resource_metadata="https://example.com/.well-known/oauth-protected-resource"');
+    });
+
+    it("should include custom error in WWW-Authenticate header via options", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse({
+        error: "insufficient_scope",
+        error_description: "The request requires higher privileges",
+      });
+
+      expect(response.headers["WWW-Authenticate"]).toContain('error="insufficient_scope"');
+      expect(response.headers["WWW-Authenticate"]).toContain('error_description="The request requires higher privileges"');
+    });
+
+    it("should include scope in WWW-Authenticate header", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com",
+          },
+          scope: "read write",
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toContain('scope="read write"');
+    });
+
+    it("should override config error with options error", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          error: "invalid_request",
+          error_description: "Config error description",
+          protectedResource: {
+            resource: "https://example.com",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse({
+        error: "invalid_token",
+        error_description: "Options error description",
+      });
+
+      expect(response.headers["WWW-Authenticate"]).toContain('error="invalid_token"');
+      expect(response.headers["WWW-Authenticate"]).toContain('error_description="Options error description"');
+      expect(response.headers["WWW-Authenticate"]).not.toContain("invalid_request");
+      expect(response.headers["WWW-Authenticate"]).not.toContain("Config error description");
+    });
+
+    it("should include error_uri in WWW-Authenticate header", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          error_uri: "https://example.com/errors/auth",
+          protectedResource: {
+            resource: "https://example.com",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      expect(response.headers["WWW-Authenticate"]).toContain('error_uri="https://example.com/errors/auth"');
+    });
+
+    it("should properly escape quotes in error_description", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          protectedResource: {
+            resource: "https://example.com",
+          },
+        },
+      });
+      const response = middleware.getUnauthorizedResponse({
+        error_description: 'Token "abc123" is invalid',
+      });
+
+      expect(response.headers["WWW-Authenticate"]).toContain('error_description="Token \\"abc123\\" is invalid"');
+    });
+
+    it("should include all parameters in correct order", () => {
+      const middleware = new AuthenticationMiddleware({
+        apiKey: "test",
+        oauth: {
+          error: "invalid_token",
+          error_description: "Token expired",
+          error_uri: "https://example.com/errors",
+          protectedResource: {
+            resource: "https://example.com",
+          },
+          realm: "my-realm",
+          scope: "read write",
+        },
+      });
+      const response = middleware.getUnauthorizedResponse();
+
+      const header = response.headers["WWW-Authenticate"];
+      expect(header).toContain('realm="my-realm"');
+      expect(header).toContain('resource_metadata="https://example.com/.well-known/oauth-protected-resource"');
+      expect(header).toContain('error="invalid_token"');
+      expect(header).toContain('error_description="Token expired"');
+      expect(header).toContain('error_uri="https://example.com/errors"');
+      expect(header).toContain('scope="read write"');
+
+      // Check order: realm, resource_metadata, error, error_description, error_uri, scope
+      expect(header.indexOf('realm=')).toBeLessThan(header.indexOf('resource_metadata='));
+      expect(header.indexOf('resource_metadata=')).toBeLessThan(header.indexOf('error='));
+      expect(header.indexOf('error=')).toBeLessThan(header.indexOf('error_description='));
+    });
   });
 });

package/src/authentication.ts

@@ -3,30 +3,76 @@ import type { IncomingMessage } from "http";
 export interface AuthConfig {
   apiKey?: string;
   oauth?: {
+    error?: string;
+    error_description?: string;
+    error_uri?: string;
     protectedResource?: {
       resource?: string;
     };
+    realm?: string;
+    scope?: string;
   };
 }
 
 export class AuthenticationMiddleware {
   constructor(private config: AuthConfig = {}) {}
 
-  getUnauthorizedResponse(): { body: string; headers: Record<string, string> } {
+  getUnauthorizedResponse(options?: {
+    error?: string;
+    error_description?: string;
+    error_uri?: string;
+    scope?: string;
+  }): { 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"`;
+    // Build WWW-Authenticate header if OAuth config is available
+    if (this.config.oauth) {
+      const params: string[] = [];
+
+      // Add realm if configured
+      if (this.config.oauth.realm) {
+        params.push(`realm="${this.config.oauth.realm}"`);
+      }
+
+      // 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"`);
+      }
+
+      // Add error from options or config (options takes precedence)
+      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";
+      // Escape quotes in error description
+      const escaped = error_description.replace(/"/g, '\\"');
+      params.push(`error_description="${escaped}"`);
+
+      // Add error_uri from options or config (options takes precedence)
+      const error_uri = options?.error_uri || this.config.oauth.error_uri;
+      if (error_uri) {
+        params.push(`error_uri="${error_uri}"`);
+      }
+
+      // Add scope from options or config (options takes precedence)
+      const scope = options?.scope || this.config.oauth.scope;
+      if (scope) {
+        params.push(`scope="${scope}"`);
+      }
+
+      if (params.length > 0) {
+        headers["WWW-Authenticate"] = `Bearer ${params.join(", ")}`;
+      }
     }
 
     return {
       body: JSON.stringify({
         error: {
           code: 401,
-          message: "Unauthorized: Invalid or missing API key",
+          message: options?.error_description || "Unauthorized: Invalid or missing API key",
         },
         id: null,
         jsonrpc: "2.0",

package/src/proxyServer.ts

@@ -124,10 +124,12 @@ export const proxyServer = async ({
     });
   }
 
-  server.setRequestHandler(CompleteRequestSchema, async (args) => {
-    return client.complete(
-      args.params,
-      requestTimeout ? { timeout: requestTimeout } : undefined,
-    );
-  });
+  if (serverCapabilities?.completions) {
+    server.setRequestHandler(CompleteRequestSchema, async (args) => {
+      return client.complete(
+        args.params,
+        requestTimeout ? { timeout: requestTimeout } : undefined,
+      );
+    });
+  }
 };

package/src/startHTTPServer.test.ts

@@ -1585,6 +1585,150 @@ it("returns 500 when createServer throws non-auth error", async () => {
   await httpServer.close();
 });
 
+it("includes WWW-Authenticate header in 401 response with OAuth config", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    createServer: async () => {
+      throw new Error("Invalid JWT token");
+    },
+    oauth: {
+      protectedResource: {
+        resource: "https://example.com",
+      },
+      realm: "mcp-server",
+    },
+    port,
+    stateless: true,
+  });
+
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: { name: "test", version: "1.0.0" },
+        protocolVersion: "2024-11-05",
+      },
+    }),
+    headers: {
+      "Accept": "application/json, text/event-stream",
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+
+  expect(response.status).toBe(401);
+
+  const wwwAuthHeader = response.headers.get("WWW-Authenticate");
+  expect(wwwAuthHeader).toBeTruthy();
+  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('error="invalid_token"');
+  expect(wwwAuthHeader).toContain('error_description="Invalid JWT token"');
+
+  await httpServer.close();
+});
+
+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 httpServer = await startHTTPServer({
+    authenticate,
+    createServer: async () => {
+      const mcpServer = new Server(
+        { name: "test", version: "1.0.0" },
+        { capabilities: {} },
+      );
+      return mcpServer;
+    },
+    oauth: {
+      error_uri: "https://example.com/docs/errors",
+      protectedResource: {
+        resource: "https://api.example.com",
+      },
+      realm: "example-api",
+    },
+    port,
+    stateless: true,
+  });
+
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: { name: "test", version: "1.0.0" },
+        protocolVersion: "2024-11-05",
+      },
+    }),
+    headers: {
+      "Accept": "application/json, text/event-stream",
+      "Authorization": "Bearer expired-token",
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+
+  expect(response.status).toBe(401);
+  expect(authenticate).toHaveBeenCalled();
+
+  const wwwAuthHeader = response.headers.get("WWW-Authenticate");
+  expect(wwwAuthHeader).toBeTruthy();
+  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('error="invalid_token"');
+  expect(wwwAuthHeader).toContain('error_description="Token signature verification failed"');
+  expect(wwwAuthHeader).toContain('error_uri="https://example.com/docs/errors"');
+
+  await httpServer.close();
+});
+
+it("does not include WWW-Authenticate header in 401 response without OAuth config", async () => {
+  const port = await getRandomPort();
+
+  const httpServer = await startHTTPServer({
+    createServer: async () => {
+      throw new Error("Authentication required");
+    },
+    port,
+    stateless: true,
+  });
+
+  const response = await fetch(`http://localhost:${port}/mcp`, {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: "2.0",
+      method: "initialize",
+      params: {
+        capabilities: {},
+        clientInfo: { name: "test", version: "1.0.0" },
+        protocolVersion: "2024-11-05",
+      },
+    }),
+    headers: {
+      "Accept": "application/json, text/event-stream",
+      "Content-Type": "application/json",
+    },
+    method: "POST",
+  });
+
+  expect(response.status).toBe(401);
+
+  const wwwAuthHeader = response.headers.get("WWW-Authenticate");
+  expect(wwwAuthHeader).toBeNull();
+
+  await httpServer.close();
+});
+
 it("succeeds when authenticate returns { authenticated: true } in stateless mode", async () => {
   const stdioTransport = new StdioClientTransport({
     args: ["src/fixtures/simple-stdio-server.ts"],