@danielblomma/cortex-mcp 2.0.2 → 2.0.3

package/README.md

@@ -255,30 +255,9 @@ Input:
 - `depth` (int, 1-3, default `1`)
 - `include_edges` (bool, default `true`)
 
-### `context.find_callers`
+### `context.impact`
 
-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.
+Traverse likely impact paths across config, code and SQL starting from an entity id or query.
 
 Input:
 
@@ -286,8 +265,9 @@ Input:
 - `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`)
+- `profile` (`"all"` | `"config_only"` | `"config_to_sql"` | `"code_only"` | `"sql_only"`, default `"all"`)
+- `sort_by` (`"impact_score"` | `"shortest_path"` | `"semantic_score"` | `"graph_score"` | `"trust_score"`, default `"impact_score"`)
 
 ### `context.get_rules`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "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/src/core/telemetry/collector.ts

@@ -95,6 +95,43 @@ export type TelemetryEvent = {
   duration_ms?: number;
 };
 
+function subtractCounter(current: number, pushed: number): number {
+  return Math.max(0, current - pushed);
+}
+
+function hasUsage(metrics: TelemetryMetrics): boolean {
+  if (
+    metrics.total_tool_calls > 0 ||
+    metrics.successful_tool_calls > 0 ||
+    metrics.failed_tool_calls > 0 ||
+    metrics.total_duration_ms > 0 ||
+    metrics.session_starts > 0 ||
+    metrics.session_ends > 0 ||
+    metrics.session_duration_ms_total > 0 ||
+    metrics.searches > 0 ||
+    metrics.related_lookups > 0 ||
+    metrics.caller_lookups > 0 ||
+    metrics.trace_lookups > 0 ||
+    metrics.impact_analyses > 0 ||
+    metrics.rule_lookups > 0 ||
+    metrics.reloads > 0 ||
+    metrics.total_results_returned > 0 ||
+    metrics.estimated_tokens_saved > 0 ||
+    metrics.estimated_tokens_total > 0
+  ) {
+    return true;
+  }
+
+  return Object.values(metrics.tool_metrics).some(
+    (bucket) =>
+      bucket.calls > 0 ||
+      bucket.failures > 0 ||
+      bucket.total_duration_ms > 0 ||
+      bucket.total_results_returned > 0 ||
+      bucket.estimated_tokens_saved > 0,
+  );
+}
+
 export class TelemetryCollector {
   private metrics: TelemetryMetrics;
   private readonly metricsPath: string;
@@ -167,6 +204,7 @@ export class TelemetryCollector {
       case "context.trace_calls":
         this.metrics.trace_lookups++;
         break;
+      case "context.impact":
       case "context.impact_analysis":
         this.metrics.impact_analyses++;
         break;
@@ -211,7 +249,143 @@ export class TelemetryCollector {
   }
 
   getMetrics(): TelemetryMetrics {
-    return { ...this.metrics };
+    return {
+      ...this.metrics,
+      tool_metrics: Object.fromEntries(
+        Object.entries(this.metrics.tool_metrics).map(([toolName, bucket]) => [
+          toolName,
+          { ...bucket },
+        ]),
+      ),
+    };
+  }
+
+  acknowledgePush(pushed: TelemetryMetrics): void {
+    const nextToolMetrics: TelemetryMetrics["tool_metrics"] = {};
+    const toolNames = new Set([
+      ...Object.keys(this.metrics.tool_metrics),
+      ...Object.keys(pushed.tool_metrics ?? {}),
+    ]);
+
+    for (const toolName of toolNames) {
+      const currentBucket = this.metrics.tool_metrics[toolName] ?? {
+        calls: 0,
+        failures: 0,
+        total_duration_ms: 0,
+        total_results_returned: 0,
+        estimated_tokens_saved: 0,
+      };
+      const pushedBucket = pushed.tool_metrics?.[toolName] ?? {
+        calls: 0,
+        failures: 0,
+        total_duration_ms: 0,
+        total_results_returned: 0,
+        estimated_tokens_saved: 0,
+      };
+
+      const nextBucket = {
+        calls: subtractCounter(currentBucket.calls, pushedBucket.calls),
+        failures: subtractCounter(currentBucket.failures, pushedBucket.failures),
+        total_duration_ms: subtractCounter(
+          currentBucket.total_duration_ms,
+          pushedBucket.total_duration_ms,
+        ),
+        total_results_returned: subtractCounter(
+          currentBucket.total_results_returned,
+          pushedBucket.total_results_returned,
+        ),
+        estimated_tokens_saved: subtractCounter(
+          currentBucket.estimated_tokens_saved,
+          pushedBucket.estimated_tokens_saved,
+        ),
+      };
+
+      if (
+        nextBucket.calls > 0 ||
+        nextBucket.failures > 0 ||
+        nextBucket.total_duration_ms > 0 ||
+        nextBucket.total_results_returned > 0 ||
+        nextBucket.estimated_tokens_saved > 0
+      ) {
+        nextToolMetrics[toolName] = nextBucket;
+      }
+    }
+
+    const nextMetrics: TelemetryMetrics = {
+      ...this.metrics,
+      period_start: pushed.period_end,
+      total_tool_calls: subtractCounter(
+        this.metrics.total_tool_calls,
+        pushed.total_tool_calls,
+      ),
+      successful_tool_calls: subtractCounter(
+        this.metrics.successful_tool_calls,
+        pushed.successful_tool_calls,
+      ),
+      failed_tool_calls: subtractCounter(
+        this.metrics.failed_tool_calls,
+        pushed.failed_tool_calls,
+      ),
+      total_duration_ms: subtractCounter(
+        this.metrics.total_duration_ms,
+        pushed.total_duration_ms,
+      ),
+      session_starts: subtractCounter(
+        this.metrics.session_starts,
+        pushed.session_starts,
+      ),
+      session_ends: subtractCounter(this.metrics.session_ends, pushed.session_ends),
+      session_duration_ms_total: subtractCounter(
+        this.metrics.session_duration_ms_total,
+        pushed.session_duration_ms_total,
+      ),
+      searches: subtractCounter(this.metrics.searches, pushed.searches),
+      related_lookups: subtractCounter(
+        this.metrics.related_lookups,
+        pushed.related_lookups,
+      ),
+      caller_lookups: subtractCounter(
+        this.metrics.caller_lookups,
+        pushed.caller_lookups,
+      ),
+      trace_lookups: subtractCounter(
+        this.metrics.trace_lookups,
+        pushed.trace_lookups,
+      ),
+      impact_analyses: subtractCounter(
+        this.metrics.impact_analyses,
+        pushed.impact_analyses,
+      ),
+      rule_lookups: subtractCounter(
+        this.metrics.rule_lookups,
+        pushed.rule_lookups,
+      ),
+      reloads: subtractCounter(this.metrics.reloads, pushed.reloads),
+      total_results_returned: subtractCounter(
+        this.metrics.total_results_returned,
+        pushed.total_results_returned,
+      ),
+      estimated_tokens_saved: subtractCounter(
+        this.metrics.estimated_tokens_saved,
+        pushed.estimated_tokens_saved,
+      ),
+      estimated_tokens_total: subtractCounter(
+        this.metrics.estimated_tokens_total,
+        pushed.estimated_tokens_total,
+      ),
+      client_version: this.clientVersion,
+      instance_id: this.instanceId,
+      tool_metrics: nextToolMetrics,
+    };
+
+    if (hasUsage(nextMetrics)) {
+      this.metrics = nextMetrics;
+      this.metrics.period_end = new Date().toISOString();
+    } else {
+      this.metrics = emptyMetrics(this.clientVersion, this.instanceId);
+    }
+
+    this.dirty = true;
   }
 
   flush(): void {

package/scaffold/mcp/src/daemon/main.ts

@@ -1,5 +1,6 @@
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
 import { basename, join } from "node:path";
+import { randomUUID } from "node:crypto";
 import { CortexDaemon } from "./server.js";
 import type {
   PolicyCheckPayload,
@@ -11,7 +12,7 @@ import type {
 } from "./protocol.js";
 import { loadEnterpriseConfig, resolveEnterpriseActivation } from "../core/config.js";
 import { pushMetrics } from "../enterprise/telemetry/sync.js";
-import type { TelemetryMetrics } from "../core/telemetry/collector.js";
+import { TelemetryCollector, type TelemetryMetrics } from "../core/telemetry/collector.js";
 import { AuditWriter, type AuditEntry } from "../core/audit/writer.js";
 import { PolicyStore } from "../core/policy/store.js";
 import {
@@ -89,6 +90,76 @@ function readMetrics(contextDir: string): TelemetryMetrics | null {
   }
 }
 
+// Pending-push state: snapshot + push_id are written to disk before the
+// network call. If the daemon crashes mid-push, the next tick replays the
+// same push_id so the server can deduplicate.
+type PendingPush = {
+  snapshot: TelemetryMetrics;
+  push_id: string;
+  written_at: string;
+};
+
+function pendingPushPath(contextDir: string): string {
+  return join(contextDir, "telemetry", "pending-push.json");
+}
+
+function readPendingPush(contextDir: string): PendingPush | null {
+  const path = pendingPushPath(contextDir);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as PendingPush;
+  } catch {
+    return null;
+  }
+}
+
+function writePendingPush(contextDir: string, pending: PendingPush): void {
+  const path = pendingPushPath(contextDir);
+  mkdirSync(join(contextDir, "telemetry"), { recursive: true });
+  writeFileSync(path, JSON.stringify(pending, null, 2), "utf8");
+}
+
+function deletePendingPush(contextDir: string): void {
+  const path = pendingPushPath(contextDir);
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // best effort
+  }
+}
+
+function ackOnDisk(contextDir: string, pushed: TelemetryMetrics): void {
+  const collector = new TelemetryCollector(contextDir, pushed.client_version || "unknown");
+  collector.acknowledgePush(pushed);
+  collector.flush();
+}
+
+// Per-cwd exponential backoff so a flapping endpoint doesn't get hammered.
+// 1m, 2m, 4m, 8m, 16m, cap 30m. Reset on success.
+type TelemetryBackoffState = { nextPushAt: number; consecutiveFailures: number };
+const telemetryBackoff = new Map<string, TelemetryBackoffState>();
+const TELEMETRY_BACKOFF_BASE_MS = 60_000;
+const TELEMETRY_BACKOFF_CAP_MS = 30 * 60_000;
+
+function shouldSkipTelemetryPush(cwd: string, now = Date.now()): boolean {
+  const state = telemetryBackoff.get(cwd);
+  return state ? now < state.nextPushAt : false;
+}
+
+function recordTelemetryPushOutcome(cwd: string, success: boolean, now = Date.now()): void {
+  if (success) {
+    telemetryBackoff.delete(cwd);
+    return;
+  }
+  const prev = telemetryBackoff.get(cwd) ?? { nextPushAt: 0, consecutiveFailures: 0 };
+  const failures = prev.consecutiveFailures + 1;
+  const delay = Math.min(TELEMETRY_BACKOFF_BASE_MS * 2 ** (failures - 1), TELEMETRY_BACKOFF_CAP_MS);
+  telemetryBackoff.set(cwd, {
+    consecutiveFailures: failures,
+    nextPushAt: now + delay,
+  });
+}
+
 async function telemetryFlush(
   payload: TelemetryFlushPayload,
 ): Promise<TelemetryFlushResult> {
@@ -111,31 +182,68 @@ async function telemetryFlush(
     return { flushed: false, events_pushed: 0 };
   }
 
+  if (shouldSkipTelemetryPush(cwd)) {
+    return { flushed: false, events_pushed: 0 };
+  }
+
+  const repo = basename(cwd);
+  const endpoint = config.telemetry.endpoint;
+  const apiKey = config.telemetry.api_key;
+
+  // Recovery: if a pending push exists, retry it first with the same
+  // push_id so the server can deduplicate against an earlier in-flight
+  // attempt that may have crashed before delete.
+  const pending = readPendingPush(contextDir);
+  if (pending) {
+    const result = await pushMetrics(pending.snapshot, endpoint, apiKey, {
+      repo,
+      session_id: payload.session_id,
+      push_id: pending.push_id,
+    });
+    recordTelemetryPushOutcome(cwd, result.success);
+    if (!result.success) {
+      process.stderr.write(
+        `[cortex-daemon] pending telemetry push retry failed: ${result.error ?? "unknown"}\n`,
+      );
+      return { flushed: false, events_pushed: 0 };
+    }
+    ackOnDisk(contextDir, pending.snapshot);
+    deletePendingPush(contextDir);
+    return { flushed: true, events_pushed: pending.snapshot.total_tool_calls };
+  }
+
   const metrics = readMetrics(contextDir);
   if (!metrics) {
-    // No metrics on disk yet — MCP probably hasn't flushed once. Nothing
-    // to push from disk. (MCP's interval flush + session-end push handle
-    // the in-memory case.)
+    // No metrics on disk yet — MCP hasn't flushed. Nothing to push.
     return { flushed: false, events_pushed: 0 };
   }
 
-  const result = await pushMetrics(
-    metrics,
-    config.telemetry.endpoint,
-    config.telemetry.api_key,
-    {
-      repo: basename(cwd),
-      session_id: payload.session_id,
-    },
-  );
+  const push_id = randomUUID();
+  writePendingPush(contextDir, {
+    snapshot: metrics,
+    push_id,
+    written_at: new Date().toISOString(),
+  });
+
+  const result = await pushMetrics(metrics, endpoint, apiKey, {
+    repo,
+    session_id: payload.session_id,
+    push_id,
+  });
+
+  recordTelemetryPushOutcome(cwd, result.success);
 
   if (!result.success) {
     process.stderr.write(
       `[cortex-daemon] telemetry push failed: ${result.error ?? "unknown"}\n`,
     );
+    // Pending stays on disk; next tick (after backoff) will retry.
     return { flushed: false, events_pushed: 0 };
   }
 
+  ackOnDisk(contextDir, metrics);
+  deletePendingPush(contextDir);
+
   return {
     flushed: true,
     events_pushed: metrics.total_tool_calls,
@@ -267,6 +375,33 @@ async function main(): Promise<void> {
       });
   }
 
+  // Periodic telemetry push. Daemon owns the network call so MCP doesn't
+  // race with itself or with this loop. Walks active sessions, dedupes
+  // cwds, and runs the existing per-cwd flush handler.
+  const telemetryPushRaw = parseInt(process.env.CORTEX_TELEMETRY_PUSH_MS ?? "", 10);
+  const telemetryPushMs =
+    Number.isFinite(telemetryPushRaw) && telemetryPushRaw > 0
+      ? telemetryPushRaw
+      : 5 * 60 * 1000;
+  if (process.env.CORTEX_DISABLE_TELEMETRY_PUSH !== "1") {
+    const telemetryTimer = setInterval(async () => {
+      const cwds = new Set<string>();
+      for (const [, state] of tracker.getActiveSessions()) {
+        if (state.cwd) cwds.add(state.cwd);
+      }
+      for (const cwd of cwds) {
+        try {
+          await telemetryFlush({ reason: "interval", cwd });
+        } catch (err) {
+          process.stderr.write(
+            `[cortex-daemon] telemetry push failed for ${cwd}: ${err instanceof Error ? err.message : String(err)}\n`,
+          );
+        }
+      }
+    }, telemetryPushMs);
+    if (typeof telemetryTimer.unref === "function") telemetryTimer.unref();
+  }
+
   if (process.env.CORTEX_DISABLE_TAMPER_CHECK !== "1") {
     const checkTimer = setInterval(() => {
       const detected = tracker.detectTamper({

package/scaffold/mcp/src/enterprise/index.ts

@@ -9,7 +9,6 @@ import {
 } from "../core/config.js";
 import { deployBundledModel } from "./model/deploy.js";
 import { TelemetryCollector } from "../core/telemetry/collector.js";
-import { pushMetrics } from "./telemetry/sync.js";
 import { AuditWriter, type AuditEntry } from "../core/audit/writer.js";
 import { pushAuditEvents, queueAuditEvent, setAuditPushContext } from "./audit/push.js";
 import { PolicyStore } from "../core/policy/store.js";
@@ -203,24 +202,10 @@ export function recordToolActivity(activity: ToolActivity): void {
 export async function onSessionEnd(): Promise<void> {
   if (!activeConfig) return;
   const config = activeConfig;
-  if (config.telemetry.enabled && config.telemetry.endpoint && activeCollector) {
+  // Telemetry push is owned by the daemon. MCP only persists in-memory
+  // metrics to disk so the daemon can pick them up on its next push tick.
+  if (config.telemetry.enabled && activeCollector) {
     activeCollector.flush();
-    try {
-      const result = await pushMetrics(
-        activeCollector.getMetrics(),
-        config.telemetry.endpoint,
-        config.telemetry.api_key,
-        {
-          repo: activeRepo ?? undefined,
-          session_id: activeSessionId ?? undefined,
-        },
-      );
-      if (!result.success) {
-        process.stderr.write(`[cortex-enterprise] Shutdown telemetry push failed: ${result.error}\n`);
-      }
-    } catch (err) {
-      process.stderr.write(`[cortex-enterprise] Shutdown telemetry push error: ${err}\n`);
-    }
   }
 
   await flushComplianceQueues(config, "shutdown");
@@ -351,28 +336,14 @@ export async function register(server: McpServer): Promise<void> {
     process.stderr.write(`[cortex-enterprise] Active: ${features.join(", ")}\n`);
   }
 
-  // Schedule telemetry flush + push
+  // Telemetry push is owned by the daemon (single network writer).
+  // MCP only persists in-memory metrics to disk on a tick so the daemon
+  // can read and push them.
   if (config.telemetry.enabled) {
-    // Push any accumulated metrics from previous sessions on startup
-    if (config.telemetry.endpoint) {
-      pushMetrics(collector.getMetrics(), config.telemetry.endpoint, config.telemetry.api_key, {
-        repo: activeRepo ?? undefined,
-        session_id: activeSessionId ?? undefined,
-      })
-        .then((r) => { if (!r.success) process.stderr.write(`[cortex-enterprise] Startup telemetry push failed: ${r.error}\n`); })
-        .catch((err) => { process.stderr.write(`[cortex-enterprise] Startup telemetry push error: ${err}\n`); });
-    }
-
     const intervalMs = config.telemetry.interval_minutes * 60000;
-    const timer = setInterval(async () => {
+    const timer = setInterval(() => {
       try {
         collector.flush();
-        if (config.telemetry.endpoint) {
-          await pushMetrics(collector.getMetrics(), config.telemetry.endpoint, config.telemetry.api_key, {
-            repo: activeRepo ?? undefined,
-            session_id: activeSessionId ?? undefined,
-          });
-        }
       } catch (err) {
         process.stderr.write(`[cortex-enterprise] Telemetry flush error: ${err}\n`);
       }

package/scaffold/mcp/src/enterprise/privacy/boundary.ts

@@ -67,6 +67,7 @@ export const OUTBOUND_DATA_BOUNDARY = {
 type TelemetryPushContext = {
   repo?: string;
   session_id?: string;
+  push_id?: string;
 };
 
 const MAX_OBJECT_KEYS = 12;
@@ -207,6 +208,7 @@ export function buildTelemetryPushPayload(
     repo: context.repo,
     instance_id: metrics.instance_id,
     session_id: context.session_id,
+    push_id: context.push_id,
     tool_metrics: metrics.tool_metrics,
   };
 }

package/scaffold/mcp/src/enterprise/telemetry/sync.ts

@@ -11,6 +11,7 @@ export type PushResult = {
 export type PushContext = {
   repo?: string;
   session_id?: string;
+  push_id?: string;
 };
 
 let lastPush: PushResult | null = null;

package/scaffold/mcp/src/loadGraph.ts

@@ -443,6 +443,8 @@ async function main(): Promise<void> {
 
   if (reset) {
     fs.rmSync(DB_PATH, { recursive: true, force: true });
+    fs.rmSync(`${DB_PATH}.wal`, { force: true });
+    fs.rmSync(`${DB_PATH}.shm`, { force: true });
   }
   fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
 

package/scaffold/mcp/tests/telemetry-collector.test.mjs

@@ -0,0 +1,30 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { TelemetryCollector } from "../dist/core/telemetry/collector.js";
+
+function createContextDir(prefix) {
+  return mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+test("TelemetryCollector counts context.impact as an impact analysis", () => {
+  const contextDir = createContextDir("cortex-telemetry-");
+  const collector = new TelemetryCollector(contextDir, "test-version");
+
+  collector.recordEvent({
+    tool: "context.impact",
+    phase: "success",
+    result_count: 2,
+    estimated_tokens_saved: 800,
+    duration_ms: 15,
+  });
+
+  const metrics = collector.getMetrics();
+  assert.equal(metrics.total_tool_calls, 1);
+  assert.equal(metrics.successful_tool_calls, 1);
+  assert.equal(metrics.impact_analyses, 1);
+  assert.equal(metrics.tool_metrics["context.impact"].calls, 1);
+});

package/docs/MCP_MARKETPLACE.md

@@ -1,160 +0,0 @@
-# MCP Marketplace Submission
-
-## Package Information
-
-**Name:** `@danielblomma/cortex-mcp`  
-**Description:** Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.  
-**Author:** Daniel Blomma  
-**License:** MIT  
-**Repository:** https://github.com/DanielBlomma/cortex
-
-## MCP Server Details
-
-### Tools Provided
-
-1. **context.search**
-   - Semantic search across indexed entities (files, rules, ADRs)
-   - Hybrid ranking (semantic + graph + trust + recency)
-   - Optional content return for high-signal snippets
-
-2. **context.get_related**
-   - Graph-based entity relationships
-   - Finds connected rules/files/ADRs with optional edge details
-
-3. **context.get_rules**
-   - Active rules and architectural decisions
-   - Scope-based filtering
-
-4. **context.reload**
-   - Hot-reload graph after code changes
-
-### Advanced Features (Experimental)
-
-Cortex can extract function-level chunks and build call graphs in experimental builds:
-
-- `context.find_callers` - What calls this function?
-- `context.trace_calls` - What does this function call?
-- `context.impact_analysis` - What is impacted if this function changes?
-- Requires JavaScript/TypeScript codebase and semantic chunking/call graph indexing enabled.
-
-Note: these APIs are experimental and are not part of the stable tool contract in this submission.
-
-### Installation
-
-#### For MCP Marketplace Users
-
-```bash
-# Install CLI globally
-npm i -g @danielblomma/cortex-mcp
-
-# Navigate to your project
-cd ~/my-project
-
-# Initialize Cortex in your project
-cortex init --bootstrap
-```
-
-This will:
-- Create `.context/` directory with graph schema
-- Set up MCP server for Claude Desktop/Code
-- Start background sync for automatic updates
-- Build a local context graph for indexed files/rules/ADRs
-
-#### Manual MCP Configuration
-
-If `cortex init` doesn't auto-register, add to Claude's MCP config:
-
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-```json
-{
-  "mcpServers": {
-    "cortex": {
-      "command": "cortex",
-      "args": ["mcp"],
-      "env": {
-        "CORTEX_PROJECT_ROOT": "/absolute/path/to/your-project"
-      }
-    }
-  }
-}
-```
-
-**Codex** (`~/.config/codex/mcp-config.json`):
-```json
-{
-  "mcpServers": {
-    "cortex-myproject": {
-      "command": "cortex",
-      "args": ["mcp"],
-      "cwd": "/absolute/path/to/your-project"
-    }
-  }
-}
-```
-
-### Usage
-
-Once installed and initialized, Cortex tools are available in Claude:
-
-```
-"Find files that handle authentication"
-"Show related files for this ADR"
-"What are the active architectural rules for this API?"
-```
-
-### Key Features
-
-- **Semantic search**: ranked retrieval across source files, rules and ADRs
-- **Graph relationships**: quickly discover related entities and constraints
-- **Experimental call graph APIs**: function caller/callee and impact traversal in semantic chunking builds
-- **Local & private**: All data stays on your machine
-- **Incremental updates**: Background sync keeps context fresh
-- **Flexible ingestion**: configurable source paths and ranking signals
-
-### Requirements
-
-- Node.js 18+
-- Git repository (for change tracking)
-- ~50MB disk space per project
-
-### Unique Value Proposition
-
-Unlike other MCP servers that provide external data (GitHub, web search), Cortex provides **deep, structured knowledge of YOUR codebase**:
-
-- Search with semantic ranking across files, rules, and ADRs
-- Understand rule and ADR dependencies in your repo
-- Enforce architectural rules and ADRs
-- Context that evolves with your code
-
-Perfect for:
-- Large codebases where plain keyword search is not enough
-- Refactoring guided by rule and ADR context
-- Onboarding (architectural rules, design decisions)
-- Code review (what constraints and related entities apply?)
-
-### Limitations
-
-- **Setup required**: Not instant plug-and-play (needs `cortex init`)
-- **Per-project**: Each repo needs its own Cortex instance
-- **Local only**: No cloud sync (by design - your code stays private)
-
-### Support
-
-- Issues: https://github.com/DanielBlomma/cortex/issues
-- Docs: https://github.com/DanielBlomma/cortex/blob/main/README.md
-
-## Submission Checklist
-
-- [x] MCP SDK integration (JSON-RPC over stdio)
-- [x] Tools documented with schemas
-- [ ] npm package published (@danielblomma/cortex-mcp)
-- [x] Marketplace-ready README
-- [ ] Example usage screenshots/GIFs
-- [ ] Submit PR to modelcontextprotocol/servers
-
-## Next Steps
-
-1. Publish to npm as `@danielblomma/cortex-mcp`
-2. Test installation from marketplace perspective
-3. Submit to https://github.com/modelcontextprotocol/servers
-4. Add to Anthropic's community registry