@context-engine-bridge/context-engine-mcp-bridge 0.0.84 → 0.0.85

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-engine-bridge/context-engine-mcp-bridge",
-  "version": "0.0.84",
+  "version": "0.0.85",
   "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/mcpServer.js

@@ -265,7 +265,7 @@ async function sendSessionDefaults(client, payload, label) {
   try {
     await client.callTool({
       name: "set_session_defaults",
-      arguments: payload,
+      arguments: { ...payload },
     });
   } catch (err) {
     // eslint-disable-next-line no-console
@@ -1242,6 +1242,62 @@ async function createBridgeServer(options) {
     uploadServiceUrl,
   });
 
+  async function recoverDeletedCollection(reason) {
+    debugLog(`[ctxce] Collection appears deleted (${reason}), clearing cache and re-resolving`);
+    defaultsPayload.collection = "";
+    try {
+      _clearExactWorkspaceCachedCollection(workspace);
+    } catch (wsErr) {
+      debugLog("[ctxce] Failed to clear workspace collection cache: " + String(wsErr));
+    }
+    try {
+      if (backendHint) {
+        const authEntry = loadAuthEntry(backendHint);
+        let repoId = "";
+        try { repoId = computeLogicalRepoIdentity(workspace)?.id || ""; } catch { repoId = ""; }
+        clearResolvedCollection(backendHint, {
+          orgId: authEntry?.org_id,
+          orgSlug: authEntry?.org_slug,
+          logicalRepoId: repoId,
+        });
+      }
+    } catch (clearErr) {
+      debugLog("[ctxce] Failed to clear resolved collection cache: " + String(clearErr));
+    }
+    try {
+      const freshPayload = await buildDefaultsPayload({
+        workspace,
+        sessionId,
+        explicitCollection: "",
+        defaultCollection: "",
+        defaultMode,
+        defaultUnder,
+        config,
+        backendHint,
+        uploadServiceUrl,
+      });
+      if (Object.hasOwn(freshPayload, "collection")) {
+        defaultsPayload.collection = freshPayload.collection;
+      }
+      if (freshPayload.collection) {
+        debugLog("[ctxce] Re-resolved collection after deletion: " + freshPayload.collection);
+      }
+    } catch (reResolveErr) {
+      debugLog("[ctxce] Failed to re-resolve collection after deletion: " + String(reResolveErr));
+    }
+    try {
+      if (indexerClient) {
+        await sendSessionDefaults(indexerClient, defaultsPayload, "indexer");
+      }
+      if (memoryClient) {
+        await sendSessionDefaults(memoryClient, defaultsPayload, "memory");
+      }
+      debugLog(`[ctxce] Re-sent session defaults after collection deletion detection (${reason})`);
+    } catch (sdErr) {
+      debugLog("[ctxce] Failed to re-send session defaults after deletion: " + String(sdErr));
+    }
+  }
+
   async function initializeRemoteClients(forceRecreate = false) {
     if (!forceRecreate && indexerClient) {
       return;
@@ -1705,59 +1761,7 @@ async function createBridgeServer(options) {
         }
         // Detect explicit collection_deleted flag in a successful response
         if (resultIndicatesCollectionDeleted(result)) {
-          debugLog("[ctxce] Collection appears deleted, clearing cache and re-resolving");
-          defaultsPayload.collection = "";
-          try {
-            _clearExactWorkspaceCachedCollection(workspace);
-          } catch (wsErr) {
-            debugLog("[ctxce] Failed to clear workspace collection cache: " + String(wsErr));
-          }
-          try {
-            if (backendHint) {
-              const authEntry = loadAuthEntry(backendHint);
-              let repoId = "";
-              try { repoId = computeLogicalRepoIdentity(workspace)?.id || ""; } catch { repoId = ""; }
-              clearResolvedCollection(backendHint, {
-                orgId: authEntry?.org_id,
-                orgSlug: authEntry?.org_slug,
-                logicalRepoId: repoId,
-              });
-            }
-          } catch (clearErr) {
-            debugLog("[ctxce] Failed to clear resolved collection cache: " + String(clearErr));
-          }
-          // Best-effort re-resolve via /bridge/state
-          try {
-            const freshPayload = await buildDefaultsPayload({
-              workspace,
-              sessionId,
-              explicitCollection: "",
-              defaultCollection: "",
-              defaultMode,
-              defaultUnder,
-              config,
-              backendHint,
-              uploadServiceUrl,
-            });
-            if (freshPayload.collection) {
-              defaultsPayload.collection = freshPayload.collection;
-              debugLog("[ctxce] Re-resolved collection after deletion: " + freshPayload.collection);
-            }
-          } catch (reResolveErr) {
-            debugLog("[ctxce] Failed to re-resolve collection after deletion: " + String(reResolveErr));
-          }
-          // Re-send session defaults so remote MCP servers stop using the stale collection
-          try {
-            if (indexerClient) {
-              await sendSessionDefaults(indexerClient, defaultsPayload, "indexer");
-            }
-            if (memoryClient) {
-              await sendSessionDefaults(memoryClient, defaultsPayload, "memory");
-            }
-            debugLog("[ctxce] Re-sent session defaults after collection deletion detection");
-          } catch (sdErr) {
-            debugLog("[ctxce] Failed to re-send session defaults after deletion: " + String(sdErr));
-          }
+          await recoverDeletedCollection("result path");
         }
 
         return maybeRemapToolResult(name, result, workspace);
@@ -1766,58 +1770,7 @@ async function createBridgeServer(options) {
 
         // Detect collection deletion from error signals
         if (isCollectionDeletedSignal(err)) {
-          debugLog("[ctxce] Collection appears deleted, clearing cache and re-resolving");
-          defaultsPayload.collection = "";
-          try {
-            _clearExactWorkspaceCachedCollection(workspace);
-          } catch (wsErr) {
-            debugLog("[ctxce] Failed to clear workspace collection cache: " + String(wsErr));
-          }
-          try {
-            if (backendHint) {
-              const authEntry = loadAuthEntry(backendHint);
-              let repoId = "";
-              try { repoId = computeLogicalRepoIdentity(workspace)?.id || ""; } catch { repoId = ""; }
-              clearResolvedCollection(backendHint, {
-                orgId: authEntry?.org_id,
-                orgSlug: authEntry?.org_slug,
-                logicalRepoId: repoId,
-              });
-            }
-          } catch (clearErr) {
-            debugLog("[ctxce] Failed to clear resolved collection cache: " + String(clearErr));
-          }
-          // Best-effort re-resolve via /bridge/state (fire-and-forget)
-          buildDefaultsPayload({
-            workspace,
-            sessionId,
-            explicitCollection: "",
-            defaultCollection: "",
-            defaultMode,
-            defaultUnder,
-            config,
-            backendHint,
-            uploadServiceUrl,
-          }).then(async (freshPayload) => {
-            if (freshPayload.collection) {
-              defaultsPayload.collection = freshPayload.collection;
-              debugLog("[ctxce] Re-resolved collection after deletion: " + freshPayload.collection);
-            }
-            // Re-send session defaults so remote MCP servers stop using the stale collection
-            try {
-              if (indexerClient) {
-                await sendSessionDefaults(indexerClient, defaultsPayload, "indexer");
-              }
-              if (memoryClient) {
-                await sendSessionDefaults(memoryClient, defaultsPayload, "memory");
-              }
-              debugLog("[ctxce] Re-sent session defaults after collection deletion detection (error path)");
-            } catch (sdErr) {
-              debugLog("[ctxce] Failed to re-send session defaults after deletion: " + String(sdErr));
-            }
-          }).catch((reResolveErr) => {
-            debugLog("[ctxce] Failed to re-resolve collection after deletion: " + String(reResolveErr));
-          });
+          await recoverDeletedCollection("error path");
         }
 
         if (isConnectionDeadError(err) && !connectionRetried) {