@prom.codes/context-mcp 0.4.3 → 0.4.5

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

@@ -8438,6 +8438,16 @@ function getStableDbPath(workspaceRoot) {
   const hash = createHash3("sha256").update(abs).digest("hex").slice(0, 16);
   return join4(homedir2(), ".prometheus", `${hash}.db`);
 }
+function isAutoIndexableRoot(workspaceRoot) {
+  const abs = resolve4(workspaceRoot);
+  if (abs === "")
+    return false;
+  if (abs === resolve4(homedir2()))
+    return false;
+  if (dirname2(abs) === abs)
+    return false;
+  return true;
+}
 var StorageConfigError = class extends Error {
   constructor(reason) {
     super(`Storage configuration error: ${reason}`);
@@ -8526,6 +8536,7 @@ async function composeFromEnv(opts) {
   const rerankTopN = intEnv(env, "PROMETHEUS_RERANK_TOP_N", 100);
   const { id: queryRewriterId, provider: queryRewriter } = discoverQueryRewriter(env, opts.fetch);
   const managed = apiKeyPresent && storageBackend === "sqlite";
+  const autoIndexable = isAutoIndexableRoot(workspaceRoot);
   let closed = false;
   return {
     storage,
@@ -8538,6 +8549,7 @@ async function composeFromEnv(opts) {
     providerId,
     storageBackend,
     managed,
+    autoIndexable,
     dbPath,
     reranker,
     rerankId,
@@ -8912,7 +8924,7 @@ var changedSinceInput = {
 };
 var emptyInput = {};
 function registerTools(server, deps) {
-  const { storage, retriever, workspaceRoot, workspaceId, workspaceName, regionMode, providerId, storageBackend, reranker, rerankTopN, queryRewriter } = deps;
+  const { storage, embedder, retriever, workspaceRoot, workspaceId, workspaceName, regionMode, providerId, storageBackend, managed, autoIndexable, dbPath, reranker, rerankTopN, queryRewriter } = deps;
   server.registerTool("search_code", {
     title: "Hybrid code search",
     description: (
@@ -8946,7 +8958,7 @@ ${hyp}`;
         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 (a real minted prom_live_\u2026 key) or a provider key (e.g. VOYAGE_API_KEY) to enable semantic ranking. Cause: ${vectorError}`);
+        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;
@@ -8981,7 +8993,7 @@ ${hyp}`;
     };
     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 a valid embedding key (PROMETHEUS_API_KEY = a real minted prom_live_\u2026 key, or e.g. VOYAGE_API_KEY) to enable semantic ranking.";
+      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);
@@ -9140,6 +9152,50 @@ ${hyp}`;
       languages
     });
   });
+  server.registerTool("index_status", {
+    title: "Index status / health check",
+    description: "Health check for this workspace's code index. Reports the resolved workspace root, the on-disk index path, whether auto-indexing is enabled AND allowed for this root (it is refused for the home directory / filesystem root), how much is indexed (files / symbols / references + per-language counts), the embedding provider, and \u2014 best-effort, zero-cost \u2014 whether embeddings are reachable with the configured key. CALL THIS FIRST when `search_code` returns nothing, when you're unsure whether the right folder is indexed, or to confirm the API key works.",
+    inputSchema: emptyInput
+  }, async () => {
+    const [stats, languages] = await Promise.all([
+      storage.stats(),
+      languageDistribution(storage)
+    ]);
+    const indexed = stats.fileCount > 0;
+    let embeddingsReachable = null;
+    let embeddingsError = null;
+    const resolveIdentity = embedder.resolveIdentity;
+    if (typeof resolveIdentity === "function") {
+      try {
+        await resolveIdentity.call(embedder);
+        embeddingsReachable = true;
+      } catch (err) {
+        embeddingsReachable = false;
+        embeddingsError = err instanceof Error ? err.message : String(err);
+      }
+    }
+    const autoIndexReason = !managed ? "disabled \u2014 no PROMETHEUS_API_KEY (keyword + symbol-graph only)" : autoIndexable ? "enabled \u2014 indexing this workspace" : "SKIPPED \u2014 workspace is your home directory or a filesystem root; open a project folder or set PROMETHEUS_WORKSPACE_ROOT, then restart";
+    const summary = indexed ? `Indexed ${stats.fileCount} files / ${stats.symbolCount} symbols at ${workspaceRoot}.` : managed && !autoIndexable ? `Empty index: auto-indexing was refused because the workspace resolved to ${workspaceRoot} (home/root). Open your project folder and restart.` : managed ? `Empty index: indexing may still be running, or this folder has no supported source files. Workspace: ${workspaceRoot}.` : `Empty index: no API key, so nothing was embedded/indexed. Semantic search is off; lexical + structural tools still work. Workspace: ${workspaceRoot}.`;
+    return textResult({
+      installed: true,
+      workspace: { id: workspaceId, name: workspaceName, root: workspaceRoot },
+      storage: { backend: storageBackend, dbPath, regionMode },
+      autoIndex: { managed, allowedForThisRoot: autoIndexable, reason: autoIndexReason },
+      index: {
+        indexed,
+        files: stats.fileCount,
+        symbols: stats.symbolCount,
+        references: stats.referenceCount,
+        languages
+      },
+      embeddings: {
+        provider: providerId,
+        reachable: embeddingsReachable,
+        ...embeddingsError !== null ? { error: embeddingsError } : {}
+      },
+      summary
+    });
+  });
 }
 
 // dist/server.js
@@ -9225,8 +9281,12 @@ async function main() {
     process.stderr.write(`prometheus-context-mcp: storage=${composed.storageBackend} provider=${composed.providerId} region-mode=${composed.regionMode} managed=${composed.managed} workspace=${composed.workspaceRoot} (via ${via})${composed.dbPath !== null ? ` db=${composed.dbPath}` : ""}
 `);
     registerTools(server, composed);
-    if (composed.managed)
+    if (composed.managed && composed.autoIndexable) {
       managedIndexer = startManagedIndexing(composed);
+    } else if (composed.managed && !composed.autoIndexable) {
+      process.stderr.write(`prometheus-context-mcp: workspace resolved to ${composed.workspaceRoot} (your home directory or a filesystem root) \u2014 NOT auto-indexing it. Open a project folder (Claude Code passes it via CLAUDE_PROJECT_DIR) or set PROMETHEUS_WORKSPACE_ROOT to your repo, then restart. Call index_status for details.
+`);
+    }
   };
   if (eagerVia !== null) {
     await boot(void 0, eagerVia);

package/package.json

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