Multi-Repository Code Knowledge Graph Engine
MindGraph is a local-first static analysis engine that turns N source repositories into a single, queryable code knowledge graph and exposes it to AI agents through the Model Context Protocol (MCP). It unifies the core capabilities of CodeGraph (symbol graph + impact analysis), GitNexus (trace, route mapping, change detection, cross-repo groups), and Graphify (community detection, god nodes, shortest path, edge confidence) into one tool with first-class multi-repo support.
- Multi-repo merging — Index an unbounded number of repositories into one unified graph. Each repo retains its identity (
repo_id,repo_name,root_path) while participating in a shared symbol space. - 22 MCP tools spanning exploration, advanced graph queries, graph intelligence, and group management (see MCP Tools Reference).
- Cross-repo dependency resolution —
#includes, calls, and type references that span repositories are resolved into explicit cross-repo edges usingcross_repo_includesmappings. - Layer architecture annotations — Tag repos with a
layer(e.g.ui,business,engine,sdk) and monorepo directories withsub_layers, then filter or group any query by layer. - Edge confidence tagging — Every edge carries a
confidenceofEXTRACTED(from source),INFERRED(heuristic), orAMBIGUOUS, plus aprovenance(static,inferred,cross-repo,synthesized). - Graph intelligence — Leiden/Louvain community detection, god-node ranking (degree / betweenness / PageRank), and shortest-path queries (directed and undirected).
- C/C++ focused, multi-language aware — C and C++ are the primary test targets; TypeScript, Python, Rust, Go, and Java extractors are included.
- Local and private — All parsing, storage, and querying happens on your machine. No network calls during indexing or querying.
- Incremental re-index — Changing one repo only re-indexes that repo and re-resolves its cross-repo edges. Circular repo dependencies are detected and reported, never infinite-looped.
Requirements: Node.js >= 22, npm.
git clone https://github.com/your-org/mindgraph.git
cd mindgraph
npm install
npm run build
npm link # optional: exposes the `mindgraph` binary on PATHmindgraph index /path/to/repo --layer engine --id engine-coreCreate a group_config.json (see Group Configuration), then:
mindgraph index ./group_config.jsonMindGraph indexes every repo in the group and resolves cross-repo edges in one pass.
mindgraph mcp --group-config ./group_config.jsonThe server speaks MCP over stdio and is intended to be launched by an MCP client (Claude Desktop, Cursor, etc.), not run interactively.
See MCP Configuration below.
Add MindGraph to your MCP client's config file.
Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"mindgraph": {
"command": "mindgraph",
"args": ["mcp", "--group-config", "/absolute/path/to/group_config.json"],
"env": {
"MINDGRAPH_DIR": "/absolute/path/to/data-dir"
}
}
}
}Cursor — .cursor/mcp.json in your workspace (or global Cursor MCP settings):
{
"mcpServers": {
"mindgraph": {
"command": "mindgraph",
"args": ["mcp", "--group-config", "/absolute/path/to/group_config.json"]
}
}
}If MindGraph isn't on PATH, use the absolute path to the binary or invoke it through Node:
{
"mcpServers": {
"mindgraph": {
"command": "node",
"args": ["/absolute/path/to/mindgraph/dist/index.js", "mcp"]
}
}
}Data directory resolution order: MINDGRAPH_DIR env var, then ./.mindgraph (if present), then ~/.mindgraph.
A group_config.json declares the repos in a group, their architectural layers, and the include-path mappings used to resolve cross-repo references.
{
"name": "av-editor",
"repos": [
{
"id": "ui-layer",
"path": "/path/to/ui-repo",
"layer": "ui",
"include_paths": ["src/", "include/"]
},
{
"id": "engine-core",
"path": "/path/to/engine-core",
"layer": "engine",
"sub_layers": ["logic", "render", "service", "base", "gpu"],
"include_paths": ["include/", "src/"]
}
],
"cross_repo_includes": [
{
"from": "ui-layer",
"to": "engine-core",
"mapping": { "engine/": "/path/to/engine-core/include/" }
}
]
}| Field | Description |
|---|---|
name |
Group identifier. |
repos[].id |
Stable repo identifier used in queries and edges. |
repos[].path |
Absolute path to the repository root. |
repos[].layer |
Architectural layer tag (e.g. ui, engine, sdk). |
repos[].sub_layers |
Optional sub-layer names for monorepo-style directories. |
repos[].include_paths |
Directories searched when resolving #includes. |
cross_repo_includes[] |
Maps an include prefix in from to an absolute path inside to. |
Generate a starter config with:
mindgraph group init --name av-editor --repo /path/to/ui --repo /path/to/engineGlobal options: --db <dir> (override data directory), -v, --verbose (debug logging).
Index a repository directory or a group_config.json.
# Single repo
mindgraph index /path/to/repo --layer engine --id engine-core --group default
# Multi-repo group
mindgraph index ./group_config.jsonOptions: --layer <layer>, --id <id>, --group <name> (default: default).
Start the MCP server over stdio.
mindgraph mcp --group-config ./group_config.jsonShow per-repo and aggregate index statistics.
mindgraph status
mindgraph status --repo engine-coreQuick symbol search from the terminal.
mindgraph search "VideoEncoder" --kind class --limit 20 --repo engine-coreManage repository groups.
# Create a group_config.json in the current directory
mindgraph group init --name my-group --repo /path/to/a --repo /path/to/b
# Add (and index) a repo into a group
mindgraph group add /path/to/repo --group my-group --layer sdk --id sdk-repo
# Re-sync cross-repo edges (incremental, or --full to re-index first)
mindgraph group sync --group my-group
mindgraph group sync --group my-group --full --group-config ./group_config.jsonAll tools are read-only, idempotent, and non-destructive (except mindgraph_rename, which is dry-run by default).
| Tool | Description |
|---|---|
mindgraph_explore |
Primary semantic exploration; returns symbols, call paths, code excerpts, and cross-repo relationships for a natural-language or symbol query. |
mindgraph_search |
Quick symbol search by name/pattern, filterable by kind and repo. |
mindgraph_node |
Detailed info for one symbol: signature, docstring, visibility, callers/callees counts, optional source code. |
mindgraph_callers |
Who calls this symbol, with call sites and configurable depth. |
mindgraph_callees |
What this symbol calls, with call sites and configurable depth. |
mindgraph_impact |
Blast-radius analysis: depth-grouped impact tree with confidence scores and affected repos/layers. |
mindgraph_files |
Indexed file tree with language, symbol counts, and layer annotations. |
mindgraph_status |
Index health: per-repo and aggregate files, nodes, edges, unresolved refs, last sync. |
| Tool | Description |
|---|---|
mindgraph_trace |
Shortest directed path between two symbols over selected edge types. |
mindgraph_detect_changes |
Git-diff impact analysis: changed files → affected symbols → downstream impact, grouped by layer. |
mindgraph_rename |
Coordinated multi-file rename, cross-repo aware, dry-run by default. |
mindgraph_route_map |
API/framework route map with handler symbols and middleware chains. |
mindgraph_cypher |
Raw Cypher-style query over the underlying SQLite graph. |
| Tool | Description |
|---|---|
mindgraph_communities |
Louvain/Leiden community detection with cross-community bridges and layer distribution. |
mindgraph_god_nodes |
Most-connected core abstractions, ranked by degree, betweenness, or PageRank. |
mindgraph_shortest_path |
Conceptual undirected shortest path with edge-type and confidence annotations. |
mindgraph_graph_stats |
Global statistics: node/edge counts by kind, communities, confidence breakdown, layer distribution, cross-repo edge count. |
mindgraph_neighbors |
Direct neighbors of a symbol, grouped by relation type with edge metadata. |
| Tool | Description |
|---|---|
mindgraph_group_list |
List configured groups with their repos, layers, and index status. |
mindgraph_group_sync |
Rebuild cross-repo links for a group (incremental or full). |
mindgraph_repo_add |
Add and index a repository in a group. |
mindgraph_repo_remove |
Remove a repository from a group and clean up its data. |
| Layer | Technology |
|---|---|
| Runtime | Node.js + TypeScript (ESM) |
| Parser | web-tree-sitter with WASM grammars (no native build required) |
| Storage | SQLite (mindgraph.db) with FTS5 full-text search |
| Graph algorithms | graphology + communities-louvain, metrics, shortest-path |
| MCP server | @modelcontextprotocol/sdk over stdio |
| CLI | commander |
| Schema validation | zod |
| Tests | vitest |
Pipeline: scan (file discovery + ignore rules) → parse (tree-sitter) → extract (per-language symbol/edge extractors) → resolve (intra-repo references) → cross-repo resolve (group-aware edge synthesis) → store (SQLite + FTS5) → serve (MCP tools).
Source layout:
src/
├── index.ts # CLI entry
├── mcp/ # MCP server + one file per tool
├── core/ # scanner, parser, language extractors, resolvers
├── graph/ # SQLite store, traversal, communities, centrality, paths
├── group/ # group config, multi-repo orchestration, sync
└── utils/ # logger, config, fs helpers
See SPEC.md for the full data model (SQLite schema) and the cross-repo resolution algorithm.
npm test # run the full vitest suite once
npm run test:watch # watch mode
npm run lint # eslint over src/Integration tests run against a synthetic 3-repo C++ fixture under test/fixtures/; end-to-end tests target real C++ projects (see SPEC.md §5).
MIT — see LICENSE for details.