@context-engine-bridge/context-engine-mcp-bridge 0.0.17 → 0.0.19

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.17",
+  "version": "0.0.19",
   "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/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";
@@ -175,6 +176,36 @@ function isAuthRejectionError(error) {
   }
 }
 
+/**
+ * Format an auth rejection error with actionable information for users.
+ * Includes the backend URL and a hint to sign in via VS Code command palette.
+ */
+function formatAuthRejectionError(originalError, backendUrl) {
+  const originalMsg =
+    (originalError && typeof originalError.message === "string" && originalError.message) ||
+    (typeof originalError === "string" ? originalError : String(originalError || "Unknown auth error"));
+
+  const serverInfo = backendUrl ? ` (server: ${backendUrl})` : "";
+  const hint = "Run 'Context Engine: Sign In' from the VS Code command palette to authenticate.";
+
+  return `Authentication failed${serverInfo}: ${originalMsg}. ${hint}`;
+}
+
+/**
+ * Emit a special log line that the VS Code extension can detect to show a notification toast.
+ * Format: [ctxce:auth-error] JSON payload
+ */
+function emitAuthErrorNotification(backendUrl, originalError) {
+  const payload = {
+    type: "auth_rejection",
+    backend: backendUrl || "unknown",
+    message: String(originalError?.message || originalError || "Authentication failed"),
+    hint: "Run 'Context Engine: Sign In' from the VS Code command palette",
+  };
+  // This special prefix allows the VS Code extension to detect auth errors in stderr
+  debugLog(`[ctxce:auth-error] ${JSON.stringify(payload)}`);
+}
+
 function getBridgeRetryAttempts() {
   try {
     const raw = process.env.CTXCE_TOOL_RETRY_ATTEMPTS;
@@ -520,8 +551,21 @@ async function createBridgeServer(options) {
     sessionId = resolveSessionId();
   }
 
+  // Only fall back to deterministic session if auth is not configured
+  // If auth backend is configured but no session found, log warning instead of creating deterministic session
   if (!sessionId) {
-    sessionId = `ctxce-${Buffer.from(workspace).toString("hex").slice(0, 24)}`;
+    if (authBackendUrl) {
+      // Auth is configured but no valid session - don't use deterministic fallback
+      debugLog(`[ctxce] WARNING: Auth backend configured (${authBackendUrl}) but no valid session found.`);
+      debugLog("[ctxce] To authenticate, run 'Context Engine: Sign In' from the VS Code command palette, or run `ctxce auth login` from the terminal.");
+      debugLog("[ctxce] Continuing with deterministic session for backward compatibility, but this may fail if backend requires auth.");
+      // Emit notification for VS Code extension
+      emitAuthErrorNotification(authBackendUrl, { message: "No valid session found - authentication required" });
+      sessionId = `ctxce-${Buffer.from(workspace).toString("hex").slice(0, 24)}`;
+    } else {
+      // No auth configured - use deterministic session for local-only operation
+      sessionId = `ctxce-${Buffer.from(workspace).toString("hex").slice(0, 24)}`;
+    }
   }
 
   // Best-effort: inform the indexer of default collection and session.
@@ -531,6 +575,17 @@ async function createBridgeServer(options) {
     defaultsPayload.collection = defaultCollection;
   }
 
+  // Include org context from auth entry if available (for org-scoped collection isolation)
+  try {
+    const authEntry = backendHint ? loadAuthEntry(backendHint) : null;
+    if (authEntry && authEntry.org_id) {
+      defaultsPayload.org_id = authEntry.org_id;
+      defaultsPayload.org_slug = authEntry.org_slug;
+    }
+  } catch {
+    // ignore auth entry lookup failures
+  }
+
   const repoName = detectRepoName(workspace, config);
 
   try {
@@ -653,7 +708,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",
@@ -782,10 +837,13 @@ async function createBridgeServer(options) {
 
         // Backend auth rejection (mcp_auth.py ValidationError) - expire local auth
         if (isAuthRejectionError(err)) {
+          const serverUrl = backendHint || uploadServiceUrl || "unknown server";
           debugLog(
-            "[ctxce] tools/call: backend auth rejection; marking local session as expired: " +
+            `[ctxce] tools/call: backend auth rejection from ${serverUrl}; marking local session as expired: ` +
             String(err),
           );
+          // Emit special notification for VS Code extension to detect and show toast
+          emitAuthErrorNotification(serverUrl, err);
           if (backendHint) {
             try {
               const entry = loadAuthEntry(backendHint);
@@ -796,6 +854,13 @@ async function createBridgeServer(options) {
               // ignore failures
             }
           }
+          // Enhance error with actionable message before throwing
+          if (!isTransientToolError(err) || attempt === maxAttempts - 1) {
+            const enhancedMessage = formatAuthRejectionError(err, serverUrl);
+            const enhancedError = new Error(enhancedMessage);
+            enhancedError.cause = err;
+            throw enhancedError;
+          }
         }
 
         if (!isTransientToolError(err) || attempt === maxAttempts - 1) {
@@ -844,17 +909,73 @@ 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 {
+    await createBridgeServer(options);
+    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.
@@ -905,24 +1026,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 token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+        const bearerToken = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : null;
+        if (bearerToken && oauthHandler.hasTokenStore()) {
+          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;
+        }
 
-        // TODO: Validate token and inject session
-        // For now, allow unauthenticated (backward compatible)
+        // ── 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;
         }
 
@@ -937,13 +1091,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 () => {
@@ -955,30 +1103,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 }));
             }
           }
         });
@@ -988,39 +1156,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

@@ -534,7 +534,7 @@ export function handleOAuthStoreSession(req, res) {
 export function handleOAuthToken(req, res) {
   let body = "";
   req.on("data", (chunk) => { body += chunk; });
-  req.on("end", () => {
+  req.on("end", async () => {
     try {
       const data = new URLSearchParams(body);
       const code = data.get("code");
@@ -585,8 +585,24 @@ export function handleOAuthToken(req, res) {
         return;
       }
 
-      // TODO: Validate PKCE code_verifier against code_challenge
-      // For now, skip validation (local bridge, trusted)
+      // TODO: PKCE validation - disabled for now, no clients implement it yet
+      // if (pendingData.codeChallenge && pendingData.codeChallengeMethod === "S256") {
+      //   const codeVerifier = data.get("code_verifier");
+      //   if (!codeVerifier) {
+      //     pendingCodes.delete(code);
+      //     res.statusCode = 400;
+      //     res.end(JSON.stringify({ error: "invalid_grant", error_description: "code_verifier required for PKCE" }));
+      //     return;
+      //   }
+      //   const crypto = await import("node:crypto");
+      //   const expectedChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");
+      //   if (expectedChallenge !== pendingData.codeChallenge) {
+      //     pendingCodes.delete(code);
+      //     res.statusCode = 400;
+      //     res.end(JSON.stringify({ error: "invalid_grant", error_description: "code_verifier validation failed" }));
+      //     return;
+      //   }
+      // }
 
       // Clean up expired tokens periodically to prevent unbounded growth
       cleanupExpiredTokens();
@@ -651,4 +667,31 @@ export function isOAuthEndpoint(pathname) {
   );
 }
 
+/**
+ * Check if the token store has any entries (indicates auth is active)
+ * @returns {boolean}
+ */
+export function hasTokenStore() {
+  return tokenStore.size > 0;
+}
+
+/**
+ * Look up a bearer token and return the associated session ID
+ * @param {string} token - Bearer token to validate
+ * @returns {string|null} - Session ID if valid, null otherwise
+ */
+export function lookupToken(token) {
+  const entry = tokenStore.get(token);
+  if (!entry) return null;
+
+  // Check expiration
+  const tokenAge = Date.now() - entry.createdAt;
+  if (tokenAge > TOKEN_EXPIRY_MS) {
+    tokenStore.delete(token);
+    return null;
+  }
+
+  return entry.sessionId || null;
+}
+
 startCleanupInterval();

package/AGENTS.md

@@ -1,18 +0,0 @@
-<!-- Parent: ../AGENTS.md -->
-# MCP Bridge CLI (ctxce)
-
-Node package that exposes indexer+memory as a single MCP server (stdio + HTTP). Optional OAuth/PKCE.
-
-## WHERE TO LOOK
-
-| Task | Location | Notes |
-|------|----------|-------|
-| CLI entry | `ctx-mcp-bridge/bin/ctxce.js` | wrapper -> src/cli |
-| CLI logic | `ctx-mcp-bridge/src/cli.js` | command parsing |
-| MCP proxy | `ctx-mcp-bridge/src/mcpServer.js` | forwards tools |
-| OAuth/PKCE | `ctx-mcp-bridge/src/oauthHandler.js` | auth flow |
-| Path mapping | `ctx-mcp-bridge/src/resultPathMapping.js` | local <-> remote |
-
-## KNOWN TODO
-
-- PKCE verifier validation is still TODO in `ctx-mcp-bridge/src/oauthHandler.js`.