Identity-first layered code graph MCP server. Deterministic indexing via tree-sitter for JavaScript, TypeScript/TSX, Python, C#, and PHP.
Grep finds text. hex-graph understands code. It indexes your codebase into a SQLite knowledge graph via tree-sitter AST parsing, workspace ownership discovery, semantic edges, and optional precise overlays. Then answers structural questions in milliseconds that would take an agent dozens of file reads.
symbol_id, workspace_qualified_name, qualified_name, or name + file. Precision filtering is explicit via min_confidence, and missing Python/C#/PHP tooling is surfaced as a direct human-actionable provider status instead of a silent downgrade.Real scenarios where a knowledge graph changes the game.
A new team member asks “what does UserService do?” An agent with grep reads the class definition, then searches for callers, then reads those files, then searches for their callers. Four separate tool calls, 38,611 characters of context. An agent with hex-graph calls inspect_symbol(path="/project", name="UserService", file="src/services/user.ts") — one request returns the canonical symbol briefing: definition, incoming edges, outgoing edges, workspace ownership, and confidence summary.
“What breaks if I change calculateTotal?” Grep finds direct references but misses workspace-resolved dependencies and deeper callers. hex-graph’s trace_paths walks reverse call, reference, import, type, or mixed paths from one canonical symbol identity and returns the proven chain up to the requested depth.
“Who ultimately calls validateInput?” The agent needs to trace callers 3 levels deep. With grep: read the file, find callers, read those files, find their callers, read again — 12,716 characters across 4 tool calls. With hex-graph: trace_paths(path="/project", workspace_qualified_name="...", path_kind="calls", direction="reverse", depth=3) — one call returns the full call chain, served from the graph.
New to a 50-file project? An agent needs to build a mental map. With built-in tools, it reads every file — 389,523 characters across 50 Read calls. With hex-graph: analyze_architecture() returns workspace modules, ownership boundaries, cycles, coupling, and cross-module/package dependency edges. One call, 2,941 characters.
For a PR or local worktree diff, the hard part is not finding the changed files — it is understanding which changed symbols are risky. With hex-graph: analyze_changes(base_ref="origin/main") returns changed symbols, deleted API warnings, high-impact edits, and optional supporting paths in one compact semantic review snapshot.
Query, analyze, and maintain the knowledge graph. Symbol/query tools stay project-scoped by requiring path; agents should auto-fill that from the active project.
| Tool | What it does |
|---|---|
| index_project | Scan and index project into a knowledge graph. Idempotent, skips unchanged files |
| install_graph_providers | Detect or install graph-specific providers and optional SCIP exporters for the current project |
| export_scip | Export indexed symbol facts to a binary SCIP artifact for external tooling |
| import_scip_overlay | Import a binary SCIP artifact into provenance-tagged overlay facts without replacing the native graph |
| find_symbols | Discover candidate symbols by name or partial name before deeper semantic analysis |
| inspect_symbol | Canonical symbol briefing: resolution, symbol context, reference summary, implementation summary, and framework roles |
| trace_paths | Unified path traversal across calls, references, imports, type, flow, or mixed graph layers |
| find_references | Find semantic usages of one symbol identity, including framework overlay wiring when present |
| find_implementations | Find implementations and overrides for a canonical symbol identity |
| trace_dataflow | Deterministic source-to-sink dataflow tracing between anchored flow points |
| analyze_changes | Review a git diff, commit range, or worktree change set and return a compact semantic risk snapshot |
| analyze_edit_region | Inspect the semantic impact of editing a concrete file range, including callers, flow, duplicates, and framework wiring |
| analyze_architecture | High-level architecture view with modules, dependency boundaries, cycles, coupling, and framework surfaces |
| audit_workspace | Workspace cleanup and maintainability review: unused exports, hotspots, and clone groups |
| index_project | Scan and index a project into the graph kernel, including precise and framework-aware overlays when available |
Language-specific capabilities for graph and liveness analysis.
| Language | Extensions | Graph Features | Unused Export Confidence |
|---|---|---|---|
| JavaScript | .js .mjs .cjs .jsx | Full | Full liveness |
| TypeScript | .ts .tsx | Full | Full liveness |
| Python | .py | Definitions, calls, `__all__` exports, workspace-aware absolute + relative imports | Proven unused + uncertain split |
| C# | .cs | Definitions, calls, public exports, project/namespace ownership, references | Proven unused + uncertain split |
| PHP | .php | Definitions, calls, top-level/public exports, PSR-4 namespace resolution | Proven unused + uncertain split |
Public benchmark mode reports only session-derived workflow comparisons against built-in grep/read chains.
Commands
npm run benchmark -- --repo /path/to/repo
npm run benchmark:diagnostic -- --repo /path/to/repo
| ID | Workflow | Built-in | Hex-graph | Savings | Ops | Steps |
|---|---|---|---|---|---|---|
| W1 | Explore unfamiliar MCP before refactor | 93,361 ch | 16,081 ch | 83% | 12→3 | 12→3 |
| W2 | Estimate blast radius before refactor | 106,117 ch | 49,674 ch | 53% | 7→3 | 5→3 |
| W3 | Audit cycles, dead exports, hotspots | 61,754 ch | 4,184 ch | 93% | 22→4 | 22→4 |
| W4 | Review PR semantic risk snapshot | 51,390 ch | 44,474 ch | 13% | 3→2 | 4→2 |
These workflows are derived from recent real Claude sessions: unfamiliar-codebase exploration, blast-radius estimation, code-quality audit, and PR risk review.
Atomic query comparisons and index-cost numbers remain available under diagnostics, but they are no longer used as headline benchmark claims.
Built on SQLite and tree-sitter — fast indexing, instant queries, zero external services.
.hex-skills/codegraph/index.db per project. FTS5 for fast symbol search.Three packages, one workflow.
| Package | Purpose | npm |
|---|---|---|
| hex-line-mcp | Local file editing + hooks | @levnikolaevich/hex-line-mcp |
| hex-ssh-mcp | Remote file editing over SSH | @levnikolaevich/hex-ssh-mcp |
| hex-graph-mcp | Code knowledge graph + AST indexing | @levnikolaevich/hex-graph-mcp |