convez.ai
MCP Server
VigneshBhaskarraj

Cartograph

VigneshBhaskarraj/Cartograph

Ver no GitHub
InicialPluginScore · de 0 a 100

A queryable knowledge graph of your codebase — for AI agents, fully offline. Traces code↔SQL blast radius over MCP.

Instalação

$npx convez-ai VigneshBhaskarraj/Cartograph

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
1
Contribuidores
4

README

A tradução para o português deste README ainda está na fila.

Cartograph

A queryable knowledge graph of your codebase — for AI agents, fully offline. Cartograph turns code and its SQL schema into one graph that a coding agent consults instead of grepping. No code ever leaves your machine.

Built for environments where source can't go to the cloud (regulated / on-prem), and for the one question neither code tools nor data-lineage tools answer alone:

"What application code breaks if I drop users.email?"

uv run cartograph impact users.email     # → the columns, the code, and its transitive callers

Status: alpha. The retrieval quality and the code↔data bridge are measured (numbers below); the API and CLI may still change. Design rationale: SPEC.md.

How it works

  • tree-sitter extracts structure locally — Python, JavaScript/TypeScript (incl. CommonJS), Java (incl. JPA annotations), Go — and SQL schemas are parsed deterministically, so app code and database schema land in the same graph.
  • Kuzu stores it as a property graph in a single embedded file (no server, no DBA).
  • Hybrid retrieval fuses vector similarity, graph traversal (personalized PageRank), and BM25 keyword search, with an optional local-LLM reranker.
  • Zero network calls by default — enforced, not promised: embeddings run on a local Ollama model, and a non-loopback OLLAMA_HOST is refused unless you explicitly allow it.
  • The graph is served over MCP, so any coding agent (Claude Code, etc.) can query structure-aware context on demand.

Install

macOS / Linux, Python 3.12+. Everything runs offline. (Windows: use WSL — not yet tested natively.)

uv tool install "cartograph[mcp,sql,ts,java,go] @ git+https://github.com/VigneshBhaskarraj/Cartograph"
cartograph --help

Or for development:

git clone https://github.com/VigneshBhaskarraj/Cartograph && cd Cartograph
uv sync --all-extras && uv run pytest    # the whole suite runs offline and deterministically

Quickstart

cartograph index path/to/repo --db graph.kuzu
cartograph query "where is retry logic" --mode hybrid

The default embedder is an offline feature-hash model; set CARTOGRAPH_EMBEDDER=ollama for real local semantic embeddings (still zero egress — only 127.0.0.1).

Use it from a coding agent (MCP)

cartograph serve --db /abs/path/to/graph.kuzu     # stdio MCP server

Or add to your project's .mcp.json (use absolute paths):

{
  "mcpServers": {
    "cartograph": {
      "command": "cartograph",
      "args": ["serve", "--db", "/abs/path/to/graph.kuzu"]
    }
  }
}

Tools: query · semantic_search · get_node · neighbors · calls · callers · shortest_path · impact. Full reference: docs/mcp.md.

The differentiator: code↔data blast radius

Code tools stop at code; data-lineage tools stop at SQL. Cartograph holds both, so impact traces across the boundary — function-level, offline:

cartograph impact users.email    # a column/table → every code path that can reach it
cartograph impact store_run      # a function → every table/column it can touch

The radius follows the call graph, the ORM/SQL bridge (including self.<column> reads), and FK/JOIN ripple — dropping a table also surfaces code touching tables that reference it. Every result carries a machine-readable completeness block (it's advisory, never a proof): each remaining gap — heuristic calls, cross-instance attribute access, undeclared foreign keys — is reported as a structured code an agent can branch on. Honest by construction.

See it

Export an interactive 3D map of any graph to one self-contained, offline HTML file — rotate, search, click a symbol for its neighborhood, trace shortest paths, filter by edge type and EXTRACTED/INFERRED confidence:

cartograph viz --db graph.kuzu --out graph.html

Does it actually work? (measured, not asserted)

Real nomic-embed-text embeddings, 101 questions / 6 corpora spanning Python, Java+JPA, and raw-SQL apps; two corpora are held out from all tuning. Mean across corpora, against two external baselines:

systemrecall@5recall@10mrr
grep over raw source0.580.720.40
naive-rag (structure-blind chunks)0.540.760.28
vector (single signal)0.850.910.71
Cartograph hybrid0.870.930.73

The fusion generalizes — hybrid wins or ties single-signal vector on recall@10 on all six corpora, including both held-out ones (click 0.944; spring-petclinic 0.833). Agent-task evidence: with grep-only vs Cartograph-only tools, an agent reaches the same answers with ~42% fewer tool calls.

Reproduce (offline):

bash eval/get_corpus.sh 0.27.2 && bash eval/get_flask.sh
uv run python eval/scorecard.py --baselines      # add --embedder ollama for the real numbers

Full tables, methodology, and the agent benchmark: eval/README.md and eval/agent_bench/RESULTS.md.

Language support

tierlanguageswhat it means
EvaluatedPython (+SQL bridge), Java (+JPA bridge)retrieval quality measured on real corpora
StructuralTypeScript, JavaScript (ES + CommonJS), Goextraction verified by tests + real-repo smoke (Express, go-chi); no retrieval numbers yet

Further languages are demand-driven — open an issue.

License

Apache License 2.0 — permissive, with an explicit patent grant. See NOTICE.

Ver o original no GitHub

Bom para

Relacionados