code-graph-context 2.8.0 → 2.10.0

package/README.md

@@ -5,7 +5,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-007ACC?logo=typescript&logoColor=white)](https://typescriptlang.org/)
 [![Neo4j](https://img.shields.io/badge/Neo4j-5.23+-018bff?logo=neo4j&logoColor=white)](https://neo4j.com/)
 [![NestJS](https://img.shields.io/badge/NestJS-Compatible-E0234E?logo=nestjs&logoColor=white)](https://nestjs.com/)
-[![OpenAI](https://img.shields.io/badge/OpenAI-Powered-412991?logo=openai&logoColor=white)](https://openai.com/)
+[![OpenAI](https://img.shields.io/badge/OpenAI-Optional-412991?logo=openai&logoColor=white)](https://openai.com/)
 [![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io/)
 
 **Give your AI coding assistant a photographic memory of your codebase.**
@@ -27,7 +27,7 @@ Code Graph Context is an MCP server that builds a semantic graph of your TypeScr
                     │                   CODE GRAPH CONTEXT                        │
                     │                                                             │
                     │   AST Parser ──► Neo4j Graph ──► Vector Embeddings          │
-                    │   (ts-morph)     (Relationships)  (OpenAI)                  │
+                    │   (ts-morph)     (Relationships)  (Local or OpenAI)         │
                     │                                                             │
                     └─────────────────────────────────────────────────────────────┘
                                                 │
@@ -56,7 +56,7 @@ Code Graph Context is an MCP server that builds a semantic graph of your TypeScr
 ## Features
 
 - **Multi-Project Support**: Parse and query multiple projects in a single database with complete isolation
-- **Semantic Search**: Vector-based search using OpenAI embeddings to find relevant code
+- **Semantic Search**: Vector-based search using local or OpenAI embeddings to find relevant code
 - **Natural Language Querying**: Convert questions into Cypher queries
 - **Framework-Aware**: Built-in NestJS schema with ability to define custom framework patterns
 - **Weighted Graph Traversal**: Intelligent traversal scoring paths by importance and relevance
@@ -79,7 +79,7 @@ TypeScript Source → AST Parser (ts-morph) → Neo4j Graph + Vector Embeddings
 **Core Components:**
 - `src/core/parsers/typescript-parser.ts` - AST parsing with ts-morph
 - `src/storage/neo4j/neo4j.service.ts` - Graph storage and queries
-- `src/core/embeddings/embeddings.service.ts` - OpenAI embeddings
+- `src/core/embeddings/embeddings.service.ts` - Embedding service (local sidecar or OpenAI)
 - `src/mcp/mcp.server.ts` - MCP server and tool registration
 
 **Dual-Schema System:**
@@ -93,29 +93,33 @@ Nodes have both `coreType` (AST) and `semanticType` (framework meaning), enablin
 ### Prerequisites
 
 - **Node.js** >= 18
+- **Python** >= 3.10 (for local embeddings)
 - **Docker** (for Neo4j)
-- **OpenAI API Key**
-
 
+> **No API keys required.** Local embeddings work out of the box using a Python sidecar.
 
 ### 1. Install
 
 ```bash
 npm install -g code-graph-context
-code-graph-context init  # Sets up Neo4j via Docker
+code-graph-context init  # Sets up Neo4j + Python sidecar + downloads embedding model
 ```
 
-### 2. Configure Claude Code
+The `init` command handles everything:
+- Starts a Neo4j container via Docker
+- Creates a Python virtual environment
+- Installs embedding dependencies (PyTorch, sentence-transformers)
+- Downloads the default embedding model (~3GB)
 
-Add to Claude Code with your OpenAI API key:
+### 2. Configure Claude Code
 
 ```bash
-claude mcp add --scope user code-graph-context \
-  -e OPENAI_API_KEY=sk-your-key-here \
-  -- code-graph-context
+claude mcp add --scope user code-graph-context -- code-graph-context
 ```
 
-**That's it.** Restart Claude Code and you're ready to go.
+**That's it.** No API keys needed. Restart Claude Code and you're ready to go.
+
+> **Want to use OpenAI instead?** See [Embedding Configuration](#embedding-configuration) below.
 
 ### 3. Parse Your Project
 
@@ -142,11 +146,23 @@ If you prefer to edit the config files directly:
 
 **~/.claude.json** (user scope - recommended):
 ```json
+{
+  "mcpServers": {
+    "code-graph-context": {
+      "command": "code-graph-context"
+    }
+  }
+}
+```
+
+**With OpenAI (optional):**
+```json
 {
   "mcpServers": {
     "code-graph-context": {
       "command": "code-graph-context",
       "env": {
+        "OPENAI_ENABLED": "true",
         "OPENAI_API_KEY": "sk-your-key-here"
       }
     }
@@ -160,10 +176,7 @@ If you prefer to edit the config files directly:
   "mcpServers": {
     "code-graph-context": {
       "command": "node",
-      "args": ["/absolute/path/to/code-graph-context/dist/cli/cli.js"],
-      "env": {
-        "OPENAI_API_KEY": "sk-your-key-here"
-      }
+      "args": ["/absolute/path/to/code-graph-context/dist/cli/cli.js"]
     }
   }
 }
@@ -173,10 +186,13 @@ If you prefer to edit the config files directly:
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `OPENAI_API_KEY` | **Yes** | - | For embeddings and NL queries |
 | `NEO4J_URI` | No | `bolt://localhost:7687` | Neo4j connection URI |
 | `NEO4J_USER` | No | `neo4j` | Neo4j username |
 | `NEO4J_PASSWORD` | No | `PASSWORD` | Neo4j password |
+| `EMBEDDING_MODEL` | No | `Qodo/Qodo-Embed-1-1.5B` | Local embedding model (see [Embedding Configuration](#embedding-configuration)) |
+| `EMBEDDING_SIDECAR_PORT` | No | `8787` | Port for local embedding server |
+| `OPENAI_ENABLED` | No | `false` | Set `true` to use OpenAI instead of local |
+| `OPENAI_API_KEY` | No* | - | Required when `OPENAI_ENABLED=true` |
 
 ---
 
@@ -515,6 +531,54 @@ This enables queries like "find all hooks that use context" while maintaining AS
 
 ---
 
+## Embedding Configuration
+
+Local embeddings are the default — **no API key needed**. The Python sidecar starts automatically on first use and runs a local model for high-quality code embeddings.
+
+### Available Models
+
+Set via the `EMBEDDING_MODEL` environment variable:
+
+| Model | Dimensions | RAM | Quality | Best For |
+|-------|-----------|-----|---------|----------|
+| `Qodo/Qodo-Embed-1-1.5B` (default) | 1536 | ~9 GB | Best | Machines with 32+ GB RAM |
+| `BAAI/bge-base-en-v1.5` | 768 | ~500 MB | Good | General purpose, low RAM |
+| `sentence-transformers/all-MiniLM-L6-v2` | 384 | ~200 MB | OK | Minimal RAM, fast |
+| `nomic-ai/nomic-embed-text-v1.5` | 768 | ~600 MB | Good | Code + prose mixed |
+| `sentence-transformers/all-mpnet-base-v2` | 768 | ~500 MB | Good | Balanced quality/speed |
+| `BAAI/bge-small-en-v1.5` | 384 | ~130 MB | OK | Smallest footprint |
+
+**Example:** Use a lightweight model on a 16GB machine:
+```bash
+claude mcp add --scope user code-graph-context \
+  -e EMBEDDING_MODEL=BAAI/bge-base-en-v1.5 \
+  -- code-graph-context
+```
+
+### Switching Models
+
+**Switching models requires re-parsing** — vector index dimensions are locked per model. Drop existing indexes first:
+
+```cypher
+DROP INDEX embedded_nodes_idx IF EXISTS;
+DROP INDEX session_notes_idx IF EXISTS;
+```
+
+Then re-parse your project with the new model configured.
+
+### Using OpenAI Instead
+
+If you prefer OpenAI embeddings (higher quality, requires API key):
+
+```bash
+claude mcp add --scope user code-graph-context \
+  -e OPENAI_ENABLED=true \
+  -e OPENAI_API_KEY=sk-your-key-here \
+  -- code-graph-context
+```
+
+---
+
 ## Troubleshooting
 
 ### MCP Server Not Connecting
@@ -530,18 +594,29 @@ docker ps | grep neo4j
 code-graph-context status
 ```
 
-### Missing OPENAI_API_KEY
+### Embedding Errors
 
-Symptoms: "Failed to generate embedding" errors
+**"Failed to generate embedding"** — The local sidecar may not have started. Check:
+```bash
+# Verify Python deps are installed
+code-graph-context status
 
-Fix: Ensure the key is in your config file:
+# Re-run init to fix sidecar setup
+code-graph-context init
+```
+
+**Out of memory (large model on 16GB machine)** — Switch to a lighter model:
 ```bash
-# Check current config
-cat ~/.claude.json | grep -A5 "code-graph-context"
+claude mcp add --scope user code-graph-context \
+  -e EMBEDDING_MODEL=BAAI/bge-base-en-v1.5 \
+  -- code-graph-context
+```
 
-# Re-add with key
+**Using OpenAI and getting auth errors** — Ensure your key is configured:
+```bash
 claude mcp remove code-graph-context
 claude mcp add --scope user code-graph-context \
+  -e OPENAI_ENABLED=true \
   -e OPENAI_API_KEY=sk-your-key-here \
   -- code-graph-context
 ```
@@ -572,8 +647,8 @@ parse_typescript_project({
 ## CLI Commands
 
 ```bash
-code-graph-context init [options]   # Set up Neo4j container
-code-graph-context status           # Check Docker/Neo4j status
+code-graph-context init [options]   # Set up Neo4j + Python sidecar + embedding model
+code-graph-context status           # Check Docker/Neo4j/sidecar status
 code-graph-context stop             # Stop Neo4j container
 ```
 

package/dist/cli/cli.js

@@ -4,7 +4,8 @@
  *
  * Handles CLI commands (init, status, stop) and delegates to MCP server
  */
-import { readFileSync } from 'fs';
+import { execSync, spawn as spawnProcess } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
@@ -47,7 +48,7 @@ const spinner = (msg) => {
     return {
         stop: (ok, finalMsg) => {
             clearInterval(interval);
-            process.stdout.write(`\r  ${ok ? sym.ok : sym.err} ${finalMsg || msg}\n`);
+            process.stdout.write(`\r  ${ok ? sym.ok : sym.err} ${finalMsg ?? msg}\n`);
         },
     };
 };
@@ -67,12 +68,11 @@ ${c.bold}Next steps:${c.reset}
        "mcpServers": {
          "code-graph-context": {
            "command": "code-graph-context",
-           "env": {
-             "OPENAI_API_KEY": "sk-..."${password !== NEO4J_CONFIG.defaultPassword
-        ? `,
-             "NEO4J_PASSWORD": "${password}"`
+           "env": {${password !== NEO4J_CONFIG.defaultPassword
+        ? `
+             "NEO4J_PASSWORD": "${password}"${boltPort !== NEO4J_CONFIG.boltPort ? ',' : ''}`
         : ''}${boltPort !== NEO4J_CONFIG.boltPort
-        ? `,
+        ? `
              "NEO4J_URI": "bolt://localhost:${boltPort}"`
         : ''}
            }
@@ -80,19 +80,239 @@ ${c.bold}Next steps:${c.reset}
        }
      }${c.reset}
 
-     ${c.yellow}Get your OpenAI API key:${c.reset} https://platform.openai.com/api-keys
+     ${c.dim}Local embeddings are used by default (no API key needed).
+     To use OpenAI instead, add:
+       "OPENAI_ENABLED": "true",
+       "OPENAI_API_KEY": "sk-..."${c.reset}
 
   3. Restart Claude Code
 `);
 };
+/**
+ * Resolve the sidecar directory (works from both src/ and dist/)
+ */
+const getSidecarDir = () => join(__dirname, '..', '..', 'sidecar');
+/**
+ * Get the path to the venv python binary inside the sidecar dir.
+ * Returns null if the venv doesn't exist yet.
+ */
+const getVenvPython = (sidecarDir) => {
+    const venvPython = join(sidecarDir, '.venv', 'bin', 'python3');
+    return existsSync(venvPython) ? venvPython : null;
+};
+/**
+ * Get the best python binary to use for the sidecar.
+ * Prefers venv python, falls back to system python3.
+ */
+const getSidecarPython = (sidecarDir) => {
+    return getVenvPython(sidecarDir) ?? 'python3';
+};
+/**
+ * Check if python3 is available and return its version
+ */
+const getPythonVersion = () => {
+    try {
+        return execSync('python3 --version', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Check if a pip package is importable using the sidecar python
+ */
+const checkPipPackage = (pkg, python = 'python3') => {
+    try {
+        execSync(`${python} -c "import ${pkg}"`, { stdio: ['pipe', 'pipe', 'pipe'] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Create a venv in the sidecar directory
+ */
+const createVenv = (sidecarDir) => {
+    try {
+        const venvPath = join(sidecarDir, '.venv');
+        execSync(`python3 -m venv ${venvPath}`, { stdio: ['pipe', 'pipe', 'pipe'] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Install sidecar Python dependencies via pip inside the venv
+ */
+const installSidecarDeps = (sidecarDir) => {
+    return new Promise((resolve) => {
+        const venvPip = join(sidecarDir, '.venv', 'bin', 'pip');
+        const requirementsPath = join(sidecarDir, 'requirements.txt');
+        const pip = spawnProcess(venvPip, ['install', '-r', requirementsPath], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        pip.stderr?.on('data', (data) => {
+            const line = data.toString().trim();
+            if (line && (line.includes('Downloading') || line.includes('Installing') || line.includes('ERROR'))) {
+                process.stdout.write(`\r  ${c.blue}⠸${c.reset} ${line.slice(0, 70).padEnd(70)}`);
+            }
+        });
+        pip.on('close', (code) => {
+            process.stdout.write('\r' + ' '.repeat(80) + '\r');
+            resolve(code === 0);
+        });
+        pip.on('error', () => {
+            resolve(false);
+        });
+    });
+};
+/**
+ * Verify sentence-transformers can be imported using the venv python
+ */
+const verifySidecar = (sidecarDir) => {
+    return new Promise((resolve) => {
+        const python = getSidecarPython(sidecarDir);
+        const test = spawnProcess(python, ['-c', 'from sentence_transformers import SentenceTransformer; print("ok")'], {
+            cwd: sidecarDir,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        test.stdout?.on('data', (d) => (stdout += d.toString()));
+        test.on('close', (code) => resolve(code === 0 && stdout.includes('ok')));
+        test.on('error', () => resolve(false));
+    });
+};
+/**
+ * Set up the Python embedding sidecar
+ */
+const setupSidecar = async () => {
+    console.log('');
+    header('Embedding Sidecar Setup');
+    const sidecarDir = getSidecarDir();
+    // Check Python
+    const pythonVersion = getPythonVersion();
+    if (!pythonVersion) {
+        log(sym.err, 'Python 3 is not installed');
+        console.log(`\n  Install Python 3.10+: ${c.cyan}https://www.python.org/downloads/${c.reset}`);
+        console.log(`  ${c.dim}Or use OpenAI embeddings instead: set OPENAI_ENABLED=true${c.reset}\n`);
+        return;
+    }
+    log(sym.ok, `${pythonVersion}`);
+    // Create or reuse venv
+    const venvPath = join(sidecarDir, '.venv');
+    if (existsSync(venvPath)) {
+        log(sym.ok, `Virtual environment exists (${c.dim}sidecar/.venv${c.reset})`);
+    }
+    else {
+        const venvSpinner = spinner('Creating virtual environment...');
+        const created = createVenv(sidecarDir);
+        if (!created) {
+            venvSpinner.stop(false, 'Failed to create virtual environment');
+            console.log(`\n  Try manually: ${c.dim}python3 -m venv ${venvPath}${c.reset}\n`);
+            return;
+        }
+        venvSpinner.stop(true, `Virtual environment created (${c.dim}sidecar/.venv${c.reset})`);
+    }
+    const python = getSidecarPython(sidecarDir);
+    // Check if deps already installed in venv
+    const hasSentenceTransformers = checkPipPackage('sentence_transformers', python);
+    const hasFastApi = checkPipPackage('fastapi', python);
+    const hasTorch = checkPipPackage('torch', python);
+    if (hasSentenceTransformers && hasFastApi && hasTorch) {
+        log(sym.ok, 'Python dependencies already installed');
+    }
+    else {
+        const missing = [];
+        if (!hasTorch)
+            missing.push('torch');
+        if (!hasSentenceTransformers)
+            missing.push('sentence-transformers');
+        if (!hasFastApi)
+            missing.push('fastapi');
+        log(sym.info, `Missing packages: ${missing.join(', ')}`);
+        const s = spinner('Installing Python dependencies (this may take a few minutes)...');
+        const installed = await installSidecarDeps(sidecarDir);
+        if (!installed) {
+            s.stop(false, 'Failed to install Python dependencies');
+            console.log(`\n  Try manually: ${c.dim}${join(venvPath, 'bin', 'pip')} install -r ${join(sidecarDir, 'requirements.txt')}${c.reset}\n`);
+            return;
+        }
+        s.stop(true, 'Python dependencies installed');
+    }
+    // Verify sentence-transformers works
+    const verifySpinner = spinner('Verifying sentence-transformers...');
+    const verified = await verifySidecar(sidecarDir);
+    verifySpinner.stop(verified, verified ? 'sentence-transformers OK' : 'sentence-transformers import failed');
+    if (!verified) {
+        console.log(`\n  ${c.dim}Try: ${python} -c "from sentence_transformers import SentenceTransformer"${c.reset}`);
+        console.log(`  ${c.dim}Or use OpenAI embeddings instead: set OPENAI_ENABLED=true${c.reset}\n`);
+        return;
+    }
+    // Pre-download the embedding model so first real use is fast
+    const modelName = process.env.EMBEDDING_MODEL ?? 'Qodo/Qodo-Embed-1-1.5B';
+    await preDownloadModel(sidecarDir, python, modelName);
+};
+/**
+ * Pre-download the embedding model during init so the first parse doesn't hang.
+ * SentenceTransformer downloads to ~/.cache/huggingface/ on first load.
+ */
+const preDownloadModel = async (sidecarDir, python, modelName) => {
+    // Check if model is already cached by trying a quick load
+    const checkCached = () => {
+        return new Promise((resolve) => {
+            const proc = spawnProcess(python, [
+                '-c',
+                `from sentence_transformers import SentenceTransformer; m = SentenceTransformer("${modelName}"); print(f"dims:{len(m.encode(['test'])[0])}")`,
+            ], { cwd: sidecarDir, stdio: ['pipe', 'pipe', 'pipe'], timeout: 30_000 });
+            let stdout = '';
+            proc.stdout?.on('data', (d) => (stdout += d.toString()));
+            proc.on('close', (code) => resolve(code === 0 && stdout.includes('dims:')));
+            proc.on('error', () => resolve(false));
+        });
+    };
+    // Quick check — if model is cached, this returns in ~5s
+    const quickSpinner = spinner(`Checking for cached model (${modelName})...`);
+    const isCached = await checkCached();
+    if (isCached) {
+        quickSpinner.stop(true, `Model ready (${modelName})`);
+        return;
+    }
+    quickSpinner.stop(false, 'Model not cached yet');
+    log(sym.info, 'Downloading embedding model (~600MB, only needed once)');
+    // Download the model — this can take a few minutes.
+    // Pipe stderr directly to the terminal so HuggingFace progress bars render natively.
+    const downloaded = await new Promise((resolve) => {
+        const proc = spawnProcess(python, [
+            '-c',
+            `from sentence_transformers import SentenceTransformer; print("downloading..."); m = SentenceTransformer("${modelName}"); print(f"done dims:{len(m.encode(['test'])[0])}")`,
+        ], { cwd: sidecarDir, stdio: ['pipe', 'pipe', 'inherit'] });
+        let stdout = '';
+        proc.stdout?.on('data', (d) => {
+            stdout += d.toString();
+        });
+        proc.on('close', (code) => {
+            resolve(code === 0 && stdout.includes('done'));
+        });
+        proc.on('error', () => resolve(false));
+    });
+    if (downloaded) {
+        log(sym.ok, 'Embedding model downloaded and cached');
+    }
+    else {
+        log(sym.warn, 'Model download failed — it will retry on first use');
+        console.log(`  ${c.dim}You can download manually: ${python} -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('${modelName}')"${c.reset}`);
+    }
+};
 /**
  * Init command - set up Neo4j
  */
 const runInit = async (options) => {
     const boltPort = options.port ? parseInt(options.port, 10) : NEO4J_CONFIG.boltPort;
     const httpPort = options.httpPort ? parseInt(options.httpPort, 10) : NEO4J_CONFIG.httpPort;
-    const password = options.password || NEO4J_CONFIG.defaultPassword;
-    const memory = options.memory || '4G';
+    const password = options.password ?? NEO4J_CONFIG.defaultPassword;
+    const memory = options.memory ?? '4G';
     header('Code Graph Context Setup');
     // Check Docker
     if (!isDockerInstalled()) {
@@ -114,6 +334,8 @@ const runInit = async (options) => {
         const apocOk = isApocAvailable(NEO4J_CONFIG.containerName, password);
         log(apocOk ? sym.ok : sym.warn, apocOk ? 'APOC plugin available' : 'APOC plugin not detected');
         console.log(`\n  ${c.dim}Use --force to recreate the container${c.reset}`);
+        // Still set up sidecar even if Neo4j is already running
+        await setupSidecar();
         printConfigInstructions(password, boltPort);
         return;
     }
@@ -165,6 +387,8 @@ ${c.bold}Neo4j is ready${c.reset}
   Browser:     ${c.cyan}http://localhost:${httpPort}${c.reset}
   Bolt URI:    ${c.cyan}bolt://localhost:${boltPort}${c.reset}
   Credentials: ${c.dim}neo4j / ${password}${c.reset}`);
+    // Set up Python embedding sidecar
+    await setupSidecar();
     printConfigInstructions(password, boltPort);
 };
 /**
@@ -189,6 +413,22 @@ const runStatus = () => {
         log(status.neo4jReady ? sym.ok : sym.warn, `Neo4j responding: ${status.neo4jReady ? 'yes' : 'no'}`);
         log(status.apocAvailable ? sym.ok : sym.warn, `APOC plugin: ${status.apocAvailable ? 'available' : 'not available'}`);
     }
+    // Sidecar status
+    console.log('');
+    const pythonVersion = getPythonVersion();
+    log(pythonVersion ? sym.ok : sym.warn, `Python: ${pythonVersion ?? 'not found'}`);
+    if (pythonVersion) {
+        const sidecarDir = getSidecarDir();
+        const venvExists = existsSync(join(sidecarDir, '.venv'));
+        log(venvExists ? sym.ok : sym.warn, `Sidecar venv: ${venvExists ? 'exists' : 'not created'}`);
+        if (venvExists) {
+            const python = getSidecarPython(sidecarDir);
+            const hasDeps = checkPipPackage('sentence_transformers', python) &&
+                checkPipPackage('fastapi', python) &&
+                checkPipPackage('torch', python);
+            log(hasDeps ? sym.ok : sym.warn, `Sidecar deps: ${hasDeps ? 'installed' : 'not installed'}`);
+        }
+    }
     console.log('');
     if (status.containerStatus !== 'running') {
         console.log(`  Run ${c.dim}code-graph-context init${c.reset} to start Neo4j\n`);