@sdsrs/code-graph 0.2.1 → 0.4.0

package/README.md

@@ -13,6 +13,34 @@ A high-performance code knowledge graph server implementing the [Model Context P
 - **Embedding model** — Optional local embedding via Candle (feature-gated `embed-model`)
 - **MCP protocol** — JSON-RPC 2.0 over stdio, plug-and-play with Claude Code, Cursor, and other MCP clients
 
+## Why code-graph-mcp?
+
+Unlike naive full-text search or simple AST dumps, code-graph-mcp builds a **structured knowledge graph** that understands the relationships between symbols across your entire codebase.
+
+### Incremental by Design
+
+BLAKE3 Merkle tree tracks every file's content hash. On re-index, only changed files are re-parsed — unchanged directory subtrees are skipped entirely via mtime cache. When a function signature changes, **dirty propagation** automatically regenerates context for all downstream callers across files.
+
+### Hybrid Search, Not Just Grep
+
+Combines BM25 full-text ranking (FTS5) with vector semantic similarity (sqlite-vec) via **Reciprocal Rank Fusion (RRF)** — so searching "handle user login" finds the right function even if it's named `authenticate_session`. Results are auto-compressed to fit LLM context windows (L0→full code, L1→summaries, L2→file groups, L3→directory overview).
+
+### Scope-Aware Relation Extraction
+
+The parser doesn't just find function calls — it tracks them within their proper scope context. Extracts calls, imports, inheritance, interface implementations, exports, and HTTP route bindings. Same-file targets are preferred over cross-file matches to minimize false-positive edges.
+
+### HTTP Request Flow Tracing
+
+Unique to code-graph-mcp: trace from `GET /api/users` → route handler → service layer → database call in a single query. Supports Express, Flask/FastAPI, and Go HTTP frameworks.
+
+### Zero External Dependencies at Runtime
+
+Single binary, embedded SQLite, bundled sqlite-vec extension, optional local embedding model via Candle — no database server, no cloud API, no Docker required. Runs entirely on your machine.
+
+### Built for AI Assistants
+
+Every design decision — from token-aware compression to node_id-based snippet expansion — is optimized for LLM context windows. Works out of the box with Claude Code, Cursor, Windsurf, and any MCP-compatible client.
+
 ## Architecture
 
 ```
@@ -35,18 +63,33 @@ src/
 One-command setup — registers as an MCP server directly in Claude Code:
 
 ```bash
-claude mcp add code-graph-mcp npx @sdsrs/code-graph
+claude mcp add code-graph-mcp -- npx -y @sdsrs/code-graph
+```
+
+### Option 2: Cursor / Windsurf / Other MCP Clients
+
+Add to your MCP settings file (e.g. `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "code-graph": {
+      "command": "npx",
+      "args": ["-y", "@sdsrs/code-graph"]
+    }
+  }
+}
 ```
 
-### Option 2: npx (No Install)
+### Option 3: npx (No Install)
 
 Run directly without installing:
 
 ```bash
-npx @sdsrs/code-graph
+npx -y @sdsrs/code-graph
 ```
 
-### Option 3: npm (Global Install)
+### Option 4: npm (Global Install)
 
 Install globally, then run anywhere:
 
@@ -55,6 +98,24 @@ npm install -g @sdsrs/code-graph
 code-graph-mcp
 ```
 
+## Uninstallation
+
+### Claude Code
+
+```bash
+claude mcp remove code-graph-mcp
+```
+
+### Cursor / Windsurf / Other MCP Clients
+
+Remove the `code-graph` entry from your MCP settings file (e.g. `~/.cursor/mcp.json`).
+
+### npm (Global)
+
+```bash
+npm uninstall -g @sdsrs/code-graph
+```
+
 ## Build from Source
 
 ### Prerequisites
@@ -72,16 +133,15 @@ cargo build --release
 cargo build --release --no-default-features
 ```
 
-### Configure with Claude Code (Manual)
+### Configure (from source)
 
-If you built from source, add to your MCP settings:
+Add the compiled binary to your MCP settings:
 
 ```json
 {
   "mcpServers": {
     "code-graph": {
-      "command": "/path/to/code-graph-mcp",
-      "cwd": "/path/to/your/project"
+      "command": "/path/to/target/release/code-graph-mcp"
     }
   }
 }
@@ -94,6 +154,7 @@ If you built from source, add to your MCP settings:
 | `semantic_code_search` | Hybrid BM25 + vector + graph search for AST nodes |
 | `get_call_graph` | Trace upstream/downstream call chains for a function |
 | `find_http_route` | Map route path to backend handler function |
+| `trace_http_chain` | Full request flow: route → handler → downstream call chain |
 | `get_ast_node` | Extract a specific code symbol from a file |
 | `read_snippet` | Read original code snippet by node ID with context |
 | `start_watch` / `stop_watch` | Start/stop file system watcher for incremental indexing |

package/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "code-graph",
+  "description": "AST knowledge graph for intelligent code navigation — auto-indexes your codebase and provides semantic search, call graph traversal, HTTP route tracing, and impact analysis via MCP tools",
+  "author": {
+    "name": "sdsrs"
+  },
+  "version": "0.3.0",
+  "keywords": ["code-graph", "ast", "navigation", "mcp", "knowledge-graph"]
+}

package/claude-plugin/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "code-graph": {
+      "command": "code-graph-mcp",
+      "args": ["serve"],
+      "env": {}
+    }
+  }
+}

package/claude-plugin/agents/code-explorer.md

@@ -0,0 +1,24 @@
+---
+name: code-explorer
+description: Deep code understanding expert using AST knowledge graph. Use when exploring unfamiliar code, tracing complex relationships, or understanding module architecture.
+tools: ["Read", "Grep", "Glob", "Bash", "mcp__code-graph__semantic_code_search", "mcp__code-graph__get_call_graph", "mcp__code-graph__get_ast_node", "mcp__code-graph__read_snippet", "mcp__code-graph__trace_http_chain"]
+model: sonnet
+---
+
+You are a code exploration specialist with access to an AST knowledge graph.
+
+## Strategy
+
+1. **Start with semantic_code_search** to locate relevant code by meaning
+2. **Use get_call_graph** to understand function relationships and call chains
+3. **Use get_ast_node** to get symbol metadata (signature, type, doc comment)
+4. **Use read_snippet** to examine specific code implementations
+5. **Use trace_http_chain** for HTTP request flow analysis
+6. **Fall back to Grep/Read** only when code-graph tools lack coverage (e.g., config files, non-code assets)
+
+## Rules
+
+- Always prefer structured graph queries over raw text search
+- Return structured findings: name, file, line, relationships
+- When reporting call chains, include depth and direction
+- Estimate token cost: if Read would require >3 files, prefer code-graph tools

package/claude-plugin/commands/impact.md

@@ -0,0 +1,19 @@
+---
+description: Analyze the impact scope of changing a symbol before modifying it
+argument-hint: <symbol_name>
+---
+
+# Impact Analysis
+
+Analyze what will be affected if you change the given symbol.
+
+## Steps
+
+1. Call `get_call_graph(symbol, "callers", depth=3)` to find all upstream callers
+2. Call `get_call_graph(symbol, "callees", depth=2)` to find downstream dependencies
+3. Check if any callers are HTTP route handlers (look for route-related nodes)
+4. Summarize findings:
+   - **Affected files**: list all unique files containing callers/callees
+   - **Affected routes**: list any HTTP routes that flow through this symbol
+   - **Risk level**: LOW (≤3 callers, no routes), MEDIUM (4-10 callers OR 1-2 routes), HIGH (>10 callers OR ≥3 routes)
+5. Present the analysis before making any modifications

package/claude-plugin/commands/trace.md

@@ -0,0 +1,15 @@
+---
+description: Trace a full HTTP request flow from route to data layer
+argument-hint: <route_path>
+---
+
+# HTTP Request Flow Tracing
+
+Trace the complete execution path of an HTTP request.
+
+## Steps
+
+1. Call `trace_http_chain(route, depth=5)` to get the full chain
+2. For each key node in the chain, call `read_snippet` to show the implementation
+3. Map the flow: route → middleware → validation → business logic → data access → response
+4. Highlight any error handling, authentication checks, or database operations

package/claude-plugin/commands/understand.md

@@ -0,0 +1,21 @@
+---
+description: Deep dive into a module or file's architecture and relationships
+argument-hint: <file_or_dir_path>
+---
+
+# Module Deep Dive
+
+Understand what a module does, its public API, and how it connects to the rest of the codebase.
+
+## Steps
+
+1. Call `get_index_status` to verify the code graph index is current
+2. Call `semantic_code_search` with the module name to find its key symbols
+3. For each important export, call `get_call_graph` to map caller/callee relationships
+4. Summarize:
+   - **Purpose**: what this module does
+   - **Public API**: exported functions/classes with signatures
+   - **Internal structure**: key internal helpers
+   - **Dependencies**: what it imports
+   - **Dependents**: who imports it
+   - **Hot paths**: most-called functions (by caller count)

package/claude-plugin/hooks/hooks.json

@@ -0,0 +1,29 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "tool == \"Write\" || tool == \"Edit\"",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-graph-mcp incremental-index --quiet",
+            "timeout": 10
+          }
+        ],
+        "description": "Auto-update code graph index after file edits"
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-graph-mcp health-check --format oneline",
+            "timeout": 5
+          }
+        ],
+        "description": "Verify code graph index freshness at session start"
+      }
+    ]
+  }
+}

package/claude-plugin/scripts/statusline.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+try {
+  const out = execSync('code-graph-mcp health-check --format json', {
+    timeout: 3000,
+    stdio: ['pipe', 'pipe', 'pipe']
+  }).toString().trim();
+  const s = JSON.parse(out);
+  const icon = s.healthy ? '\u2713' : '\u2717';
+  process.stdout.write(
+    `code-graph: ${icon} ${s.nodes} nodes | ${s.files} files` +
+    (s.watching ? ' | watching' : '')
+  );
+} catch {
+  process.stdout.write('code-graph: offline');
+}

package/claude-plugin/skills/code-navigation.md

@@ -0,0 +1,29 @@
+---
+name: code-navigation
+description: Smart code navigation decision tree for code-graph MCP tools. Use when exploring, understanding, or navigating code in a project indexed by code-graph.
+---
+
+# Code Navigation with Code Graph
+
+This project has a code-graph MCP server providing AST-level code intelligence.
+These tools return structured, token-efficient results. Use them as your
+PRIMARY navigation method for code understanding tasks.
+
+| You want to... | Use this | NOT this |
+|---|---|---|
+| Find code by concept/meaning | `semantic_code_search` | Grep multiple patterns |
+| Understand who calls what | `get_call_graph` | Grep function name + Read files |
+| Trace HTTP request flow | `trace_http_chain` | Read router -> handler -> service |
+| Find route handler | `find_http_route` | Grep route string |
+| Get symbol signature + relations | `get_ast_node` | Read entire file |
+| Read specific code after search | `read_snippet` (by node_id) | Read entire file |
+| Analyze change impact | `impact_analysis` | Manual call graph tracing |
+| Understand a module | `module_overview` | Read all files in directory |
+| Map dependencies | `dependency_graph` | Grep import statements |
+| Find similar code | `find_similar_code` | Grep partial function names |
+
+## Still use native tools for
+- Exact string match → Grep
+- File path lookup → Glob
+- Reading a specific known file → Read
+- Creating/editing files → Write/Edit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,8 @@
   },
   "files": [
     "bin/cli.js",
-    "README.md"
+    "README.md",
+    "claude-plugin"
   ],
   "scripts": {
     "build": "cargo build --release --no-default-features && node scripts/copy-binary.js"
@@ -32,10 +33,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.2.1",
-    "@sdsrs/code-graph-linux-arm64": "0.2.1",
-    "@sdsrs/code-graph-darwin-x64": "0.2.1",
-    "@sdsrs/code-graph-darwin-arm64": "0.2.1",
-    "@sdsrs/code-graph-win32-x64": "0.2.1"
+    "@sdsrs/code-graph-linux-x64": "0.4.0",
+    "@sdsrs/code-graph-linux-arm64": "0.4.0",
+    "@sdsrs/code-graph-darwin-x64": "0.4.0",
+    "@sdsrs/code-graph-darwin-arm64": "0.4.0",
+    "@sdsrs/code-graph-win32-x64": "0.4.0"
   }
 }