MindGraph

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.

---

Features

• 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 using cross_repo_includes mappings.
• Layer architecture annotations — Tag repos with a layer (e.g. ui, business, engine, sdk) and monorepo directories with sub_layers, then filter or group any query by layer.
• Edge confidence tagging — Every edge carries a confidence of EXTRACTED (from source), INFERRED (heuristic), or AMBIGUOUS, plus a provenance (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.

---

Quick Start

Installation

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 PATH

Index a single repository

mindgraph index /path/to/repo --layer engine --id engine-core

Index a multi-repo group

Create a group_config.json (see Group Configuration), then:

mindgraph index ./group_config.json

MindGraph indexes every repo in the group and resolves cross-repo edges in one pass.

Start the MCP server

mindgraph mcp --group-config ./group_config.json

The server speaks MCP over stdio and is intended to be launched by an MCP client (Claude Desktop, Cursor, etc.), not run interactively.

Configure your MCP client

See MCP Configuration below.

---

MCP Configuration

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.

---

Group Configuration

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/engine

---

CLI Reference

Global options: --db <dir> (override data directory), -v, --verbose (debug logging).

mindgraph index [path]

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.json

Options: --layer <layer>, --id <id>, --group <name> (default: default).

mindgraph mcp

Start the MCP server over stdio.

mindgraph mcp --group-config ./group_config.json

mindgraph status

Show per-repo and aggregate index statistics.

mindgraph status
mindgraph status --repo engine-core

mindgraph search <query>

Quick symbol search from the terminal.

mindgraph search "VideoEncoder" --kind class --limit 20 --repo engine-core

mindgraph group

Manage 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.json

---

MCP Tools Reference

All tools are read-only, idempotent, and non-destructive (except mindgraph_rename, which is dry-run by default).

Core (CodeGraph)

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.

Advanced (GitNexus)

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.

Graph Intelligence (Graphify)

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.

Multi-Repo Management

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.

---

Architecture

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.

---

Testing

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).

---

License

MIT — see LICENSE for details.