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.

Related MCP server: Axon

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/" }
    }
  ]
}

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)

Advanced (GitNexus)

Graph Intelligence (Graphify)

Multi-Repo Management

Architecture

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.