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

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.6",
   "description": "Context Engine MCP bridge (http/stdio proxy combining indexer + memory servers)",
   "bin": {
     "ctxce": "bin/ctxce.js",

package/src/authCli.js

@@ -0,0 +1,206 @@
+import process from "node:process";
+import { loadAuthEntry, saveAuthEntry, deleteAuthEntry } 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") && i + 1 < args.length) {
+      username = args[i + 1];
+      i += 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 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);
+  const url = requireBackendUrl(backendUrl);
+  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);
+  const url = getBackendUrl(backendUrl);
+  if (!url) {
+    if (outputJson) {
+      outputJsonStatus("", "missing_backend", null, null);
+      process.exit(1);
+    }
+    console.error("[ctxce] Auth backend URL not configured. 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);
+    }
+    console.error("[ctxce] Not logged in for", url);
+    process.exit(1);
+  }
+
+  if (expired) {
+    if (outputJson) {
+      outputJsonStatus(url, "expired", entry, rawExpires);
+      process.exit(2);
+    }
+    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;
+  }
+  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);
+  const url = requireBackendUrl(backendUrl);
+  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

@@ -247,6 +247,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";
 
 async function createBridgeServer(options) {
   const workspace = options.workspace || process.cwd();
@@ -281,8 +282,54 @@ 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;
+
+  if (!sessionId) {
+    let backendToUse = authBackendUrl;
+    let entry = null;
+
+    if (backendToUse) {
+      try {
+        entry = loadAuthEntry(backendToUse);
+      } catch (err) {
+        entry = null;
+      }
+    }
+
+    if (!entry) {
+      try {
+        const any = loadAnyAuthEntry();
+        if (any && any.entry) {
+          backendToUse = any.backendUrl;
+          entry = any.entry;
+        }
+      } catch (err) {
+        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) {
+        sessionId = entry.sessionId;
+      } else if (expired) {
+        debugLog("[ctxce] Stored auth session appears expired; please run `ctxce auth login` again.");
+      }
+    }
+  }
+
+  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.