# 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](#mcp-tools-reference)).
- **Cross-repo dependency resolution** — `#include`s, 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.

```bash
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

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

### Index a multi-repo group

Create a `group_config.json` (see [Group Configuration](#group-configuration)), then:

```bash
mindgraph index ./group_config.json
```

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

### Start the MCP server

```bash
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](#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):

```json
{
  "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):

```json
{
  "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:

```json
{
  "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.

```json
{
  "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 `#include`s. |
| `cross_repo_includes[]` | Maps an include prefix in `from` to an absolute path inside `to`. |

Generate a starter config with:

```bash
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`.

```bash
# 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.

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

### `mindgraph status`

Show per-repo and aggregate index statistics.

```bash
mindgraph status
mindgraph status --repo engine-core
```

### `mindgraph search <query>`

Quick symbol search from the terminal.

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

### `mindgraph group`

Manage repository groups.

```bash
# 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

```bash
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](./LICENSE) for details.