@context-engine-bridge/context-engine-mcp-bridge 0.0.5 → 0.0.7

package/README.md

@@ -0,0 +1,212 @@
+# Context Engine MCP Bridge
+
+`@context-engine-bridge/context-engine-mcp-bridge` provides the `ctxce` CLI, a
+Model Context Protocol (MCP) bridge that speaks to the Context Engine indexer
+and memory servers and exposes them as a single MCP server.
+
+It is primarily used by the VS Code **Context Engine Uploader** extension,
+available on the Marketplace:
+
+- <https://marketplace.visualstudio.com/items?itemName=context-engine.context-engine-uploader>
+
+The bridge can also be run standalone (e.g. from a terminal, or wired into
+other MCP clients) as long as the Context Engine stack is running.
+
+## Prerequisites
+
+- Node.js **>= 18** (see `engines` in `package.json`).
+- A running Context Engine stack (e.g. via `docker-compose.dev-remote.yml`) with:
+  - MCP indexer HTTP endpoint (default: `http://localhost:8003/mcp`).
+  - MCP memory HTTP endpoint (optional, default: `http://localhost:8002/mcp`).
+- For optional auth:
+  - The upload/auth services must be configured with `CTXCE_AUTH_ENABLED=1` and
+    a reachable auth backend URL (e.g. `http://localhost:8004`).
+
+## Installation
+
+You can install the package globally, or run it via `npx`.
+
+### Global install
+
+```bash
+npm install -g @context-engine-bridge/context-engine-mcp-bridge
+```
+
+This installs the `ctxce` (and `ctxce-bridge`) CLI in your PATH.
+
+### Using npx (no global install)
+
+```bash
+npx @context-engine-bridge/context-engine-mcp-bridge ctxce --help
+```
+
+The examples below assume `ctxce` is available on your PATH; if you use `npx`,
+just prefix commands with `npx @context-engine-bridge/context-engine-mcp-bridge`.
+
+## CLI overview
+
+The main entrypoint is:
+
+```bash
+ctxce <command> [...args]
+```
+
+Supported commands (from `src/cli.js`):
+
+- `ctxce mcp-serve`        – stdio MCP bridge (for stdio-based MCP clients).
+- `ctxce mcp-http-serve`   – HTTP MCP bridge (for HTTP-based MCP clients).
+- `ctxce auth <subcmd>`    – auth helper commands (`login`, `status`, `logout`).
+
+### Environment variables
+
+These environment variables are respected by the bridge:
+
+- `CTXCE_INDEXER_URL` – MCP indexer URL (default: `http://localhost:8003/mcp`).
+- `CTXCE_MEMORY_URL`  – MCP memory URL, or empty/omitted to disable memory
+  (default: `http://localhost:8002/mcp`).
+- `CTXCE_HTTP_PORT`   – port for `mcp-http-serve` (default: `30810`).
+
+For auth (optional, shared with the upload/auth backend):
+
+- `CTXCE_AUTH_ENABLED`       – whether auth is enabled in the backend.
+- `CTXCE_AUTH_BACKEND_URL`   – auth backend URL (e.g. `http://localhost:8004`).
+- `CTXCE_AUTH_TOKEN`         – dev/shared token for `ctxce auth login`.
+- `CTXCE_AUTH_SESSION_TTL_SECONDS` – session TTL / sliding expiry (seconds).
+
+The CLI also stores auth sessions in `~/.ctxce/auth.json`, keyed by backend URL.
+
+## Running the MCP bridge (stdio)
+
+The stdio bridge is suitable for MCP clients that speak stdio directly (for
+example, certain editors or tools that expect an MCP server on stdin/stdout).
+
+```bash
+ctxce mcp-serve \
+  --workspace /path/to/your/workspace \
+  --indexer-url http://localhost:8003/mcp \
+  --memory-url http://localhost:8002/mcp
+```
+
+Flags:
+
+- `--workspace` / `--path` – workspace root (default: current working directory).
+- `--indexer-url`          – override indexer URL (default: `CTXCE_INDEXER_URL` or
+  `http://localhost:8003/mcp`).
+- `--memory-url`           – override memory URL (default: `CTXCE_MEMORY_URL` or
+  disabled when empty).
+
+## Running the MCP bridge (HTTP)
+
+The HTTP bridge exposes the MCP server via an HTTP endpoint (default
+`http://127.0.0.1:30810/mcp`) and is what the VS Code extension uses in its
+`http` transport mode.
+
+```bash
+ctxce mcp-http-serve \
+  --workspace /path/to/your/workspace \
+  --indexer-url http://localhost:8003/mcp \
+  --memory-url http://localhost:8002/mcp \
+  --port 30810
+```
+
+Flags:
+
+- `--workspace` / `--path` – workspace root (default: current working directory).
+- `--indexer-url`          – MCP indexer URL.
+- `--memory-url`           – MCP memory URL (or omit/empty to disable memory).
+- `--port`                 – HTTP port for the bridge (default: `CTXCE_HTTP_PORT`
+  or `30810`).
+
+Once running, you can point an MCP client at:
+
+```text
+http://127.0.0.1:<port>/mcp
+```
+
+## Auth helper commands (`ctxce auth ...`)
+
+These commands are used both by the VS Code extension and standalone flows to
+log in and manage auth sessions for the backend.
+
+### Login (token)
+
+```bash
+ctxce auth login \
+  --backend-url http://localhost:8004 \
+  --token $CTXCE_AUTH_SHARED_TOKEN
+```
+
+This hits the backend `/auth/login` endpoint and stores a session entry in
+`~/.ctxce/auth.json` under the given backend URL.
+
+### Login (username/password)
+
+```bash
+ctxce auth login \
+  --backend-url http://localhost:8004 \
+  --username your-user \
+  --password your-password
+```
+
+This calls `/auth/login/password` and persists the returned session the same
+way as the token flow.
+
+### Status
+
+Human-readable status:
+
+```bash
+ctxce auth status --backend-url http://localhost:8004
+```
+
+Machine-readable status (used by the VS Code extension):
+
+```bash
+ctxce auth status --backend-url http://localhost:8004 --json
+```
+
+The `--json` variant prints a single JSON object to stdout, for example:
+
+```json
+{
+  "backendUrl": "http://localhost:8004",
+  "state": "ok",           // "ok" | "missing" | "expired" | "missing_backend"
+  "sessionId": "...",
+  "userId": "user-123",
+  "expiresAt": 0           // 0 or a Unix timestamp
+}
+```
+
+Exit codes:
+
+- `0` – `state: "ok"` (valid session present).
+- `1` – `state: "missing"` or `"missing_backend"`.
+- `2` – `state: "expired"`.
+
+### Logout
+
+```bash
+ctxce auth logout --backend-url http://localhost:8004
+```
+
+Removes the stored auth entry for the given backend URL from
+`~/.ctxce/auth.json`.
+
+## Relationship to the VS Code extension
+
+The VS Code **Context Engine Uploader** extension is the recommended way to use
+this bridge for day-to-day development. It:
+
+- Launches the standalone upload client to push code into the remote stack.
+- Starts/stops the MCP HTTP bridge (`ctxce mcp-http-serve`) for the active
+  workspace when `autoStartMcpBridge` is enabled.
+- Uses `ctxce auth status --json` and `ctxce auth login` under the hood to
+  manage user sessions via UI prompts.
+
+This package README is aimed at advanced users who want to:
+
+- Run the MCP bridge outside of VS Code.
+- Integrate the Context Engine MCP servers with other MCP-compatible clients.
+
+You can safely mix both approaches: the extension and the standalone bridge
+share the same auth/session storage in `~/.ctxce/auth.json`.

package/package.json

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

package/src/authCli.js

@@ -0,0 +1,284 @@
+import process from "node:process";
+import { loadAuthEntry, saveAuthEntry, deleteAuthEntry, loadAnyAuthEntry } from "./authConfig.js";
+
+function parseAuthArgs(args) {
+  let backendUrl = process.env.CTXCE_AUTH_BACKEND_URL || "";
+  let token = process.env.CTXCE_AUTH_TOKEN || "";
+  let username = process.env.CTXCE_AUTH_USERNAME || "";
+  let password = process.env.CTXCE_AUTH_PASSWORD || "";
+  let outputJson = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if ((a === "--backend-url" || a === "--auth-url") && i + 1 < args.length) {
+      backendUrl = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if ((a === "--token" || a === "--api-key") && i + 1 < args.length) {
+      token = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (a === "--username" || a === "--user") {
+      const hasNext = i + 1 < args.length;
+      const next = hasNext ? String(args[i + 1]) : "";
+      if (hasNext && !next.startsWith("-")) {
+        username = args[i + 1];
+        i += 1;
+      } else {
+        console.error("[ctxce] Missing value for --username/--user; expected a username.");
+        process.exit(1);
+      }
+      continue;
+    }
+    if ((a === "--password" || a === "--pass") && i + 1 < args.length) {
+      password = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (a === "--json" || a === "-j") {
+      outputJson = true;
+      continue;
+    }
+  }
+  return { backendUrl, token, username, password, outputJson };
+}
+
+function getBackendUrl(backendUrl) {
+  return (backendUrl || process.env.CTXCE_AUTH_BACKEND_URL || "").trim();
+}
+
+function getDefaultUploadBackend() {
+  // Default to upload service when nothing else is configured
+  return (process.env.CTXCE_UPLOAD_ENDPOINT || process.env.UPLOAD_ENDPOINT || "http://localhost:8004").trim();
+}
+
+function requireBackendUrl(backendUrl) {
+  const url = getBackendUrl(backendUrl);
+  if (!url) {
+    console.error("[ctxce] Auth backend URL not configured. Set CTXCE_AUTH_BACKEND_URL or use --backend-url.");
+    process.exit(1);
+  }
+  return url;
+}
+
+function outputJsonStatus(url, state, entry, rawExpires) {
+  const expiresAt = typeof rawExpires === "number"
+    ? rawExpires
+    : entry && typeof entry.expiresAt === "number"
+      ? entry.expiresAt
+      : null;
+  console.log(JSON.stringify({
+    backendUrl: url,
+    state,
+    sessionId: entry && entry.sessionId ? entry.sessionId : null,
+    userId: entry && entry.userId ? entry.userId : null,
+    expiresAt,
+  }));
+}
+
+async function doLogin(args) {
+  const { backendUrl, token, username, password } = parseAuthArgs(args);
+  let url = getBackendUrl(backendUrl);
+  if (!url) {
+    // Fallback: use any stored auth entry when no backend is provided
+    const any = loadAnyAuthEntry();
+    if (any && any.backendUrl) {
+      url = any.backendUrl;
+      console.error("[ctxce] Using stored backend for login:", url);
+    }
+  }
+  if (!url) {
+    // Final fallback: default upload endpoint (extension's upload endpoint or localhost:8004)
+    url = getDefaultUploadBackend();
+    if (url) {
+      console.error("[ctxce] Using default upload backend for login:", url);
+    }
+  }
+  if (!url) {
+    console.error("[ctxce] Auth backend URL not configured. Set CTXCE_AUTH_BACKEND_URL or use --backend-url.");
+    process.exit(1);
+  }
+  const trimmedUser = (username || "").trim();
+  const usePassword = trimmedUser && (password || "").length > 0;
+
+  let body;
+  let target;
+  if (usePassword) {
+    body = {
+      username: trimmedUser,
+      password,
+      workspace: process.cwd(),
+    };
+    target = url.replace(/\/+$/, "") + "/auth/login/password";
+  } else {
+    body = {
+      client: "ctxce",
+      workspace: process.cwd(),
+    };
+    if (token) {
+      body.token = token;
+    }
+    target = url.replace(/\/+$/, "") + "/auth/login";
+  }
+  let resp;
+  try {
+    resp = await fetch(target, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    console.error("[ctxce] Auth login request failed:", String(err));
+    process.exit(1);
+  }
+  if (!resp || !resp.ok) {
+    console.error("[ctxce] Auth login failed with status", resp ? resp.status : "<no-response>");
+    process.exit(1);
+  }
+  let data;
+  try {
+    data = await resp.json();
+  } catch (err) {
+    data = {};
+  }
+  const sessionId = data.session_id || data.sessionId || null;
+  const userId = data.user_id || data.userId || null;
+  const expiresAt = data.expires_at || data.expiresAt || null;
+  if (!sessionId) {
+    console.error("[ctxce] Auth login response missing session id.");
+    process.exit(1);
+  }
+  saveAuthEntry(url, { sessionId, userId, expiresAt });
+  console.error("[ctxce] Auth login successful for", url);
+}
+
+async function doStatus(args) {
+  const { backendUrl, outputJson } = parseAuthArgs(args);
+  let url = getBackendUrl(backendUrl);
+  let usedFallback = false;
+  if (!url) {
+    // Fallback: use any stored auth entry when no backend is provided
+    const any = loadAnyAuthEntry();
+    if (any && any.backendUrl) {
+      url = any.backendUrl;
+      usedFallback = true;
+    }
+  }
+  if (!url) {
+    // Final fallback: default upload endpoint
+    url = getDefaultUploadBackend();
+    if (url) {
+      usedFallback = true;
+      console.error("[ctxce] Using default upload backend for status:", url);
+    }
+  }
+  if (!url) {
+    if (outputJson) {
+      outputJsonStatus("", "missing_backend", null, null);
+      process.exit(1);
+    }
+    console.error("[ctxce] Auth backend URL not configured and no stored sessions found. Set CTXCE_AUTH_BACKEND_URL or use --backend-url.");
+    process.exit(1);
+  }
+  let entry;
+  try {
+    entry = loadAuthEntry(url);
+  } catch (err) {
+    entry = null;
+  }
+  const nowSecs = Math.floor(Date.now() / 1000);
+  const rawExpires = entry && typeof entry.expiresAt === "number" ? entry.expiresAt : null;
+  const hasSession = !!(entry && typeof entry.sessionId === "string" && entry.sessionId);
+  const expired = !!(rawExpires && rawExpires > 0 && rawExpires < nowSecs);
+
+  if (!entry || !hasSession) {
+    if (outputJson) {
+      outputJsonStatus(url, "missing", null, rawExpires);
+      process.exit(1);
+    }
+    if (usedFallback) {
+      console.error("[ctxce] Not logged in for stored backend", url);
+    } else {
+      console.error("[ctxce] Not logged in for", url);
+    }
+    process.exit(1);
+  }
+
+  if (expired) {
+    if (outputJson) {
+      outputJsonStatus(url, "expired", entry, rawExpires);
+      process.exit(2);
+    }
+    if (usedFallback) {
+      console.error("[ctxce] Stored auth session appears expired for stored backend", url);
+    } else {
+      console.error("[ctxce] Stored auth session appears expired for", url);
+    }
+    if (rawExpires) {
+      console.error("[ctxce] Session expired at", rawExpires);
+    }
+    process.exit(2);
+  }
+
+  if (outputJson) {
+    outputJsonStatus(url, "ok", entry, rawExpires);
+    return;
+  }
+  if (usedFallback) {
+    console.error("[ctxce] Using stored backend for status:", url);
+  }
+  console.error("[ctxce] Logged in to", url, "as", entry.userId || "<unknown>");
+  if (rawExpires) {
+    console.error("[ctxce] Session expires at", rawExpires);
+  }
+}
+
+async function doLogout(args) {
+  const { backendUrl } = parseAuthArgs(args);
+  let url = getBackendUrl(backendUrl);
+  if (!url) {
+    // Fallback: use any stored auth entry when no backend is provided
+    const any = loadAnyAuthEntry();
+    if (any && any.backendUrl) {
+      url = any.backendUrl;
+      console.error("[ctxce] Using stored backend for logout:", url);
+    }
+  }
+  if (!url) {
+    // Final fallback: default upload endpoint
+    url = getDefaultUploadBackend();
+    if (url) {
+      console.error("[ctxce] Using default upload backend for logout:", url);
+    }
+  }
+  if (!url) {
+    console.error("[ctxce] Auth backend URL not configured and no stored sessions found. Set CTXCE_AUTH_BACKEND_URL or use --backend-url.");
+    process.exit(1);
+  }
+  const entry = loadAuthEntry(url);
+  if (!entry) {
+    console.error("[ctxce] No stored auth session for", url);
+    return;
+  }
+  deleteAuthEntry(url);
+  console.error("[ctxce] Logged out from", url);
+}
+
+export async function runAuthCommand(subcommand, args) {
+  const sub = (subcommand || "").toLowerCase();
+  if (sub === "login") {
+    await doLogin(args || []);
+    return;
+  }
+  if (sub === "status") {
+    await doStatus(args || []);
+    return;
+  }
+  if (sub === "logout") {
+    await doLogout(args || []);
+    return;
+  }
+  console.error("Usage: ctxce auth <login|status|logout> [--backend-url <url>] [--token <token>]");
+  process.exit(1);
+}

package/src/authConfig.js

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CONFIG_DIR_NAME = ".ctxce";
+const CONFIG_BASENAME = "auth.json";
+
+function getConfigPath() {
+  const home = os.homedir() || process.cwd();
+  const dir = path.join(home, CONFIG_DIR_NAME);
+  return path.join(dir, CONFIG_BASENAME);
+}
+
+function readConfig() {
+  try {
+    const cfgPath = getConfigPath();
+    const raw = fs.readFileSync(cfgPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") {
+      return parsed;
+    }
+  } catch (err) {
+  }
+  return {};
+}
+
+function writeConfig(data) {
+  try {
+    const cfgPath = getConfigPath();
+    const dir = path.dirname(cfgPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(cfgPath, JSON.stringify(data, null, 2), "utf8");
+  } catch (err) {
+  }
+}
+
+export function loadAuthEntry(backendUrl) {
+  if (!backendUrl) {
+    return null;
+  }
+  const all = readConfig();
+  const key = String(backendUrl);
+  const entry = all[key];
+  if (!entry || typeof entry !== "object") {
+    return null;
+  }
+  return entry;
+}
+
+export function saveAuthEntry(backendUrl, entry) {
+  if (!backendUrl || !entry || typeof entry !== "object") {
+    return;
+  }
+  const all = readConfig();
+  const key = String(backendUrl);
+  all[key] = entry;
+  writeConfig(all);
+}
+
+export function deleteAuthEntry(backendUrl) {
+  if (!backendUrl) {
+    return;
+  }
+  const all = readConfig();
+  const key = String(backendUrl);
+  if (Object.prototype.hasOwnProperty.call(all, key)) {
+    delete all[key];
+    writeConfig(all);
+  }
+}
+
+export function loadAnyAuthEntry() {
+  const all = readConfig();
+  const keys = Object.keys(all);
+  for (const key of keys) {
+    const entry = all[key];
+    if (entry && typeof entry === "object") {
+      return { backendUrl: key, entry };
+    }
+  }
+  return null;
+}

package/src/cli.js

@@ -4,11 +4,19 @@ import process from "node:process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runMcpServer, runHttpMcpServer } from "./mcpServer.js";
+import { runAuthCommand } from "./authCli.js";
 
 export async function runCli() {
   const argv = process.argv.slice(2);
   const cmd = argv[0];
 
+  if (cmd === "auth") {
+    const sub = argv[1] || "";
+    const args = argv.slice(2);
+    await runAuthCommand(sub, args);
+    return;
+  }
+
   if (cmd === "mcp-http-serve") {
     const args = argv.slice(1);
     let workspace = process.cwd();
@@ -109,7 +117,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>]`,
+    `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>]`,
   );
   process.exit(1);
 }

package/src/mcpServer.js

@@ -1,3 +1,17 @@
+import process from "node:process";
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { createServer } from "node:http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+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 { maybeRemapToolResult } from "./resultPathMapping.js";
+
 function debugLog(message) {
   try {
     const text = typeof message === "string" ? message : String(message);
@@ -236,18 +250,6 @@ function isTransientToolError(error) {
 // Acts as a low-level proxy for tools, forwarding tools/list and tools/call
 // to the remote qdrant-indexer MCP server while adding a local `ping` tool.
 
-import process from "node:process";
-import fs from "node:fs";
-import path from "node:path";
-import { execSync } from "node:child_process";
-import { createServer } from "node:http";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-
 async function createBridgeServer(options) {
   const workspace = options.workspace || process.cwd();
   const indexerUrl = options.indexerUrl;
@@ -281,8 +283,61 @@ 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 sessionId =
-    process.env.CTXCE_SESSION_ID || `ctxce-${Buffer.from(workspace).toString("hex").slice(0, 24)}`;
+  const explicitSession = process.env.CTXCE_SESSION_ID || "";
+  const authBackendUrl = process.env.CTXCE_AUTH_BACKEND_URL || "";
+  let sessionId = explicitSession;
+
+  function resolveSessionId() {
+    const explicit = process.env.CTXCE_SESSION_ID || "";
+    if (explicit) {
+      return explicit;
+    }
+    let backendToUse = authBackendUrl;
+    let entry = null;
+    if (backendToUse) {
+      try {
+        entry = loadAuthEntry(backendToUse);
+      } catch {
+        entry = null;
+      }
+    }
+    if (!entry) {
+      try {
+        const any = loadAnyAuthEntry();
+        if (any && any.entry) {
+          backendToUse = any.backendUrl;
+          entry = any.entry;
+        }
+      } catch {
+        entry = null;
+      }
+    }
+    if (entry) {
+      let expired = false;
+      const rawExpires = entry.expiresAt;
+      if (typeof rawExpires === "number" && Number.isFinite(rawExpires) && rawExpires > 0) {
+        const nowSecs = Math.floor(Date.now() / 1000);
+        if (rawExpires < nowSecs) {
+          expired = true;
+        }
+      }
+      if (!expired && typeof entry.sessionId === "string" && entry.sessionId) {
+        return entry.sessionId;
+      }
+      if (expired) {
+        debugLog("[ctxce] Stored auth session appears expired; please run `ctxce auth login` again.");
+      }
+    }
+    return "";
+  }
+
+  if (!sessionId) {
+    sessionId = resolveSessionId();
+  }
+
+  if (!sessionId) {
+    sessionId = `ctxce-${Buffer.from(workspace).toString("hex").slice(0, 24)}`;
+  }
 
   // Best-effort: inform the indexer of default collection and session.
   // If this fails we still proceed, falling back to per-call injection.
@@ -430,7 +485,16 @@ async function createBridgeServer(options) {
 
     debugLog(`[ctxce] tools/call: ${name || "<no-name>"}`);
 
-    // Attach session id so the target server can apply per-session defaults.
+    // Refresh session before each call; re-init clients if session changes.
+    const freshSession = resolveSessionId() || sessionId;
+    if (freshSession && freshSession !== sessionId) {
+      sessionId = freshSession;
+      try {
+        await initializeRemoteClients(true);
+      } catch (err) {
+        debugLog("[ctxce] Failed to reinitialize clients after session refresh: " + String(err));
+      }
+    }
     if (sessionId && (args === undefined || args === null || typeof args === "object")) {
       const obj = args && typeof args === "object" ? { ...args } : {};
       if (!Object.prototype.hasOwnProperty.call(obj, "session")) {
@@ -478,7 +542,7 @@ async function createBridgeServer(options) {
           undefined,
           { timeout: timeoutMs },
         );
-        return result;
+        return maybeRemapToolResult(name, result, workspace);
       } catch (err) {
         lastError = err;
 

package/src/resultPathMapping.js

@@ -0,0 +1,266 @@
+import process from "node:process";
+import fs from "node:fs";
+import path from "node:path";
+
+function envTruthy(value, defaultVal = false) {
+  try {
+    if (value === undefined || value === null) {
+      return defaultVal;
+    }
+    const s = String(value).trim().toLowerCase();
+    if (!s) {
+      return defaultVal;
+    }
+    return s === "1" || s === "true" || s === "yes" || s === "on";
+  } catch {
+    return defaultVal;
+  }
+}
+
+function _posixToNative(rel) {
+  try {
+    if (!rel) {
+      return "";
+    }
+    return String(rel).split("/").join(path.sep);
+  } catch {
+    return rel;
+  }
+}
+
+function computeWorkspaceRelativePath(containerPath, hostPath) {
+  try {
+    const cont = typeof containerPath === "string" ? containerPath.trim() : "";
+    if (cont.startsWith("/work/")) {
+      const rest = cont.slice("/work/".length);
+      const parts = rest.split("/").filter(Boolean);
+      if (parts.length >= 2) {
+        return parts.slice(1).join("/");
+      }
+      if (parts.length === 1) {
+        return parts[0];
+      }
+    }
+  } catch {
+  }
+  try {
+    const hp = typeof hostPath === "string" ? hostPath.trim() : "";
+    if (!hp) {
+      return "";
+    }
+    // If we don't have a container path, at least try to return a basename.
+    return path.posix.basename(hp.replace(/\\/g, "/"));
+  } catch {
+    return "";
+  }
+}
+
+function remapHitPaths(hit, workspaceRoot) {
+  if (!hit || typeof hit !== "object") {
+    return hit;
+  }
+  const hostPath = typeof hit.host_path === "string" ? hit.host_path : "";
+  const containerPath = typeof hit.container_path === "string" ? hit.container_path : "";
+  const relPath = computeWorkspaceRelativePath(containerPath, hostPath);
+  const out = { ...hit };
+  if (relPath) {
+    out.rel_path = relPath;
+  }
+  if (workspaceRoot && relPath) {
+    try {
+      const relNative = _posixToNative(relPath);
+      const candidate = path.join(workspaceRoot, relNative);
+      const diagnostics = envTruthy(process.env.CTXCE_BRIDGE_PATH_DIAGNOSTICS, false);
+      const strictClientPath = envTruthy(process.env.CTXCE_BRIDGE_CLIENT_PATH_STRICT, false);
+      if (strictClientPath) {
+        out.client_path = candidate;
+        if (diagnostics) {
+          out.client_path_joined = candidate;
+          out.client_path_source = "workspace_join";
+        }
+      } else {
+        // Prefer a host_path that is within the current bridge workspace.
+        // This keeps provenance (host_path) intact while providing a user-local
+        // absolute path even when the bridge workspace is a parent directory.
+        const hp = typeof hostPath === "string" ? hostPath : "";
+        const hpNorm = hp ? hp.replace(/\\/g, path.sep) : "";
+        if (
+          hpNorm &&
+          hpNorm.startsWith(workspaceRoot) &&
+          (!fs.existsSync(candidate) || fs.existsSync(hpNorm))
+        ) {
+          out.client_path = hpNorm;
+          if (diagnostics) {
+            out.client_path_joined = candidate;
+            out.client_path_source = "host_path";
+          }
+        } else {
+          out.client_path = candidate;
+          if (diagnostics) {
+            out.client_path_joined = candidate;
+            out.client_path_source = "workspace_join";
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+  const overridePath = envTruthy(process.env.CTXCE_BRIDGE_OVERRIDE_PATH, true);
+  if (overridePath && relPath) {
+    out.path = relPath;
+  }
+  return out;
+}
+
+function remapStringPath(p) {
+  try {
+    const s = typeof p === "string" ? p : "";
+    if (!s) {
+      return p;
+    }
+    if (s.startsWith("/work/")) {
+      const rest = s.slice("/work/".length);
+      const parts = rest.split("/").filter(Boolean);
+      if (parts.length >= 2) {
+        const rel = parts.slice(1).join("/");
+        const override = envTruthy(process.env.CTXCE_BRIDGE_OVERRIDE_PATH, true);
+        if (override) {
+          return rel;
+        }
+        return p;
+      }
+    }
+    return p;
+  } catch {
+    return p;
+  }
+}
+
+function maybeParseToolJson(result) {
+  try {
+    if (
+      result &&
+      typeof result === "object" &&
+      result.structuredContent &&
+      typeof result.structuredContent === "object"
+    ) {
+      return { mode: "structured", value: result.structuredContent };
+    }
+  } catch {
+  }
+  try {
+    const content = result && result.content;
+    if (!Array.isArray(content)) {
+      return null;
+    }
+    const first = content.find(
+      (c) => c && c.type === "text" && typeof c.text === "string",
+    );
+    if (!first) {
+      return null;
+    }
+    const txt = String(first.text || "").trim();
+    if (!txt || !(txt.startsWith("{") || txt.startsWith("["))) {
+      return null;
+    }
+    return { mode: "text", value: JSON.parse(txt) };
+  } catch {
+    return null;
+  }
+}
+
+function applyPathMappingToPayload(payload, workspaceRoot) {
+  if (!payload || typeof payload !== "object") {
+    return payload;
+  }
+  const out = Array.isArray(payload) ? payload.slice() : { ...payload };
+
+  const mapHitsArray = (arr) => {
+    if (!Array.isArray(arr)) {
+      return arr;
+    }
+    return arr.map((h) => remapHitPaths(h, workspaceRoot));
+  };
+
+  // Common result shapes across tools
+  if (Array.isArray(out.results)) {
+    out.results = mapHitsArray(out.results);
+  }
+  if (Array.isArray(out.citations)) {
+    out.citations = mapHitsArray(out.citations);
+  }
+  if (Array.isArray(out.related_paths)) {
+    out.related_paths = out.related_paths.map((p) => remapStringPath(p));
+  }
+
+  // context_search: {results:[{source:"code"|"memory", ...}]}
+  if (Array.isArray(out.results)) {
+    out.results = out.results.map((r) => {
+      if (!r || typeof r !== "object") {
+        return r;
+      }
+      // Only code results have path-like fields
+      return remapHitPaths(r, workspaceRoot);
+    });
+  }
+
+  // Some tools nest under {result:{...}}
+  if (out.result && typeof out.result === "object") {
+    out.result = applyPathMappingToPayload(out.result, workspaceRoot);
+  }
+
+  return out;
+}
+
+export function maybeRemapToolResult(name, result, workspaceRoot) {
+  try {
+    if (!name || !result || !workspaceRoot) {
+      return result;
+    }
+    const enabled = envTruthy(process.env.CTXCE_BRIDGE_MAP_PATHS, true);
+    if (!enabled) {
+      return result;
+    }
+    const lower = String(name).toLowerCase();
+    const shouldMap = (
+      lower === "repo_search" ||
+      lower === "context_search" ||
+      lower === "context_answer" ||
+      lower.endsWith("search_tests_for") ||
+      lower.endsWith("search_config_for") ||
+      lower.endsWith("search_callers_for") ||
+      lower.endsWith("search_importers_for")
+    );
+    if (!shouldMap) {
+      return result;
+    }
+
+    const parsed = maybeParseToolJson(result);
+    if (!parsed) {
+      return result;
+    }
+
+    const mapped = applyPathMappingToPayload(parsed.value, workspaceRoot);
+    if (parsed.mode === "structured") {
+      return { ...result, structuredContent: mapped };
+    }
+
+    // Replace text payload for clients that only read `content[].text`
+    try {
+      const content = Array.isArray(result.content) ? result.content.slice() : [];
+      const idx = content.findIndex(
+        (c) => c && c.type === "text" && typeof c.text === "string",
+      );
+      if (idx >= 0) {
+        content[idx] = { ...content[idx], text: JSON.stringify(mapped) };
+        return { ...result, content };
+      }
+    } catch {
+      // ignore
+    }
+    return result;
+  } catch {
+    return result;
+  }
+}