{"id":47046127,"url":"https://github.com/sdsrss/code-graph-mcp","last_synced_at":"2026-04-16T21:07:40.655Z","repository":{"id":343569302,"uuid":"1178111583","full_name":"sdsrss/code-graph-mcp","owner":"sdsrss","description":"AST knowledge graph MCP server for Claude Code — semantic search, call graph traversal, HTTP route tracing, impact analysis. Auto-indexes 10 languages via Tree-sitter.","archived":false,"fork":false,"pushed_at":"2026-03-25T16:55:14.000Z","size":1005,"stargazers_count":17,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T17:43:20.292Z","etag":null,"topics":["ast","call-graph","claude-code","claude-code-plugin","code-navigation","knowledge-graph","mcp","rust","semantic-search","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sdsrss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-10T17:42:45.000Z","updated_at":"2026-03-25T17:53:38.000Z","dependencies_parsed_at":"2026-03-15T09:01:36.602Z","dependency_job_id":null,"html_url":"https://github.com/sdsrss/code-graph-mcp","commit_stats":null,"previous_names":["sdsrss/code-graph-mcp"],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/sdsrss/code-graph-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fcode-graph-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fcode-graph-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fcode-graph-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fcode-graph-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sdsrss","download_url":"https://codeload.github.com/sdsrss/code-graph-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fcode-graph-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","call-graph","claude-code","claude-code-plugin","code-navigation","knowledge-graph","mcp","rust","semantic-search","tree-sitter"],"created_at":"2026-03-12T01:58:03.942Z","updated_at":"2026-04-01T21:30:30.622Z","avatar_url":"https://github.com/sdsrss.png","language":"Rust","readme":"# code-graph-mcp\n\nA high-performance code knowledge graph server implementing the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Indexes codebases into a structured AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing — designed to give AI coding assistants deep, structured understanding of your code.\n\n## Features\n\n- **Multi-language parsing** — Tree-sitter AST extraction for TypeScript, JavaScript, Go, Python, Rust, Java, C, C++, HTML, CSS\n- **Semantic code search** — Hybrid BM25 full-text + vector semantic search with Reciprocal Rank Fusion (RRF), powered by sqlite-vec\n- **Call graph traversal** — Recursive CTE queries to trace callers/callees with cycle detection\n- **HTTP route tracing** — Map route paths to backend handler functions (Express, Flask/FastAPI, Go)\n- **Impact analysis** — Determine the blast radius of code changes by tracing all dependents\n- **Incremental indexing** — Merkle tree change detection with file system watcher for real-time updates\n- **Context compression** — Token-aware snippet extraction for LLM context windows (L0→full code, L1→summaries, L2→file groups, L3→directory overview)\n- **Embedding model** — Optional local embedding via Candle (feature-gated `embed-model`)\n- **MCP protocol** — JSON-RPC 2.0 over stdio, plug-and-play with Claude Code, Cursor, Windsurf, and other MCP clients\n- **Claude Code Plugin** — First-class plugin with slash commands (`/understand`, `/trace`, `/impact`), agents, skills, auto-indexing hooks, StatusLine integration, and self-updating\n\n## Why code-graph-mcp?\n\nUnlike 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.\n\n### Incremental by Design\n\nBLAKE3 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.\n\n### Hybrid Search, Not Just Grep\n\nCombines 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.\n\n### Scope-Aware Relation Extraction\n\nThe 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.\n\n### HTTP Request Flow Tracing\n\nUnique 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.\n\n### Zero External Dependencies at Runtime\n\nSingle 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.\n\n### Built for AI Assistants\n\nEvery 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.\n\n## Efficiency: code-graph vs Traditional Tools\n\nReal-world benchmarks comparing code-graph-mcp tools against traditional approaches (Grep + Read + Glob) on a 33-file Rust project (~537 AST nodes).\n\n### Tool Call Reduction\n\n| Scenario | Traditional | code-graph | Savings |\n|----------|:-----------:|:----------:|:-------:|\n| Project architecture overview | 5-8 calls | 1 call (`project_map`) | **~85%** |\n| Find function by concept | 3-5 calls | 1 call (`semantic_code_search`) | **~75%** |\n| Trace 2-level call chain | 8-15 calls | 1 call (`get_call_graph`) | **~90%** |\n| Pre-change impact analysis | 10-20+ calls | 1 call (`impact_analysis`) | **~95%** |\n| Module structure \u0026 exports | 5+ calls | 1 call (`module_overview`) | **~80%** |\n| File dependency mapping | 3-5 calls | 1 call (`dependency_graph`) | **~75%** |\n| Similar code detection | N/A | 1 call (`find_similar_code`) | **unique** |\n\n### Overall Session Efficiency\n\n| Metric | Without code-graph | With code-graph | Improvement |\n|--------|:------------------:|:---------------:|:-----------:|\n| Tool calls per navigation task | ~6 | ~1.2 | **~80% fewer** |\n| Source lines read into context | ~8,000 lines | ~400 lines (structured) | **~95% less** |\n| Navigation token cost | ~36K tokens | ~7K tokens | **~80% saved** |\n| Full session token savings | — | — | **40-60%** |\n\n### What code-graph Uniquely Enables\n\n- **Impact analysis** — \"Changing `conn` affects 33 functions across 4 files, 78 tests at HIGH risk\" — impossible to derive manually with Grep\n- **Transitive call tracing** — Follow `main` → `run_serve` → `handle_message` → `handle_tools_call` → `conn` in one query\n- **Semantic search** — Find `authenticate_session` when searching \"handle user login\"\n- **Dependency strength** — Not just \"file A imports file B\", but \"file A uses 38 symbols from file B\"\n\n### When Traditional Tools Are Still Better\n\n| Use Case | Best Tool |\n|----------|-----------|\n| Exact string / constant search | Grep |\n| Reading a file to edit it | Read |\n| Finding files by name pattern | Glob |\n\n## Architecture\n\n```\nsrc/\n├── mcp/          # MCP protocol layer (JSON-RPC, tool registry, server)\n├── parser/       # Tree-sitter parsing, relation extraction, language support\n├── indexer/      # 3-phase pipeline, Merkle tree, file watcher\n├── storage/      # SQLite schema, CRUD, FTS5 full-text search\n├── graph/        # Recursive CTE call graph queries\n├── search/       # RRF fusion search combining BM25 + vector\n├── embedding/    # Candle embedding model (optional)\n├── sandbox/      # Context compressor with token estimation\n└── utils/        # Language detection, config\n```\n\n## Installation\n\n### Option 1: Claude Code Plugin (Recommended)\n\nInstall as a Claude Code plugin for the best experience — includes slash commands, agents, skills, auto-indexing hooks, StatusLine health display, and automatic updates:\n\n```bash\n# Step 1: Add the marketplace\n/plugin marketplace add sdsrss/code-graph-mcp\n\n# Step 2: Install the plugin\n/plugin install code-graph-mcp\n```\n\nWhat you get:\n- **MCP Server** — All code-graph tools available to Claude\n- **Slash Commands** — `/understand \u003cmodule\u003e`, `/trace \u003croute\u003e`, `/impact \u003csymbol\u003e`\n- **Code Explorer Agent** — Deep code understanding expert via `code-explorer`\n- **Auto-indexing Hook** — Incremental index on every file edit (PostToolUse)\n- **StatusLine** — Real-time health display (nodes, files, watch status) — compatible with other plugins' StatusLine via composite multiplexer\n- **Auto-update** — Checks for new versions every 24h, updates silently\n\n#### Manual Update\n\n```bash\nnpm update -g @sdsrs/code-graph\n```\n\nThen reconnect the MCP server in Claude Code with `/mcp`.\n\n\u003e **Note:** Auto-update is disabled in the source repo directory (dev mode). Use manual update when developing the plugin itself.\n\n### Option 2: Claude Code MCP Server Only\n\nRegister as an MCP server without the plugin features:\n\n```bash\nclaude mcp add code-graph-mcp -- npx -y @sdsrs/code-graph\n```\n\n### Option 3: Cursor / Windsurf / Other MCP Clients\n\nAdd to your MCP settings file (e.g. `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"code-graph\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@sdsrs/code-graph\"]\n    }\n  }\n}\n```\n\n### Option 4: npx (No Install)\n\nRun directly without installing:\n\n```bash\nnpx -y @sdsrs/code-graph\n```\n\n### Option 5: npm (Global Install)\n\nInstall globally, then run anywhere:\n\n```bash\nnpm install -g @sdsrs/code-graph\ncode-graph-mcp\n```\n\n## Uninstallation\n\n### Claude Code Plugin\n\n```bash\n# Uninstall the plugin\n/plugin uninstall code-graph-mcp\n\n# (Optional) Remove the marketplace\n/plugin marketplace remove code-graph-mcp\n\n# (Optional) Clean up all config and cache data\nnode ~/.claude/plugins/cache/code-graph-mcp/code-graph-mcp/*/scripts/lifecycle.js uninstall\n```\n\n### Claude Code MCP Server\n\n```bash\nclaude mcp remove code-graph-mcp\n```\n\n### Cursor / Windsurf / Other MCP Clients\n\nRemove the `code-graph` entry from your MCP settings file (e.g. `~/.cursor/mcp.json`).\n\n### npm (Global)\n\n```bash\nnpm uninstall -g @sdsrs/code-graph\n```\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `project_map` | Full project architecture: modules, dependencies, entry points, hot functions |\n| `semantic_code_search` | Hybrid BM25 + vector + graph search for AST nodes |\n| `get_call_graph` | Trace upstream/downstream call chains for a function |\n| `trace_http_chain` | Full request flow: route → handler → downstream call chain |\n| `impact_analysis` | Analyze the blast radius of changing a symbol |\n| `module_overview` | High-level overview of a module's structure and exports |\n| `dependency_graph` | Visualize dependency relationships between modules |\n| `find_similar_code` | Find code snippets similar to a given pattern |\n| `get_ast_node` | Extract a specific code symbol with signature, body, and relations |\n\n## Plugin Slash Commands\n\nAvailable when installed as a Claude Code plugin:\n\n| Command | Description |\n|---------|-------------|\n| `/understand \u003cmodule\u003e` | Deep dive into a module or file's architecture and relationships |\n| `/trace \u003croute\u003e` | Trace a full HTTP request flow from route to data layer |\n| `/impact \u003csymbol\u003e` | Analyze the impact scope of changing a symbol before modifying it |\n| `/status` | Show code-graph index status and embedding progress |\n| `/rebuild` | Force a full code-graph index rebuild |\n\n## Supported Languages\n\nTypeScript, JavaScript, Go, Python, Rust, Java, C, C++, HTML, CSS\n\n## Storage\n\nUses SQLite with:\n- FTS5 for full-text search\n- sqlite-vec extension for vector similarity search\n- Merkle tree hashes for incremental change detection\n\nData is stored in `.code-graph/index.db` under the project root (auto-created, gitignored).\n\n## Build from Source\n\n### Prerequisites\n\n- Rust 1.75+ (2021 edition)\n- A C compiler (for bundled SQLite / sqlite-vec)\n\n### Build\n\n```bash\n# Default build (with local embedding model)\ncargo build --release\n\n# Without embedding model (lighter build)\ncargo build --release --no-default-features\n```\n\n### Configure (from source)\n\nAdd the compiled binary to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"code-graph\": {\n      \"command\": \"/path/to/target/release/code-graph-mcp\"\n    }\n  }\n}\n```\n\n## Development\n\n```bash\n# Run tests\ncargo test\n\n# Run tests without embedding model\ncargo test --no-default-features\n\n# Check compilation\ncargo check\n```\n\n## License\n\nSee [LICENSE](LICENSE) for details.\n","funding_links":[],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdsrss%2Fcode-graph-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsdsrss%2Fcode-graph-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdsrss%2Fcode-graph-mcp/lists"}