@danielblomma/cortex-mcp 0.6.5 → 1.0.1

package/README.md

@@ -131,6 +131,59 @@ Codex (`~/.config/codex/mcp-config.json`):
 }
 ```
 
+## WSL Mode (Windows)
+
+If you run Node.js inside WSL but use Claude Desktop or another MCP client on Windows:
+
+1. Install Cortex inside WSL:
+
+```bash
+# In a WSL terminal
+npm i -g @danielblomma/cortex-mcp
+cd /mnt/c/Users/yourname/your-project
+cortex init --bootstrap
+```
+
+2. Configure Claude Desktop (`%APPDATA%\Claude\claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "cortex": {
+      "command": "wsl.exe",
+      "args": ["--distribution", "Ubuntu", "--exec", "cortex", "mcp"],
+      "env": {
+        "CORTEX_PROJECT_ROOT": "C:\\Users\\yourname\\your-project",
+        "CORTEX_AUTO_BOOTSTRAP_ON_MCP": "1"
+      }
+    }
+  }
+}
+```
+
+Cortex automatically converts Windows paths (e.g. `C:\Users\...`) to WSL paths (`/mnt/c/Users/...`).
+
+For projects on the WSL filesystem (e.g. `~/projects/myapp`), use the WSL path directly:
+
+```json
+{
+  "mcpServers": {
+    "cortex": {
+      "command": "wsl.exe",
+      "args": ["--distribution", "Ubuntu", "--exec", "cortex", "mcp"],
+      "env": {
+        "CORTEX_PROJECT_ROOT": "/home/yourname/projects/myapp",
+        "CORTEX_AUTO_BOOTSTRAP_ON_MCP": "1"
+      }
+    }
+  }
+}
+```
+
+**Notes:**
+- File watching on `/mnt/` paths (Windows filesystem) automatically uses poll mode since `inotify` is unreliable across filesystem boundaries.
+- For best performance, keep projects on the WSL filesystem (`~/...`) rather than `/mnt/c/...`.
+
 ## MCP Tools
 
 ### `context.search`
@@ -154,6 +207,40 @@ Input:
 - `depth` (int, 1-3, default `1`)
 - `include_edges` (bool, default `true`)
 
+### `context.find_callers`
+
+Return chunk callers for a chunk or file entity using the indexed call graph.
+
+Input:
+
+- `entity_id` (string, required)
+- `depth` (int, 1-4, default `1`)
+- `include_edges` (bool, default `true`)
+
+### `context.trace_calls`
+
+Trace call graph neighbors from a chunk or file entity in the requested direction.
+
+Input:
+
+- `entity_id` (string, required)
+- `depth` (int, 1-4, default `2`)
+- `direction` (`"outgoing"` | `"incoming"` | `"both"`, default `"outgoing"`)
+- `include_edges` (bool, default `true`)
+
+### `context.impact_analysis`
+
+Analyze likely impacted call-graph entities starting from an entity id or search query.
+
+Input:
+
+- `entity_id` (string, optional) — either `entity_id` or `query` is required
+- `query` (string, optional)
+- `depth` (int, 1-4, default `2`)
+- `top_k` (int, 1-20, default `8`)
+- `direction` (`"incoming"` | `"outgoing"` | `"both"`, default `"incoming"`)
+- `include_edges` (bool, default `true`)
+
 ### `context.get_rules`
 
 List indexed rules and optionally include inactive rules.

package/bin/cortex.mjs

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
+import { normalizeProjectRoot } from "./wsl.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -599,9 +600,9 @@ async function run() {
   }
 
   if (command === "mcp") {
-    const target = process.env.CORTEX_PROJECT_ROOT
-      ? path.resolve(process.env.CORTEX_PROJECT_ROOT)
-      : process.cwd();
+    const rawTarget = process.env.CORTEX_PROJECT_ROOT || process.cwd();
+    const target = path.resolve(normalizeProjectRoot(rawTarget));
+    process.env.CORTEX_PROJECT_ROOT = target;
     await ensureProjectInitializedForMcp(target);
     ensureProjectInitialized(target);
     const serverEntry = path.join(target, "mcp", "dist", "server.js");

package/bin/wsl.mjs

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+
+let _isWSL = null;
+
+export function isWSL() {
+  if (_isWSL !== null) return _isWSL;
+  try {
+    const version = fs.readFileSync("/proc/version", "utf8");
+    _isWSL = /microsoft|wsl/i.test(version);
+  } catch {
+    _isWSL = false;
+  }
+  return _isWSL;
+}
+
+export function windowsToWslPath(winPath) {
+  const match = winPath.match(/^([A-Za-z]):[/\\](.*)/);
+  if (!match) return winPath;
+  const drive = match[1].toLowerCase();
+  const rest = match[2].replace(/\\/g, "/").replace(/\/+$/, "");
+  return `/mnt/${drive}/${rest}`;
+}
+
+export function normalizeProjectRoot(rawPath) {
+  if (!isWSL()) return rawPath;
+  if (/^[A-Za-z]:[/\\]/.test(rawPath)) {
+    return windowsToWslPath(rawPath);
+  }
+  return rawPath;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "0.6.5",
+  "version": "1.0.1",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",

package/scaffold/mcp/package-lock.json

@@ -33,9 +33,9 @@
       }
     },
     "node_modules/@hono/node-server": {
-      "version": "1.19.10",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.10.tgz",
-      "integrity": "sha512-hZ7nOssGqRgyV3FVVQdfi+U4q02uB23bpnYpdvNXkYTRRyWx84b7yf1ans+dnJ/7h41sGL3CeQTfO+ZGxuO+Iw==",
+      "version": "1.19.13",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.13.tgz",
+      "integrity": "sha512-TsQLe4i2gvoTtrHje625ngThGBySOgSK3Xo2XRYOdqGN1teR8+I7vchQC46uLJi8OF62YTYA3AhSpumtkhsaKQ==",
       "license": "MIT",
       "engines": {
         "node": ">=18.14.1"
@@ -236,6 +236,7 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.13.tgz",
       "integrity": "sha512-akNQMv0wW5uyRpD2v2IEyRSZiR+BeGuoB6L310EgGObO44HSMNT8z1xzio28V8qOrgYaopIDNA18YgdXd+qTiw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -1284,10 +1285,11 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.7",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.7.tgz",
-      "integrity": "sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw==",
+      "version": "4.12.12",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.12.tgz",
+      "integrity": "sha512-p1JfQMKaceuCbpJKAPKVqyqviZdS0eUxH9v82oWo1kb9xjQ5wA6iP3FNVAPDFlz5/p7d45lO+BpSk1tuSZMF4Q==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
@@ -2444,6 +2446,7 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -2602,6 +2605,7 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
       "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
       "license": "MIT",
+      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

package/scaffold/mcp/src/paths.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { RankingWeights } from "./types.js";
@@ -5,9 +6,23 @@ import type { RankingWeights } from "./types.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+function normalizeForWsl(rawPath: string): string {
+  const winMatch = rawPath.match(/^([A-Za-z]):[/\\](.*)/);
+  if (!winMatch) return rawPath;
+  try {
+    const version = fs.readFileSync("/proc/version", "utf8");
+    if (!/microsoft|wsl/i.test(version)) return rawPath;
+  } catch {
+    return rawPath;
+  }
+  const drive = winMatch[1].toLowerCase();
+  const rest = winMatch[2].replace(/\\/g, "/").replace(/\/+$/, "");
+  return `/mnt/${drive}/${rest}`;
+}
+
 const PROJECT_ROOT_OVERRIDE = process.env.CORTEX_PROJECT_ROOT?.trim();
 export const REPO_ROOT = PROJECT_ROOT_OVERRIDE
-  ? path.resolve(PROJECT_ROOT_OVERRIDE)
+  ? path.resolve(normalizeForWsl(PROJECT_ROOT_OVERRIDE))
   : path.resolve(__dirname, "../..");
 export const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
 export const CACHE_DIR = path.join(CONTEXT_DIR, "cache");

package/scaffold/scripts/memory-compile.mjs

@@ -6,8 +6,17 @@ import { parseFrontmatter, parseStringList } from "../mcp/dist/frontmatter.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+
+function normalizeForWsl(rawPath) {
+  const m = rawPath.match(/^([A-Za-z]):[/\\](.*)/);
+  if (!m) return rawPath;
+  try { if (!/microsoft|wsl/i.test(fs.readFileSync("/proc/version", "utf8"))) return rawPath; }
+  catch { return rawPath; }
+  return `/mnt/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/").replace(/\/+$/, "")}`;
+}
+
 const REPO_ROOT = process.env.CORTEX_PROJECT_ROOT
-  ? path.resolve(process.env.CORTEX_PROJECT_ROOT)
+  ? path.resolve(normalizeForWsl(process.env.CORTEX_PROJECT_ROOT))
   : path.resolve(__dirname, "..");
 const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
 const MEMORY_DIR = path.join(CONTEXT_DIR, "memory");

package/scaffold/scripts/memory-lint.mjs

@@ -6,8 +6,17 @@ import { parseFrontmatter, parseStringList } from "../mcp/dist/frontmatter.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+
+function normalizeForWsl(rawPath) {
+  const m = rawPath.match(/^([A-Za-z]):[/\\](.*)/);
+  if (!m) return rawPath;
+  try { if (!/microsoft|wsl/i.test(fs.readFileSync("/proc/version", "utf8"))) return rawPath; }
+  catch { return rawPath; }
+  return `/mnt/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/").replace(/\/+$/, "")}`;
+}
+
 const REPO_ROOT = process.env.CORTEX_PROJECT_ROOT
-  ? path.resolve(process.env.CORTEX_PROJECT_ROOT)
+  ? path.resolve(normalizeForWsl(process.env.CORTEX_PROJECT_ROOT))
   : path.resolve(__dirname, "..");
 const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
 const MEMORY_DIR = path.join(CONTEXT_DIR, "memory");

package/scaffold/scripts/watch.sh

@@ -84,10 +84,18 @@ detect_event_backend() {
   return 1
 }
 
+is_wsl_mnt_path() {
+  grep -qi microsoft /proc/version 2>/dev/null && [[ "$REPO_ROOT" == /mnt/* ]]
+}
+
 resolve_mode() {
   case "$WATCH_MODE" in
     auto)
-      if EVENT_BACKEND="$(detect_event_backend)"; then
+      if is_wsl_mnt_path; then
+        echo "[watch] WSL detected with /mnt/ path, using poll mode (inotify unreliable on Windows mounts)"
+        WATCH_MODE="poll"
+        EVENT_BACKEND=""
+      elif EVENT_BACKEND="$(detect_event_backend)"; then
         WATCH_MODE="event"
       else
         WATCH_MODE="poll"