@context-engine-bridge/context-engine-mcp-bridge 0.0.14 → 0.0.15

package/AGENTS.md

@@ -1,319 +1,18 @@
 <!-- Parent: ../AGENTS.md -->
-# Context-Engine MCP Bridge
+# MCP Bridge CLI (ctxce)
 
-## Purpose
+Node package that exposes indexer+memory as a single MCP server (stdio + HTTP). Optional OAuth/PKCE.
 
-TypeScript/Node.js MCP bridge server that acts as a proxy between MCP clients (Claude Code, Cursor, Windsurf) and the Context Engine backend. Provides SSE/HTTP transport, OAuth 2.0 authentication, and transparent path mapping between local and container filesystems.
+## WHERE TO LOOK
 
-## Key Responsibilities
+| 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 |
 
-1. **MCP Protocol Translation**: Converts stdio/HTTP requests from MCP clients to HTTP requests for the Python backend
-2. **Authentication**: Manages OAuth 2.0 flows and session persistence for multi-user environments
-3. **Path Mapping**: Translates container paths (`/work/repo/...`) to local workspace paths for client consumption
-4. **Session Management**: Maintains per-connection session state and default collection/workspace settings
-5. **Tool Routing**: Routes `memory.*` tools to memory server, other tools to indexer server
+## KNOWN TODO
 
-## Architecture
-
-```
-┌────────────────────────────────────────────────────────┐
-│  MCP Client (Claude Code, etc.)                        │
-└──────────────┬─────────────────────────────────────────┘
-               │ stdio or HTTP
-┌──────────────▼─────────────────────────────────────────┐
-│  ctx-mcp-bridge (src/mcpServer.js)                     │
-│  ┌─────────────────────────────────────────────────┐   │
-│  │  MCP SDK Server (stdio/HTTP transport)          │   │
-│  │  - tools/list → merge indexer + memory tools    │   │
-│  │  - tools/call → route to appropriate backend    │   │
-│  └────────────────┬────────────────────────────────┘   │
-│                   │                                     │
-│  ┌────────────────▼─────────────┐  ┌─────────────────┐ │
-│  │  MCP HTTP Client (indexer)   │  │  HTTP Client    │ │
-│  │  http://localhost:8003/mcp   │  │  (memory)       │ │
-│  └──────────────────────────────┘  └─────────────────┘ │
-└────────────────────────────────────────────────────────┘
-               │
-┌──────────────▼─────────────────────────────────────────┐
-│  Python Backend (indexer_mcp.py, memory_mcp.py)        │
-└────────────────────────────────────────────────────────┘
-```
-
-## Core Files
-
-### src/mcpServer.js (800+ lines)
-
-Main MCP server implementation. Key functions:
-
-- `createBridgeServer()`: Initializes MCP server with dual backend clients
-- `initializeRemoteClients()`: Connects to indexer and memory servers via StreamableHTTPClientTransport
-- `ListToolsRequestSchema` handler: Merges tools from both backends, deduplicates
-- `CallToolRequestSchema` handler: Routes tools, injects session ID, handles retries
-- `selectClientForTool()`: Routes `memory.*` tools to memory server, others to indexer
-- `fetchBridgeCollectionState()`: Queries `/bridge/state` for active collection overrides
-- Session retry logic: Detects `"No valid session ID"` errors and reinitializes clients
-
-**Environment Variables**:
-- `CTXCE_INDEXER_URL`: Default `http://localhost:8003/mcp`
-- `CTXCE_MEMORY_URL`: Default `http://localhost:8002/mcp` (optional)
-- `CTXCE_SESSION_ID`: Explicit session ID (overrides derived session)
-- `CTXCE_TOOL_TIMEOUT_MSEC`: Tool call timeout (default 300000 = 5 min)
-- `CTXCE_TOOL_RETRY_ATTEMPTS`: Retry count for transient errors (default 2)
-- `CTXCE_BRIDGE_STATE_TOKEN`: Auth token for `/bridge/state` endpoint
-
-### src/oauthHandler.js (586 lines)
-
-OAuth 2.0 implementation (RFC9728 Protected Resource Metadata + RFC7591 Dynamic Client Registration):
-
-- **Endpoints**:
-  - `GET /.well-known/oauth-authorization-server`: OAuth metadata
-  - `POST /oauth/register`: Dynamic client registration (auto-approve local clients)
-  - `GET /oauth/authorize`: Authorization flow (shows login page or auto-approves if session exists)
-  - `POST /oauth/store-session`: Stores session from login page, returns auth code
-  - `POST /oauth/token`: Exchanges auth code for bearer token
-
-- **Security**:
-  - PKCE code_challenge validation (TODO: currently skipped for local bridge)
-  - Client ID and redirect URI validation against registered clients
-  - Origin/Referer header validation (localhost-only for `/oauth/store-session`)
-  - 10-minute auth code expiry, 24-hour token expiry
-  - Binds to `127.0.0.1` only (no remote access)
-
-- **Storage**: In-memory `tokenStore`, `pendingCodes`, `registeredClients` (not persisted across restarts)
-
-### src/resultPathMapping.js (507 lines)
-
-Bidirectional path translation between container and client filesystems:
-
-**Request Path Mapping** (`maybeRemapToolArgs`):
-- Detects `/work/<repo>/...` container paths in tool args
-- Extracts repo-relative POSIX path (e.g., `/work/myrepo/src/main.py` → `src/main.py`)
-- Handles `path`, `under`, `root`, `subdir`, `path_glob`, `not_glob` parameters
-- Recursively processes nested objects and arrays
-
-**Response Path Mapping** (`maybeRemapToolResult`):
-- Parses JSON from `content[].text` or `structuredContent`
-- For each hit object:
-  - Computes `rel_path` from container path
-  - Joins `rel_path` to workspace root to produce `client_path`
-  - Prefers existing `host_path` if it exists and is within workspace
-  - Optionally overrides `hit.path` with `client_path` (default: enabled via `CTXCE_BRIDGE_OVERRIDE_PATH=1`)
-- Remaps `related_paths` arrays to absolute local paths
-
-**Environment Variables**:
-- `CTXCE_BRIDGE_MAP_PATHS=1`: Enable/disable path mapping (default: enabled)
-- `CTXCE_BRIDGE_OVERRIDE_PATH=1`: Replace `path` field with `client_path` (default: enabled)
-- `CTXCE_BRIDGE_CLIENT_PATH_STRICT=0`: Use `workspace_join` always vs preferring `host_path`
-- `CTXCE_BRIDGE_PATH_DIAGNOSTICS=0`: Add debug fields `client_path_source`, `client_path_joined`
-
-### src/authConfig.js (not shown, ~100 lines)
-
-Auth entry persistence to `~/.ctxce/auth.json`:
-
-- `loadAuthEntry(backendUrl)`: Load session for specific backend
-- `saveAuthEntry(backendUrl, {sessionId, userId, expiresAt})`: Persist session
-- `deleteAuthEntry(backendUrl)`: Remove session
-- `loadAnyAuthEntry()`: Find any stored session (fallback)
-
-### src/authCli.js (285 lines)
-
-CLI commands for auth management:
-
-- `ctxce auth login`: Calls `/auth/login` or `/auth/login/password`, saves session
-- `ctxce auth status`: Checks stored session, prints human or JSON output
-- `ctxce auth logout`: Deletes stored session
-
-**Fallback logic**: If `--backend-url` omitted, tries stored sessions, then `CTXCE_UPLOAD_ENDPOINT`, then `http://localhost:8004`
-
-### src/cli.js (124 lines)
-
-Main CLI dispatcher:
-
-- `ctxce mcp-serve`: Starts stdio MCP bridge (default mode for MCP clients)
-- `ctxce mcp-http-serve`: Starts HTTP MCP bridge on port 30810 (used by VS Code extension)
-- `ctxce auth <subcmd>`: Delegates to `authCli.js`
-
-**Flags**:
-- `--workspace` / `--path`: Workspace root (default: cwd)
-- `--indexer-url`: Override indexer URL
-- `--memory-url`: Override memory URL (or omit to disable)
-- `--port`: HTTP port (for `mcp-http-serve`)
-
-### bin/ctxce.js (2 lines)
-
-Shebang wrapper: `#!/usr/bin/env node`, imports `runCli()` from `src/cli.js`
-
-## Key Features
-
-### 1. Tool Routing
-
-```javascript
-function selectClientForTool(name, indexerClient, memoryClient) {
-  const lowered = name.toLowerCase();
-  if (memoryClient && lowered.includes("memory")) {
-    return memoryClient;
-  }
-  return indexerClient;
-}
-```
-
-Tools starting with `memory.` or containing "memory" route to memory server; all others route to indexer.
-
-### 2. Session Injection
-
-Bridge injects `session` parameter into all tool calls:
-1. Explicit `CTXCE_SESSION_ID` env var
-2. Stored auth session from `~/.ctxce/auth.json`
-3. Fallback: `ctxce-<workspace-hash>` (deterministic per workspace)
-
-### 3. Retry Logic
-
-Automatic retry on transient errors (timeouts, network errors, 502/503/504):
-- Default: 2 attempts with 200ms delay
-- Detects session errors (`"No valid session ID"`) and reinitializes clients
-- Configurable via `CTXCE_TOOL_RETRY_ATTEMPTS` and `CTXCE_TOOL_RETRY_DELAY_MSEC`
-
-### 4. Collection State Override
-
-Queries `/bridge/state?collection=...&repo_name=...` on startup to resolve active collection:
-- Prefers `serving_collection` from backend over `ctx_config.json`
-- Falls back to `default_collection` from `ctx_config.json`
-- Logs active collection for transparency
-
-### 5. Path Mapping Examples
-
-**Request**: Client sends `path: "/Users/dev/myrepo/src/main.py"`
-→ Bridge normalizes to `src/main.py` (repo-relative)
-→ Backend receives `path: "src/main.py"`
-
-**Response**: Backend returns `path: "/work/myrepo/src/main.py"`, `container_path: "/work/myrepo/src/main.py"`
-→ Bridge computes `rel_path: "src/main.py"`, `client_path: "/Users/dev/myrepo/src/main.py"`
-→ Client receives `path: "/Users/dev/myrepo/src/main.py"` (if `CTXCE_BRIDGE_OVERRIDE_PATH=1`)
-
-## Usage Patterns
-
-### Stdio Mode (for MCP clients)
-
-```bash
-ctxce mcp-serve --workspace /path/to/repo
-```
-
-Add to Claude Desktop `claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "context-engine": {
-      "command": "ctxce",
-      "args": ["mcp-serve", "--workspace", "/path/to/repo"]
-    }
-  }
-}
-```
-
-### HTTP Mode (for VS Code extension)
-
-```bash
-ctxce mcp-http-serve --workspace /path/to/repo --port 30810
-```
-
-Extension uses HTTP transport to avoid stdio buffering issues.
-
-### Authentication Flow
-
-1. User initiates OAuth via browser: `GET /oauth/authorize?client_id=...&redirect_uri=...&code_challenge=...`
-2. Bridge checks for existing session in `~/.ctxce/auth.json`
-3. If no session, shows login page with backend URL input
-4. User submits credentials, page POSTs to backend `/auth/login`
-5. Backend returns `session_id`, page POSTs to `/oauth/store-session`
-6. Bridge saves session to `~/.ctxce/auth.json`, generates auth code, redirects with code
-7. Client exchanges code for bearer token via `/oauth/token`
-8. Client includes `Authorization: Bearer <token>` in subsequent MCP requests
-
-## Testing
-
-No automated tests currently. Manual testing via:
-
-1. Start backend: `docker-compose up -d`
-2. Run bridge: `ctxce mcp-http-serve --workspace /path/to/repo`
-3. Test OAuth flow: Open `http://127.0.0.1:30810/oauth/authorize?client_id=test&redirect_uri=http://localhost/callback&code_challenge=...`
-4. Test MCP tools: Use MCP client (Claude Code) or `curl` to POST tool calls to `/mcp`
-
-## Debugging
-
-Set `CTXCE_DEBUG_LOG=/tmp/ctxce.log` to log all bridge activity:
-```bash
-export CTXCE_DEBUG_LOG=/tmp/ctxce.log
-ctxce mcp-serve --workspace /path/to/repo
-tail -f /tmp/ctxce.log
-```
-
-Common issues:
-- **Session errors**: Check `~/.ctxce/auth.json` has valid `sessionId`
-- **Path mapping issues**: Set `CTXCE_BRIDGE_PATH_DIAGNOSTICS=1` to see `client_path_source`
-- **Tool routing issues**: Check tool name includes `"memory"` for memory server routing
-- **Timeout errors**: Increase `CTXCE_TOOL_TIMEOUT_MSEC` for slow queries
-
-## Integration Points
-
-### Upstream (MCP Clients)
-- **Claude Code**: Uses stdio transport via `claude_desktop_config.json`
-- **Cursor**: Supports MCP via settings
-- **VS Code Extension**: Uses HTTP transport on port 30810
-
-### Downstream (Python Backend)
-- **indexer_mcp.py**: Provides 30+ search/graph tools on port 8003
-- **memory_mcp.py**: Provides memory storage tools on port 8002
-- **upload_service.py**: Auth backend on port 8004 (`/auth/login`, `/bridge/state`)
-
-## Security Considerations
-
-1. **Local-only binding**: HTTP server binds to `127.0.0.1` only (no remote access)
-2. **Origin validation**: `/oauth/store-session` requires `Origin` or `Referer` header from localhost
-3. **Client validation**: OAuth endpoints validate `client_id` and `redirect_uri` against registered clients
-4. **Session persistence**: `~/.ctxce/auth.json` stores sessions (file permissions: 0600)
-5. **Token expiry**: Auth codes expire in 10 min, bearer tokens in 24 hours
-6. **PKCE**: Code challenge method `S256` supported (validation TODO)
-
-## Configuration Files
-
-### ~/.ctxce/auth.json
-
-```json
-{
-  "http://localhost:8004": {
-    "sessionId": "sess_abc123",
-    "userId": "user-456",
-    "expiresAt": 1704974400
-  }
-}
-```
-
-### ctx_config.json (in workspace)
-
-```json
-{
-  "default_collection": "myrepo-abc123",
-  "default_mode": "refrag",
-  "default_under": "src/",
-  "repo_name": "myrepo"
-}
-```
-
-Bridge reads this on startup and sends to backend via `set_session_defaults`.
-
-## Future Enhancements
-
-1. **PKCE validation**: Implement `code_verifier` hash validation in `/oauth/token`
-2. **Persistent storage**: Migrate OAuth state to Redis/SQLite (currently in-memory)
-3. **Token refresh**: Support `refresh_token` grant type for long-lived sessions
-4. **Multi-workspace**: Allow clients to switch workspaces without restarting bridge
-5. **Rate limiting**: Add per-client rate limits for tool calls
-6. **Metrics**: Expose Prometheus metrics for tool call latency, error rates
-
-## Related Documentation
-
-- [MCP SDK Documentation](https://modelcontextprotocol.io/docs)
-- [OAuth 2.0 RFC9728](https://www.rfc-editor.org/rfc/rfc9728.html) (Protected Resource Metadata)
-- [OAuth 2.0 RFC7591](https://www.rfc-editor.org/rfc/rfc7591.html) (Dynamic Client Registration)
-- [Context Engine Python Backend](../scripts/AGENTS.md)
-- [VS Code Extension Integration](../README.md#vs-code-extension)
+- PKCE verifier validation is still TODO in `ctx-mcp-bridge/src/oauthHandler.js`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-engine-bridge/context-engine-mcp-bridge",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "Context Engine MCP bridge (http/stdio proxy combining indexer + memory servers)",
   "bin": {
     "ctxce": "bin/ctxce.js",

package/src/authConfig.js

@@ -11,7 +11,7 @@ function getConfigPath() {
   return path.join(dir, CONFIG_BASENAME);
 }
 
-function readConfig() {
+export function readConfig() {
   try {
     const cfgPath = getConfigPath();
     const raw = fs.readFileSync(cfgPath, "utf8");

package/src/mcpServer.js

@@ -9,7 +9,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { loadAnyAuthEntry, loadAuthEntry } from "./authConfig.js";
+import { loadAnyAuthEntry, loadAuthEntry, readConfig, saveAuthEntry } from "./authConfig.js";
 import { maybeRemapToolArgs, maybeRemapToolResult } from "./resultPathMapping.js";
 import * as oauthHandler from "./oauthHandler.js";
 
@@ -63,11 +63,7 @@ async function listMemoryTools(client) {
     return [];
   }
   try {
-    const remote = await withTimeout(
-      client.listTools(),
-      5000,
-      "memory tools/list",
-    );
+    const remote = await client.listTools();
     return Array.isArray(remote?.tools) ? remote.tools.slice() : [];
   } catch (err) {
     debugLog("[ctxce] Error calling memory tools/list: " + String(err));
@@ -113,15 +109,15 @@ function getBridgeToolTimeoutMs() {
   try {
     const raw = process.env.CTXCE_TOOL_TIMEOUT_MSEC;
     if (!raw) {
-      return 300000;
+      return 600000; // 10 minutes default for remote operations
     }
     const parsed = Number.parseInt(String(raw), 10);
     if (!Number.isFinite(parsed) || parsed <= 0) {
-      return 300000;
+      return 600000;
     }
     return parsed;
   } catch {
-    return 300000;
+    return 600000;
   }
 }
 
@@ -130,7 +126,7 @@ function selectClientForTool(name, indexerClient, memoryClient) {
     return indexerClient;
   }
   const lowered = name.toLowerCase();
-  if (memoryClient && (lowered.startsWith("memory.") || lowered.startsWith("mcp_memory_") || lowered.includes("memory"))) {
+  if (memoryClient && (lowered.startsWith("memory.") || lowered.startsWith("mcp_memory_"))) {
     return memoryClient;
   }
   return indexerClient;
@@ -155,11 +151,34 @@ function isSessionError(error) {
   }
 }
 
+/**
+ * Detect actual backend auth rejection (from mcp_auth.py ValidationError).
+ * These indicate the session is truly invalid on the backend, not just
+ * an MCP SDK transport issue that can be fixed by reinit.
+ */
+function isAuthRejectionError(error) {
+  try {
+    const msg =
+      (error && typeof error.message === "string" && error.message) ||
+      (typeof error === "string" ? error : String(error || ""));
+    if (!msg) {
+      return false;
+    }
+    return (
+      msg.includes("Invalid or expired session") ||
+      msg.includes("Missing session for authorized operation") ||
+      msg.includes("Not authenticated")
+    );
+  } catch {
+    return false;
+  }
+}
+
 function getBridgeRetryAttempts() {
   try {
     const raw = process.env.CTXCE_TOOL_RETRY_ATTEMPTS;
     if (!raw) {
-      return 2;
+      return 3; // 3 attempts for better reliability on remote
     }
     const parsed = Number.parseInt(String(raw), 10);
     if (!Number.isFinite(parsed) || parsed <= 0) {
@@ -167,7 +186,7 @@ function getBridgeRetryAttempts() {
     }
     return parsed;
   } catch {
-    return 2;
+    return 3;
   }
 }
 
@@ -175,7 +194,7 @@ function getBridgeRetryDelayMs() {
   try {
     const raw = process.env.CTXCE_TOOL_RETRY_DELAY_MSEC;
     if (!raw) {
-      return 200;
+      return 1000; // 1 second delay between retries for remote
     }
     const parsed = Number.parseInt(String(raw), 10);
     if (!Number.isFinite(parsed) || parsed < 0) {
@@ -183,7 +202,7 @@ function getBridgeRetryDelayMs() {
     }
     return parsed;
   } catch {
-    return 200;
+    return 1000;
   }
 }
 
@@ -255,6 +274,15 @@ const ADMIN_SESSION_COOKIE_NAME = "ctxce_session";
 const SLUGGED_REPO_RE = /.+-[0-9a-f]{16}(?:_old)?$/i;
 const BRIDGE_STATE_TOKEN = (process.env.CTXCE_BRIDGE_STATE_TOKEN || "").trim();
 
+function getHostname(candidate) {
+  try {
+    const url = new URL(candidate);
+    return url.hostname;
+  } catch {
+    return "";
+  }
+}
+
 function normalizeBackendUrl(candidate) {
   const trimmed = (candidate || "").trim();
   if (!trimmed) {
@@ -271,11 +299,35 @@ function normalizeBackendUrl(candidate) {
   return trimmed.replace(/\/+$/, "");
 }
 
-function resolveAuthBackendContext() {
+function resolveAuthBackendContext(indexerUrl, memoryUrl) {
   const envBackend = normalizeBackendUrl(process.env.CTXCE_AUTH_BACKEND_URL || "");
   if (envBackend) {
     return { backendUrl: envBackend, source: "CTXCE_AUTH_BACKEND_URL" };
   }
+
+  // If no env override, try to find a saved session.
+  // We prefer one that matches the host of indexer or memory URL if they look like backend roots.
+  const targetHosts = new Set();
+  const ih = getHostname(indexerUrl);
+  if (ih) {
+    targetHosts.add(ih);
+  }
+  const mh = getHostname(memoryUrl);
+  if (mh) {
+    targetHosts.add(mh);
+  }
+
+  if (targetHosts.size > 0) {
+    const all = readConfig();
+    const backends = Object.keys(all);
+    for (const backendUrl of backends) {
+      const bh = getHostname(backendUrl);
+      if (bh && targetHosts.has(bh)) {
+        return { backendUrl, source: "auth_entry_host_match" };
+      }
+    }
+  }
+
   try {
     const any = loadAnyAuthEntry();
     const stored = normalizeBackendUrl(any?.backendUrl || "");
@@ -288,32 +340,22 @@ function resolveAuthBackendContext() {
   return { backendUrl: "", source: "" };
 }
 
-const {
-  backendUrl: AUTH_BACKEND_URL,
-  source: AUTH_BACKEND_SOURCE,
-} = resolveAuthBackendContext();
-const UPLOAD_SERVICE_URL = AUTH_BACKEND_URL;
-const UPLOAD_AUTH_BACKEND = AUTH_BACKEND_URL;
-
-if (UPLOAD_SERVICE_URL) {
-  debugLog(`[ctxce] Upload/auth backend resolved from ${AUTH_BACKEND_SOURCE}: ${UPLOAD_SERVICE_URL}`);
-} else {
-  debugLog("[ctxce] No auth backend detected; bridge/state overrides disabled.");
-}
-
 async function fetchBridgeCollectionState({
   workspace,
   collection,
   sessionId,
   repoName,
   bridgeStateToken,
+  backendHint,
+  uploadServiceUrl,
 }) {
   try {
-    if (!UPLOAD_SERVICE_URL) {
+    if (!uploadServiceUrl) {
       debugLog("[ctxce] Skipping bridge/state fetch: no upload endpoint configured.");
       return null;
     }
-    const url = new URL("/bridge/state", UPLOAD_SERVICE_URL);
+    const url = new URL("/bridge/state", uploadServiceUrl);
+    // ...
     if (collection && collection.trim()) {
       url.searchParams.set("collection", collection.trim());
     } else if (workspace && workspace.trim()) {
@@ -341,8 +383,18 @@ 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, falling back to ctx_config defaults.`,
+          `[ctxce] /bridge/state responded ${resp.status}; missing or invalid token/session, marking local session as expired.`,
         );
+        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}`);
@@ -389,9 +441,23 @@ async function createBridgeServer(options) {
   // future this can be made user-aware (e.g. from auth), but for now we
   // keep it deterministic per workspace to help the indexer reuse
   // session-scoped defaults.
+  const {
+    backendUrl: authBackendUrl,
+    source: authBackendSource,
+  } = resolveAuthBackendContext(indexerUrl, memoryUrl);
+
+  const uploadServiceUrl = authBackendUrl;
+  const uploadAuthBackend = authBackendUrl;
+
+  if (uploadServiceUrl) {
+    debugLog(`[ctxce] Upload/auth backend resolved from ${authBackendSource}: ${uploadServiceUrl}`);
+  } else {
+    debugLog("[ctxce] No auth backend detected; bridge/state overrides disabled.");
+  }
+
   const explicitSession = process.env.CTXCE_SESSION_ID || "";
   const authBackendEnv = (process.env.CTXCE_AUTH_BACKEND_URL || "").trim();
-  let backendHint = authBackendEnv || UPLOAD_AUTH_BACKEND || "";
+  let backendHint = authBackendEnv || uploadAuthBackend || "";
   let sessionId = explicitSession;
 
   function sessionFromEntry(entry) {
@@ -446,7 +512,7 @@ async function createBridgeServer(options) {
     if (explicit) {
       return explicit;
     }
-    return findSavedSession([backendHint, UPLOAD_AUTH_BACKEND, authBackendEnv]);
+    return findSavedSession([backendHint, uploadAuthBackend, authBackendEnv]);
   }
 
   if (!sessionId) {
@@ -473,6 +539,8 @@ async function createBridgeServer(options) {
       sessionId,
       repoName,
       bridgeStateToken: BRIDGE_STATE_TOKEN,
+      backendHint,
+      uploadServiceUrl,
     });
     if (state) {
       const serving = state.serving_collection || state.active_collection;
@@ -502,10 +570,23 @@ async function createBridgeServer(options) {
     }
 
     if (forceRecreate) {
-      try {
-        debugLog("[ctxce] Reinitializing remote MCP clients after session error.");
-      } catch {
-        // ignore logging failures
+      debugLog("[ctxce] Reinitializing remote MCP clients after session error.");
+      
+      if (indexerClient) {
+        try {
+          await indexerClient.close();
+        } catch {
+          // ignore close errors
+        }
+        indexerClient = null;
+      }
+      if (memoryClient) {
+        try {
+          await memoryClient.close();
+        } catch {
+          // ignore close errors
+        }
+        memoryClient = null;
       }
     }
 
@@ -592,11 +673,7 @@ async function createBridgeServer(options) {
       if (!indexerClient) {
         throw new Error("Indexer MCP client not initialized");
       }
-      remote = await withTimeout(
-        indexerClient.listTools(),
-        10000,
-        "indexer tools/list",
-      );
+      remote = await indexerClient.listTools();
     } catch (err) {
       debugLog("[ctxce] Error calling remote tools/list: " + String(err));
       const memoryToolsFallback = await listMemoryTools(memoryClient);
@@ -695,20 +772,38 @@ async function createBridgeServer(options) {
         if (isSessionError(err) && !sessionRetried) {
           debugLog(
             "[ctxce] tools/call: detected remote MCP session error; reinitializing clients and retrying once: " +
-              String(err),
+            String(err),
           );
           await initializeRemoteClients(true);
           sessionRetried = true;
           continue;
         }
 
+        // Backend auth rejection (mcp_auth.py ValidationError) - expire local auth
+        if (isAuthRejectionError(err)) {
+          debugLog(
+            "[ctxce] tools/call: backend auth rejection; marking local session as expired: " +
+            String(err),
+          );
+          if (backendHint) {
+            try {
+              const entry = loadAuthEntry(backendHint);
+              if (entry) {
+                saveAuthEntry(backendHint, { ...entry, expiresAt: 1 });
+              }
+            } catch {
+              // ignore failures
+            }
+          }
+        }
+
         if (!isTransientToolError(err) || attempt === maxAttempts - 1) {
           throw err;
         }
 
         debugLog(
           `[ctxce] tools/call: transient error (attempt ${attempt + 1}/${maxAttempts}), retrying: ` +
-            String(err),
+          String(err),
         );
         // Loop will retry
       }
@@ -830,11 +925,28 @@ export async function runHttpMcpServer(options) {
           return;
         }
 
+        const MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB
         let body = "";
+        let bodyLimitExceeded = false;
         req.on("data", (chunk) => {
+          if (bodyLimitExceeded) return;
           body += chunk;
+          if (body.length > MAX_BODY_SIZE) {
+            bodyLimitExceeded = true;
+            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,
+              }),
+            );
+          }
         });
         req.on("end", async () => {
+          if (bodyLimitExceeded) return;
           let parsed;
           try {
             parsed = body ? JSON.parse(body) : {};
@@ -902,6 +1014,25 @@ export async function runHttpMcpServer(options) {
   httpServer.listen(port, '127.0.0.1', () => {
     debugLog(`[ctxce] HTTP MCP bridge listening on 127.0.0.1:${port}`);
   });
+
+  let shuttingDown = false;
+  const shutdown = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    debugLog(`[ctxce] Received ${signal}; closing HTTP server (waiting for in-flight requests).`);
+    httpServer.close(() => {
+      debugLog("[ctxce] HTTP server closed.");
+      process.exit(0);
+    });
+    const SHUTDOWN_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes for long MCP calls
+    setTimeout(() => {
+      debugLog("[ctxce] Forcing exit after shutdown timeout.");
+      process.exit(1);
+    }, SHUTDOWN_TIMEOUT_MS).unref();
+  };
+
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
 }
 
 function loadConfig(startDir) {

package/src/oauthHandler.js

@@ -16,24 +16,97 @@ const pendingCodes = new Map();
 // Maps client_id to client info
 const registeredClients = new Map();
 
+// ============================================================================
+// Storage Limits and Cleanup Configuration
+// ============================================================================
+
+const MAX_TOKEN_STORE_SIZE = 10000;
+const MAX_PENDING_CODES_SIZE = 1000;
+const MAX_REGISTERED_CLIENTS_SIZE = 1000;
+const TOKEN_EXPIRY_MS = 86400000; // 24 hours
+const CODE_EXPIRY_MS = 600000; // 10 minutes
+const CLIENT_EXPIRY_MS = 7 * 86400000; // 7 days
+const CLEANUP_INTERVAL_MS = 300000; // 5 minutes
+
+// Cleanup interval reference (for cleanup on shutdown if needed)
+let cleanupIntervalId = null;
+
 // ============================================================================
 // OAuth Utilities
 // ============================================================================
 
-/**
- * Clean up expired tokens from tokenStore
- * Called periodically to prevent unbounded memory growth
- */
 function cleanupExpiredTokens() {
   const now = Date.now();
-  const expiryMs = 86400000; // 24 hours
   for (const [token, data] of tokenStore.entries()) {
-    if (now - data.createdAt > expiryMs) {
+    if (now - data.createdAt > TOKEN_EXPIRY_MS) {
       tokenStore.delete(token);
     }
   }
 }
 
+function cleanupExpiredCodes() {
+  const now = Date.now();
+  for (const [code, data] of pendingCodes.entries()) {
+    if (now - data.createdAt > CODE_EXPIRY_MS) {
+      pendingCodes.delete(code);
+    }
+  }
+}
+
+function cleanupExpiredClients() {
+  const now = Date.now();
+  for (const [clientId, data] of registeredClients.entries()) {
+    if (now - data.createdAt > CLIENT_EXPIRY_MS) {
+      registeredClients.delete(clientId);
+    }
+  }
+}
+
+function enforceStorageLimits() {
+  if (tokenStore.size > MAX_TOKEN_STORE_SIZE) {
+    const entries = [...tokenStore.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+    const toRemove = entries.slice(0, tokenStore.size - MAX_TOKEN_STORE_SIZE);
+    for (const [key] of toRemove) {
+      tokenStore.delete(key);
+    }
+  }
+  if (pendingCodes.size > MAX_PENDING_CODES_SIZE) {
+    const entries = [...pendingCodes.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+    const toRemove = entries.slice(0, pendingCodes.size - MAX_PENDING_CODES_SIZE);
+    for (const [key] of toRemove) {
+      pendingCodes.delete(key);
+    }
+  }
+  if (registeredClients.size > MAX_REGISTERED_CLIENTS_SIZE) {
+    const entries = [...registeredClients.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+    const toRemove = entries.slice(0, registeredClients.size - MAX_REGISTERED_CLIENTS_SIZE);
+    for (const [key] of toRemove) {
+      registeredClients.delete(key);
+    }
+  }
+}
+
+function runPeriodicCleanup() {
+  cleanupExpiredTokens();
+  cleanupExpiredCodes();
+  cleanupExpiredClients();
+  enforceStorageLimits();
+}
+
+export function startCleanupInterval() {
+  if (!cleanupIntervalId) {
+    cleanupIntervalId = setInterval(runPeriodicCleanup, CLEANUP_INTERVAL_MS);
+    cleanupIntervalId.unref?.();
+  }
+}
+
+export function stopCleanupInterval() {
+  if (cleanupIntervalId) {
+    clearInterval(cleanupIntervalId);
+    cleanupIntervalId = null;
+  }
+}
+
 function generateToken() {
   return randomBytes(32).toString("hex");
 }
@@ -545,20 +618,14 @@ export function handleOAuthToken(req, res) {
   });
 }
 
-/**
- * Validate Bearer token and return session info
- * @param {string} token - Bearer token
- * @returns {{sessionId: string, backendUrl: string} | null}
- */
 export function validateBearerToken(token) {
   const tokenData = tokenStore.get(token);
   if (!tokenData) {
     return null;
   }
 
-  // Check token age (24 hour expiry)
   const tokenAge = Date.now() - tokenData.createdAt;
-  if (tokenAge > 86400000) {
+  if (tokenAge > TOKEN_EXPIRY_MS) {
     tokenStore.delete(token);
     return null;
   }
@@ -583,3 +650,5 @@ export function isOAuthEndpoint(pathname) {
     pathname === "/oauth/token"
   );
 }
+
+startCleanupInterval();

package/src/resultPathMapping.js

@@ -326,6 +326,8 @@ function remapHitPaths(hit, workspaceRoot) {
       out.path = finalRelPath;
     }
   }
+  // Strip internal container_path before returning to client.
+  delete out.container_path;
   return out;
 }