@danielblomma/cortex-mcp 1.3.1 → 1.4.0

package/README.md

@@ -2,30 +2,78 @@
   <img src="docs/logo.png" alt="Cortex" width="600" />
 </p>
 
-# Cortex MCP
+# Cortex
+
+**The context layer for AI-assisted software engineering.**
 
 [![npm version](https://img.shields.io/npm/v/%40danielblomma%2Fcortex-mcp)](https://www.npmjs.com/package/@danielblomma/cortex-mcp)
 [![npm downloads](https://img.shields.io/npm/dw/%40danielblomma%2Fcortex-mcp)](https://www.npmjs.com/package/@danielblomma/cortex-mcp)
+[![license](https://img.shields.io/npm/l/%40danielblomma%2Fcortex-mcp)](./LICENSE)
 
-`@danielblomma/cortex-mcp` is a local, repo-scoped context platform for coding assistants.
-It indexes your codebase into structured entities (files, rules, ADRs) and exposes that context over MCP (JSON-RPC over stdio).
+---
 
-![Cortex install and bootstrap demo](https://raw.githubusercontent.com/DanielBlomma/cortex/main/docs/install-demo.gif)
+## What Cortex is
 
-## Why Use Cortex
+Cortex is a local, repository-scoped context engine for coding assistants. It parses your source code with tree-sitter, indexes it into a structured knowledge graph of entities (files, symbols, rules, ADRs) and their relationships (calls, defines, constrains, implements, supersedes), and serves that context to AI assistants over the Model Context Protocol (MCP).
 
-- Semantic search across code and documentation.
-- Graph relationships between entities and architectural constraints.
-- Local-first: your code and context stay on your machine.
-- Incremental updates keep context fresh as the repo changes.
-- Works with Claude Code/Desktop and Codex MCP clients.
+Where a general-purpose AI assistant sees your codebase as a pile of text files, Cortex gives it a precise map: what exists, how it is connected, which rules govern it, and which parts are source-of-truth versus deprecated.
+
+Cortex runs entirely on the developer's machine. Source code never leaves the host.
+
+## When to use Cortex
+
+Cortex is designed for engineering teams that rely on AI assistants for non-trivial work on real codebases. Use it when:
+
+- Your codebase is large or fragmented enough that assistants waste context window on irrelevant files.
+- You need assistants to respect architectural rules, deprecations, and source-of-truth decisions already made by the team.
+- You work across multiple languages and want consistent, structured retrieval across all of them.
+- Security or compliance requires that source code stay on-premise and that all AI interactions remain auditable.
+- You want retrieval to surface *existing* functionality before an assistant proposes new code — reducing duplication and drift.
+
+Cortex is not a replacement for your editor, your version control, or your coding assistant. It is the grounding layer that makes those assistants act with knowledge of your specific repository.
+
+## Benefits
+
+- **Higher-quality suggestions.** Assistants see the right files and rules instead of guessing from filenames.
+- **Lower token cost.** Targeted retrieval replaces broad file reads. Typical sessions use a fraction of the context a raw assistant would consume.
+- **Architectural governance.** Rules and ADRs are surfaced with every answer, so assistants follow the team's established patterns rather than generic best practices.
+- **Multi-language coverage.** A single engine indexes multiple languages through tree-sitter grammars, giving polyglot teams consistent tooling.
+- **Privacy by design.** Your code and its derived index stay on your machine. No upload, no cloud dependency for the core product.
+- **Low friction.** One command (`cortex init --bootstrap`) scaffolds everything: indexing, git hooks, MCP registration for Claude Code, Claude Desktop, and Codex.
+
+## How it works
+
+Cortex operates as a five-stage pipeline between your repository and your AI assistant.
+
+1. **Ingestion.** Source files are parsed with tree-sitter, producing structured entities (files, functions, classes, rules, ADRs) and relations (`CALLS`, `DEFINES`, `CONSTRAINS`, `IMPLEMENTS`, `IMPORTS`, `SUPERSEDES`).
+2. **Storage.** Entities and relations are persisted to a local graph database (RyuGraph). An optional vector index provides semantic search across entity content.
+3. **Retrieval.** MCP tools combine semantic search with graph traversal to assemble the smallest context package that answers the task.
+4. **Policy.** Architectural rules and source-of-truth markers filter conflicting or deprecated content before it reaches the assistant.
+5. **Assembly.** Results are delivered to the assistant as a compact, ranked context package over MCP.
+
+Git hooks keep the index fresh on every checkout, pull, commit, and rewrite. A live TUI dashboard (`cortex dashboard`) shows what Cortex adds to the repository in real time.
+
+## Why it works
+
+Modern coding assistants are bottlenecked by context, not by model capability. Feeding a model more files rarely helps; feeding it the *right* files almost always does.
+
+Cortex is built on one principle: **prefer retrieval quality over analysis completeness.** A smaller, sharper context package outperforms a broad dump of files. Every component — from tree-sitter parsing to graph traversal to rule filtering — exists to raise the signal-to-noise ratio of what the assistant sees.
+
+The result is an assistant that behaves as if it already knows your codebase, because — through Cortex — it does.
+
+## Quick demo
+
+![Cortex install and bootstrap demo](https://raw.githubusercontent.com/DanielBlomma/cortex/main/docs/install-demo.gif)
 
-## Core Features
+## Core capabilities
 
-- Semantic search across files, rules, and ADRs.
+- Semantic search across code, rules, and ADRs.
 - Graph relationships between entities and architectural constraints.
-- Architectural rules and ADR context for implementation decisions.
-- Live TUI dashboard showing what Cortex adds to your repo.
+- Call-graph traversal, caller lookup, and impact analysis.
+- Architectural rules and ADR enforcement at retrieval time.
+- Incremental index updates driven by git hooks.
+- Live TUI dashboard showing what Cortex adds to your repository.
+- First-class integrations with Claude Code, Claude Desktop, and Codex.
 
 ## Requirements
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",
@@ -46,7 +46,7 @@
     "docs/MCP_MARKETPLACE.md"
   ],
   "scripts": {
-    "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.test.mjs tests/javascript-parser.test.mjs tests/sql-parser.test.mjs tests/config-parser.test.mjs tests/resources-parser.test.mjs tests/vbnet-parser.test.mjs tests/cpp-parser.test.mjs tests/multi-level.test.mjs",
+    "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.test.mjs tests/javascript-parser.test.mjs tests/sql-parser.test.mjs tests/config-parser.test.mjs tests/resources-parser.test.mjs tests/vbnet-parser.test.mjs tests/cpp-parser.test.mjs tests/multi-level.test.mjs tests/no-legacy-paths.test.mjs",
     "release:sync-version": "node scripts/sync-release-version.mjs",
     "release:check-version-sync": "node scripts/sync-release-version.mjs --check",
     "prepublishOnly": "echo 'Ready to publish to npm'"

package/scaffold/mcp/package-lock.json

@@ -236,7 +236,6 @@
       "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"
       }
@@ -1285,11 +1284,10 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.12",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.12.tgz",
-      "integrity": "sha512-p1JfQMKaceuCbpJKAPKVqyqviZdS0eUxH9v82oWo1kb9xjQ5wA6iP3FNVAPDFlz5/p7d45lO+BpSk1tuSZMF4Q==",
+      "version": "4.12.14",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.14.tgz",
+      "integrity": "sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
@@ -2446,7 +2444,6 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -2605,7 +2602,6 @@
       "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/package.json

@@ -20,7 +20,7 @@
   "overrides": {
     "cmake-js": "^8.0.0",
     "express-rate-limit": "^8.3.1",
-    "hono": "^4.12.12",
+    "hono": "^4.12.14",
     "@hono/node-server": "^1.19.13",
     "tar": "^7.5.11"
   },

package/scaffold/scripts/dashboard.mjs

@@ -543,6 +543,19 @@ function emptyLine(width) {
   return col("│", C.gray) + " ".repeat(width - 2) + col("│", C.gray);
 }
 
+// ── Edition detection ────────────────────────────────────────
+import { createRequire } from "node:module";
+const __require = createRequire(import.meta.url);
+
+function detectEdition() {
+  try {
+    __require.resolve("@danielblomma/cortex-enterprise");
+    return "Enterprise";
+  } catch {
+    return "Community";
+  }
+}
+
 // ── Render sections ──────────────────────────────────────────
 function render(data, isTTY) {
   const termWidth = process.stdout.columns || 80;
@@ -551,7 +564,8 @@ function render(data, isTTY) {
 
   // Header
   const clock = new Date().toLocaleTimeString("sv-SE", { hour: "2-digit", minute: "2-digit" });
-  const title = "─ cortex dashboard ";
+  const edition = detectEdition();
+  const title = `─ cortex dashboard [${edition}] `;
   const clockPart = ` ${clock} ─`;
   const fillLen = w - 2 - title.length - clockPart.length;
   lines.push(col(`┌${title}${"─".repeat(Math.max(0, fillLen))}${clockPart}┐`, C.gray));

package/scaffold/scripts/doctor.sh

@@ -221,19 +221,59 @@ if [[ -n "$ENTERPRISE_CONFIG" ]]; then
     console.log(fields["policy.endpoint"] || "");
   ' "$ENTERPRISE_CONFIG" 2>/dev/null || echo "")
 
+  TELEMETRY_API_KEY=$(node -e '
+    const fs = require("node:fs");
+    const raw = fs.readFileSync(process.argv[1], "utf8");
+    let section = "", fields = {};
+    for (const line of raw.split("\n")) {
+      const t = line.trimEnd();
+      if (!t || t.startsWith("#")) continue;
+      const sm = t.match(/^(\w+):\s*$/);
+      if (sm) { section = sm[1]; continue; }
+      const kv = t.match(/^\s+(\w+):\s*(.+?)\s*$/);
+      if (kv && section) fields[section + "." + kv[1]] = kv[2].replace(/^["\x27]|["\x27]$/g, "");
+    }
+    console.log(fields["telemetry.api_key"] || "");
+  ' "$ENTERPRISE_CONFIG" 2>/dev/null || echo "")
+
+  POLICY_API_KEY=$(node -e '
+    const fs = require("node:fs");
+    const raw = fs.readFileSync(process.argv[1], "utf8");
+    let section = "", fields = {};
+    for (const line of raw.split("\n")) {
+      const t = line.trimEnd();
+      if (!t || t.startsWith("#")) continue;
+      const sm = t.match(/^(\w+):\s*$/);
+      if (sm) { section = sm[1]; continue; }
+      const kv = t.match(/^\s+(\w+):\s*(.+?)\s*$/);
+      if (kv && section) fields[section + "." + kv[1]] = kv[2].replace(/^["\x27]|["\x27]$/g, "");
+    }
+    console.log(fields["policy.api_key"] || "");
+  ' "$ENTERPRISE_CONFIG" 2>/dev/null || echo "")
+
   # Telemetry
   if [[ -n "$TELEMETRY_ENDPOINT" ]]; then
     pass "Telemetry: endpoint configured"
-    HTTP_CODE=$(curl -so /dev/null -w '%{http_code}' --max-time 5 -X POST \
-      -H "Content-Type: application/json" \
-      -d '{}' \
-      "$TELEMETRY_ENDPOINT" 2>/dev/null | tail -c 3 || echo "000")
+    TELEMETRY_CURL_ARGS=(-so /dev/null -w '%{http_code}' --max-time 5 -X POST \
+      -H "Content-Type: application/json" -d '{}')
+    if [[ -n "$TELEMETRY_API_KEY" ]]; then
+      TELEMETRY_CURL_ARGS+=(-H "Authorization: Bearer ${TELEMETRY_API_KEY}")
+    fi
+    HTTP_CODE=$(curl "${TELEMETRY_CURL_ARGS[@]}" "$TELEMETRY_ENDPOINT" 2>/dev/null | tail -c 3 || echo "000")
     if [[ "$HTTP_CODE" == "000" ]]; then
       fail "Telemetry: endpoint not reachable (timeout/DNS)"
     elif [[ "$HTTP_CODE" =~ ^[23] ]]; then
-      pass "Telemetry: endpoint reachable (HTTP ${HTTP_CODE})"
-    elif [[ "$HTTP_CODE" == "401" ]]; then
-      pass "Telemetry: endpoint reachable (auth required — expected)"
+      if [[ -n "$TELEMETRY_API_KEY" ]]; then
+        pass "Telemetry: endpoint authenticated (HTTP ${HTTP_CODE})"
+      else
+        pass "Telemetry: endpoint reachable (HTTP ${HTTP_CODE})"
+      fi
+    elif [[ "$HTTP_CODE" == "401" || "$HTTP_CODE" == "403" ]]; then
+      if [[ -n "$TELEMETRY_API_KEY" ]]; then
+        fail "Telemetry: auth rejected (HTTP ${HTTP_CODE}) — check telemetry.api_key in enterprise.yaml"
+      else
+        pass "Telemetry: endpoint reachable (auth required — expected)"
+      fi
     else
       warn "Telemetry: endpoint returned HTTP ${HTTP_CODE}"
     fi
@@ -258,11 +298,25 @@ if [[ -n "$ENTERPRISE_CONFIG" ]]; then
   fi
 
   if [[ -n "$POLICY_ENDPOINT" ]]; then
-    POLICY_HTTP=$(curl -so /dev/null -w '%{http_code}' --max-time 5 "$POLICY_ENDPOINT" 2>/dev/null | tail -c 3 || echo "000")
+    POLICY_CURL_ARGS=(-so /dev/null -w '%{http_code}' --max-time 5)
+    if [[ -n "$POLICY_API_KEY" ]]; then
+      POLICY_CURL_ARGS+=(-H "Authorization: Bearer ${POLICY_API_KEY}")
+    fi
+    POLICY_HTTP=$(curl "${POLICY_CURL_ARGS[@]}" "$POLICY_ENDPOINT" 2>/dev/null | tail -c 3 || echo "000")
     if [[ "$POLICY_HTTP" == "000" ]]; then
       fail "Policy: endpoint not reachable (timeout/DNS)"
-    elif [[ "$POLICY_HTTP" =~ ^[23] ]] || [[ "$POLICY_HTTP" == "401" ]]; then
-      pass "Policy: endpoint reachable (HTTP ${POLICY_HTTP})"
+    elif [[ "$POLICY_HTTP" =~ ^[23] ]]; then
+      if [[ -n "$POLICY_API_KEY" ]]; then
+        pass "Policy: endpoint authenticated (HTTP ${POLICY_HTTP})"
+      else
+        pass "Policy: endpoint reachable (HTTP ${POLICY_HTTP})"
+      fi
+    elif [[ "$POLICY_HTTP" == "401" || "$POLICY_HTTP" == "403" ]]; then
+      if [[ -n "$POLICY_API_KEY" ]]; then
+        fail "Policy: auth rejected (HTTP ${POLICY_HTTP}) — check policy.api_key in enterprise.yaml"
+      else
+        pass "Policy: endpoint reachable (auth required — expected)"
+      fi
     else
       warn "Policy: endpoint returned HTTP ${POLICY_HTTP}"
     fi