@context-engine-bridge/context-engine-mcp-bridge 0.0.18 → 0.0.20

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "context-engine"
+  ],
+  "permissions": {
+    "allow": [
+      "mcp__context-engine__repo_search"
+    ]
+  }
+}

package/.sisyphus/ultrawork-state.json

@@ -0,0 +1,7 @@
+{
+  "active": true,
+  "started_at": "2026-01-25T14:25:53.146Z",
+  "original_prompt": "/oh-my-claude-sisyphus:ultrawork we need to figure out, research context engine a bit.... how to make our agent tools better via mcp... (the claude.example.md is\n  clear) but maybe we need an agents.md, we have claude skills... can we make the descriptors better? research alot fo other\n  tools and see",
+  "reinforcement_count": 5,
+  "last_checked_at": "2026-01-25T14:43:28.449Z"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-engine-bridge/context-engine-mcp-bridge",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Context Engine MCP bridge (http/stdio proxy combining indexer + memory servers)",
   "bin": {
     "ctxce": "bin/ctxce.js",
@@ -9,12 +9,20 @@
   "type": "module",
   "scripts": {
     "start": "node bin/ctxce.js",
-    "postinstall": "node -e \"try{require('fs').chmodSync('bin/ctxce.js',0o755)}catch(e){}\""
+    "postinstall": "node -e \"try{require('fs').chmodSync('bin/ctxce.js',0o755)}catch(e){}\"",
+    "test:e2e": "playwright test",
+    "test:e2e:auth": "playwright test --project=auth-enforcement",
+    "test:e2e:happy": "playwright test --project=happy-paths-chromium",
+    "test:e2e:edge": "playwright test --project=edge-cases",
+    "test:e2e:ui": "playwright test --ui"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.3",
     "zod": "^3.25.0"
   },
+  "devDependencies": {
+    "@playwright/test": "^1.57.0"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/cli.js

@@ -23,6 +23,7 @@ export async function runCli() {
     let indexerUrl = process.env.CTXCE_INDEXER_URL || "http://localhost:8003/mcp";
     let memoryUrl = process.env.CTXCE_MEMORY_URL || null;
     let port = Number.parseInt(process.env.CTXCE_HTTP_PORT || "30810", 10) || 30810;
+    let collection = null;
 
     for (let i = 0; i < args.length; i += 1) {
       const a = args[i];
@@ -57,13 +58,20 @@ export async function runCli() {
           continue;
         }
       }
+      if (a === "--collection") {
+        if (i + 1 < args.length) {
+          collection = args[i + 1];
+          i += 1;
+          continue;
+        }
+      }
     }
 
     // eslint-disable-next-line no-console
     console.error(
-      `[ctxce] Starting HTTP MCP bridge: workspace=${workspace}, port=${port}, indexerUrl=${indexerUrl}, memoryUrl=${memoryUrl || "disabled"}`,
+      `[ctxce] Starting HTTP MCP bridge: workspace=${workspace}, port=${port}, indexerUrl=${indexerUrl}, memoryUrl=${memoryUrl || "disabled"}, collection=${collection || "auto"}`,
     );
-    await runHttpMcpServer({ workspace, indexerUrl, memoryUrl, port });
+    await runHttpMcpServer({ workspace, indexerUrl, memoryUrl, port, collection });
     return;
   }
 
@@ -72,10 +80,12 @@ export async function runCli() {
     // Supported flags:
     //   --workspace / --path   : workspace root (default: cwd)
     //   --indexer-url          : override MCP indexer URL (default env CTXCE_INDEXER_URL or http://localhost:8003/mcp)
+    //   --collection           : collection name to use for MCP calls
     const args = argv.slice(1);
     let workspace = process.cwd();
     let indexerUrl = process.env.CTXCE_INDEXER_URL || "http://localhost:8003/mcp";
     let memoryUrl = process.env.CTXCE_MEMORY_URL || null;
+    let collection = null;
 
     for (let i = 0; i < args.length; i += 1) {
       const a = args[i];
@@ -100,13 +110,20 @@ export async function runCli() {
           continue;
         }
       }
+      if (a === "--collection") {
+        if (i + 1 < args.length) {
+          collection = args[i + 1];
+          i += 1;
+          continue;
+        }
+      }
     }
 
     // eslint-disable-next-line no-console
     console.error(
-      `[ctxce] Starting MCP bridge: workspace=${workspace}, indexerUrl=${indexerUrl}, memoryUrl=${memoryUrl || "disabled"}`,
+      `[ctxce] Starting MCP bridge: workspace=${workspace}, indexerUrl=${indexerUrl}, memoryUrl=${memoryUrl || "disabled"}, collection=${collection || "auto"}`,
     );
-    await runMcpServer({ workspace, indexerUrl, memoryUrl });
+    await runMcpServer({ workspace, indexerUrl, memoryUrl, collection });
     return;
   }
 
@@ -117,7 +134,7 @@ export async function runCli() {
 
   // eslint-disable-next-line no-console
   console.error(
-    `Usage: ${binName} mcp-serve [--workspace <path>] [--indexer-url <url>] [--memory-url <url>] | ${binName} mcp-http-serve [--workspace <path>] [--indexer-url <url>] [--memory-url <url>] [--port <port>] | ${binName} auth <login|status|logout> [--backend-url <url>] [--token <token>] [--username <name> --password <pass>]`,
+    `Usage: ${binName} mcp-serve [--workspace <path>] [--indexer-url <url>] [--memory-url <url>] [--collection <name>] | ${binName} mcp-http-serve [--workspace <path>] [--indexer-url <url>] [--memory-url <url>] [--port <port>] [--collection <name>] | ${binName} auth <login|status|logout> [--backend-url <url>] [--token <token>] [--username <name> --password <pass>]`,
   );
   process.exit(1);
 }

package/src/mcpServer.js

@@ -1,6 +1,7 @@
 import process from "node:process";
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { execSync } from "node:child_process";
 import { createServer } from "node:http";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -414,18 +415,8 @@ async function fetchBridgeCollectionState({
     if (!resp.ok) {
       if (resp.status === 401 || resp.status === 403) {
         debugLog(
-          `[ctxce] /bridge/state responded ${resp.status}; missing or invalid token/session, marking local session as expired.`,
+          `[ctxce] /bridge/state responded ${resp.status}; session may not be accepted by this endpoint.`,
         );
-        if (backendHint) {
-          try {
-            const entry = loadAuthEntry(backendHint);
-            if (entry) {
-              saveAuthEntry(backendHint, { ...entry, expiresAt: 1 });
-            }
-          } catch {
-            // ignore failures
-          }
-        }
         return null;
       }
       throw new Error(`bridge/state responded ${resp.status}`);
@@ -443,12 +434,15 @@ async function createBridgeServer(options) {
   const workspace = options.workspace || process.cwd();
   const indexerUrl = options.indexerUrl;
   const memoryUrl = options.memoryUrl;
+  const explicitCollection = options.collection;
 
   const config = loadConfig(workspace);
   const defaultCollection =
-    config && typeof config.default_collection === "string"
-      ? config.default_collection
-      : null;
+    explicitCollection && typeof explicitCollection === "string"
+      ? explicitCollection
+      : config && typeof config.default_collection === "string"
+        ? config.default_collection
+        : null;
   const defaultMode =
     config && typeof config.default_mode === "string" ? config.default_mode : null;
   const defaultUnder =
@@ -502,8 +496,8 @@ async function createBridgeServer(options) {
       expiresAt > 0 &&
       expiresAt < Math.floor(Date.now() / 1000)
     ) {
-      debugLog("[ctxce] Stored auth session appears expired; please run `ctxce auth login` again.");
-      return "";
+      debugLog("[ctxce] Stored auth session has local expiry in the past; attempting to use it anyway (server will validate).");
+      return entry.sessionId;
     }
     return entry.sessionId;
   }
@@ -707,7 +701,7 @@ async function createBridgeServer(options) {
 
   await initializeRemoteClients(false);
 
-  const server = new Server( // TODO: marked as depreciated
+  const server = new Server(
     {
       name: "ctx-context-engine-bridge",
       version: "0.0.1",
@@ -908,17 +902,74 @@ export async function runMcpServer(options) {
 }
 
 export async function runHttpMcpServer(options) {
-  const server = await createBridgeServer(options);
+  // Multi-client HTTP mode: each MCP client (Claude, Codex, Kiro, Windsurf,
+  // Augment, etc.) gets its own session with a dedicated Server+Transport
+  // pair. Sessions are tracked by the Mcp-Session-Id header. This allows
+  // multiple IDEs to share the same bridge simultaneously.
+  //
+  // Flow:
+  //   1. Client sends POST with initialize request (no session ID)
+  //   2. Bridge creates a new Server+Transport, generates a session ID
+  //   3. Response includes Mcp-Session-Id header
+  //   4. Client includes Mcp-Session-Id on all subsequent requests
+  //   5. Bridge routes to the correct Server+Transport for that session
+  //
+  // Each session has its own upstream connections (indexer, memory) created
+  // by createBridgeServer. Sessions are cleaned up after 30 min of inactivity.
+
   const port =
     typeof options.port === "number"
       ? options.port
       : Number.parseInt(process.env.CTXCE_HTTP_PORT || "30810", 10) || 30810;
 
-  const transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: undefined,
-  });
+  // ──────────────────────────────────────────────────────────────────────
+  // Session management
+  // ──────────────────────────────────────────────────────────────────────
+  const sessions = new Map(); // sessionId → { server, transport, lastUsed }
+  const SESSION_TTL_MS = 30 * 60 * 1000; // 30 minutes inactive
+  const MAX_SESSIONS = 20;
+
+  // Periodic cleanup of stale sessions
+  const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [sid, session] of sessions) {
+      if (now - session.lastUsed > SESSION_TTL_MS) {
+        debugLog(`[ctxce] Cleaning up stale MCP session: ${sid}`);
+        session.transport.close().catch(() => {});
+        session.server.close().catch(() => {});
+        sessions.delete(sid);
+      }
+    }
+  }, 60_000);
+  cleanupInterval.unref();
+
+  function evictOldestSession() {
+    if (sessions.size < MAX_SESSIONS) return;
+    let oldest = null;
+    let oldestTime = Infinity;
+    for (const [sid, s] of sessions) {
+      if (s.lastUsed < oldestTime) {
+        oldest = sid;
+        oldestTime = s.lastUsed;
+      }
+    }
+    if (oldest) {
+      const s = sessions.get(oldest);
+      sessions.delete(oldest);
+      s.transport.close().catch(() => {});
+      s.server.close().catch(() => {});
+      debugLog(`[ctxce] Evicted oldest MCP session: ${oldest}`);
+    }
+  }
 
-  await server.connect(transport);
+  // Pre-warm: validate upstream connectivity (best-effort)
+  try {
+    const warmupServer = await createBridgeServer(options);
+    await warmupServer.close();
+    debugLog("[ctxce] HTTP bridge validated upstream connectivity");
+  } catch (err) {
+    debugLog("[ctxce] HTTP bridge warmup failed (non-fatal): " + String(err));
+  }
 
   // Build issuer URL for OAuth
   // Note: Local-only bridge uses 127.0.0.1. For remote access, this would need to be configurable.
@@ -969,56 +1020,57 @@ export async function runHttpMcpServer(options) {
       // MCP Endpoint
       // ================================================================
 
-      // Check Bearer token for MCP endpoint (accept /mcp and /mcp/ for compatibility)
+      // Accept /mcp and /mcp/ for compatibility
       if (parsedUrl.pathname === "/mcp" || parsedUrl.pathname === "/mcp/") {
+        // ── Bearer token auth (permissive: validate if provided, don't require) ──
         const authHeader = req.headers["authorization"] || "";
         const bearerToken = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
-
-        // ----------------------------------------------------------------
-        // AUTHENTICATION DESIGN: Permissive by default for backward compatibility
-        // ----------------------------------------------------------------
-        // The condition `bearerToken && hasTokenStore()` is INTENTIONALLY permissive:
-        //
-        // 1. PRE-EXISTING USERS (v3.0.0, local/dev mode):
-        //    - No OAuth flow occurs → tokenStore remains empty
-        //    - hasTokenStore() returns false → auth check skipped entirely
-        //    - Requests proceed without authentication (local dev experience)
-        //
-        // 2. SAAS PLATFORM USERS (multi-tenant):
-        //    - User completes OAuth flow → token stored in tokenStore
-        //    - hasTokenStore() returns true → bearer token validation required
-        //    - Invalid/missing tokens are rejected with 401
-        //
-        // WHY NOT `hasTokenStore() && !bearerToken` (require token when store exists)?
-        //    - Mixed environments: Some clients may be local (no auth) while others
-        //      are authenticated. Requiring auth globally after first login would
-        //      break local dev workflows in hybrid setups.
-        //    - The current design: "validate if provided, but don't require"
-        //
-        // SECURITY NOTE: If strict authentication is required for all clients once
-        // any user authenticates, add an environment flag like CTXCE_REQUIRE_AUTH=1
-        // and check it here to enforce bearer tokens regardless of token store state.
-        // ----------------------------------------------------------------
         if (bearerToken && oauthHandler.hasTokenStore()) {
-          const sessionId = oauthHandler.lookupToken(bearerToken);
-          if (!sessionId) {
-            // Token provided but invalid - reject
+          const oauthSessionId = oauthHandler.lookupToken(bearerToken);
+          if (!oauthSessionId) {
             res.writeHead(401, { "Content-Type": "application/json" });
             res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Invalid or expired bearer token" }, id: null }));
             return;
           }
         }
 
+        const mcpSessionId = typeof req.headers["mcp-session-id"] === "string"
+          ? req.headers["mcp-session-id"]
+          : undefined;
+
+        // ── GET: SSE streaming for existing session ──
+        if (req.method === "GET") {
+          if (mcpSessionId && sessions.has(mcpSessionId)) {
+            const session = sessions.get(mcpSessionId);
+            session.lastUsed = Date.now();
+            session.transport.handleRequest(req, res).catch((err) => {
+              debugLog("[ctxce] SSE stream error: " + String(err));
+            });
+          } else {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Bad Request: No valid session for SSE" }, id: null }));
+          }
+          return;
+        }
+
+        // ── DELETE: terminate session ──
+        if (req.method === "DELETE") {
+          if (mcpSessionId && sessions.has(mcpSessionId)) {
+            const session = sessions.get(mcpSessionId);
+            sessions.delete(mcpSessionId);
+            session.transport.close().catch(() => {});
+            session.server.close().catch(() => {});
+            debugLog(`[ctxce] Session terminated by client: ${mcpSessionId}`);
+          }
+          res.writeHead(200).end();
+          return;
+        }
+
+        // ── POST: MCP JSON-RPC requests ──
         if (req.method !== "POST") {
           res.statusCode = 405;
           res.setHeader("Content-Type", "application/json");
-          res.end(
-            JSON.stringify({
-              jsonrpc: "2.0",
-              error: { code: -32000, message: "Method not allowed" },
-              id: null,
-            }),
-          );
+          res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed" }, id: null }));
           return;
         }
 
@@ -1033,13 +1085,7 @@ export async function runHttpMcpServer(options) {
             req.destroy();
             res.statusCode = 413;
             res.setHeader("Content-Type", "application/json");
-            res.end(
-              JSON.stringify({
-                jsonrpc: "2.0",
-                error: { code: -32000, message: "Request body too large" },
-                id: null,
-              }),
-            );
+            res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Request body too large" }, id: null }));
           }
         });
         req.on("end", async () => {
@@ -1051,30 +1097,50 @@ export async function runHttpMcpServer(options) {
             debugLog("[ctxce] Failed to parse HTTP MCP request body: " + String(err));
             res.statusCode = 400;
             res.setHeader("Content-Type", "application/json");
-            res.end(
-              JSON.stringify({
-                jsonrpc: "2.0",
-                error: { code: -32700, message: "Invalid JSON" },
-                id: null,
-              }),
-            );
+            res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32700, message: "Invalid JSON" }, id: null }));
             return;
           }
 
           try {
+            // ── Route to existing session ──
+            if (mcpSessionId && sessions.has(mcpSessionId)) {
+              const session = sessions.get(mcpSessionId);
+              session.lastUsed = Date.now();
+              await session.transport.handleRequest(req, res, parsed);
+              return;
+            }
+
+            // ── Unknown session ID (expired or invalid) ──
+            if (mcpSessionId) {
+              res.writeHead(404, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Session not found. Client must re-initialize." }, id: null }));
+              return;
+            }
+
+            // ── New session (no session ID = first request / initialize) ──
+            evictOldestSession();
+
+            const server = await createBridgeServer(options);
+            const transport = new StreamableHTTPServerTransport({
+              sessionIdGenerator: () => randomUUID(),
+              onsessioninitialized: (newSessionId) => {
+                debugLog(`[ctxce] New MCP session: ${newSessionId} (active: ${sessions.size + 1})`);
+                sessions.set(newSessionId, { server, transport, lastUsed: Date.now() });
+              },
+              onsessionclosed: (closedSessionId) => {
+                debugLog(`[ctxce] MCP session closed by transport: ${closedSessionId}`);
+                sessions.delete(closedSessionId);
+                server.close().catch(() => {});
+              },
+            });
+            await server.connect(transport);
             await transport.handleRequest(req, res, parsed);
           } catch (err) {
             debugLog("[ctxce] Error handling HTTP MCP request: " + String(err));
             if (!res.headersSent) {
               res.statusCode = 500;
               res.setHeader("Content-Type", "application/json");
-              res.end(
-                JSON.stringify({
-                  jsonrpc: "2.0",
-                  error: { code: -32603, message: "Internal server error" },
-                  id: null,
-                }),
-              );
+              res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "Internal server error" }, id: null }));
             }
           }
         });
@@ -1084,39 +1150,34 @@ export async function runHttpMcpServer(options) {
       // 404 for everything else
       res.statusCode = 404;
       res.setHeader("Content-Type", "application/json");
-      res.end(
-        JSON.stringify({
-          jsonrpc: "2.0",
-          error: { code: -32000, message: "Not found" },
-          id: null,
-        }),
-      );
+      res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Not found" }, id: null }));
     } catch (err) {
       debugLog("[ctxce] Unexpected error in HTTP MCP server: " + String(err));
       if (!res.headersSent) {
         res.statusCode = 500;
         res.setHeader("Content-Type", "application/json");
-        res.end(
-          JSON.stringify({
-            jsonrpc: "2.0",
-            error: { code: -32603, message: "Internal server error" },
-            id: null,
-          }),
-        );
+        res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "Internal server error" }, id: null }));
       }
     }
   });
 
   // Bind to 127.0.0.1 only (localhost) for local-only OAuth security
   httpServer.listen(port, '127.0.0.1', () => {
-    debugLog(`[ctxce] HTTP MCP bridge listening on 127.0.0.1:${port}`);
+    debugLog(`[ctxce] HTTP MCP bridge listening on 127.0.0.1:${port} (multi-session enabled)`);
   });
 
   let shuttingDown = false;
   const shutdown = (signal) => {
     if (shuttingDown) return;
     shuttingDown = true;
-    debugLog(`[ctxce] Received ${signal}; closing HTTP server (waiting for in-flight requests).`);
+    debugLog(`[ctxce] Received ${signal}; closing HTTP server and ${sessions.size} active session(s).`);
+    clearInterval(cleanupInterval);
+    // Close all active sessions
+    for (const [, session] of sessions) {
+      session.transport.close().catch(() => {});
+      session.server.close().catch(() => {});
+    }
+    sessions.clear();
     httpServer.close(() => {
       debugLog("[ctxce] HTTP server closed.");
       process.exit(0);

package/src/oauthHandler.js

@@ -277,7 +277,11 @@ export function getLoginPage(redirectUri, clientId, state, codeChallenge, codeCh
         throw new Error('No redirect URL');
       }
     } catch (err) {
-      result.innerHTML = '<p class="error">' + err.message + '</p>';
+      result.textContent = '';
+      var p = document.createElement('p');
+      p.className = 'error';
+      p.textContent = err.message;
+      result.appendChild(p);
     }
   });
   </script>