convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
adder-factory

Cartograph

adder-factory/cartograph

Inteligência semântica de código para agentes IA — 45% menos chamadas de ferramentas

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que constrói um grafo de conhecimento local do seu codebase, permitindo que agentes IA façam perguntas estruturadas sobre símbolos, chamadores, impacto de mudanças e saúde do código sem rescanejar arquivos repetidamente. Funciona 100% localmente com SQLite ou PostgreSQL.

Instalação

$npx convez-ai adder-factory/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
4
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 1 dia
Versão
v4.0.6
Issues abertas
1
Contribuidores
1

Casos de uso

  • Análise de impacto de mudanças em grandes codebases
  • Exploração semântica de arquitetura e dependências
  • Identificação de hotspots e dívida técnica
  • Contexto local para agentes de codificação (Claude Code, Cursor, GitHub Copilot)

Veredito

Ferramenta sólida e bem documentada para potencializar agentes IA com compreensão profunda de codebases. Ideal para times que usam assistentes de código e precisam reduzir latência nas buscas contextuais. Implementação técnica madura com suporte a múltiplos backends de armazenamento.

README

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

Cartograph

Code intelligence for AI coding agents

Index a repo once. Ask structured questions instead of rereading files.

License: MIT Runtime: Bun MCP Storage

Cartograph builds a local knowledge graph of your codebase and exposes it through CLI commands, MCP tools, and a TypeScript API. Agents can ask for symbols, callers, impact radius, affected tests, hotspots, code-health findings, SQL/env references, and semantic matches without repeatedly scanning the same files.

SQLite is the zero-config default and is capability-checked through Bun's embedded SQLite runtime. PostgreSQL 18+ is available when you want shared/external storage, managed backups, operational database controls, or native pgvector search.

Cartograph is a fork of codegraph by Colby Mchenry, used under the MIT License. See ACKNOWLEDGEMENTS.md.

Quickstart

curl -fsSL https://raw.githubusercontent.com/adder-factory/cartograph/main/install.sh | sh

cd /path/to/your/project
cartograph admin init -i
cartograph status --verbose

Then connect your agent:

cartograph install

The installer detects and configures Claude Code, Cursor, Codex CLI, GitHub Copilot CLI, CodeBuddy, CodeWhale, Zed, opencode, Hermes, Gemini CLI, Antigravity, Kiro, Factory Droid, Rovo Dev, Qoder CLI, IBM Bob, Kimi Code, Pi Agent, and Reasonix. It writes MCP config plus agent instructions where the target supports them.

For Claude Code, --location=local is private to you and the current project: the MCP entry is written under this project in ~/.claude.json, permissions go to .claude/settings.local.json, and Cartograph instructions go to CLAUDE.local.md with both local files added to .gitignore.

If your MCP client is launched from a GUI shell that cannot find cartograph, write an absolute executable path into the config:

cartograph install --command "$(command -v cartograph)"

To keep the graph fresh after pulls, branch switches, and rebases, install the managed git hooks:

cartograph install-hooks --command "$(command -v cartograph)"

Or give this task to your coding agent:

Install Cartograph for this repository. Use non-interactive commands.
If `cartograph --version` fails, run:
curl -fsSL https://raw.githubusercontent.com/adder-factory/cartograph/main/install.sh | sh

Then, from this repository, run:
cartograph install --yes --target=auto --location=local
cartograph status --verbose

If the agent or MCP host cannot find `cartograph` on PATH, retry install with:
cartograph install --yes --target=auto --location=local --command "$(command -v cartograph)"

Report changed files, status output, and whether I need to restart the agent.
Do not configure LLMs, download models, migrate storage, or switch to
PostgreSQL unless I ask.

See Agent-Assisted Install for the full prompt, PowerShell command, and source-install fallback.

Source install for development:

git clone https://github.com/adder-factory/cartograph.git
cd cartograph
bun install
bun link

Why Cartograph

ProblemCartograph gives agents
"Where is this implemented?"Name, regex, env-var, SQL-ref, semantic, and intent search over the indexed graph
"What happens if I edit this?"Callers, callees, impact radius, related symbols, co-change history, and affected tests
"Is this risky?"Biomarkers, Code Health, hotspots, churn, coverage joins, dependency audit, and trust checks
"What should I read first?"A route plan from cartograph context --format plan, then exact source only when needed
"What changed in my worktree?"cartograph compare-to-ref structural delta and new finding summary before handoff

Core graph features do not need an LLM. Optional OpenAI-compatible LLM tiers power summaries, embeddings, semantic search, ask, and rerank.

Use It From

SurfaceStart here
Human CLIcartograph status --verbose, cartograph find, cartograph graph, cartograph review
MCP agentcartograph serve --mcp or cartograph install
Local viewercartograph viewer .
Library APICartograph.init('/path/to/project')

Cartograph's MCP server exposes all 35 registered tools. The default core profile is smaller; the full 35-tool server is available with cartograph serve --mcp --profile full.

Storage

SQLite is the default and works immediately:

cartograph admin init -i

PostgreSQL 18+ is opt-in:

docker run --rm -d --name cartograph-postgres \
  -e POSTGRES_USER=cartograph \
  -e POSTGRES_PASSWORD=cartograph \
  -e POSTGRES_DB=cartograph \
  -p 5432:5432 \
  pgvector/pgvector:pg18

cartograph admin init -i \
  --database-provider postgres \
  --database-url postgres://cartograph:cartograph@localhost:5432/cartograph \
  --database-schema cartograph \
  --database-pgvector auto

cartograph doctor .

Move an existing SQLite graph to PostgreSQL:

cartograph admin storage-migrate . \
  --database-url postgres://cartograph:cartograph@localhost:5432/cartograph \
  --database-schema cartograph \
  --database-pgvector auto

Move a PostgreSQL-backed project back to local SQLite:

cartograph admin storage-migrate . \
  --database-provider sqlite

See Storage Backends for the PostgreSQL 18+ minimum, pgvector modes, production grants, hosted TLS notes, and migration details.

Local storage benchmark, run 2026-06-07 with Bun 1.3.14 on darwin arm64:

BackendInit medianWrite medianRead medianTotal medianDB size
SQLite7 ms70 ms35 ms112 ms2.12 MB
PostgreSQL102 ms241 ms470 ms795 ms7.46 MB

Workload: 200 files, 1,600 nodes, 3,200 candidate edges, 40 read iterations, three fresh runs per backend. SQLite remains the fastest local single-writer default; PostgreSQL is for shared/external storage, database operations, hosted backups, and native pgvector search.

Viewer

cartograph viewer .
# open http://127.0.0.1:8765/

The viewer is local-only and uses the same graph index as the CLI and MCP server. Use it to inspect symbol neighborhoods, source, callers, callees, health, coverage, and graph layout directly.

Common Workflows

# First-time setup with LLM backend checks
cartograph setup .
cartograph doctor --fix .

# Find and inspect code
cartograph find "AuthService" --by name --mode fuzzy
cartograph graph AuthService --direction impact
cartograph node AuthService --include-callers --include-tests

# Review current work
cartograph review context --diff "$(git diff)"
cartograph affected --include-commands
cartograph compare-to-ref --findings-delta

# MCP server controls
cartograph serve --mcp --profile core
cartograph serve --mcp --profile full --low-tokens-default
cartograph mcp-budget

For agents, a good edit-session chain is:

cartograph_context({task: "<task>", format: "plan"})
→ follow the suggested next action
→ cartograph_affected({includeCommands: true})
→ cartograph_compare_to_ref({findingsDelta: true})

Cartograph starts from Git-visible files, then applies local indexing policy. A root .ignore file can re-include useful gitignored source with negated patterns such as !customer/ without changing repository semantics; explicit Cartograph exclude entries and .cartographignore marker directories still win.

Docs

NeedGo to
Pasteable task for a coding agent to install Cartographdocs/AGENT-INSTALL.md
PostgreSQL, pgvector, migration, storage benchmarkdocs/STORAGE-BACKENDS.md
CLI command referencedocs/CLI-REFERENCE.md
Graph export artifact formatsdocs/GRAPH-EXPORT-FORMATS.md
MCP setup, profiles, load budget, client snippetsdocs/MCP-USAGE.md
Configuration and advanced optionsdocs/CONFIGURATION.md
Language/framework matrixdocs/SUPPORT-MATRIX.md
Troubleshootingdocs/TROUBLESHOOTING.md
Add a languagedocs/ADDING-A-LANGUAGE.md

Command Map

CommandUse for
cartograph adminProject lifecycle, indexing, setup, doctor, storage migration, and LLM admin actions
cartograph affectedFind test files affected by changed source files
cartograph askAsk natural-language questions about the codebase with an LLM
cartograph at-rangeResolve file:line ranges or diff hunks to indexed symbols
cartograph backendManage configured local llama-server processes
cartograph biomarkersStatic-analysis findings and Code Health
cartograph blameSymbol-level git blame
cartograph changed-sinceFile drift since index time or timestamp
cartograph compare-to-refEnd-of-task structural and finding delta
cartograph completionsShell completion scripts for Bash, Zsh, Fish, and PowerShell
cartograph contextTask-specific context and route plans
cartograph coveragePer-symbol coverage joined to graph data
cartograph dead-codePotentially-dead symbol candidates
cartograph depspackage.json dependency audit
cartograph digest"Land in a new repo" overview
cartograph discoverFind other .cartograph indexes
cartograph entry-pointsRoutes, CLI commands, MCP tools, and public exports
cartograph exploreDeep topic exploration
cartograph exportGraph artifact export: JSON, DOT, Mermaid, Cytoscape
cartograph file-depsLocal file dependencies and dependents for one indexed file
cartograph file-symbolsSymbols in one indexed file
cartograph filesIndexed file tree and summaries
cartograph findSymbol, content, env-var, and SQL-ref search
cartograph graphCall/dependency graph traversal
cartograph historySymbol-level co-change
cartograph hotspotsChurn x centrality triage
cartograph importsImport statement graph data
cartograph installConfigure MCP server entries for supported agents
cartograph install-hooksInstall managed git hooks for quiet background sync
cartograph llmLocal/cloud LLM provider setup and smoke checks
cartograph local-chatDelegate bulk prose to a local LLM
cartograph mcp-budgetMeasure MCP startup payload size
cartograph moduleDirectory/module summary
cartograph nodeSymbol details, optionally with source and related data
cartograph notePersistent annotations/bookmarks
cartograph playbookTool-selection playbook
cartograph propose-renameRename plan with call sites and mentions
cartograph reviewDiff, neighbor, risk, audit, and trust review helpers
cartograph roleSymbol role classification
cartograph serveStart the MCP server
cartograph sessionSession state, macros, and audits
cartograph setupOne-shot bootstrap: init, models, doctor
cartograph similarEmbedding-cosine peers of a symbol
cartograph sqlRead-only SQL escape hatch
cartograph statusIndex status and feature readiness
cartograph summariesPull/save agent-written summaries
cartograph sync-if-dirtyHook compatibility sync that no-ops on clean git trees
cartograph tests-forTests covering a symbol or files
cartograph trace-to-culpritsStack trace to likely fix sites
cartograph viewerLocal graph viewer

Supported Languages & File Formats

Cartograph supports 73 language modes. Framework-aware and derived signals are listed separately so the core language matrix stays readable.

LanguageExtensions / scope
ABAP.abap
TypeScript / TSX.ts, .mts, .cts, .tsx
JavaScript / JSX / ArkTS.js, .mjs, .cjs, .xsjs, .xsjslib, .jsx, .ets
Python.py, .pyw
Go.go
Rust.rs
Java / Kotlin / Scala / Groovy.java, .kt, .kts, .scala, .sc, .groovy, .gradle
C / C++ / C# / CUDA.c, .h, .cpp, .cc, .cxx, .hpp, .hxx, .cs, .cu, .cuh
VB.NET / Visual Basic 6.vb, .bas, .frm, .ctl, .dob, .dsr, .pag, .vbp, VB6 .cls by content
Clojure / ClojureScript.clj, .cljs, .cljc, .edn, .bb
Common Lisp.lisp, .lsp, .l, .cl, .asd, .ros
Objective-C / Swift.m, .mm, .swift
PHP / Ruby.php, .module, .install, .theme, .inc, .rb, .rake
Salesforce.cls, .trigger, plus Aura/Visualforce markup extensions in Salesforce source paths
BG3 modding data.lsx, .lsf, .lsfx, .lsefx, .tbl, .stats, .mei, .lsj, .ann, .anc, .khn, .div, BG3 Stats/Generated .txt, BG3 Story goal .txt, BG3 Localization XML
Dart / ReScript / R / Lua / Luau / Elixir / Lean.dart, .res, .resi, .r, .R, .lua, .luau, .ex, .exs, .lean
F# / Haskell / Julia / OCaml.fs, .fsx, .hs, .jl, .ml, .mli
HTML / CSS / ERB / EJS.html, .htm, .css, .erb, .ejs, .eta, .etlua
Astro / Svelte / Vue / Liquid.astro, .svelte, .vue, .liquid
Pascal / Delphi.pas, .dpr, .dpk, .lpr, .dfm, .fmx
Bash / Zsh / Fish / PowerShell.sh, .bash, .zsh, .zshrc, .fish, .ps1, .psm1, .psd1
GraphQL / GLSL / HLSL / Nix / Solidity / SQL / HCL / Prisma / Properties / XML / YAML.graphql, .gql, .glsl, .vert, .frag, .comp, .geom, .tesc, .tese, .hlsl, .hlsli, .fx, .fxh, .nix, .sol, .sql, .tf, .tfvars, .hcl, .tofu, .prisma, .properties, .xml, .yaml, .yml
JSON / Jupyter / JSDoc / Regex / Verilog.json, .ipynb, .jsdoc, .regex, .regexp, .v, .vh, .sv, .svh

Framework-Aware Signals

EcosystemSignals
JavaScript / TypeScriptAngular routes, Express routes, Hono routes and mounted sub-routers, Bun.serve routes, React components, Vue/Nuxt aliases/routes, SvelteKit routes, Commander CLI commands
PythonDjango, Flask, FastAPI route/controller patterns, and NeuG graph resource landmarks
PHPLaravel facades/routes, Drupal routes/services/hooks/plugins/service tags, Symfony routes/controllers, and CodeIgniter 3 routes/controller/model/library conventions
RubyRails routes and controller conventions
JVMSpring route/config references including @Value and @ConditionalOnProperty, Play routes, and MyBatis Java/XML bindings including SqlSessionTemplate statement ids
SalesforceApex classes/methods/triggers, LWC component bundles and Apex imports, Aura controllers/actions, Visualforce routes/actions
Go / Rust / C# / Dart / SwiftCommon route and entry-point patterns, Flutter routes, Cargo workspace crate aliases
Apple / React NativeSwiftUI, UIKit, Vapor, Swift-Objective-C bridging, React Native legacy/TurboModules, Expo Modules, Fabric/Paper view components

Static resolution also handles language-specific ownership and call shapes, including Python package-member imports, Go receiver methods split across files, C# primary constructors, PHP include/require imports, and return-type-backed chained calls.

Embedded DSLs & Derived Signals

SignalWhat gets added
Zod / PydanticSchema structs, fields, and enum members
GraphQL SDLTypes, fields, enums, interfaces, and references
Prisma / SQLModels, tables, views, functions, triggers, schemas, and table references
Config / env refsEnv-var, config-key, feature-flag, and build-context reference edges
Dynamic dispatchBounded TS/JS dispatch-table call edges with inferred confidence
Tests / coverage / historyTest edges, lcov joins, churn, issue history, co-change, and hotspot signals

See docs/SUPPORT-MATRIX.md for the full matrix.

What Cartograph Is Not

ExpectationReality
Hosted SaaSCartograph is local-first; the graph database is local SQLite by default or your configured PostgreSQL instance
Test replacementIt finds affected tests and risks; your test suite remains the source of truth
LLM-only reviewerReview tools are deterministic graph queries first; LLM features are optional
Cloud dependencyCore indexing and graph tools work offline after dependencies are installed

License

MIT

Report Bug · Request Feature

Ver o original no GitHub

Bom para

Relacionados