repo-graph

Mapa estrutural em grafo de qualquer base de código. A LLM consulta o grafo em vez de pesquisar em tudo. 13 linguagens, fluxos detectados automaticamente, vinculação entre stacks. Zero dependências.

GitHub

Documentação

repo-graph

Memória estrutural de grafo para assistentes de codificação com IA. Mapeie seu código. Navegue pela estrutura. Leia apenas o que importa.

repo-graph dá aos LLMs um mapa do seu código — entidades, relacionamentos e fluxos — para que eles possam navegar até os arquivos certos sem ler tudo primeiro.

Em vez de inundar a janela de contexto de um LLM com todo o seu código (ou esperar que ele adivinhe certo), repo-graph constrói um grafo leve do que existe, como as coisas se conectam e onde estão os pontos de entrada. O LLM consulta o grafo, encontra o conjunto mínimo de arquivos de que precisa e lê apenas esses.

Ele compensa mais onde isso é mais difícil de fazer manualmente: repositórios grandes, monorepos que abrangem várias linguagens e sistemas multi-serviço onde o caminho de um recurso cruza arquivos, stacks e limites de serviço. Em um projeto pequeno de linguagem única, um modelo pode simplesmente ler os arquivos — veja Onde se encaixa melhor para o ponto ideal honesto.

Instale com um clique:

Ou um único comando no seu terminal conecta todos os agentes que você tem: uvx mcp-repo-graph install (veja Instalação).

Atualizando para 0.5.2

A maioria das pessoas não precisa fazer nada. uvx e pip install mcp-repo-graph puxam o novo mecanismo (glia 0.5.1, fixado exatamente). O grafo em cache em .glia/graph/ está em um novo formato, então o primeiro início em cada repositório o reconstrói uma vez. Depois disso, volta ao normal.

Você só precisa agir se também executar os hooks de CLI do próprio glia (glia install-hooks) no mesmo repositório. Reinstale a CLI a partir da tag v0.5.1 também. Se a CLI e o servidor estiverem em versões diferentes do glia, eles reconstroem o cache um do outro a cada commit.

O mesmo vale para uma equipe que faz commit do cache com o hook de pre-commit do repo-graph: o próximo commit o re-adiciona uma vez no novo formato, e qualquer pessoa cujo servidor ainda execute o mecanismo glia 0.5.0 o reconstrói a cada carregamento até atualizar (uv tool upgrade mcp-repo-graph se você o instalou como uma ferramenta uv).

O que é melhor: um grafo mais rico (rotas Go montadas carregam seu prefixo, endpoints de frontend pareiam através de sua URL base, muito mais chamadas são resolvidas), read mostra o host que um cliente WebSocket / gRPC / GraphQL disca, e o servidor não cresce mais em memória ao longo de sessões longas.

⚠️ Atualizando para 0.5.0

O pacote do mecanismo foi renomeado de repo-graph-py para glia-py. Se você instala com uvx ou pip install mcp-repo-graph, você não precisa fazer nada. O novo mecanismo é puxado para você.

Você só precisa agir se importar o mecanismo diretamente:
- import repo_graph_py as rg
+ import glia_py as rg
Outras três coisas mudaram nesse mesmo lançamento:

As respostas são objetos Python, não strings JSON. find, resolve, blast_radius, cross_stack_trace e governing_docs retornam um dict {"results": [...], "absence": {...}}. Se você estava fazendo json.loads(...) em um resultado, remova isso.

find_node e find_nodes_by_qname desapareceram. Um único find(query, top_k) substitui ambos.

O cache do grafo mudou de .ai/repo-graph/ para .glia/graph/. Ele é reconstruído automaticamente, então você pode excluir o diretório antigo. O novo ignora a si mesmo e nunca aparece em git status.

As seis ferramentas MCP não mudaram (orient, find, impact, trace, read, refresh), então nada na sua configuração de agente precisa ser tocado. Detalhes completos nas notas de lançamento 0.5.0.

Demonstração

https://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a

https://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883

Mesmo bug, mesmo modelo, mesmo prompt — a única diferença é se o repo-graph está instalado.

A tarefa: corrigir um operador de comparação invertido em um monorepo Go + Angular.

(Gravado em um mecanismo anterior, que mapeou esse repositório para 566 nós / 620 arestas. O mecanismo glia 0.5.1 extrai muito mais do mesmo código, 3.466 nós e 6.869 arestas (medido em 2026-10-02), então o grafo que o modelo recebe hoje é mais rico do que o do vídeo. Os números de tokens e tempo são da execução gravada e são deixados como medidos.)

	Sem repo-graph	Com repo-graph
Tokens usados	75.308	29.838
Tempo para corrigir	4m 36s	~30s
Arquivos explorados	~15 (grep, leitura, grep, leitura...)	2 (consulta de rastreamento + arquivo do handler)
Resultado	Bug encontrado e corrigido	Bug encontrado e corrigido

2,5x menos tokens. ~9x mais rápido. Mesma correção correta.

Como o teste foi executado

Ambas as execuções usaram condições idênticas para manter a comparação justa:

Mesmo modelo: Claude Opus, 100% (sem roteamento Haiku)
Mesmo prompt: "Grupos criados recentemente estão aparecendo como fechados, e grupos antigos aparecem como abertos. Isso está invertido — novos grupos deveriam estar abertos para membros entrarem. Encontre e corrija o bug."
Contexto novo: cada execução começou de /clear sem conversa anterior
Sem outras ferramentas: CLAUDE.md, plugins, hooks e todos os outros servidores MCP foram removidos em ambas as execuções — a única variável era se o repo-graph estava instalado
Sem dicas: o prompt descreve o sintoma, não a localização — Claude tem que encontrar group_controller.go:57 por conta própria

Sem repo-graph, Claude faz grep por palavras-chave, lê arquivos, faz grep novamente, lê mais arquivos e eventualmente reduz o escopo até o bug. Com repo-graph, Claude chama trace("groups"), recebe de volta a função handler exata e o arquivo, lê e corrige.

Navegue pelos exemplos pré-gerados para FastAPI, Gin, Hono e NestJS — saída de grafo real que você pode inspecionar sem instalar nada.

O problema

LLMs trabalhando em código desperdiçam a maior parte do seu contexto em orientação:

Lendo arquivos que acabam sendo irrelevantes
Perdendo conexões entre componentes em diferentes linguagens
Não sabendo onde um recurso começa ou o que ele toca
Carregando 50 arquivos quando 5 bastariam

Isso é caro, lento e piora à medida que os codebases crescem.

Como o repo-graph resolve isso

repo-graph escaneia seu codebase uma vez e constrói um grafo de:

Entidades: módulos, pacotes, classes, funções, rotas, serviços, componentes
Relacionamentos: imports, chamadas, handlers, definições, contém, HTTP entre stacks
Fluxos: caminhos de ponta a ponta do ponto de entrada até a camada de dados

Então ele expõe 6 ferramentas MCP que permitem ao LLM:

Orientar-se — "Quais linguagens estão neste repositório? Quais são os principais recursos? Onde o grafo é cego?"
Navegar — "Trace o fluxo de login da rota até o banco de dados" / "Qual é o caminho mais curto entre UserService e a API de pagamentos?"
Escopar — "Quais nós importam para este bug?" / "Dê-me apenas os arquivos que preciso para esta correção"
Avaliar — "Qual é o raio de impacto de mudar esta função?" / "O que aqui é código morto?"

O LLM recebe contexto estrutural em algumas centenas de tokens em vez de ler milhares de linhas.

Onde se encaixa melhor

repo-graph compensa quando um codebase é maior ou mais emaranhado do que o modelo consegue segurar na cabeça de uma vez. O retorno escala com três coisas:

Tamanho — arquivos suficientes para que ler os relevantes estoure o orçamento de contexto.
Complexidade — regras, indireção e camadas, então "apenas leia" deixa de funcionar.
Alcance entre limites — a resposta atravessa arquivos, linguagens ou serviços que uma busca de texto não consegue conectar.

Ajustes fortes:

Monorepos — um frontend chamando um backend através de um limite de linguagem. repo-graph liga a chamada HTTP à rota que ela atinge e ao handler por trás dela, o que uma busca de texto não consegue fazer porque os dois lados não compartilham nenhuma string. Aponte --repo para a raiz do monorepo e um único grafo abrange todos os projetos. (A demonstração acima é exatamente isso: Go + Angular em um repositório.)

Outras ferramentas ligam fetch/axios a rotas Express, Fastify e Koa. O que difere aqui é o alcance: o mesmo pareamento funciona em Go, Python, Java, C#, Rust, PHP, Ruby e o resto, em um único grafo, e cobre gRPC, GraphQL, WebSockets, filas e eventos no mesmo nível. Essa amplitude não é comparada com benchmarks contra eles, então trate-a como uma diferença de design, não uma vitória medida.
Sistemas multi-serviço / polyrepo — coloque os serviços sob um diretório e aponte --repo para ele; o grafo traça um recurso através dos limites de serviço em uma única chamada.
Codebases grandes de linguagem única — milhares de arquivos onde a orientação em si é o custo.
Código desconhecido ou legado — onde você ainda não sabe o que toca o quê.

Onde ele não compensa: um repositório pequeno, de linguagem única, com uma tarefa clara. O modelo pode simplesmente ler os arquivos — grep vence e o grafo é sobrecarga. Não use para economizar tokens também: a camada MCP é um custo fixo por turno, então em tarefas fáceis pode custar mais. A economia de tokens só aparece quando evita uma espiral de grep-leitura-grep (como na demonstração acima). O que ele compra de forma confiável são respostas corretas, completas e entre limites em poucas chamadas em código grande demais ou interconectado demais para caber no contexto — seu ou do modelo. (Não quer a camada MCP de jeito nenhum? Pule-a e chame o mecanismo diretamente.)

Use sem MCP

O servidor MCP é o caminho de configuração zero, mas o grafo não está preso a ele. O mecanismo é distribuído como uma wheel Python simples — pip install glia-py — então você pode construir o grafo e chamar as mesmas primitivas de resposta diretamente, de um script ou de suas próprias ferramentas, com nenhum dos custos MCP por turno:

import glia_py as rg

g = rg.load_from_gmap(rg.default_gmap_dir("."), ".")   # builds it if there's no cache yet

g.find("checkout")                              # ranked, located nodes for a name
g.blast_radius(["checkout", "Cart.add"], "both")  # many seeds, one walk, one ranking
g.cross_stack_trace("notifications")            # feature path across the stack, mechanism-labelled
g.resolve(open("error.log").read())             # stacktrace / test / diff → the nodes that matter
g.coverage()                                    # where extraction is partial (grep those)

Cada uma dessas retorna Python puro — um dict {"results": [...], "absence": {...}} para as buscas, uma lista para coverage(). Quando results está vazio, absence diz porquê, então um script pode ramificar com base nisso em vez de adivinhar.

Mesmo grafo, mesmas respostas — apenas sem os esquemas de ferramentas no seu contexto. É o mesmo mecanismo Rust (glia) que o servidor MCP envolve; glia-py é a wheel publicada dele. Bom para verificações de CI, análise em lote ou para conectar o grafo ao seu próprio agente.

Linguagens suportadas

Linguagem	Detecção	O que extrai
Go	`go.mod`	Pacotes, funções, rotas HTTP (gin/echo/chi/stdlib), imports
Rust	`Cargo.toml`	Crates, módulos, structs, traits, funções, rotas (Actix/Rocket/Axum)
TypeScript	`tsconfig.json` / `package.json`	Módulos, classes, funções, relações de import
React	`react` em `package.json`	Componentes, hooks, context providers, rotas React Router, chamadas fetch/axios, fluxos
Angular	`@angular/core` em `package.json`	Componentes, serviços, guards, injeção de DI, chamadas HTTP, fluxos de funcionalidades
Vue	`vue` em `package.json`	SFCs, composables, rotas Vue Router, chamadas fetch/axios
Python	`pyproject.toml` / `setup.py` / `requirements.txt`	Pacotes, módulos, classes, funções, rotas (Flask/FastAPI/Django)
Java/Kotlin	`pom.xml` / `build.gradle`	Pacotes, classes, rotas (Spring/JAX-RS/Ktor/WebFlux/Micronaut)
Scala	`build.sbt`	Pacotes, objetos/classes/traits, rotas (Play/Akka HTTP/http4s)
Clojure	`project.clj` / `deps.edn`	Namespaces, defn/defprotocol/defrecord, rotas (Compojure/Reitit)
C#/.NET	`.csproj` / `.sln`	Namespaces, classes, rotas (ASP.NET/Minimal API)
Ruby	`Gemfile` / `.gemspec`	Arquivos, classes, módulos, rotas Rails
PHP	`composer.json`	Namespaces, classes, interfaces, rotas (Laravel/Symfony)
Swift	`Package.swift` / `.xcodeproj`	Arquivos, tipos (class/struct/enum/protocol/actor), rotas Vapor
C/C++	`CMakeLists.txt` / `Makefile` / `meson.build`	Fontes, cabeçalhos, classes, structs, enums, namespaces, includes
Dart/Flutter	`pubspec.yaml`	Módulos, classes, widgets, rotas go_router/shelf
Elixir/Phoenix	`mix.exs`	Módulos, funções, escopos + rotas do roteador Phoenix
Solidity	`.sol` arquivos / `foundry.toml` / `hardhat.config.*`	Contratos, interfaces, bibliotecas, eventos, herança
Terraform	`.tf` arquivos	Módulos, recursos, variáveis, saídas, fontes de módulos
SCSS	`.scss` arquivos presentes	Análise de inchaço em nível de arquivo

Extratores transversais (funcionam em todas as linguagens):

HTTP entre stacks: chamadas de frontend fetch/axios vinculadas à rota de backend que atingem e ao handler por trás dela
WebSockets: handlers e clientes (gorilla, browser, Python, Java, C#), pareados por caminho
gRPC: serviços, métodos e tipos de mensagem de .proto, além de stubs de cliente e implementações de servidor
GraphQL: resolvers e as operações que os chamam
Filas: consumidores e produtores (Celery, Dramatiq, BullMQ, Sidekiq, Oban, NATS), com tópicos resolvidos por constante
Eventos: emissores e handlers
Jobs Cron: pontos de entrada agendados
Navegação de páginas: rotas de frontend e os links entre elas (NAVIGATES_TO)
Fontes de dados: clientes de DB / cache / fila / blob / busca / email, e qual código acessa qual
Entidades de dados: esquemas compartilhados e o código que os lê ou escreve
Pontos de entrada CLI: Python click, JS commander/yargs, Go cobra, Rust clap, Java picocli, C# System.CommandLine e Spectre
Contratos: operações OpenAPI / AsyncAPI / Pact vinculadas às rotas que as implementam
Injeção de dependência: injeção via construtor conectada ao que é injetado
Chaves de configuração: onde uma chave é definida e todos os lugares que a leem
Infra: recursos Terraform e Kubernetes
Docs: seções de documentação vinculadas aos símbolos que regem (o que read apresenta como governado por)
Testes: quais testes cobrem qual código

Várias linguagens podem corresponder a um único repositório (ex.: backend Go + frontend Angular + SCSS). Cada uma contribui com seus nós e arestas para um único grafo unificado.

Instalação

Um comando

uvx mcp-repo-graph install

Isso detecta os agentes de codificação de IA que você tem instalados (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Gemini CLI, opencode, Kiro), grava a configuração MCP de cada um e adiciona um pequeno bloco de uso ao arquivo de instruções para que o agente recorra ao grafo antes de usar grep. Onde o agente suporta, também concede auto-permissão para que as ferramentas do repo-graph não solicitem confirmação a cada chamada.

É seguro executar novamente, e uvx mcp-repo-graph uninstall reverte tudo (configuração, instruções, permissões) mantendo seus dados de grafo no lugar.

uvx mcp-repo-graph install --agents all          # every supported agent, not just detected
uvx mcp-repo-graph install --scope user          # your global config, not this project
uvx mcp-repo-graph install --dry-run             # show what it would write, change nothing
uvx mcp-repo-graph install --yes                 # no prompt (scripts and CI)
uvx mcp-repo-graph install --print-config cursor # print one agent's config, write nothing

Manual, por cliente

Se preferir configurar manualmente, o nome do pacote é o comando de execução. uvx mcp-repo-graph simplesmente funciona. Sem pip install prévio, nada para manter em PATH. Este é o mesmo comando que VS Code, Cursor e o registro MCP usam internamente.

Requisitos: Python 3.11+, e uv se você usar o caminho uvx. Wheels pré-compilados são fornecidos para o motor Rust em Linux (x86_64, aarch64), macOS (Intel + Apple Silicon) e Windows (x86_64) — sem necessidade de toolchain Rust.

Claude Code

claude mcp add repo-graph -- uvx mcp-repo-graph --repo .

(--repo . aponta o grafo para o projeto atual; use um caminho absoluto para fixá-lo.)

VS Code

Um comando — adiciona o servidor à sua configuração de usuário:

code --add-mcp '{"name":"repo-graph","command":"uvx","args":["mcp-repo-graph","--repo","${workspaceFolder}"]}'

Ou clique em Instalar na entrada da galeria MCP, ou adicione manualmente em .vscode/mcp.json (veja abaixo).

Cursor / qualquer cliente MCP — configuração manual

Adicione isto à configuração MCP do seu cliente (.mcp.json, .cursor/mcp.json, .vscode/mcp.json ou ~/.claude.json):

{
  "mcpServers": {
    "repo-graph": {
      "command": "uvx",
      "args": ["mcp-repo-graph", "--repo", "/path/to/your/project"]
    }
  }
}

Prefere uma instalação persistente? pip install mcp-repo-graph (ou uv tool install mcp-repo-graph) puts a mcp-repo-graph / repo-graph command on your PATH; depois use "command": "mcp-repo-graph" na configuração acima.

--repo também aceita uma URL git. Aponte para qualquer repositório público sem clonar primeiro — ele faz um shallow-clone e mapeia (requer git):

uvx mcp-repo-graph --repo https://github.com/org/repo

Início rápido

1. Inicialize o repositório alvo (opcional)

uvx --from mcp-repo-graph repo-graph-init --repo /path/to/your/project
# or, if installed:  repo-graph-init --repo /path/to/your/project

Isso gera o grafo, grava .mcp.json e instruções CLAUDE.md, e deixa seu assistente de IA pronto para usar o repo-graph. Se você usou os one-liners acima, pode pular isto — o servidor constrói o grafo na primeira conexão.

2. Use

O assistente de IA agora tem acesso a todas as 6 ferramentas. Exemplos de consultas que ele pode responder:

"O que este codebase faz?" → ferramenta orient
"Trace o fluxo de checkout" → ferramenta trace
"O que quebraria se eu mudar UserService?" → ferramenta impact
"Quais nós são relevantes para este bug?" / "Aqui está um stacktrace — onde devo olhar?" → ferramenta find
"Mostre o código-fonte dessa função" → ferramenta read
"Dê-me o contexto completo do grafo de forma barata" → orient full=true
"Reconstruir após um grande refactor" → ferramenta refresh

3. Atualização (automática)

O grafo se mantém atualizado sozinho. Enquanto o servidor está em execução, ele observa o repositório e faz uma reconstrução incremental um momento após você salvar, então uma pergunta estrutural logo após uma edição reflete a mudança sem refresh manual. Além disso, o grafo se auto-repara na inicialização a frio — se o .gmap em cache estiver desatualizado, em formato antigo ou ausente, o motor o reconstrói e grava de volta, então nunca fica desatualizado quando seu assistente conecta.

O observador está ativado por padrão. Defina REPO_GRAPH_WATCH=0 para desativá-lo (a atualização na inicialização a frio ainda se aplica). Ele precisa do pacote watchdog, que acompanha como dependência.

Quer o cache pré-construído e commitado para que colegas e CI também o recebam? Adicione o hook de pre-commit automaticamente:

uvx mcp-repo-graph install --agents none --git-hook

Isso instala um hook pre-commit com marcadores que atualiza o grafo e prepara .glia/graph/ a cada commit. uvx mcp-repo-graph uninstall o remove novamente.

Dica: O diretório do grafo ignora a si mesmo (.glia/graph/.gitignore), então nunca aparece em git status a menos que o hook o prepare com git add -f. Pule o hook e o observador mais a atualização na inicialização a frio o mantêm atualizado localmente.

Referência das ferramentas MCP

O repo-graph expõe 6 ferramentas — um verbo natural cada, apoiado por primitivas do motor Rust.

Ferramenta	Parâmetros	Descrição
`orient`	`seed` (opcional), `full`, `budget`	A primeira chamada em um repositório: contagens de nós/arestas, tipos detectados, pontos de entrada e uma nota de pontos cegos sinalizando quais linguagens/arestas estão subconectadas (para você usar grep deliberadamente neles). `seed=<node>` → mapa com escopo; `full=true` → mapa denso do repositório inteiro
`find`	`query`, `expand`, `kind`, `top_k`, `budget`	Transforma qualquer texto nos nós classificados que importam — um símbolo/palavra-chave, ou um stacktrace colado / id de teste com falha / diff (resolvido para o código que ele implica). `expand=true` se expande para a vizinhança ao redor. Cada linha carrega `path:line`
`impact`	`nodes` (separados por vírgula), `direction`, `depth`, `live_only`, `top_k`, `budget`	Raio de explosão: o que uma mudança afeta (`forward`) ou do que depende / pelo que é usado (`backward`), como um fechamento classificado e localizado — cada linha com o motivo da aresta `via` e um `⊘` quando o motor o encontra inalcançável (provavelmente morto). Passe vários nós para um raio de diff inteiro
`trace`	`from_node`, `to_node` (opcional), `depth`, `budget`	Um argumento: uma funcionalidade de ponta a ponta através da stack, cada salto rotulado com seu mecanismo (chamada / HTTP / fila / evento) e saltos entre serviços marcados. Dois argumentos: o caminho mais curto entre dois nós
`read`	`node` (separados por vírgula), `context_lines`, `budget`	O código-fonte exato de um nó, fatiado de seu arquivo pelo intervalo de linhas do grafo, mais um rodapé `context:` (método HTTP, chamadores entre stacks ou o alvo de dial de um cliente, testes de cobertura, documentação que rege). Separe por vírgula para leitura em lote de um conjunto classificado
`refresh`	`repo_path` (opcional), `full`	Reconstrói o grafo (incremental por padrão — apenas arquivos alterados são reanalisados). `repo_path` redireciona para um caminho ou URL git diferente; `full=true` força uma reanálise limpa. Edições rotineiras são capturadas automaticamente pelo observador de arquivos

A maioria das ferramentas também aceita um budget (máx. de caracteres) para que um resultado caiba na janela de contexto de um modelo pequeno.

Estas 6 colapsaram de 13 anteriores quando o motor ganhou primitivas em formato de resposta — find, blast_radius, cross_stack_trace, resolve, coverage — que retornam resultados completos, classificados, localizados e filtrados ao vivo em uma única chamada. Menos ferramentas = menos sobrecarga fixa por turno e menos confusão para o agente.

Ele avisa quando não sabe

A maioria das ferramentas responde a uma consulta vazia com nada, o que deixa o assistente adivinhando se isso significa "essa aresta não existe" ou "não consegui ver". Desde 0.5.0, um resultado vazio retorna como uma ausência estruturada: o motivo, se esse motivo é um FATO ou uma HEURÍSTICA, e quais extrações estão parciais para o mecanismo que veio vazio.

  No answer (no_edges, FACT): no carry edge touches `backend::server::server` in this graph;
  `backend::server::server` is a container: structural IMPORTS/CONTAINS/DEFINES are not carry
  edges, so seed a symbol inside it
    looked over: CALLS
    blind spots (grep to confirm):
      ⚠ CALLS (*): calls through reflection, dynamic dispatch, or higher-order indirection are
        not resolved — verify: grep the callee name
    searched 26 nodes

orient expõe os mesmos pontos cegos antecipadamente, para que o modelo saiba quando usar grep em vez de confiar em uma lacuna. O que medimos. 14 símbolos em FastAPI, Gin, Hono e NestJS, cada um um caso onde o grafo honestamente não tem aresta, mas chamadores reais existem. Mesmo agente, mesma tarefa, a única diferença sendo se uma resposta vazia se explicava. A ausência estruturada reduziu o custo cerca de 3x em tarefas idênticas, em 28 de 28 pares correspondentes, no mesmo número de turnos: ao saber por que a resposta está vazia, o agente para de reconsultar. Isso não mudou a correção. Sonnet 5 respondeu "não é seguro excluir" em todas as 56 execuções, então se você esperava que isso impedisse um agente de excluir código em produção, não temos evidências disso e algumas evidências contra em um modelo cuidadoso. Harness e resultados brutos estão em bench/absence/. Um modelo, n=14, nosso próprio harness: trate como direcional.

0.5.0 também adiciona impact de diff completo em uma chamada (nomes não resolvidos são relatados, não descartados), caminhos distintos classificados entre stacks em trace, e rótulos cientes de papel para que um componente ou serviço declarado não seja achatado para "classe".

Como funciona

mcp-repo-graph é um servidor MCP Python leve que envolve glia, um motor Rust.

Parse — parsers tree-sitter por linguagem extraem nós brutos e referências não resolvidas
Extract — extratores transversais adicionam rotas HTTP, fontes de dados, entrypoints CLI, serviços gRPC, consumidores de fila
Resolve — o construtor de grafo resolve referências intra-repositório; resolvedores entre grafos vinculam stacks (chamadas HTTP de frontend → rotas de backend, etc.)
Store — o grafo mesclado vai para .glia/graph/ como um .gmap fragmentado com zero-copy (rkyv + mmap) além de um manifesto
Serve — o servidor MCP carrega o grafo na memória e expõe as 6 ferramentas

O motor Rust vive em seu próprio repositório glia; mcp-repo-graph é o wrapper fino voltado para MCP.

Detecção de layout

repo-graph encontra seus projetos sozinho — go.mod, package.json, pyproject.toml, Cargo.toml, pom.xml, build.gradle, composer.json, pubspec.yaml, mix.exs, Package.swift, CMakeLists.txt e amigos. Aponte --repo para a raiz de um monorepo e todo projeto sob ela entra em um único grafo.

Ele também poda por conta própria: node_modules, vendor, .venv, site-packages, saída de build (dist, target, .next, .nuxt, .angular, coverage) e diretórios de bundles com hash colapsam para uma única âncora de região em vez de serem parseados arquivo por arquivo, e .gitignore é respeitado.

Nota: versões anteriores documentavam uma saída de emergência config.yaml com chaves skip: / roots:. Isso era um recurso da era Python e o motor Rust não o lê — se você tiver um, ele está sendo ignorado. Se a auto-detecção não pegar seu layout, por favor abra uma issue com o formato do repositório; isso é mais útil do que um arquivo de configuração que ninguém pode ver.

Formato dos dados do grafo

Arquivos gerados ficam em .glia/graph/ dentro do repositório alvo:

repo-<id>.gmap: o próprio grafo, fragmentado, como rkyv com zero-copy (mmap'd no carregamento)
manifest.json: versão do formato, rótulos do repositório, raízes e erros de parse, para que um carregamento quente seja igual a uma geração nova
parse_cache.bin: cache de parse com hash de conteúdo por arquivo, para que um rebuild incremental só re-parseie arquivos editados
.gitignore: o próprio diretório de ignores, para que nunca apareça em git status

O diretório inteiro é regenerado: delete-o e a próxima chamada o reconstrói.

O motor carrega 36 categorias de aresta. As que você verá mais: CALLS, IMPORTS, CONTAINS, DEFINES, USES, HANDLED_BY, HTTP_CALLS, IMPLEMENTS, INHERITS_FROM, INJECTS, ACCESSES_DATA, TESTS, DOCUMENTS, NAVIGATES_TO, além das de canal (GRPC_CALLS, QUEUE_FLOWS, WS_CONNECTS, EVENT_FLOWS, GRAPHQL_CALLS, RPC_CALLS). Há 49 tipos de nó. Ambas as tabelas vêm do motor, então orient sempre reporta o conjunto que sua versão realmente tem.

Política de Privacidade

repo-graph roda na sua máquina e é feito para manter seu código lá. Texto completo: PRIVACY.md.

Telemetria / analytics: Nenhuma. Sem rastreamento, sem verificações de atualização, sem phone-home.
Coleta e compartilhamento de dados: Nenhum. Seu código-fonte e dados do grafo nunca são enviados para repo-graph, seu autor ou terceiros.
Processamento e armazenamento local: Escaneamento e construção do grafo acontecem localmente; o grafo é cacheado no diretório .glia/graph/ do seu projeto e permanece no seu dispositivo.
Acesso à rede — apenas dois casos, ambos iniciados pelo usuário:
1. Instalação — uvx/pip baixa o pacote e sua wheel de engine pré-construída do PyPI.
2. Alvos com URL Git — se você passar uma URL git para --repo, repo-graph executa git clone contra a URL que você especificou; nada é enviado para repo-graph ou seu autor. Um caminho --repo local (o padrão) faz zero chamadas de rede.
Retenção de dados: O cache local persiste até você deletá-lo — totalmente sob seu controle.
Contato: Issues no GitHub

Licença

MIT

Suporte

Se repo-graph economizou seu tempo, considere me pagar um café.

buymeacoffee.com/polycrisis