# Cartog

> Pre-indexed code knowledge graph via treesitter, enchanced query with RAG, MCP server, private and local storage. Agent ready.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jrollin-cartog`
- **Verified:** Pending review
- **Seller:** [jrollin](https://agentstack.voostack.com/s/jrollin)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jrollin](https://github.com/jrollin)
- **Source:** https://github.com/jrollin/cartog
- **Website:** https://www.cartog.dev

## Install

```sh
agentstack add mcp-jrollin-cartog
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Cartog

[](https://github.com/jrollin/cartog/actions/workflows/ci.yml)
[](https://codecov.io/gh/jrollin/cartog)
[](https://crates.io/crates/cartog)
[](https://crates.io/crates/cartog)
[](https://github.com/jrollin/cartog)
[](LICENSE)

**Map your codebase. Navigate by graph, not grep.**

**Semantic search that returns named symbols, not text chunks — ranked, reranked, and budget-aware.**

**~280 tokens per query vs ~1,700 for grep+read · 97% recall · 8 µs–20 ms structural-query latency · 15 languages + 4 frameworks.**

Cartog pre-computes a code graph — symbols, and the calls, imports, and inheritance between them — so you can query structure instantly instead of grepping for text. Ask "who calls this?", "what breaks if I change it?", or "find the auth logic" and get a ranked, structured answer: an exact function with its signature and span, not a file-and-line guess you have to open and read.

Use it from the CLI for day-to-day navigation, or as an MCP server so AI agents query the graph instead of flooding their context with raw file dumps — at a fraction of the token cost. One static binary, one SQLite file. No Python, no pip, no Docker, no cloud: 100% local by default.

> **[Documentation site](https://www.cartog.dev/)**

## Contents

- [Quick Start](#quick-start)
- [Why Cartog](#why-cartog)
- [What You Get](#what-you-get)
- [Install](#install)
- [Commands](#commands)
- [MCP Server Setup](#mcp-server-setup)
- [Supported Languages](#supported-languages)
- [Configuration](#configuration)
- [Privacy](#privacy)
- [Troubleshooting](#troubleshooting)
- [Articles](#articles)

## Quick Start

```bash
curl -fsSL https://www.cartog.dev/install.sh | sh   # or: cargo install cartog
cd your-project
cartog init                   # 1. scaffold .cartog.toml
cartog index                  # 2. build the code graph
```

That's it for CLI use. Two commands.

If you want MCP wired into your editor (Claude Code, Cursor, VS Code, Claude Desktop, Codex CLI, Gemini CLI, OpenCode, Windsurf, Zed, Antigravity, Kiro, Hermes Agent), add one more:

```bash
cartog ide                    # optional — only if you want editor integration
```

All three commands are idempotent.

Now query:

```bash
cartog search validate        # find symbols by name         (sub-ms)
cartog refs validate_token    # who calls this?              (
> **\*** 97 % recall requires a matching language server on PATH. The
> default build ships LSP support; heuristic-only resolution (no server
> found, or `--no-lsp`) lands around 25–37 %, with specifics varying by
> language.

## What You Get

### Fast structural queries

Pre-computed graph means no re-reading files, no multi-step discovery.

```bash
cartog search parse              # symbol name lookup (sub-ms)
cartog refs UserService          # all callers, importers, inheritors
cartog callees authenticate      # what does this function call?
cartog impact SessionManager     # blast radius — callers-of-callers, depth N
cartog hierarchy BaseService     # inheritance tree
cartog deps src/routes/auth.py   # file-level imports
cartog changes --commits 5       # symbols affected by recent git commits
cartog map --tokens 4000         # codebase overview, ranked by centrality
```

### Semantic search (optional, still fully local)

```bash
cartog rag setup                 # download models (~1.2 GB, one-time)
cartog rag index .               # embed symbols + docs into sqlite-vec
cartog rag search "authentication token validation"
```

Three-tier hybrid pipeline: **FTS5 keyword** + **vector KNN** + **cross-encoder re-ranking**. Indexes both code (functions, classes, methods) and Markdown documents. Models run locally via ONNX Runtime — no API keys, no network calls.

> **Prefer Ollama or a hosted endpoint?** Set `provider = "ollama"` or `provider = "openai"` (any OpenAI-compatible `/v1` endpoint) in `.cartog.toml`. See [Configuration](#configuration).

### Live index

```bash
cartog watch .                   # auto re-index on file changes
cartog watch . --rag             # also re-embed (deferred, non-blocking)
```

### MCP server for AI agents

```bash
cartog serve                     # 16 tools over stdio
cartog serve --watch --rag       # with live re-indexing + semantic search
```

Works with Claude Code, Cursor, Windsurf, Zed, OpenCode — any MCP client. Tool output is **compact by default** (locations + signatures + snippet previews, not full bodies) so it stays within an agent's context budget; set `CARTOG_MCP_COMPACT=0` to restore full bodies. On the CLI, `cartog --json --compact …` does the same — ~60% smaller payloads that still carry symbols, signatures, and scores.

### LSP precision, built in

Cartog auto-detects language servers on PATH (rust-analyzer, pyright, typescript-language-server, gopls, ruby-lsp, solargraph, jdtls, intelephense, dart, sourcekit-lsp, kotlin-language-server, vue-language-server, svelteserver, astro-ls) and uses them to boost edge resolution from ~25% to **up to 81%**. Enabled by default; results persist in SQLite — pay the cost once. Disable at runtime with `--no-lsp`, or omit at build time with `cargo install cartog --no-default-features`.

## Install

### Install script (macOS / Linux, no Rust required)

```bash
curl -fsSL https://www.cartog.dev/install.sh | sh
```

Detects your OS + architecture, downloads the matching binary from the latest
GitHub Release, verifies its SHA-256, and installs to `/usr/local/bin` (or
`~/.local/bin` if non-root). Override with `CARTOG_INSTALL_DIR`; pin a
version with `CARTOG_VERSION=` (e.g. the tag from [Releases](https://github.com/jrollin/cartog/releases)). Audit the script: [`site/public/install.sh`](site/public/install.sh).

### From crates.io (Rust toolchain required)

```bash
cargo install cartog                                  # default: LSP + S3 sync + Ollama + OpenAI providers
cargo install cartog --no-default-features            # minimal: drops LSP, S3, Ollama, OpenAI
cargo install cartog --no-default-features --features lsp  # LSP only
```

### Pre-built binaries (manual)

```bash
# macOS (Apple Silicon)
curl -L https://github.com/jrollin/cartog/releases/latest/download/cartog-aarch64-apple-darwin.tar.gz | tar xz
sudo mv cartog /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/jrollin/cartog/releases/latest/download/cartog-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv cartog /usr/local/bin/

# Linux (ARM64)
curl -L https://github.com/jrollin/cartog/releases/latest/download/cartog-aarch64-unknown-linux-gnu.tar.gz | tar xz
sudo mv cartog /usr/local/bin/

# Windows (x86_64) — download .zip from releases page
```

### Upgrade

Once cartog is on your `PATH`:

```bash
cartog self update           # upgrade in place to the latest stable
cartog self update --check   # report whether an update exists; exit 1 if outdated
cartog self version          # show installed version + last-check timestamp
cartog self rollback         # restore the previous binary
```

Cargo-installed binaries upgrade with `cargo install cartog --force`. See [docs/updates.md](docs/updates.md) for env vars, exit codes, and the state file location.

### Agent integration: which path?

Three setup paths for agents and editors. Pick the one that matches your stack — they are alternatives, not steps.

| Path | Use it when | What you get |
|---|---|---|
| `cartog ide` | You want MCP wired into one or more editors (Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, Claude Desktop, OpenCode, Windsurf, Zed, Antigravity, Kiro, Hermes Agent). | MCP entries written to the right files; interactive picker if you run it without flags. |
| Claude Code plugin | You are on Claude Code and want install + skill + MCP wired in one step. | Bundled: binary install, behavioural skill, MCP server, all preconfigured. |
| Agent skill | You use an agent that follows the skills protocol (Cursor, Copilot, others) and only need the behavioural rules, not MCP. | Skill files installed into the agent's skill directory; works alongside any install method. |

### Claude Code plugin

Run these two commands **one at a time** in Claude Code:

```bash
/plugin marketplace add jrollin/cartog
```

```bash
/plugin install cartog@cartog-plugins
```

**First session**: if the cartog binary is not already on your PATH, the plugin starts a background install and prints a one-line notice. The cartog MCP server cannot start in this first session because the binary lands after Claude Code has already tried to spawn it.

**Second session**: restart Claude Code. The MCP server starts, code-graph tools become available, and the SessionStart hook keeps the index fresh on every subsequent session.

**Repair or upgrade**: type `/cartog-install` at any time to install the binary synchronously (e.g. to retry a failed background install), or to upgrade an existing install to match the plugin's pinned version. The skill at [`skills/cartog-install/`](skills/cartog-install/SKILL.md) handles both cases.

**Offline / vetted install**: the manual fallback is the same one used by the curl one-liner at the top of this section: download [`site/public/install.sh`](site/public/install.sh) (served at `https://www.cartog.dev/install.sh`), inspect it, then run it.

### Agent Skill (Cursor, Copilot, others)

```bash
npx skills add jrollin/cartog
```

## Why Not...

**grep/ripgrep?** Great for string literals and config values. But grep can't trace call chains, can't do transitive impact analysis, and floods your context with raw text. Cartog returns structured, ranked, deduplicated results — one `refs` call replaces 6+ discovery steps.

**A language server?** LSPs give perfect precision but require per-language setup, take seconds to start, and only cover one language at a time. Cartog covers 15 languages with one binary and answers in microseconds. When you need LSP precision, cartog can use it as an optional layer.

**Python-based graph tools?** They solve a similar problem but require a Python runtime, pip dependencies, and virtual environments. Cartog is a single static binary — download and run. It also queries 10-100x faster thanks to compiled Rust + SQLite.

**An embedding-search tool (chunk + vector)?** Tools that chunk files and embed them find code by concept, but return **file-and-line windows** — you still open and read to learn *what* matched. Cartog returns the **named symbol** (function/class/method) with its kind, signature, and exact span, then sharpens ranking with a **cross-encoder re-ranker** and **centrality** that chunk-only tools lack. It also embeds **in-process** (local ONNX, zero external server — no Ollama daemon to keep running) and ships LSP-precise call/import edges, so the same query that finds code can also trace it. Add `--compact` and the JSON stays symbol-level while dropping ~60% of the bytes.

## MCP Server Setup

Fastest path: let cartog write the right config for your editor.

```bash
cartog ide                                  # all installed clients, all scopes
cartog ide --client cursor                  # one client
cartog ide --client claude-desktop --dry-run  # preview without writing
```

Idempotent. Existing servers in each file are preserved.

Prefer the brew/npm shape? `cartog install` takes editors as positional args
and is always non-interactive — safer than `cartog ide` for scripts and agents:

```bash
cartog install cursor                 # one editor
cartog install cursor vscode codex    # several at once
cartog install                        # all detected editors
cartog install cursor --dry-run       # preview
```

Prefer to wire it yourself? Pick your client below.

Claude Code — project-scoped .mcp.json or user settings

One-shot:

```bash
cartog ide --client claude-code             # writes .mcp.json + user settings
claude mcp add cartog -- cartog serve --watch       # user scope
claude mcp add --scope project cartog -- cartog serve --watch
```

Manual (`/.mcp.json`):

```json
{
  "mcpServers": {
    "cartog": { "command": "cartog", "args": ["serve", "--watch"] }
  }
}
```

> Only Claude Code gets `--watch` by default — the others ship plain `["serve"]`.
> Agent-driven flows churn files faster than human-driven editor flows, so the
> in-process file watcher pays off. Drop `--watch` with `cartog ide --no-watch`
> if you don't want it.

Cursor — project .cursor/mcp.json or user settings

One-shot:

```bash
cartog ide --client cursor
```

Manual:

```json
{
  "mcpServers": {
    "cartog": { "command": "cartog", "args": ["serve"] }
  }
}
```

Codex CLI — user-only TOML at ~/.codex/config.toml

One-shot:

```bash
cartog ide --client codex
```

Manual:

```toml
[mcp_servers.cartog]
command = "cartog"
args = ["serve"]
```

Codex is user-global only. If you use cartog on multiple projects, `cartog ide`
auto-names each section `cartog--` so they coexist.

Windsurf — ~/.codeium/windsurf/mcp_config.json

```bash
cartog ide --client windsurf
```

```json
{
  "mcpServers": {
    "cartog": { "command": "cartog", "args": ["serve"] }
  }
}
```

VS Code (GitHub Copilot) — project .vscode/mcp.json

```bash
cartog ide --client vscode
```

Note: VS Code's top-level key is `servers` (no `mcp` prefix):

```json
{
  "servers": {
    "cartog": { "type": "stdio", "command": "cartog", "args": ["serve"] }
  }
}
```

Zed — ~/.config/zed/settings.json

```bash
cartog ide --client zed
```

```json
{
  "context_servers": {
    "cartog": { "command": "cartog", "args": ["serve"] }
  }
}
```

OpenCode — ~/.config/opencode/opencode.json

```bash
cartog ide --client opencode
```

```json
{
  "mcp": {
    "cartog": {
      "type": "local",
      "command": ["cartog", "serve"],
      "enabled": true
    }
  }
}
```

Gemini CLI — ~/.gemini/settings.json

```bash
cartog ide --client gemini
```

```json
{
  "mcpServers": {
    "cartog": { "command": "cartog", "args": ["serve"] }
  }
}
```

Claude Desktop — claude_desktop_config.json

```bash
cartog ide --client claude-desktop
```

Manual (macOS: `~/Library/Application Support/Claude/`; Windows: `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "cartog": { "command": "cartog", "args": ["serve"] }
  }
}
```

Restart Claude Desktop after editing.

See [docs/mcp-setup.md](docs/mcp-setup.md) for the canonical long-form reference,
including the path-naming scheme for Codex's multi-project setup, and
[docs/usage.md](docs/usage.md#mcp-server) for all `cartog ide` flags.

## Commands

```bash
# Index
cartog index .                              # build the graph (with LSP if available)
cartog index . --no-lsp                     # heuristic-only (~1-4s)
cartog index . --force                      # re-index all files

# Search
cartog search validate                      # partial name match (sub-ms)
cartog search validate --kind function      # filter by kind
cartog rag search "token validation"        # semantic search (natural language)

# Navigate
cartog outline src/auth/tokens.py           # file structure without reading it
cartog refs validate_token                  # who references this?
cartog refs validate_token --kind calls     # only call sites
cartog callees authenticate                 # what does this call?
cartog impact SessionManager --depth 3      # what breaks if I change this?
cartog hierarchy BaseService                # inheritance tree
cartog hierarchy BaseService --mermaid      # paste-into-PR diagram
cartog deps src/routes/auth.py              # file-level imports
cartog deps src/routes/auth.py --mermaid    # graph LR with file as root

# Inspect
cartog stats                                # index summary
cartog savings                              # tokens saved vs grep+read baseline
cartog map --tokens 4000                    # codebase overview by centrality
cartog map --mermaid                        # codebase map as graph TD
cartog changes --commits 5                  # recently changed symbols
cartog doctor                               # environment health check

# Watch & Serve
cartog watch .

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jrollin](https://github.com/jrollin)
- **Source:** [jrollin/cartog](https://github.com/jrollin/cartog)
- **License:** MIT
- **Homepage:** https://www.cartog.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jrollin-cartog
- Seller: https://agentstack.voostack.com/s/jrollin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.