Lets AI agents query a function-level dependency graph of a codebase through an MCP server and CLI for impact, complexity, and architecture analysis.
Also known as optave/ops-codegraph-tool, @optave/codegraph
- Stars
- 100
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is codegraph MCP?
codegraph lets AI agents query a function-level dependency graph of a codebase through an MCP server and CLI for impact, complexity, and architecture analysis.
Summary generated from the project's README
About codegraph MCP server
Providing AI agents with a structural map of a codebase is what ops-codegraph-tool enables. It builds a function-level dependency graph that tracks every function, caller, and dependency within a project. By using tree-sitter for parsing and storing data in SQLite, the tool provides an intelligent way for AI clients to understand code architecture without exhausting context windows through massive file reads.
Developers can use this tool via a CLI or an MCP server that exposes 34 specialized tools for direct querying. It operates entirely locally with no network calls or telemetry, meaning your code stays on your machine. There are no API keys, accounts, or Docker containers required to get started; you simply install the package via npm and run the build command. This setup allows agents to proactively identify impact, such as discovering how many files import a specific function, before making any edits.
What you can do with it
- 1Analyze function impactAsk an AI agent to identify all callers of a specific function to prevent breaking changes during a refactor.
- 2Enforce architectural boundariesUse the tool to ensure new code commits do not violate established architectural rules or layer boundaries.
- 3Audit code complexityRequest a report on the cognitive or cyclomatic complexity of a specific module to identify technical debt.
- 4Detect dead codeHave an agent find unused exports or functions that are no longer reachable within the dependency graph.
Written from the project's README. Every use case is checked against a quote from it.
How to install codegraph MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall codegraph MCP in Claude Code
$ claude mcp add ops-codegraph-tool -- npx -y @optave/codegraphInstall codegraph MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"ops-codegraph-tool": {
"command": "npx",
"args": [
"-y",
"@optave/codegraph"
]
}
}
}Install codegraph MCP in VS Code
.vscode/mcp.json
{
"servers": {
"ops-codegraph-tool": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@optave/codegraph"
]
}
}
}Install codegraph MCP in VS Code CLI
$ code --add-mcp '{"name":"ops-codegraph-tool","type":"stdio","command":"npx","args":["-y","@optave/codegraph"]}'Install codegraph MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"ops-codegraph-tool": {
"command": "npx",
"args": [
"-y",
"@optave/codegraph"
]
}
}
}Install codegraph MCP in Codex
$ codex mcp add ops-codegraph-tool -- npx -y @optave/codegraphInstall codegraph MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.ops-codegraph-tool] command = "npx" args = ["-y", "@optave/codegraph"]
Install codegraph MCP in Gemini CLI
$ gemini mcp add -s user ops-codegraph-tool npx -- -y @optave/codegraphInstall codegraph MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"ops-codegraph-tool": {
"command": "npx",
"args": [
"-y",
"@optave/codegraph"
]
}
}
}Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubThe Problem
AI agents face an impossible trade-off. They either spend thousands of tokens reading files to understand a codebase's structure — blowing up their context window until quality degrades — or they assume how things work, and the assumptions are often wrong. Either way, things break. The larger the codebase, the worse it gets.
An agent modifies a function without knowing 9 files import it. It misreads what a helper does and builds logic on top of that misunderstanding. It leaves dead code behind after a refactor. The PR gets opened, and your reviewer — human or automated — flags the same structural issues again and again: "this breaks 14 callers," "that function already exists," "this export is now dead." If the reviewer catches it, that's multiple rounds of back-and-forth. If they don't, it can ship to production. Multiply that by every PR, every developer, every repo.
The information to prevent these issues exists — it's in the code itself. But without a structured map, agents lack the context to get it right consistently, reviewers waste cycles on preventable issues, and architecture degrades one unreviewed change at a time.
What Codegraph Does
Codegraph builds a function-level dependency graph of your entire codebase — every function, every caller, every dependency — and keeps it current with sub-second incremental rebuilds.
It parses your code with tree-sitter (native Rust or WASM), stores the graph in SQLite, and exposes it where it matters most:
- MCP server — AI agents query the graph directly through 34 tools — one call instead of dozens of
grep/find/catinvocations - CLI — developers and agents explore, query, and audit code from the terminal
- CI gates —
checkandmanifestocommands enforce quality thresholds with exit codes - Programmatic API — embed codegraph in your own tools via
npm install
Instead of an agent editing code without structural context and letting reviewers catch the fallout, it knows "this function has 14 callers across 9 files" before it touches anything. Dead exports, circular dependencies, and boundary violations surface during development — not during review. The result: PRs that need fewer review rounds.
Free. Open source. Fully local. Zero network calls, zero telemetry. Your code stays on your machine. When you want deeper intelligence, bring your own LLM provider — your code only goes where you choose to send it.
Three commands to a queryable graph:
npm install -g @optave/codegraph
cd your-project
codegraph build
No config files, no Docker, no JVM, no API keys, no accounts. Point your agent at the MCP server and it has structural awareness of your codebase.
Why it matters
| Without codegraph | With codegraph | |
|---|---|---|
| Code review | Reviewers flag broken callers, dead code, and boundary violations round after round | Structural issues are caught during development — PRs pass review with fewer rounds |
| AI agents | Modify parseConfig() without knowing 9 files import it — reviewer catches it |
fn-impact parseConfig shows every caller before the edit — agent fixes it proactively |
| AI agents | Leave dead exports and duplicate helpers behind after refactors | Dead code, cycles, and duplicates surface in real time via hooks and MCP queries |
| AI agents | Produce code that works but doesn't fit the codebase structure | context <name> -T returns source, deps, callers, and tests — the agent writes code that fits |
| CI pipelines | Catch test failures but miss structural degradation | check --staged fails the build when blast radius or complexity thresholds are exceeded |
| Developers | Inherit a codebase and grep for hours to understand what calls what | context handleAuth -T gives the same structured view agents use |
| Architects | Draw boundary rules that erode within weeks | manifesto and boundaries enforce architecture rules on every commit |
Feature comparison
Comparison last verified: August 2026 (full re-verification of every linked repo's live README + GitHub API on 2026-08-09). Full analysis: COMPETITIVE_ANALYSIS.md
| Capability | codegraph (this repo) | code-review-graph | narsil-mcp | codegraph (other)¹ | claude-context | GitNexus |
|---|---|---|---|---|---|---|
| GitHub stars | ||||||
| Languages | 34 | 30+ | 32 | 20+ (34 named)² | 17³ | 14 |
| CLI tool | Yes (44 commands) | Yes | Partial (config/serve only)⁴ | Yes | — (MCP + library only) | Yes |
| API functionality (embeddable library) | Yes | — | — | Yes | Yes | Partial (HTTP API only)⁵ |
| Dataflow + CFG + AST querying | Yes | Call graph only | Yes | — | — | PDG opt-in, TS/JS only |
| Interprocedural dataflow (cross-function) | Yes⁶ | — | Partial (taint-only)⁷ | — | — | Partial (taint-only, opt-in)⁸ |
| Hybrid search (BM25 + semantic) | Yes | Yes | Yes (local ONNX, no key needed) | Keyword only | Yes | Yes |
| Git-aware (diff impact, co-change, branch diff) | All 3 | Partial (co-change unreliable)⁹ | Partial (no co-change/branch-diff) | — | — | Partial (no co-change) |
| Dead code / role classification | Yes | Yes | Yes | — | — | — |
| Code health (complexity metrics) | Yes (cognitive, cyclomatic, Halstead, MI) | — | Partial (cyclomatic + cognitive)¹⁰ | — | — | — |
| Incremental rebuilds | O(changed) | O(changed) | **O(changed)**¹¹ | **O(changed)**¹² | **O(changed)**¹³ | Partial (chunk cache-key)¹⁴ |
| Architecture rules + CI gate | Yes | Partial (risk-gate, no boundary rules) | Partial (layer model, no CI gate) | — | — | — |
| Security scanning (SAST / vuln detection) | Intentionally out of scope¹⁵ | — | Yes | — | — | Partial (opt-in taint, --pdg only) |
Zero config, npm install |
Yes | — (pip) | Yes | Yes | No¹⁶ | Yes |
| Runtime dependencies (direct packages)¹⁷ | 4 | 7 | 0¹⁸ | 10 | 23¹⁹ | 36 |
| Graph export (GraphML / Neo4j / DOT) | Yes | Yes²⁰ | Partial²¹ | — | — | — |
| Open source + commercial use | Yes (Apache-2.0) | Yes (MIT) | Yes (Apache-2.0/MIT) | Yes (MIT) | Yes (MIT) | Non-commercial²² |
¹ Unrelated tool sharing the name; focuses on AI token reduction via pre-indexed context, not structural analysis or CI gates. ² README says "20+ languages"; architecture docs list 34 across native + fallback grammar tiers. ³ Indexes 17 file extensions by default; AST-aware chunking covers ~10 — the rest fall back to plain text splitting. ⁴ narsil-mcp's CLI only manages config, lists tools, and serves the visualization frontend — no query commands; all graph queries require an MCP client. ⁵ GitNexus's local HTTP API (gitnexus serve, port 4747) only serves its own web UI — no importable library package. ⁶ Variable-level vertex model (arg_in/return_out/def_use) stitched across call edges — general-purpose, not just security, across all 34 languages. ⁷ trace_taint/get_typed_taint_flow cross function calls for security; general dataflow tools (get_data_flow, get_reaching_definitions) are per-function only. ⁸ Optional --pdg index (TS/JS only) adds taint source→sink tracking — security-scoped, not general cross-function flow. ⁹ Per its own README benchmark (2026-08-02), co-change eval returns 0 predicted files on every graded commit — "not yet a usable measurement." ¹⁰ get_complexity covers cyclomatic + cognitive complexity only — no Halstead metrics or maintainability index. ¹¹ Added Merkle-tree incremental indexing + watch mode (previously full re-index). ¹² OS-native file watcher reprocesses only changed files (debounced auto-sync); --force forces a full rebuild. ¹³ Merkle DAG + per-file MD5 hashing skips unchanged files, but each changed file still round-trips to the embedding provider + vector DB. ¹⁴ Cache-keyed, byte-budgeted chunk dispatch with incremental per-branch updates on checkout — finer than a full reprocess, but not per-file hashing. ¹⁵ Structural understanding, not vulnerability detection — use dedicated SAST tools (Semgrep, CodeQL, Snyk). ¹⁶ Requires an external Milvus vector DB + an embedding provider. A local keyless path exists (self-hosted Milvus + Ollama) but needs two running services; the managed path (Zilliz Cloud + OpenAI/VoyageAI/Gemini) trades that for cost. ¹⁷ Direct runtime deps declared in each project's own manifest (package.json/pyproject.toml), excluding dev/optional/transitive deps. ¹⁸ Single compiled binary — no separate packages to install. ¹⁹ mcp + core packages combined — plus the external vector DB + embedding provider noted above. ²⁰ Added GraphML, Neo4j Cypher, Obsidian vault, and SVG export. ²¹ Visualization frontend graph views, plus JSON-LD/N-Quads export for its Code Context Graph — but not GraphML or Neo4j specifically (a repo-wide code search found zero matches for either string); an internal DOT exporter exists (to_dot()) but isn't exposed via CLI or MCP. ²² PolyForm Noncommercial 1.0.0 license; separate commercial/enterprise licensing available.
What makes codegraph different
| Differentiator | In practice | |
|---|---|---|
| 🤖 | AI-first architecture | 34-tool MCP server — agents query the graph directly instead of scraping the filesystem. One call replaces 20+ grep/find/cat invocations |
| 🏷️ | Role classification | Every symbol auto-tagged as entry/core/utility/adapter/dead/leaf — agents understand a symbol's architectural role without reading surrounding code |
| 🔬 | Function-level, not just files | Traces handleAuth() → validateToken() → decryptJWT() and shows 14 callers across 9 files break if decryptJWT changes |
| ⚡ | Always-fresh graph | Three-tier change detection: journal (O(changed)) → mtime+size (O(n) stats) → hash (O(changed) reads). Sub-second rebuilds — agents work with current data |
| 💥 | Git diff impact | codegraph diff-impact shows changed functions, their callers, and full blast radius — enriched with historically coupled files from git co-change analysis. Ships with a GitHub Actions workflow |
| 🌐 | Multi-language, one graph | 34 languages in a single graph — JS/TS, Python, Go, Rust, Java, C#, PHP, Ruby, C/C++, Kotlin, Swift, Scala, Bash, HCL, Elixir, Lua, Dart, Zig, Haskell, OCaml, F#, Gleam, Clojure, Julia, R, Erlang, Solidity, Objective-C, CUDA, Groovy, Verilog — agents don't need per-language tools |
| 🧠 | Hybrid search | BM25 keyword + semantic embeddings fused via RRF — hybrid (default), semantic, or keyword mode; multi-query via "auth; token; JWT" |
| 🔬 | Dataflow + CFG | Track how data flows through and between functions — function-level edges (flows_to, returns, mutates), interprocedural variable-level edges (arg_in, return_out, def_use), and intraprocedural control flow graphs — all 34 languages |
| 🔓 | Fully local, zero cost | No API keys, no accounts, no network calls. Optionally bring your own LLM provider — your code only goes where you choose |
🚀 Quick Start
npm install -g @optave/codegraph
cd your-project
codegraph build # → .codegraph/graph.db created
That's it. The graph is ready. Now connect your AI agent.
For AI agents (primary use case)
Connect directly via MCP — your agent gets 34 tools to query the graph:
codegraph mcp # 34-tool MCP server — AI queries the graph directly
Or add codegraph to your agent's instructions (e.g. CLAUDE.md):
Before modifying code, always:
1. `codegraph where <name>` — find where the symbol lives
2. `codegraph context <name> -T` — get full context (source, deps, callers)
3. `codegraph fn-impact <name> -T` — check blast radius before editing
After modifying code:
4. `codegraph diff-impact --staged -T` — verify impact before committing
Full agent setup: AI Agent Guide · CLAUDE.md template
For developers
The same graph is available via CLI:
codegraph map # see most-connected files
codegraph query myFunc # find any function, see callers & callees
codegraph deps src/index.ts # file-level import/export map
Or install from source:
git clone https://github.com/optave/ops-codegraph-tool.git
cd codegraph && npm install && npm link
Dev builds: Pre-release tarballs are attached to GitHub Releases. Install with
npm install -g <path-to-tarball>. Note thatnpm install -g <tarball-url>does not work because npm cannot resolve optional platform-specific dependencies from a URL — download the.tgzfirst, then install from the local file.
✨ Features
| Feature | Description | |
|---|---|---|
| 🤖 | MCP server | 34-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
| 🎯 | Deep context | context gives agents source, deps, callers, signature, and tests for a function in one call; audit --quick gives structural summaries |
| 🏷️ | Node role classification | Every symbol auto-tagged as entry/core/utility/adapter/dead/leaf based on connectivity — agents instantly know architectural role |
| 📦 | Batch querying | Accept a list of targets and return all results in one JSON payload — enables multi-agent parallel dispatch |
| 💥 | Impact analysis | Trace every file affected by a change (transitive) |
| 🧬 | Function-level tracing | Call chains, caller trees, function-level impact, and A→B pathfinding with qualified call resolution |
| 📍 | Fast lookup | where shows exactly where a symbol is defined and used — minimal, fast |
| 🔍 | Symbol search | Find any function, class, or method by name — exact match priority, relevance scoring, --file and --kind filters |
| 📁 | File dependencies | See what a file imports and what imports it |
| 📊 | Diff impact | Parse git diff, find overlapping functions, trace their callers |
| 🔗 | Co-change analysis | Analyze git history for files that always change together — surfaces hidden coupling the static graph can't see; enriches diff-impact with historically coupled files |
| 🗺️ | Module map | Bird's-eye view of your most-connected files |
| 🏗️ | Structure & hotspots | Directory cohesion scores, fan-in/fan-out hotspot detection, module boundaries |
| 🔄 | Cycle detection | Find circular dependencies at file or function level |
| 📤 | Export | DOT, Mermaid, JSON, GraphML, GraphSON, and Neo4j CSV graph export |
| 🧠 | Semantic search | Embeddings-powered natural language search with multi-query RRF ranking |
| 👀 | Watch mode | Incrementally update the graph as files change |
| ⚡ | Always fresh | Three-tier incremental detection — sub-second rebuilds even on large codebases |
| 🔬 | Data flow analysis | Intraprocedural parameter tracking, return consumers, argument flows, and mutation detection — all 34 languages |
| 🧮 | Complexity metrics | Cognitive, cyclomatic, nesting depth, Halstead, and Maintainability Index per function |
| 🏘️ | Community detection | Leiden clustering to discover natural module boundaries and architectural drift |
| 📜 | Manifesto rule engine | Configurable pass/fail rules with warn/fail thresholds for CI gates via check (exit code 1 on fail) |
| 👥 | CODEOWNERS integration | Map graph nodes to CODEOWNERS entries — see who owns each function, ownership boundaries in diff-impact |
| 💾 | Graph snapshots | snapshot save/restore for instant DB backup and rollback — checkpoint before refactoring, restore without rebuilding |
| 🔎 | Hybrid BM25 + semantic search | FTS5 keyword search + embedding-based semantic search fused via Reciprocal Rank Fusion — hybrid, semantic, or keyword modes |
| 📄 | Pagination & NDJSON streaming | Universal --limit/--offset pagination on all MCP tools and CLI commands; --ndjson for newline-delimited JSON streaming |
| 🔀 | Branch structural diff | Compare code structure between two git refs — added/removed/changed symbols with transitive caller impact |
| 🛡️ | Architecture boundaries | User-defined dependency rules between modules with onion architecture preset — violations flagged in manifesto and CI |
| ✅ | CI validation predicates | check command with configurable gates: complexity, blast radius, cycles, boundary violations — exit code 0/1 for CI |
| 📋 | Composite audit | Single audit command combining explain + impact + health metrics per function — one call instead of 3-4 |
| 🚦 | Triage queue | triage merges connectivity, hotspots, roles, and complexity into a ranked audit priority queue |
| 🔬 | Dataflow analysis | Track how data moves through and between functions — function-level (flows_to, returns, mutates) and interprocedural variable-level edges (arg_in, return_out, def_use) — all 34 languages, included by default, skip with --no-dataflow |
| 🧩 | Control flow graph | Intraprocedural CFG construction for all 34 languages — cfg command with text/DOT/Mermaid output, included by default, skip with --no-cfg |
| 🔎 | AST node querying | Stored queryable AST nodes (calls, new, string, regex, throw, await) — ast command with SQL GLOB pattern matching |
| 🧬 | Expanded node/edge types | parameter, property, constant node kinds with parent_id for sub-declaration queries; contains, parameter_of, receiver edge kinds |
| 📊 | Exports analysis | exports <file> shows all exported symbols with per-symbol consumers, re-export detection, and counts |
| 📈 | Interactive viewer | codegraph plot generates an interactive HTML graph viewer with hierarchical/force/radial layouts, complexity overlays, and drill-down |
| 🏷️ | Stable JSON schema | normalizeSymbol utility ensures consistent 7-field output (name, kind, file, line, endLine, role, fileHash) across all commands |
See docs/examples for real-world CLI and MCP usage examples.
📦 Commands
Build & Watch
codegraph build [dir] # Parse and build the dependency graph
codegraph build --no-incremental # Force full rebuild
codegraph build --dataflow # Extract data flow edges (flows_to, returns, mutates)
codegraph build --engine wasm # Force WASM engine (skip native)
codegraph watch [dir] # Watch for changes, update graph incrementally
Query & Explore
codegraph query <name> # Find a symbol — shows callers and callees
codegraph deps <file> # File imports/exports
codegraph map # Top 20 most-connected files
codegraph map -n 50 --no-tests # Top 50, excluding test files
codegraph where <name> # Where is a symbol defined and used?
codegraph where --file src/db.js # List symbols, imports, exports for a file
codegraph stats # Graph health: nodes, edges, languages, quality score
codegraph roles # Node role classification (entry, core, utility, adapter, dead, leaf)
codegraph roles --role dead -T # Find dead code (unreferenced, non-exported symbols)
codegraph roles --dynamic # Show dynamic call sink edges (eval, computed-key, unresolved)
codegraph roles --role core --file src/ # Core symbols in src/
codegraph exports src/queries.js # Per-symbol consumer analysis (who calls each export)
codegraph children <name> # List parameters, properties, constants of a symbol
Deep Context (designed for AI agents)
codegraph context <name> # Full context: source, deps, callers, signature, tests
codegraph context <name> --depth 2 --no-tests # Include callee source 2 levels deep
codegraph brief <file> # Token-efficient file summary: symbols, roles, risk tiers
codegraph audit <file> --quick # Structural summary: public API, internals, data flow
codegraph audit <function> --quick # Function summary: signature, calls, callers, tests
Impact Analysis
codegraph impact <file> # Transitive reverse dependency trace
codegraph query <name> # Function-level: callers, callees, call chain
codegraph query <name> --no-tests --depth 5
codegraph fn-impact <name> # What functions break if this one changes
codegraph path <from> <to> # Shortest path between two symbols (A calls...calls B)
codegraph path <from> <to> --reverse # Follow edges backward
codegraph path <from> <to> --depth 5 --kinds calls,imports
codegraph diff-impact # Impact of unstaged git changes
codegraph diff-impact --staged # Impact of staged changes
codegraph diff-impact HEAD~3 # Impact vs a specific ref
codegraph diff-impact main --format mermaid -T # Mermaid flowchart of blast radius
codegraph branch-compare main feature-branch # Structural diff between two refs
codegraph branch-compare main HEAD --no-tests # Symbols added/removed/changed vs main
codegraph branch-compare v2.4.0 v2.5.0 --json # JSON output for programmatic use
codegraph branch-compare main HEAD --format mermaid # Mermaid diagram of structural changes
codegraph MCP questions
How do I add codegraph MCP to Claude Code?
Run claude mcp add ops-codegraph-tool -- npx -y @optave/codegraph in your terminal. Add --scope user to make it available in every project.
How do I add codegraph MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How many tools does the codegraph MCP server provide?
The MCP server exposes 34 tools so AI agents can query the dependency graph directly.
Does codegraph require API keys or network access?
No. It runs fully locally with no API keys, accounts, or telemetry.
How many languages does codegraph support?
It builds function-level dependency graphs across 34 languages.
How do I get started with codegraph?
Install the npm package globally, then run the build command inside your project.
Can codegraph enforce architecture rules in CI?
Yes, the check and manifesto commands enforce quality and boundary thresholds with exit codes.