npm package: @munero/cindex
Description: Offline MCP codebase graph indexer for Claude Code — indexes codebases into dependency/symbol graphs and serves context bundles
Latest version: 0.2.1

# cindex

Offline MCP codebase graph indexer for AI-powered editors. Parses codebases into dependency/symbol graphs using Tree-sitter and serves ranked context bundles on demand.

Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), and any editor that supports [MCP](https://modelcontextprotocol.io).

## Setup

### Claude Code

```bash
claude mcp add -s user cindex -- npx -y @munero/cindex
```

### Cursor

Add to your project's `.cursor/mcp.json` (or global `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "cindex": {
      "command": "npx",
      "args": ["-y", "@munero/cindex"]
    }
  }
}
```

Then restart Cursor. The cindex tools will be available in Cursor's AI agent mode.

### Other MCP-compatible editors

cindex runs as a stdio MCP server. For any editor that supports MCP, point it at:

```
npx -y @munero/cindex
```

Or install globally and use the binary directly:

```bash
npm install -g @munero/cindex
cindex
```

## What it does

cindex parses your codebase using Tree-sitter, builds a graph of files, symbols (functions, classes, interfaces, types), and relationships (imports, exports, extends, implements), stores it in a local SQLite database, and exposes it via MCP tools.

When the AI works on a task, `repo_context_get` returns a ranked bundle of the most relevant files and code snippets based on the dependency graph and text search — so it starts with the right context.

## MCP Tools

| Tool | Purpose |
|------|---------|
| `repo_status` | Check if a repo is indexed |
| `repo_index` | Index/re-index a codebase (incremental by default) |
| `repo_search` | Full-text search across files and symbols |
| `repo_snippet` | Read source code from indexed files |
| `repo_context_get` | Get ranked context bundle for a task description |

## Making the AI use cindex automatically

The AI won't proactively use cindex tools unless instructed. Add these instructions to your project:

**Claude Code** — add to your project's `CLAUDE.md`:

**Cursor** — add to your project's `.cursorrules`:

```markdown
## Codebase Index (cindex)

This project is indexed with cindex (MCP codebase graph indexer).

Workflow — do this at the start of every session:
1. Call `repo_status` with this project's root path to check if the index exists
2. If not indexed or if many files have changed, call `repo_index` to update
3. Before starting any coding task, call `repo_context_get` with a description of the task
4. Use `repo_search` to find specific symbols, files, or types by keyword
5. Use `repo_snippet` to read full source of files identified by search or context
```

## Supported Languages

| Language | Extensions | Extracts |
|----------|-----------|----------|
| **TypeScript** | `.ts`, `.tsx` | imports, exports, classes, interfaces, types, enums, functions |
| **JavaScript** | `.js`, `.jsx`, `.mjs`, `.cjs` | ESM + CommonJS imports/exports, classes, functions |
| **Python** | `.py`, `.pyi` | imports, classes, inheritance, functions, methods |
| **Go** | `.go` | imports, structs, interfaces, functions, methods |
| **Rust** | `.rs` | use imports, structs, traits, impl blocks, functions |
| **PHP** | `.php` | use/namespace, classes, interfaces, methods |
| **Java** | `.java` | imports, classes, interfaces, extends/implements, methods |
| **Ruby** | `.rb` | require, modules, classes, inheritance, methods |
| **C** | `.c`, `.h` | #include, functions, #defines |
| **C++** | `.cpp`, `.cc`, `.hpp`, etc. | #include, classes, namespaces, methods |
| **C#** | `.cs` | using, namespaces, classes, interfaces, enums, methods |

## CLI

cindex includes a CLI for terminal use alongside its MCP server mode.

```bash
# Check index status
cindex status
cindex status /path/to/repo

# Index a repository
cindex index                      # auto-detect mode (full or incremental)
cindex index --full               # force full re-index
cindex index /path/to/repo        # index a specific repo

# Visualize the dependency graph
cindex visualize                  # generate and open in browser
cindex visualize --no-open        # generate without opening
cindex visualize /path/to/repo

# Start MCP server (default, used by editors)
cindex

# Help
cindex help
```

Running `cindex` with no arguments starts the MCP server on stdio — this is backwards-compatible with existing editor configurations.

## Graph Visualizer

cindex includes an interactive graph visualizer that renders your codebase as a D3.js force-directed graph in the browser.

```bash
cindex visualize
cindex visualize /path/to/repo
cindex visualize --no-open
```

The visualizer shows files (blue), classes (orange), interfaces (purple), and enums (green) with import, extends, and implements relationships. Features include search, zoom/pan, node pinning, and type filtering.

The repo must be indexed first (`cindex index` or `repo_index` via MCP).

## How it works

1. **Walk** — Discovers files respecting `.gitignore`
2. **Parse** — Extracts symbols, imports, and exports via Tree-sitter ASTs
3. **Resolve** — Links import paths to actual files in the repo
4. **Store** — Writes to SQLite with FTS5 full-text search index
5. **Retrieve** — Candidate discovery → BFS graph expansion → ranking → budget-aware snippet extraction

Indexing is fast (~2s for medium repos) and incremental updates only re-parse changed files.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `CINDEX_DB_PATH` | `~/.cindex/cindex.db` | Database file location |

## Development

```bash
git clone https://github.com/MuneroLtd/cIndex.git
cd cIndex
npm install
npm test          # 198 tests
npm run build     # production bundle
npm run dev       # dev server with tsx
```

## Requirements

- Node.js >= 20
- C++ compiler (for native tree-sitter/SQLite bindings — installed automatically on most systems)

## License

MIT