@mcp-web/bridge 0.1.0

package/src/index.ts

@@ -0,0 +1,90 @@
+/**
+ * @mcp-web/bridge - MCP Web Bridge for connecting web frontends to AI agents.
+ *
+ * This package provides a runtime-agnostic bridge that mediates between
+ * web frontends and AI agents via the Model Context Protocol (MCP).
+ *
+ * @example Node.js (recommended)
+ * ```typescript
+ * import { MCPWebBridgeNode } from '@mcp-web/bridge';
+ *
+ * const bridge = new MCPWebBridgeNode({
+ *   name: 'My App',
+ *   description: 'My awesome app',
+ *   port: 3001,
+ * });
+ * ```
+ *
+ * @example Custom adapter (advanced)
+ * ```typescript
+ * import { MCPWebBridge } from '@mcp-web/bridge';
+ *
+ * const core = new MCPWebBridge(config);
+ * const handlers = core.getHandlers();
+ * // Wire handlers to your runtime's WebSocket/HTTP servers
+ * ```
+ */
+
+// Re-export types from @mcp-web/types
+export type {
+  QueryAcceptedMessage,
+  QueryCompleteBridgeMessage,
+  QueryCompleteClientMessage,
+  QueryFailureMessage,
+  QueryMessage,
+  QueryProgressMessage,
+} from '@mcp-web/types';
+
+export {
+  InternalErrorCode,
+  InvalidAuthenticationErrorCode,
+  MissingAuthenticationErrorCode,
+  QueryNotActiveErrorCode,
+  QueryNotFoundErrorCode,
+  UnknownMethodErrorCode,
+} from '@mcp-web/types';
+export type { MCPWebBridgeBunConfig, MCPWebBridgeDenoConfig, MCPWebBridgeNodeConfig, MCPWebBridgeNodeSSLConfig, MCPWebBridgePartyConfig } from './adapters/index.js';
+// Adapters
+// Deno adapter
+// Bun adapter
+// PartyKit adapter
+export { AlarmScheduler, Bridge, createPartyKitBridge, MCPWebBridgeBun, MCPWebBridgeDeno, MCPWebBridgeNode, MCPWebBridgeParty } from './adapters/index.js';
+// Core bridge (runtime-agnostic)
+// Backwards compatibility: re-export MCPWebBridge as the old name
+// Note: The old MCPWebBridge class used dual ports. The new architecture
+// uses single port via adapters. For migration, use MCPWebBridgeNode.
+/**
+ * @deprecated Use MCPWebBridgeNode for new code. This export exists for backwards compatibility.
+ */
+export { MCPWebBridge, MCPWebBridge as MCPWebBridgeCore } from './core.js';
+// Runtime abstractions (for custom adapter authors)
+export type {
+  BridgeAdapterConfig,
+  BridgeHandlers,
+  HttpRequest,
+  HttpResponse,Scheduler,
+  WebSocketConnection
+} from './runtime/index.js';
+export {
+  createHttpResponse,
+  jsonResponse,NoopScheduler,
+  readyStateToString,TimerScheduler,
+  WebSocketReadyState
+} from './runtime/index.js';
+// Legacy types (for backwards compatibility)
+export type {
+  ActivityMessage,
+  AuthenticatedMessage,
+  AuthenticateMessage,
+  BridgeMessage,
+  FrontendMessage,
+  QueryTracking,
+  RegisterResourceMessage,
+  RegisterToolMessage,
+  ResourceReadMessage,
+  ResourceResponseMessage,
+  ToolCallMessage,
+  ToolRegistrationErrorMessage,
+  ToolResponseMessage,
+  TrackedToolCall,
+} from './types.js';

package/src/limits.test.ts

@@ -0,0 +1,436 @@
+import { test, expect, beforeEach, afterEach, describe } from 'bun:test';
+import { MCPWebBridgeNode } from './adapters/node.js';
+import { WebSocket } from 'ws';
+
+// Helper to create a mock WebSocket client
+function createMockClient(port: number, sessionId: string): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://localhost:${port}?session=${sessionId}`);
+    ws.on('open', () => resolve(ws));
+    ws.on('error', reject);
+  });
+}
+
+// Helper to wait for a specific message type
+function waitForMessage<T>(ws: WebSocket, type: string, timeout = 5000): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`Timeout waiting for ${type}`)), timeout);
+    
+    const handler = (data: Buffer) => {
+      try {
+        const message = JSON.parse(data.toString());
+        if (message.type === type) {
+          clearTimeout(timer);
+          ws.removeListener('message', handler);
+          resolve(message);
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    };
+    
+    ws.on('message', handler);
+  });
+}
+
+// Helper to authenticate a client
+async function authenticateClient(ws: WebSocket, authToken: string): Promise<void> {
+  ws.send(JSON.stringify({
+    type: 'authenticate',
+    authToken,
+    origin: 'http://localhost:3000',
+    pageTitle: 'Test Page',
+    userAgent: 'Test Agent',
+    timestamp: Date.now()
+  }));
+  
+  await waitForMessage(ws, 'authenticated');
+}
+
+describe('Session Limits', () => {
+  let bridge: MCPWebBridgeNode;
+  let clients: WebSocket[] = [];
+  const port = 4101;
+
+  afterEach(async () => {
+    // Close all clients
+    for (const client of clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.close();
+      }
+    }
+    clients = [];
+    
+    // Close bridge
+    if (bridge) {
+      await bridge.close();
+    }
+  });
+
+  test('rejects new session when limit exceeded (reject mode)', async () => {
+    bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port,
+      maxSessionsPerToken: 2,
+      onSessionLimitExceeded: 'reject'
+    });
+
+    const authToken = 'test-token-reject';
+
+    // Create and authenticate 2 sessions (at limit)
+    const client1 = await createMockClient(port, 'session-1');
+    clients.push(client1);
+    await authenticateClient(client1, authToken);
+
+    const client2 = await createMockClient(port, 'session-2');
+    clients.push(client2);
+    await authenticateClient(client2, authToken);
+
+    // Try to create a 3rd session - should be rejected
+    const client3 = await createMockClient(port, 'session-3');
+    clients.push(client3);
+
+    const closePromise = new Promise<{ code: number; reason: string }>((resolve) => {
+      client3.on('close', (code, reason) => {
+        resolve({ code, reason: reason.toString() });
+      });
+    });
+
+    // Send authenticate - should fail
+    client3.send(JSON.stringify({
+      type: 'authenticate',
+      authToken,
+      origin: 'http://localhost:3000',
+      timestamp: Date.now()
+    }));
+
+    // Wait for the authentication-failed message and close
+    const failedMessage = await waitForMessage<{ type: string; code: string }>(client3, 'authentication-failed');
+    expect(failedMessage.code).toBe('SessionLimitExceeded');
+
+    const closeResult = await closePromise;
+    expect(closeResult.code).toBe(1008);
+    expect(closeResult.reason).toBe('Session limit exceeded');
+  });
+
+  test('closes oldest session when limit exceeded (close_oldest mode)', async () => {
+    bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port,
+      maxSessionsPerToken: 2,
+      onSessionLimitExceeded: 'close_oldest'
+    });
+
+    const authToken = 'test-token-close-oldest';
+
+    // Create and authenticate first session
+    const client1 = await createMockClient(port, 'session-oldest-1');
+    clients.push(client1);
+    await authenticateClient(client1, authToken);
+
+    // Track if client1 gets closed
+    const client1ClosePromise = new Promise<{ code: number }>((resolve) => {
+      client1.on('close', (code) => resolve({ code }));
+    });
+
+    // Small delay to ensure different connectedAt timestamps
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    // Create and authenticate second session
+    const client2 = await createMockClient(port, 'session-oldest-2');
+    clients.push(client2);
+    await authenticateClient(client2, authToken);
+
+    // Create and authenticate third session - should close the oldest (client1)
+    const client3 = await createMockClient(port, 'session-oldest-3');
+    clients.push(client3);
+    await authenticateClient(client3, authToken);
+
+    // client1 should have been closed
+    const closeResult = await client1ClosePromise;
+    expect(closeResult.code).toBe(1008);
+
+    // client2 and client3 should still be open
+    expect(client2.readyState).toBe(WebSocket.OPEN);
+    expect(client3.readyState).toBe(WebSocket.OPEN);
+  });
+
+  test('different tokens have separate session limits', async () => {
+    bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port,
+      maxSessionsPerToken: 1,
+      onSessionLimitExceeded: 'reject'
+    });
+
+    // Create sessions with different tokens - both should succeed
+    const client1 = await createMockClient(port, 'session-token-a');
+    clients.push(client1);
+    await authenticateClient(client1, 'token-a');
+
+    const client2 = await createMockClient(port, 'session-token-b');
+    clients.push(client2);
+    await authenticateClient(client2, 'token-b');
+
+    // Both should be connected
+    expect(client1.readyState).toBe(WebSocket.OPEN);
+    expect(client2.readyState).toBe(WebSocket.OPEN);
+  });
+
+  test('no limit when maxSessionsPerToken is not set', async () => {
+    bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port
+      // No maxSessionsPerToken
+    });
+
+    const authToken = 'test-token-no-limit';
+
+    // Create many sessions - all should succeed
+    for (let i = 0; i < 5; i++) {
+      const client = await createMockClient(port, `session-no-limit-${i}`);
+      clients.push(client);
+      await authenticateClient(client, authToken);
+      expect(client.readyState).toBe(WebSocket.OPEN);
+    }
+  });
+});
+
+describe('Query Limits', () => {
+  let bridge: MCPWebBridgeNode;
+  let clients: WebSocket[] = [];
+  const port = 4201;
+  let originalFetch: typeof fetch;
+
+  beforeEach(() => {
+    // Save original fetch
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(async () => {
+    // Restore original fetch
+    globalThis.fetch = originalFetch;
+
+    for (const client of clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.close();
+      }
+    }
+    clients = [];
+    
+    if (bridge) {
+      await bridge.close();
+    }
+  });
+
+  test('rejects query when limit exceeded', async () => {
+    // Mock fetch to return a never-resolving promise (keeps queries "in flight")
+    globalThis.fetch = () => new Promise(() => {});
+
+    bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port,
+      maxInFlightQueriesPerToken: 2,
+      agentUrl: 'localhost:9999'
+    });
+
+    const authToken = 'test-token-query-limit';
+
+    const client = await createMockClient(port, 'session-query-limit');
+    clients.push(client);
+    await authenticateClient(client, authToken);
+
+    // Send first query - will hang because fetch never resolves
+    client.send(JSON.stringify({
+      type: 'query',
+      uuid: 'query-1',
+      prompt: 'Test query 1',
+      context: [],
+      tools: []
+    }));
+
+    // Small delay to ensure query is registered
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    // Send second query
+    client.send(JSON.stringify({
+      type: 'query',
+      uuid: 'query-2',
+      prompt: 'Test query 2',
+      context: [],
+      tools: []
+    }));
+
+    // Small delay to ensure query is registered
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    // Send third query - should be rejected due to limit (2 queries already in flight)
+    client.send(JSON.stringify({
+      type: 'query',
+      uuid: 'query-3',
+      prompt: 'Test query 3',
+      context: [],
+      tools: []
+    }));
+
+    // Wait for failure message for query-3
+    const failureMessage = await waitForMessage<{ type: string; uuid: string; error: string }>(
+      client, 
+      'query_failure'
+    );
+
+    expect(failureMessage.uuid).toBe('query-3');
+    expect(failureMessage.error).toContain('Query limit exceeded');
+  });
+
+  test('no limit when maxInFlightQueriesPerToken is not set', async () => {
+    // Mock fetch to return a never-resolving promise
+    globalThis.fetch = () => new Promise(() => {});
+
+    bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port,
+      agentUrl: 'localhost:9999'
+      // No maxInFlightQueriesPerToken
+    });
+
+    const authToken = 'test-token-no-query-limit';
+
+    const client = await createMockClient(port, 'session-no-query-limit');
+    clients.push(client);
+    await authenticateClient(client, authToken);
+
+    // Send many queries - all should be accepted since no limit is set
+    for (let i = 0; i < 10; i++) {
+      client.send(JSON.stringify({
+        type: 'query',
+        uuid: `query-unlimited-${i}`,
+        prompt: `Test query ${i}`,
+        context: [],
+        tools: []
+      }));
+    }
+
+    // Wait a bit - no query_failure messages should be received
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    // If we got here without the test failing, no limit errors were sent
+    // The queries are still "in flight" (waiting on the mock fetch)
+  });
+});
+
+describe('Session Timeout', () => {
+  let bridge: MCPWebBridgeNode;
+  let clients: WebSocket[] = [];
+  const port = 4301;
+
+  afterEach(async () => {
+    for (const client of clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.close();
+      }
+    }
+    clients = [];
+    
+    if (bridge) {
+      await bridge.close();
+    }
+  });
+
+  test('session expires after maxDuration', async () => {
+    // Use a very short duration for testing (100ms)
+    // Note: The actual checker runs every 60s, so we need to test differently
+    // We'll verify the config is accepted and the timeout checker starts
+    bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port,
+      sessionMaxDurationMs: 100 // Very short for testing
+    });
+
+    const client = await createMockClient(port, 'session-timeout');
+    clients.push(client);
+    await authenticateClient(client, 'test-token-timeout');
+
+    // The session should be open initially
+    expect(client.readyState).toBe(WebSocket.OPEN);
+
+    // Note: In a real test we'd wait for the timeout interval (60s) to fire
+    // For unit testing, we just verify the bridge accepts the config
+    // Integration tests would test the actual timeout behavior
+  });
+
+  test('no timeout when sessionMaxDurationMs is not set', async () => {
+    bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port
+      // No sessionMaxDurationMs
+    });
+
+    const client = await createMockClient(port, 'session-no-timeout');
+    clients.push(client);
+    await authenticateClient(client, 'test-token-no-timeout');
+
+    // Session should stay open
+    expect(client.readyState).toBe(WebSocket.OPEN);
+  });
+});
+
+describe('Config Schema', () => {
+  test('accepts all new limit properties', async () => {
+    // This should not throw
+    const bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port: 4401,
+      maxSessionsPerToken: 5,
+      onSessionLimitExceeded: 'close_oldest',
+      maxInFlightQueriesPerToken: 10,
+      sessionMaxDurationMs: 3600000
+    });
+
+    await bridge.close();
+  });
+
+  test('defaults onSessionLimitExceeded to reject', async () => {
+    const bridge = new MCPWebBridgeNode({
+      name: 'Test Bridge',
+      description: 'Test',
+      port: 4501,
+      maxSessionsPerToken: 1
+      // onSessionLimitExceeded not specified
+    });
+
+    // Create first session
+    const client1 = await createMockClient(4501, 'session-default-1');
+    await authenticateClient(client1, 'token-default');
+
+    // Second session should be rejected (default behavior)
+    const client2 = await createMockClient(4501, 'session-default-2');
+    
+    const closePromise = new Promise<{ code: number }>((resolve) => {
+      client2.on('close', (code) => resolve({ code }));
+    });
+
+    client2.send(JSON.stringify({
+      type: 'authenticate',
+      authToken: 'token-default',
+      origin: 'http://localhost:3000',
+      timestamp: Date.now()
+    }));
+
+    const closeResult = await closePromise;
+    expect(closeResult.code).toBe(1008);
+
+    client1.close();
+    client2.close();
+    await bridge.close();
+  });
+});