@context-engine-bridge/context-engine-mcp-bridge 0.0.28 → 0.0.29

package/.omc/state/hud-state.json

@@ -0,0 +1,6 @@
+{
+  "timestamp": "2026-02-20T02:56:43.457Z",
+  "backgroundTasks": [],
+  "sessionStartTimestamp": "2026-02-20T02:54:38.180Z",
+  "sessionId": "391fa45d902019af"
+}

package/AGENTS.md

@@ -0,0 +1,69 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-02-19 | Updated: 2026-02-19 -->
+
+# ctx-mcp-bridge
+
+## Purpose
+
+The MCP bridge (`ctxce` CLI) is a Model Context Protocol server that aggregates the Context Engine indexer and memory servers into a single unified MCP server. It supports both stdio and HTTP transport modes, making it compatible with MCP clients like Claude Code, Windsurf, Augment, and others. The bridge is primarily launched by the VS Code extension but can run standalone.
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `bin/ctxce.js` | CLI entry point and executable (chmod +x 755) |
+| `src/cli.js` | Command routing and argument parsing for `mcp-serve`, `mcp-http-serve`, `auth`, `connect` |
+| `src/mcpServer.js` | MCP server implementation with stdio/HTTP transport, tool deduping, and auth handling |
+| `src/authCli.js` | Auth command handlers: `login`, `logout`, `status` with token and password flows |
+| `src/authConfig.js` | Session storage and management in `~/.ctxce/auth.json` |
+| `src/oauthHandler.js` | OAuth protocol support for remote deployments |
+| `src/uploader.js` | Standalone code uploader integration |
+| `src/connectCli.js` | Connection validation and setup helpers |
+| `src/resultPathMapping.js` | Path remapping for tool results (container/host paths) |
+| `package.json` | Node.js package manifest (requires Node >= 18) |
+
+## Subdirectories
+
+| Directory | Purpose |
+|-----------|---------|
+| `bin/` | Executable CLI entry point |
+| `docs/` | Debugging guides and documentation |
+| `src/` | Core MCP server and auth logic (see `src/AGENTS.md`) |
+
+## For AI Agents
+
+### Working In This Directory
+
+This is a Node.js MCP bridge package. Changes to MCP routing, tool forwarding, or auth handling require updates to `src/cli.js` and `src/mcpServer.js`. The bridge proxies requests between MCP clients and remote indexer/memory HTTP servers, so test both stdio and HTTP modes.
+
+### Testing Requirements
+
+- Run with `npm start` or `node bin/ctxce.js --help`
+- Test MCP stdio mode: `ctxce mcp-serve --workspace /tmp/test`
+- Test MCP HTTP mode: `ctxce mcp-http-serve --workspace /tmp/test --port 30810`
+- Test auth commands: `ctxce auth login --backend-url http://localhost:8004 --token TEST_TOKEN`
+- Verify auth state: `ctxce auth status --backend-url http://localhost:8004 --json`
+- E2E tests: `npm run test:e2e`
+
+### Common Patterns
+
+- Environment variables: `CTXCE_INDEXER_URL`, `CTXCE_MEMORY_URL`, `CTXCE_HTTP_PORT`, `CTXCE_AUTH_*`
+- Auth sessions stored in `~/.ctxce/auth.json` keyed by backend URL
+- MCP tools are deduplicated and forwarded from indexer and memory servers
+- Path remapping (host paths <-> container paths) handled transparently
+- All MCP requests are logged to stderr or `CTXCE_DEBUG_LOG` if set
+
+## Dependencies
+
+### Internal
+- Context Engine indexer (HTTP endpoint at `CTXCE_INDEXER_URL` or `http://localhost:8003/mcp`)
+- Context Engine memory server (HTTP endpoint at `CTXCE_MEMORY_URL` or `http://localhost:8002/mcp`)
+- Auth backend (optional, at `CTXCE_AUTH_BACKEND_URL` or `http://localhost:8004`)
+
+### External
+- `@modelcontextprotocol/sdk` (^1.24.3) – MCP protocol implementation
+- `zod` (^3.25.0) – Runtime type validation
+- `tar` (^7.5.9) – Archive support for uploads
+- `ignore` (^7.0.5) – .gitignore-style file filtering
+
+<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

package/bin/AGENTS.md

@@ -0,0 +1,34 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-02-19 | Updated: 2026-02-19 -->
+
+# bin
+
+## Purpose
+
+Executable CLI entry point for the `ctxce` command (also aliased as `ctxce-bridge`). This directory contains the shebang-wrapped Node.js script that is installed globally or via npm when the package is installed.
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `ctxce.js` | CLI executable entry point (Node.js script, chmod +x 755) |
+
+## For AI Agents
+
+### Working In This Directory
+
+Do not modify `ctxce.js` directly unless changing the CLI bootstrap. The actual CLI logic is in `src/cli.js`. The executable must have a shebang (`#!/usr/bin/env node`) and be marked executable on Unix systems.
+
+### Testing Requirements
+
+- Verify executable permission: `ls -l bin/ctxce.js` should show `-rwxr-xr-x`
+- Test global install: `npm install -g` and run `ctxce --help`
+- Test npx mode: `npx @context-engine-bridge/context-engine-mcp-bridge ctxce --help`
+- Postinstall script auto-fixes permissions on non-Windows systems
+
+## Dependencies
+
+### Internal
+- `src/cli.js` – Main CLI router and handler
+
+<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

package/docs/AGENTS.md

@@ -0,0 +1,22 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-02-19 | Updated: 2026-02-19 -->
+
+# docs
+
+## Purpose
+
+Debugging guides and developer documentation for the MCP bridge. Currently contains minimal documentation; most usage is covered in the main `README.md`.
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `debugging.md` | Debug logging and troubleshooting tips |
+
+## For AI Agents
+
+### Working In This Directory
+
+This directory is for developer guides, not API documentation (which belongs in the main README). When adding debugging tips or advanced usage patterns, place them here.
+
+<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

package/package.json

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

package/src/AGENTS.md

@@ -0,0 +1,59 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-02-19 | Updated: 2026-02-19 -->
+
+# src
+
+## Purpose
+
+Core MCP server implementation, auth handling, and CLI routing for the `ctxce` bridge. This module aggregates the Context Engine indexer and memory servers, manages authentication sessions, and handles both stdio and HTTP transport modes.
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `cli.js` | Main command router for `mcp-serve`, `mcp-http-serve`, `auth`, `connect` subcommands; parses CLI flags and environment variables |
+| `mcpServer.js` | MCP server implementation; proxies requests to indexer/memory servers, dedupes tools, handles auth, supports stdio and HTTP transports |
+| `authCli.js` | Auth command handlers for `login`, `logout`, `status` with token and password flows; manages session lifecycle |
+| `authConfig.js` | Persistent auth state in `~/.ctxce/auth.json`; session loading, saving, TTL handling, OAuth support |
+| `oauthHandler.js` | OAuth protocol implementation for token refresh and remote auth flows |
+| `uploader.js` | Integration with the standalone code uploader (tar archive support, progress tracking) |
+| `connectCli.js` | Connection validation, workspace discovery, and setup helpers |
+| `resultPathMapping.js` | Path remapping for tool results (host paths <-> container paths); handles path translation for Docker environments |
+
+## For AI Agents
+
+### Working In This Directory
+
+This is the core business logic. Changes to MCP command handling, tool routing, or auth flows affect both the CLI and the VS Code extension. The server proxies all tool requests to remote indexer/memory servers and dedupes tool lists to prevent duplicates. Auth is optional but handles session TTL, token refresh, and fallback to dev tokens.
+
+### Testing Requirements
+
+- Test MCP stdio transport: `node src/cli.js mcp-serve --workspace /tmp/test`
+- Test MCP HTTP transport: `node src/cli.js mcp-http-serve --workspace /tmp/test --port 30810`
+- Test auth login: `node src/cli.js auth login --backend-url http://localhost:8004 --token TOKEN`
+- Test auth status: `node src/cli.js auth status --backend-url http://localhost:8004 --json`
+- Verify tool deduping: Check that tools from indexer and memory are merged without duplicates
+- Test path remapping: Verify that container paths are correctly mapped for Docker environments
+- Run E2E tests: `npm run test:e2e`, `npm run test:e2e:auth`, `npm run test:e2e:happy`, `npm run test:e2e:edge`
+
+### Common Patterns
+
+- Environment variables guide server initialization: `CTXCE_INDEXER_URL`, `CTXCE_MEMORY_URL`, `CTXCE_HTTP_PORT`, `CTXCE_AUTH_BACKEND_URL`, `CTXCE_AUTH_ENABLED`, `CTXCE_DEBUG_LOG`
+- Sessions are stored per backend URL in `~/.ctxce/auth.json` with TTL tracking
+- All MCP tools from indexer and memory are merged and deduplicated before listing
+- Path remapping is applied to tool arguments and results for Docker host/container path translation
+- Debug logging goes to stderr and optionally to a file (set `CTXCE_DEBUG_LOG` env var)
+- HTTP transport uses Node.js `createServer` with MCP's `StreamableHTTPServerTransport`
+
+## Dependencies
+
+### Internal
+- `bin/ctxce.js` – CLI entry point that imports and runs these modules
+
+### External
+- `@modelcontextprotocol/sdk` – MCP protocol (Server, StdioServerTransport, StreamableHTTPServerTransport, Client, StreamableHTTPClientTransport)
+- `zod` – Runtime type validation (used in config parsing)
+- `tar` – Archive handling for uploader
+- `ignore` – File filtering for .gitignore patterns
+
+<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

package/src/connectCli.js

@@ -2,7 +2,7 @@ import process from "node:process";
 import path from "node:path";
 import fs from "node:fs";
 import { saveAuthEntry } from "./authConfig.js";
-import { indexWorkspace } from "./uploader.js";
+import { indexWorkspace, loadGitignore, isCodeFile } from "./uploader.js";
 
 const SAAS_ENDPOINTS = {
   uploadEndpoint: "https://dev.context-engine.ai/upload",
@@ -160,12 +160,35 @@ async function triggerIndexing(workspace, sessionId, authEntry) {
   return result.success;
 }
 
-function startWatcher(workspace, sessionId, authEntry, intervalMs) {
+function startWatcher(workspace, initialSessionId, authEntry, intervalMs) {
   console.error(`[ctxce] Starting file watcher (sync every ${intervalMs / 1000}s)...`);
   console.error("[ctxce] Press Ctrl+C to stop.");
 
   let isRunning = false;
   let pendingSync = false;
+  let sessionId = initialSessionId;
+
+  async function refreshSessionIfNeeded() {
+    // If the auth entry has an expiry and we're within 5 minutes of it,
+    // re-authenticate using the stored API key.
+    if (!authEntry || !authEntry.apiKey) return;
+    const expiresAt = authEntry.expiresAt;
+    if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= 0) return;
+    const nowSecs = Math.floor(Date.now() / 1000);
+    const remainingSecs = expiresAt - nowSecs;
+    if (remainingSecs > 300) return;  // still valid for > 5 min
+    console.error("[ctxce] Session approaching expiry, refreshing...");
+    try {
+      const refreshed = await authenticateWithApiKey(authEntry.apiKey);
+      if (refreshed && refreshed.sessionId) {
+        sessionId = refreshed.sessionId;
+        authEntry = refreshed;
+        console.error("[ctxce] Session refreshed successfully.");
+      }
+    } catch (err) {
+      console.error(`[ctxce] Session refresh failed: ${err}`);
+    }
+  }
 
   const fileHashes = new Map();
 
@@ -178,26 +201,29 @@ function startWatcher(workspace, sessionId, authEntry, intervalMs) {
     }
   }
 
+  // Use gitignore from uploader.js so the watcher ignores the same files as
+  // the bundle creator -- prevents redundant uploads for generated/ignored files.
+  const _ig = loadGitignore(workspace);
+
   function scanDirectory(dir, files = []) {
     try {
       const entries = fs.readdirSync(dir, { withFileTypes: true });
       for (const entry of entries) {
+        if (entry.isSymbolicLink()) continue;
         const fullPath = path.join(dir, entry.name);
-        
-        if (entry.name.startsWith(".") || 
-            entry.name === "node_modules" || 
-            entry.name === "__pycache__" ||
-            entry.name === "venv" ||
-            entry.name === ".venv" ||
-            entry.name === "dist" ||
-            entry.name === "build") {
-          continue;
-        }
+        // Normalize to forward slashes for the `ignore` library (expects POSIX paths)
+        const relPath = path.relative(workspace, fullPath).split(path.sep).join('/');
 
+        // Use the same ignore rules as the bundle creator
+        // Directories need a trailing slash for gitignore pattern matching
         if (entry.isDirectory()) {
+          if (_ig.ignores(relPath + '/')) continue;
           scanDirectory(fullPath, files);
         } else if (entry.isFile()) {
-          files.push(fullPath);
+          if (_ig.ignores(relPath)) continue;
+          if (isCodeFile(fullPath)) {
+            files.push(fullPath);
+          }
         }
       }
     } catch {
@@ -242,6 +268,9 @@ function startWatcher(workspace, sessionId, authEntry, intervalMs) {
     console.error(`[ctxce] [${now}] Syncing changes...`);
 
     try {
+      // Refresh session before upload if approaching expiry
+      await refreshSessionIfNeeded();
+
       const result = await indexWorkspace(
         workspace,
         SAAS_ENDPOINTS.uploadEndpoint,

package/src/mcpServer.js

@@ -501,7 +501,13 @@ async function createBridgeServer(options) {
       expiresAt > 0 &&
       expiresAt < Math.floor(Date.now() / 1000)
     ) {
-      debugLog("[ctxce] Stored auth session has local expiry in the past; attempting to use it anyway (server will validate).");
+      // Allow 5-minute grace period for clock skew; beyond that, reject
+      const expiredSecs = Math.floor(Date.now() / 1000) - expiresAt;
+      if (expiredSecs > 300) {
+        debugLog(`[ctxce] Session expired ${expiredSecs}s ago (beyond 5min grace), triggering re-auth.`);
+        return "";
+      }
+      debugLog("[ctxce] Session expired but within 5min grace period; using it (server will validate).");
       return entry.sessionId;
     }
     return entry.sessionId;

package/src/uploader.js

@@ -36,7 +36,7 @@ const DEFAULT_IGNORES = [
 
 const MAX_FILE_SIZE = 10 * 1024 * 1024;
 
-function loadGitignore(workspacePath) {
+export function loadGitignore(workspacePath) {
   const ig = ignore();
   ig.add(DEFAULT_IGNORES);
 
@@ -52,7 +52,7 @@ function loadGitignore(workspacePath) {
   return ig;
 }
 
-function isCodeFile(filePath) {
+export function isCodeFile(filePath) {
   const ext = path.extname(filePath).toLowerCase();
   if (CODE_EXTS.has(ext)) return true;
 
@@ -224,19 +224,10 @@ export async function createBundle(workspacePath, options = {}) {
 export async function uploadBundle(bundlePath, manifest, uploadEndpoint, sessionId, options = {}) {
   const { log = console.error, orgId, orgSlug } = options;
 
-  const bundleData = fs.readFileSync(bundlePath);
+  const bundleSize = fs.statSync(bundlePath).size;
   const boundary = `----ctxce${Date.now()}${Math.random().toString(36).slice(2)}`;
 
-  const parts = [];
-
-  parts.push(
-    `--${boundary}\r\n`,
-    `Content-Disposition: form-data; name="bundle"; filename="bundle.tar.gz"\r\n`,
-    `Content-Type: application/gzip\r\n\r\n`,
-  );
-  parts.push(bundleData);
-  parts.push(`\r\n`);
-
+  // Build form fields (small metadata -- kept in memory)
   const logicalRepoId = computeLogicalRepoId(manifest.workspace_path);
   const fields = {
     workspace_path: manifest.workspace_path,
@@ -246,35 +237,67 @@ export async function uploadBundle(bundlePath, manifest, uploadEndpoint, session
     logical_repo_id: logicalRepoId,
     session: sessionId,
   };
-
   if (orgId) fields.org_id = orgId;
   if (orgSlug) fields.org_slug = orgSlug;
 
+  // Build multipart preamble (file header) and epilogue (fields + close)
+  const filePreamble = Buffer.from(
+    `--${boundary}\r\n` +
+    `Content-Disposition: form-data; name="bundle"; filename="bundle.tar.gz"\r\n` +
+    `Content-Type: application/gzip\r\n\r\n`
+  );
+  const fileEpilogue = Buffer.from(`\r\n`);
+
+  let fieldsPart = '';
   for (const [key, value] of Object.entries(fields)) {
     if (value) {
-      parts.push(
-        `--${boundary}\r\n`,
-        `Content-Disposition: form-data; name="${key}"\r\n\r\n`,
-        `${value}\r\n`,
-      );
+      fieldsPart += `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="${key}"\r\n\r\n` +
+        `${value}\r\n`;
     }
   }
-
-  parts.push(`--${boundary}--\r\n`);
-
-  const bodyParts = parts.map(p => typeof p === "string" ? Buffer.from(p) : p);
-  const body = Buffer.concat(bodyParts);
+  fieldsPart += `--${boundary}--\r\n`;
+  const fieldsBuffer = Buffer.from(fieldsPart);
+
+  // Stream the bundle file instead of loading it entirely into memory.
+  // This prevents OOM for large repositories (hundreds of MB bundles).
+  const totalLength = filePreamble.length + bundleSize + fileEpilogue.length + fieldsBuffer.length;
+
+  const { Readable } = await import('node:stream');
+  const bodyStream = new Readable({
+    read() {
+      // Push preamble
+      this.push(filePreamble);
+      // Push file data in chunks via sync read to keep it simple
+      const CHUNK = 256 * 1024;  // 256KB chunks
+      const fd = fs.openSync(bundlePath, 'r');
+      try {
+        const buf = Buffer.allocUnsafe(CHUNK);
+        let bytesRead;
+        while ((bytesRead = fs.readSync(fd, buf, 0, CHUNK)) > 0) {
+          this.push(bytesRead === CHUNK ? buf : buf.subarray(0, bytesRead));
+        }
+      } finally {
+        fs.closeSync(fd);
+      }
+      // Push epilogue + fields + close
+      this.push(fileEpilogue);
+      this.push(fieldsBuffer);
+      this.push(null);  // EOF
+    }
+  });
 
   const url = `${uploadEndpoint}/api/v1/delta/upload`;
-  log(`[uploader] Uploading to ${url}...`);
+  log(`[uploader] Uploading to ${url} (${(bundleSize / 1024).toFixed(0)}KB bundle, streaming)...`);
 
   const resp = await fetch(url, {
     method: "POST",
     headers: {
       "Content-Type": `multipart/form-data; boundary=${boundary}`,
-      "Content-Length": String(body.length),
+      "Content-Length": String(totalLength),
     },
-    body,
+    body: bodyStream,
+    duplex: "half",  // required for streaming request bodies in Node.js fetch
   });
 
   let result;
@@ -298,8 +321,23 @@ export async function uploadBundle(bundlePath, manifest, uploadEndpoint, session
   return { success: true, result };
 }
 
+let _indexInFlight = false;
 export async function indexWorkspace(workspacePath, uploadEndpoint, sessionId, options = {}) {
   const { log = console.error, orgId, orgSlug } = options;
+  if (_indexInFlight) {
+    log("[uploader] indexWorkspace already in progress, skipping concurrent call");
+    return { success: false, error: "already_in_progress" };
+  }
+  _indexInFlight = true;
+  try {
+    return await _indexWorkspaceInner(workspacePath, uploadEndpoint, sessionId, options);
+  } finally {
+    _indexInFlight = false;
+  }
+}
+
+async function _indexWorkspaceInner(workspacePath, uploadEndpoint, sessionId, options = {}) {
+  const { log = console.error, orgId, orgSlug } = options;
 
   log(`[uploader] Scanning workspace: ${workspacePath}`);
 

package/.claude/settings.local.json

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