@prom.codes/context-mcp 0.4.2 → 0.4.4

package/README.md

@@ -2,28 +2,33 @@
 
 prom.codes Context — local-first codebase indexing & retrieval as an MCP server (stdio).
 
-## Quick start
-
-```jsonc
-// Claude Desktop / Cursor MCP config
-{
-  "mcpServers": {
-    "prometheus": {
-      "command": "npx",
-      "args": ["-y", "@prom.codes/context-mcp@latest"],
-      "env": {
-        "PROMETHEUS_API_KEY": "prom_live_…",
-        "PROMETHEUS_WORKSPACE_ROOT": "/absolute/path/to/your/repo"
-      }
-    }
-  }
-}
+## Quick start (Claude Code)
+
+```bash
+claude mcp add context --env PROMETHEUS_API_KEY=prom_live_… -- npx -y @prom.codes/context-mcp@latest
 ```
 
-With a `PROMETHEUS_API_KEY` the server runs in managed mode: it indexes
-your workspace into a local SQLite database (`~/.prometheus/<hash>.db`)
-and embeds via the prom.codes API. Your code never leaves your machine —
-only embedding text transits to the API.
+`claude mcp add` defaults to local scope (just you); add `--scope project` to
+write a committable `.mcp.json`, or `--scope user` for all your projects. Other
+MCP hosts (Cursor, VS Code) use the same command/args in their own config.
+
+## Configuration
+
+- **`PROMETHEUS_API_KEY`** (required for semantic search) — a real key minted at
+  [app.prom.codes/app/api-keys](https://app.prom.codes), shape
+  `prom_live_<tag>_<secret>`. Embeddings route through the managed prom.codes
+  proxy — you never bring your own provider key. Without a valid key, code
+  search **degrades gracefully** to lexical (keyword) + symbol-graph retrieval
+  (no embeddings needed) and every structural tool still works.
+- **Workspace root is auto-detected** — no need to set `PROMETHEUS_WORKSPACE_ROOT`.
+  Claude Code passes the open project via `CLAUDE_PROJECT_DIR`; Cursor/VS Code via
+  the MCP `roots` capability. Set it only to point at a different folder.
+- The index is a local SQLite DB at `~/.prometheus/<hash>.db` (one per project).
+  Your code never leaves your machine — only embedding *text* transits to the proxy.
+
+Tools: `search_code`, `get_symbol`, `find_references`, `find_callers`,
+`find_callees`, `expand_context`, `get_file`, `list_changed_since`,
+`list_workspaces`, `framework_overview`.
 
 ## Native modules
 
@@ -32,6 +37,8 @@ Prebuilt binaries are fetched automatically on the mainstream platforms
 (macOS x64/arm64, Linux x64, Windows x64) — no compiler needed. On other
 platforms (e.g. Linux/Windows arm64) or a Node ABI without a prebuild, install
 C/C++ build tools so the native modules can compile (Windows: VS Build Tools).
+If `npx` skips the native build under a hardened npm (`ignore-scripts=true`),
+install globally once and point Claude Code at the built binary — see the docs.
 Requires Node ≥ 20.10.
 
-Docs: https://prom.codes/docs
+Docs: https://prom.codes/docs/mcp/claude-code

package/dist/bin.js

@@ -3484,6 +3484,153 @@ function isSensitivePath(path) {
 }
 var SENSITIVE_PATH_ERROR = "path matches the sensitive-file deny-list";
 
+// ../shared/dist/update-check.js
+import { mkdir, readFile as readFile2, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+async function packageIdentity(binImportMetaUrl) {
+  try {
+    const binPath = fileURLToPath(binImportMetaUrl);
+    const pkgPath = join(binPath, "..", "..", "package.json");
+    const raw = await readFile2(pkgPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.name !== "string" || typeof parsed.version !== "string") {
+      return null;
+    }
+    return { name: parsed.name, version: parsed.version };
+  } catch {
+    return null;
+  }
+}
+async function maybeNotifyUpdate(binImportMetaUrl, env = process.env) {
+  try {
+    const id = await packageIdentity(binImportMetaUrl);
+    if (id === null)
+      return;
+    await checkForUpdate({ name: id.name, version: id.version, env });
+  } catch {
+  }
+}
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+var DEFAULT_TIMEOUT_MS = 1500;
+var OPT_OUT_RE = /^(1|true|yes|on)$/i;
+function parseSemver(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(v.trim());
+  if (m === null)
+    return null;
+  return {
+    core: [Number(m[1]), Number(m[2]), Number(m[3])],
+    pre: m[4] ?? null
+  };
+}
+function isNewerVersion(latest, current) {
+  const a = parseSemver(latest);
+  const b = parseSemver(current);
+  if (a === null || b === null)
+    return false;
+  for (let i = 0; i < 3; i++) {
+    if (a.core[i] > b.core[i])
+      return true;
+    if (a.core[i] < b.core[i])
+      return false;
+  }
+  if (a.pre === null && b.pre !== null)
+    return true;
+  return false;
+}
+function cachePath(dir, name) {
+  const safe = name.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return join(dir, `.update-check-${safe}.json`);
+}
+async function readCache(path) {
+  try {
+    const raw = await readFile2(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.checkedAt !== "number")
+      return null;
+    return {
+      checkedAt: parsed.checkedAt,
+      latest: typeof parsed.latest === "string" ? parsed.latest : null
+    };
+  } catch {
+    return null;
+  }
+}
+async function writeCache(path, data) {
+  try {
+    await writeFile(path, JSON.stringify(data), "utf8");
+  } catch {
+  }
+}
+async function fetchLatest(name, fetchImpl, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+  try {
+    const url = `https://registry.npmjs.org/${name.replace("/", "%2F")}/latest`;
+    const res = await fetchImpl(url, {
+      signal: controller.signal,
+      headers: { accept: "application/vnd.npm.install-v1+json" }
+    });
+    if (!res.ok)
+      return null;
+    const body = await res.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function checkForUpdate(options) {
+  const { name, version, env = process.env, log = (line) => process.stderr.write(line), fetch: fetchImpl = globalThis.fetch, cacheDir = join(homedir(), ".prometheus"), cacheTtlMs = DEFAULT_TTL_MS, timeoutMs = DEFAULT_TIMEOUT_MS, force = false } = options;
+  const base = {
+    latest: null,
+    current: version
+  };
+  if (OPT_OUT_RE.test(env.PROMETHEUS_NO_UPDATE_CHECK ?? "")) {
+    return { ...base, checked: false, updateAvailable: false, reason: "opted-out" };
+  }
+  if (parseSemver(version) === null || version === "0.0.0") {
+    return { ...base, checked: false, updateAvailable: false, reason: "invalid-version" };
+  }
+  if (typeof fetchImpl !== "function") {
+    return { ...base, checked: false, updateAvailable: false, reason: "error" };
+  }
+  const file = cachePath(cacheDir, name);
+  const now = Date.now();
+  if (!force) {
+    const cached = await readCache(file);
+    if (cached !== null && now - cached.checkedAt < cacheTtlMs) {
+      const updateAvailable2 = cached.latest !== null && isNewerVersion(cached.latest, version);
+      if (updateAvailable2)
+        notify(log, name, version, cached.latest);
+      return {
+        ...base,
+        latest: cached.latest,
+        checked: false,
+        updateAvailable: updateAvailable2,
+        reason: "throttled"
+      };
+    }
+  }
+  await mkdir(cacheDir, { recursive: true }).catch(() => void 0);
+  const latest = await fetchLatest(name, fetchImpl, timeoutMs);
+  await writeCache(file, { checkedAt: now, latest });
+  if (latest === null) {
+    return { ...base, checked: true, updateAvailable: false, reason: "error" };
+  }
+  const updateAvailable = isNewerVersion(latest, version);
+  if (updateAvailable)
+    notify(log, name, version, latest);
+  return { ...base, latest, checked: true, updateAvailable };
+}
+function notify(log, name, current, latest) {
+  log(`${name}: a newer version (${latest}) is available \u2014 you are on ${current}. npx users get it automatically on the next restart; for a global install run \`npm update -g ${name}\`. (Set PROMETHEUS_NO_UPDATE_CHECK=1 to silence.)
+`);
+}
+
 // ../shared/dist/index.js
 var PROMETHEUS_VERSION = "0.1.0";
 
@@ -3542,6 +3689,8 @@ var WorkspaceWatcher = class extends EventEmitter {
   #root;
   #ignored;
   #debounceMs;
+  #usePolling;
+  #pollIntervalMs;
   #watcher = null;
   #pending = /* @__PURE__ */ new Map();
   constructor(options) {
@@ -3549,6 +3698,10 @@ var WorkspaceWatcher = class extends EventEmitter {
     this.#root = resolve(options.root);
     this.#ignored = options.ignored ?? DEFAULT_IGNORED;
     this.#debounceMs = options.debounceMs ?? 50;
+    const envPolling = process.env.CHOKIDAR_USEPOLLING === "true" || process.env.CHOKIDAR_USEPOLLING === "1";
+    this.#usePolling = options.usePolling ?? envPolling;
+    const envInterval = Number.parseInt(process.env.CHOKIDAR_INTERVAL ?? "", 10);
+    this.#pollIntervalMs = options.pollIntervalMs ?? (Number.isInteger(envInterval) && envInterval > 0 ? envInterval : 80);
   }
   /** Absolute workspace root. */
   get root() {
@@ -3558,14 +3711,25 @@ var WorkspaceWatcher = class extends EventEmitter {
   async start() {
     if (this.#watcher !== null)
       return;
+    const relativeMatch = (pat) => (abs) => {
+      const rel = toRelative(this.#root, abs);
+      if (rel === abs)
+        return false;
+      if (typeof pat === "string") {
+        return rel === pat || rel.startsWith(`${pat}/`);
+      }
+      return pat.test(rel);
+    };
     const denySensitive = (abs) => {
       const rel = toRelative(this.#root, abs);
       return rel !== abs && isSensitivePath(rel);
     };
     const watcher = chokidar.watch(this.#root, {
-      ignored: [...this.#ignored, denySensitive],
+      ignored: [...this.#ignored.map(relativeMatch), denySensitive],
       ignoreInitial: false,
       persistent: true,
+      usePolling: this.#usePolling,
+      ...this.#usePolling ? { interval: this.#pollIntervalMs, binaryInterval: this.#pollIntervalMs } : {},
       awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 10 }
     });
     this.#watcher = watcher;
@@ -3608,8 +3772,8 @@ var WorkspaceWatcher = class extends EventEmitter {
 };
 
 // ../indexer/dist/workspace-indexer.js
-import { readFile as readFile2, readdir, stat } from "node:fs/promises";
-import { join, resolve as resolve2, sep as sep2 } from "node:path";
+import { readFile as readFile3, readdir, stat } from "node:fs/promises";
+import { join as join2, resolve as resolve2, sep as sep2 } from "node:path";
 
 // ../indexer/dist/co-change.js
 import { spawn } from "node:child_process";
@@ -3811,6 +3975,7 @@ var WorkspaceIndexer = class {
   #ignored;
   #concurrency;
   #coChangeBuilder;
+  #watchTuning;
   #watcher = null;
   constructor(options) {
     this.#root = resolve2(options.root);
@@ -3819,6 +3984,7 @@ var WorkspaceIndexer = class {
     this.#ownsIndexer = options.indexer === void 0;
     this.#ignored = options.ignored;
     this.#concurrency = Math.max(1, options.concurrency ?? 8);
+    this.#watchTuning = options.watch;
     this.#coChangeBuilder = options.coChange === false ? null : new CoChangeBuilder({
       repoRoot: this.#root,
       storage: this.#storage,
@@ -3882,7 +4048,7 @@ var WorkspaceIndexer = class {
       return;
     }
     for (const entry of entries) {
-      const abs = join(dir, entry.name);
+      const abs = join2(dir, entry.name);
       const rel = toRelative2(this.#root, abs);
       if (this.#isIgnored(rel))
         continue;
@@ -3929,7 +4095,11 @@ var WorkspaceIndexer = class {
       this.#indexer.dispose();
   }
   #watcherOptions() {
-    return this.#ignored === void 0 ? { root: this.#root } : { root: this.#root, ignored: this.#ignored };
+    return {
+      root: this.#root,
+      ...this.#ignored !== void 0 ? { ignored: this.#ignored } : {},
+      ...this.#watchTuning ?? {}
+    };
   }
   async #handleEvent(ev) {
     try {
@@ -3949,7 +4119,7 @@ var WorkspaceIndexer = class {
     let raw;
     let stats;
     try {
-      raw = await readFile2(absPath);
+      raw = await readFile3(absPath);
       stats = await stat(absPath);
     } catch (err) {
       return { error: err instanceof Error ? err.message : String(err) };
@@ -4001,8 +4171,8 @@ var WorkspaceIndexer = class {
 // dist/composition.js
 import { createHash as createHash3 } from "node:crypto";
 import { mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename as basename5, dirname as dirname2, join as join3, resolve as resolve4 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+import { basename as basename5, dirname as dirname2, join as join4, resolve as resolve4 } from "node:path";
 
 // ../storage-sqlite/dist/adapter.js
 import Database from "better-sqlite3";
@@ -4727,8 +4897,8 @@ var DEFAULT_VECTOR_DIMENSION = 1024;
 var DEFAULT_SCHEMA = "public";
 
 // ../storage-supabase/dist/migrations.js
-import { dirname, join as join2, resolve as resolve3 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { dirname, join as join3, resolve as resolve3 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // ../storage-supabase/dist/migrations-data.generated.js
 var EMBEDDED_MIGRATIONS = {
@@ -4819,13 +4989,13 @@ COMMIT;
 };
 
 // ../storage-supabase/dist/migrations.js
-var HERE = dirname(fileURLToPath(import.meta.url));
+var HERE = dirname(fileURLToPath2(import.meta.url));
 var REPO_ROOT = resolve3(HERE, "..", "..", "..");
-var MIGRATIONS_DIR = join2(REPO_ROOT, "infra", "supabase", "migrations");
+var MIGRATIONS_DIR = join3(REPO_ROOT, "infra", "supabase", "migrations");
 var MIGRATIONS = Object.keys(EMBEDDED_MIGRATIONS).sort().map((filename, idx) => ({
   id: idx + 1,
   filename,
-  path: join2(MIGRATIONS_DIR, filename)
+  path: join3(MIGRATIONS_DIR, filename)
 }));
 async function loadMigrationSql(filename) {
   const sql = EMBEDDED_MIGRATIONS[filename];
@@ -6149,7 +6319,7 @@ var HybridRetriever = class {
     const coChangeActive = effectiveEdgeWeights[CO_CHANGE] > 0;
     const lexCols = options.lexicalColumnWeights;
     const lexicalPromise = wLex > 0 ? this.#storage.searchByText(trimmed, candidateLimit, lexCols !== void 0 ? { columnWeights: lexCols } : void 0) : Promise.resolve([]);
-    const vectorPromise = wVec > 0 ? this.#runVector(trimmed, candidateLimit, options.signal) : Promise.resolve({ hits: [], queryVector: null });
+    const vectorPromise = wVec > 0 ? this.#runVector(trimmed, candidateLimit, options.signal, options.onVectorError) : Promise.resolve({ hits: [], queryVector: null });
     const [lexicalHits, vectorResult] = await Promise.all([
       lexicalPromise,
       vectorPromise
@@ -6240,15 +6410,24 @@ var HybridRetriever = class {
     }
     return fusedResults;
   }
-  async #runVector(query, limit, signal) {
+  async #runVector(query, limit, signal, onVectorError) {
     const opts = signal !== void 0 ? { inputType: "query", signal } : { inputType: "query" };
-    const vectors = await this.#embedder.embed([query], opts);
-    if (vectors.length === 0 || vectors[0] === void 0) {
+    try {
+      const vectors = await this.#embedder.embed([query], opts);
+      if (vectors.length === 0 || vectors[0] === void 0) {
+        return { hits: [], queryVector: null };
+      }
+      const queryVector = vectors[0];
+      const hits = await this.#storage.searchByVector(queryVector, limit);
+      return { hits, queryVector };
+    } catch (err) {
+      if (err?.name === "AbortError")
+        throw err;
+      if (onVectorError === void 0)
+        throw err;
+      onVectorError(err);
       return { hits: [], queryVector: null };
     }
-    const queryVector = vectors[0];
-    const hits = await this.#storage.searchByVector(queryVector, limit);
-    return { hits, queryVector };
   }
   /**
    * Run typed symbol-graph expansion from `seeds`.
@@ -8257,7 +8436,7 @@ function discoverQueryRewriter(env, fetchImpl) {
 function getStableDbPath(workspaceRoot) {
   const abs = resolve4(workspaceRoot);
   const hash = createHash3("sha256").update(abs).digest("hex").slice(0, 16);
-  return join3(homedir(), ".prometheus", `${hash}.db`);
+  return join4(homedir2(), ".prometheus", `${hash}.db`);
 }
 var StorageConfigError = class extends Error {
   constructor(reason) {
@@ -8375,7 +8554,7 @@ async function composeFromEnv(opts) {
 }
 
 // dist/roots.js
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 async function rootFromClient(server, timeoutMs = 2500) {
   let supportsRoots = false;
   try {
@@ -8396,7 +8575,7 @@ async function rootFromClient(server, timeoutMs = 2500) {
     const uri = typeof r?.uri === "string" ? r.uri : "";
     if (uri.startsWith("file://")) {
       try {
-        return fileURLToPath2(uri);
+        return fileURLToPath3(uri);
       } catch {
       }
     }
@@ -8408,8 +8587,8 @@ async function rootFromClient(server, timeoutMs = 2500) {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // dist/tools.js
-import { readFile as readFile3 } from "node:fs/promises";
-import { isAbsolute, join as join4, normalize, relative, resolve as resolve5, sep as sep3 } from "node:path";
+import { readFile as readFile4 } from "node:fs/promises";
+import { isAbsolute, join as join5, normalize, relative, resolve as resolve5, sep as sep3 } from "node:path";
 import { z } from "zod";
 
 // dist/frameworks.js
@@ -8611,7 +8790,7 @@ async function snippetForSymbol(workspaceRoot, symbol, cache, capBytes = MAX_SNI
     let buf = cache.get(relPath);
     if (buf === void 0) {
       const abs = resolveInWorkspace(workspaceRoot, relPath);
-      buf = await readFile3(abs).catch(() => null);
+      buf = await readFile4(abs).catch(() => null);
       cache.set(relPath, buf);
     }
     if (buf === null)
@@ -8760,7 +8939,16 @@ ${hyp}`;
       } catch {
       }
     }
-    const pool = await retriever.search(searchQuery, { k: poolK });
+    let vectorError = null;
+    const pool = await retriever.search(searchQuery, {
+      k: poolK,
+      onVectorError: (err) => {
+        if (vectorError !== null)
+          return;
+        vectorError = err instanceof Error ? err.message : String(err);
+        console.error(`[context-mcp] search_code: vector (semantic) search unavailable \u2014 falling back to lexical + symbol-graph. Likely a missing/invalid embedding API key; set PROMETHEUS_API_KEY to a real minted prom_live_<tag>_<secret> key (mint at app.prom.codes/app/api-keys) to enable semantic ranking. Cause: ${vectorError}`);
+      }
+    });
     let ordered = pool;
     let reranked = false;
     if (reranker && pool.length > 0) {
@@ -8785,7 +8973,18 @@ ${hyp}`;
       const snip = await snippetForSymbol(workspaceRoot, r.symbol, cache);
       return snip === null ? base : { ...base, snippet: snip.text, snippetTruncated: snip.truncated };
     }));
-    return textResult({ query: args.query, k, reranked, results: mapped });
+    const payload = {
+      query: args.query,
+      k,
+      reranked,
+      results: mapped
+    };
+    if (vectorError !== null) {
+      payload.degraded = "lexical+graph-only";
+      payload.note = "Semantic (vector) search was unavailable \u2014 results are lexical (keyword) + symbol-graph only, which can rank less precisely on concept queries. Set PROMETHEUS_API_KEY to a real minted prom_live_<tag>_<secret> key (app.prom.codes/app/api-keys) to enable semantic ranking.";
+      payload.vectorError = vectorError;
+    }
+    return textResult(payload);
   });
   server.registerTool("get_symbol", {
     title: "Exact symbol lookup",
@@ -8855,7 +9054,7 @@ ${hyp}`;
     if (isSensitivePath(relative(workspaceRoot, abs))) {
       throw new Error(`${SENSITIVE_PATH_ERROR}: "${args.path}".`);
     }
-    const buf = await readFile3(abs);
+    const buf = await readFile4(abs);
     const start = args.startByte ?? 0;
     const end = args.endByte ?? buf.byteLength;
     if (end < start) {
@@ -8926,7 +9125,7 @@ ${hyp}`;
     const manifests = {};
     for (const name of FRAMEWORK_MANIFESTS) {
       try {
-        manifests[name] = await readFile3(join4(workspaceRoot, name), "utf8");
+        manifests[name] = await readFile4(join5(workspaceRoot, name), "utf8");
       } catch {
       }
     }
@@ -8994,6 +9193,7 @@ async function main() {
   const explicitRoot = (env.PROMETHEUS_WORKSPACE_ROOT ?? "").trim();
   const claudeRoot = (env.CLAUDE_PROJECT_DIR ?? "").trim();
   const eagerVia = explicitRoot !== "" ? "PROMETHEUS_WORKSPACE_ROOT" : claudeRoot !== "" ? "CLAUDE_PROJECT_DIR" : null;
+  void maybeNotifyUpdate(import.meta.url, env);
   const transport = new StdioServerTransport();
   const server = new McpServer2(SERVER_IDENTITY, { capabilities: { tools: {} } });
   let composed = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prom.codes/context-mcp",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "prom.codes Context — local-first codebase indexing & retrieval as an MCP server.",
   "type": "module",
   "bin": {