better-code-review-graph
Grafo de conhecimento para revisões de código com eficiência de tokens, utilizando parsing Tree-sitter, incorporação de modo duplo (ONNX + LiteLLM) e análise de raio de impacto via ferramentas MCP.
Documentação
Better Code Review Graph
mcp-name: io.github.n24q02m/better-code-review-graph
Grafo de conhecimento para revisões de código eficientes em tokens -- busca semântica e resolução de grafo de chamadas em toda a sua base de código.
Projetos irmãos da n24q02m (clique para expandir)
| Projeto | Tagline | Tag |
|---|---|---|
| agent-chat-plugin | Agentes de IA conversam entre si em uma pasta compartilhada — sem intermediário humano, sem orquestrador, funci... | Tooling |
| better-code-review-graph | Grafo de conhecimento para revisões de código eficientes em tokens -- busca semântica e resolu... | MCP |
| better-drive | Sincronização bidirecional do Google Drive com filtro .driveignore — mecanismo rclone, bandeja do Windows | Tooling |
| better-email-mcp | E-mail IMAP/SMTP para agentes de IA -- ler, enviar, organizar pastas e gerenciar ane... | MCP |
| better-godot-mcp | Servidor MCP composto para Godot Engine -- 17 ferramentas compostas para de... | MCP |
| better-notion-mcp | Notion com foco em Markdown para agentes de IA -- páginas, bancos de dados, blocos e comentá... | MCP |
| better-semantic-release | Fork drop-in do python-semantic-release com proteções de segurança de release integradas (orp...) | Tooling |
| better-telegram-mcp | Telegram para agentes de IA -- mensagens, chats, mídia e contatos em ambos... | MCP |
| better-workspace-mcp | Servidor MCP do Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...) | MCP |
| claude-plugins | Marketplace de plugins do Claude Code para os servidores MCP da n24q02m -- instale busca web... | Marketplace |
| imagine-mcp | Compreensão de imagem e vídeo + geração para agentes de IA -- em Gemini, Op... | MCP |
| jules-task-archiver | Extensão do Chrome para operações em lote em tarefas do Jules via API batchexecute -- a... | Tooling |
| mcp-core | Fundação compartilhada para construir servidores MCP -- transporte HTTP Streamable, OAut... | MCP |
| mnemo-mcp | Memória de IA persistente com busca híbrida e sincronização embutida. Aberto, gratuito, ilimi... | MCP |
| fastretrieval | Runtime de recuperação multi-modelo rápido para embeddings ONNX e GGUF, re-ranking e contratos de modelo | Library |
| skret | Segredos sem o servidor. | CLI |
| tacet | Uma cascata neuro-simbólica autodestilante que amortiza o custo de LLM em conheci... | Tooling |
| web-core | Pacote de infraestrutura web compartilhada para busca, scraping, segurança HTTP e st... | Library |
| wet-mcp | Servidor MCP de código aberto para agentes de IA: busca web, extração de conteúdo e lib... | MCP |
Um servidor MCP que analisa sua base de código com Tree-sitter, constrói um grafo estrutural de funções/classes/imports e dá ao Claude (ou a qualquer cliente MCP) contexto preciso para que ele leia apenas o que importa, em vez da árvore inteira. A busca semântica roda através do registro local de modelos ONNX do fastretrieval por padrão (zero configuração, sem chave de API), com uma cadeia opcional de embeddings em nuvem. Fork do code-review-graph com busca multi-palavra corrigida, resolução qualificada de chamadas, embeddings de modo duplo, paginação de saída e CI/CD de produção.
Migração v2.0 (BREAKING)
A v2.0 adiciona colunas temporais (valid_from_sha / valid_to_sha em cada nó + aresta) e um scanner de segurança opcional. A migração de esquema é aplicada automaticamente na primeira abertura do GraphStore, e um backup do banco de dados pré-2.0 é salvo em <graph_db>.pre-2.0.bak para que você possa reverter. Consulte BREAKING_CHANGES.md para a lista completa de mudanças de esquema, mudanças de comportamento, requisitos de ambiente e o procedimento de downgrade (CRG_DOWNGRADE_TO_1_X=1 uv run better-code-review-graph).
Sumário
- Migração v2.0 (BREAKING)
- Instalação
- Smithery
- Configuração
- Ferramentas
- CLI
- Recursos
- Comparação
- Segurança
- Compilar a partir do código-fonte
- Modelo de confiança
- Migração e changelog
- Documentação
- Licença
Instalação
O servidor roda sobre stdio por padrão e funciona com qualquer cliente MCP. O
lançador recomendado é o uvx (sem etapa de
instalação -- ele busca e executa o pacote publicado em um ambiente isolado):
{
"mcpServers": {
"better-code-review-graph": {
"command": "uvx",
"args": ["--python", "3.13", "better-code-review-graph"],
"env": { "MCP_TRANSPORT": "stdio" }
}
}
}
Ou instale-o como um pacote Python:
uvx better-code-review-graph # run without installing
pip install better-code-review-graph
O mecanismo opcional Semgrep para varreduras de segurança mais profundas é um extra separado:
pip install 'better-code-review-graph[security]'
Instale com um agente de IA -- cole isto no seu agente de codificação de IA:
Instale o servidor MCP
better-code-review-graphseguindo os passos em https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-code-review-graph/setup-with-agent.md
A configuração completa por cliente (Claude Code, Codex, Gemini CLI, Cursor, Windsurf,
mcp.json puro) está em
mcp.n24q02m.com/servers/better-code-review-graph/setup/.
Smithery
O repositório inclui um smithery.yaml para que o servidor possa ser compilado e
executado através do Smithery. Ele é implantado sobre stdio e não
precisa de configuração de inicialização -- o esquema de configuração é vazio, e quaisquer
chaves opcionais de embedding/resumo em nuvem são fornecidas em tempo de execução através do fluxo
de configuração do próprio servidor (veja Configuração abaixo). O comando de
lançamento é a mesma invocação de uvx que uma instalação local:
startCommand:
type: stdio
commandFunction: |-
(config) => ({ command: 'uvx', args: ['--python', '3.13', 'better-code-review-graph'] })
Configuração
Tudo funciona pronto para uso com zero configuração -- a busca semântica
usa o registro local ONNX do fastretrieval
(Qwen3-Embedding-0.6B é a entrada de referência integrada atual, ~570 MB
baixados na primeira graph embed). Esta entrada de referência não é um limite exclusivo
do Qwen: qualquer ID de registro integrado ou manifesto de artefato não-Qwen válido segue o
mesmo resolvedor. Todas as variáveis de ambiente abaixo são opcionais e só são necessárias
para embeddings em nuvem, resumos de LLM ou um artefato local BYO explícito.
Cadeias de modelos
Embeddings e resumos são cada um conduzidos por uma cadeia de modelos ordenada -- um
CSV de entradas provider/model onde a ordem é a ordem de fallback do litellm
(a primeira entrada é o modelo ativo). O provedor é inferido a partir do prefixo do modelo,
então o <PROVIDER>_API_KEY correspondente é tudo o que você precisa adicionar.
| Variável | Finalidade | Vazio (padrão) |
|---|---|---|
EMBEDDING_MODELS | Cadeia de embeddings em nuvem, ex.: jina_ai/jina-embeddings-v5-text-small,gemini/gemini-embedding-001 | Registro local fastretrieval |
SUMMARY_MODELS | Cadeia de resumos para graph(action="summarize"), ex.: gemini/gemini-2.5-flash,openai/gpt-4o-mini | Resumos desativados |
Todos os vetores são armazenados em 768 dimensões fixas (truncamento MRL), então o esquema da tabela de embeddings permanece válido entre provedores. Trocar o modelo de embedding muda o espaço vetorial; os embeddings são rastreados por provedor e uma troca de provedor aciona re-embedding em vez de misturar vetores incomparáveis.
Chaves de API do provedor
Modelos em nuvem precisam da chave do provedor para quaisquer prefixos que apareçam em suas cadeias. Sem nenhuma chave de nuvem, o servidor permanece no ONNX local. Os resumidores devem expor uma API de chat-completion (então Jina e Cohere são apenas para embeddings).
| Prefixo do modelo | Variável de ambiente da chave de API | Obter uma chave |
|---|---|---|
jina_ai/ | JINA_AI_API_KEY | https://jina.ai/api-key |
gemini/ | GEMINI_API_KEY (ou GOOGLE_API_KEY) | https://aistudio.google.com/apikey |
openai/ (ou text-embedding-* puro) | OPENAI_API_KEY | https://platform.openai.com/api-keys |
cohere/ | COHERE_API_KEY | https://dashboard.cohere.com/api-keys |
vertex_express/ | GOOGLE_VERTEX_EXPRESS_API_KEY | https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview |
Qualquer outro provedor litellm funciona via
seu <PROVIDER>_API_KEY padrão.
Avançado
| Variável | Finalidade |
|---|---|
EMBEDDING_API_BASE | URL base personalizada compatível com OpenAI para embedding em nuvem (protegida contra SSRF) |
LLM_API_BASE | URL base personalizada compatível com OpenAI para o resumidor (protegida contra SSRF) |
DISABLE_LOCAL_EMBED | Pular o download local do ONNX; o embedding fica indisponível a menos que uma cadeia em nuvem seja configurada |
LOCAL_EMBEDDING_MODEL | ID de modelo fastretrieval integrado, ou um diretório local contendo fastretrieval-manifest.json |
LOCAL_EMBEDDING_DIM | Dimensão necessária para um ID de modelo externo sem manifesto |
LOCAL_EMBEDDING_MODEL_FILE | Caminho do arquivo ONNX dentro de um diretório de artefato com manifesto |
LOCAL_EMBEDDING_POOLING | Pooling explícito para um ID externo sem manifesto: CLS, MEAN, LAST_TOKEN ou DISABLED |
LOCAL_EMBEDDING_NORMALIZE | Normalização L2 explícita para um ID externo sem manifesto |
CRG_DATA_DIR | Substituir o diretório de dados por usuário (padrão ~/.crg) usado para grafos e credenciais por usuário no modo multi-usuário HTTP |
EMBEDDING_BACKEND / EMBEDDING_MODEL / SUMMARY_MODEL | Variáveis singulares obsoletas, aceitas por um release com aviso -- migre para as cadeias *_MODELS |
O CRG intencionalmente não expõe configurações de re-ranking local porque este servidor não
tem caminho de re-ranking local. Um ID de embedding externo personalizado sem manifesto deve
fornecer LOCAL_EMBEDDING_DIM; um diretório de artefato local deve fornecer um
fastretrieval-manifest.json válido, caso contrário a inicialização falha de forma segura.
Exemplo -- embeddings em nuvem + resumos
{
"mcpServers": {
"better-code-review-graph": {
"command": "uvx",
"args": ["--python", "3.13", "better-code-review-graph"],
"env": {
"MCP_TRANSPORT": "stdio",
"EMBEDDING_MODELS": "jina_ai/jina-embeddings-v5-text-small,gemini/gemini-embedding-001",
"SUMMARY_MODELS": "gemini/gemini-2.5-flash",
"JINA_AI_API_KEY": "jina_...",
"GEMINI_API_KEY": "AIza..."
}
}
}
}
Você também pode configurar chaves de nuvem interativamente no modo HTTP através do formulário
de configuração do relay (config(action="setup_start") retorna a URL do navegador). Consulte a
visão geral dos modos e a
configuração multi-usuário.
Nome de usuário do workspace (formulário de configuração HTTP)
O formulário de configuração do relay tem um campo opcional de nome de usuário do workspace.
Inserir o mesmo nome de usuário sempre o leva ao mesmo bucket por sub, então suas chaves e
grafo permanecem acessíveis em uma re-autorização e entre dispositivos, em vez de ficarem
vinculados ao subject único cunhado para cada round-trip de /authorize.
Deixar em branco mantém o comportamento anterior por autorização.
Limite de confiança: quando o formulário é protegido por um MCP_RELAY_PASSWORD compartilhado, o
nome de usuário é uma chave de partição, não um segredo -- qualquer pessoa que conheça essa senha pode
digitar qualquer nome de usuário e alcançar esse bucket. Isso é aceitável para um grupo confiável; uma
implantação multi-tenant não confiável precisa de um segredo por usuário ou OAuth delegado
em vez disso.
Migração única: usuários existentes devem re-inserir suas credenciais uma vez após esta mudança. Nada é excluído; credenciais armazenadas sob o antigo subject aleatório simplesmente não são mais endereçadas.
Ferramentas
Sete ferramentas, cada uma agrupando ações relacionadas para manter a superfície de ferramentas pequena.
graph -- Ciclo de vida do grafo
Ações: build | update | stats | embed | export | summarize
| Ação | Descrição |
|---|---|
build | Construção de grafo completa ou incremental. Defina full_rebuild=true para reanalisar todos os arquivos; passe roots para federar diretórios de repositório extras em um único grafo. |
update | Alias para build com full_rebuild=false (incremental). |
stats | Tamanho do grafo, linguagens, detalhamento de nós/arestas, contagem de embeddings. |
embed | Calcula embeddings vetoriais para busca semântica. Modo duplo: ONNX local ou cadeia em nuvem. |
export | Exporta o grafo como graphml / json-ld / dot / cypher. Inline ou para output_path. |
summarize | Docstrings de um parágrafo geradas por LLM para nós Function (via cadeia SUMMARY_MODELS; sem efeito quando nenhuma chave de provedor está definida). Custo limitado via max_nodes. |
query -- Consultas de grafo
Ações: query | search | impact | large_functions | spot_check | renamed_in_diff | diff
| Ação | Descrição |
|---|---|
query | Padrões predefinidos: callers_of, callees_of, imports_of, importers_of, children_of, tests_for, inheritors_of, file_summary. |
search | Busca entidades de código por nome/palavra-chave ou similaridade semântica. |
impact | Raio de impacto de arquivos alterados. Detecta automaticamente a partir do git diff. Paginado com max_results. |
large_functions | Encontra funções/classes que excedem um limite de contagem de linhas. |
spot_check | Trechos aleatórios de callsite do último resultado callers_of/callees_of/inheritors_of/importers_of. |
renamed_in_diff | Símbolos cuja linha de callsite mudou em relação a uma referência base. |
diff | Nós adicionados/removidos/modificados entre dois SHAs de commit (from_sha, to_sha). |
A maioria das ações de leitura aceita as_of=<sha> para snapshots temporais (ponto no tempo) e repo=<repo_id> para escopar um grafo federado de múltiplos repositórios.
review -- Contexto de revisão de código
Ações: context (padrão) | delta
Contexto de revisão otimizado por tokens com resumo estrutural, nós impactados, trechos de código e orientação de revisão. context detecta automaticamente arquivos alterados a partir do git diff; delta (com from_sha/to_sha, opcional show_line_shifts) expõe movimentos de refatoração entre dois commits.
config -- Configuração do servidor e configuração de credenciais
Ações: status | set | cache_clear | setup_status | setup_start | setup_skip | setup_reset | setup_complete
| Ação | Descrição |
|---|---|
status | Informações do servidor: versão, caminho do grafo, contagens de nós/arestas, backend de embeddings, contagem de embeddings. |
set | Atualiza uma configuração de tempo de execução (key=log_level). |
cache_clear | Remove todos os embeddings calculados. |
setup_status | Mostra o estado atual das credenciais, provedores configurados e URL de configuração. |
setup_start | Inicia a configuração do relay para configurar chaves de API via navegador (modo HTTP). |
setup_skip | Define o modo local (ignora o relay permanentemente, usa apenas ONNX). |
setup_reset | Limpa credenciais e redefine o estado. |
setup_complete | Re-resolve credenciais a partir de variáveis de ambiente. |
security -- Varredura de segurança
Ações: scan | report | suppress | rule_list
| Ação | Descrição |
|---|---|
scan | Executa uma varredura de segurança (engine='heuristic' padrão = 5 regras regex, ou 'semgrep'). Os achados persistem em nodes.security_tags. |
report | Reemite achados em cache como JSON (format='json') ou SARIF v2.1.0 (format='sarif'). |
suppress | Suprime um achado por rule_id (ou remove=true para reativar). |
rule_list | Lista as regras disponíveis para um mecanismo. |
O mecanismo semgrep requer o extra [security] e executa o pacote de registro p/auto do Semgrep, além de uma sobreposição curada de 3 regras.
help -- Documentação completa
Tópicos: graph | query | review | config | security | recipes
Retorna documentação completa para cada ferramenta. Use quando as descrições compactadas acima forem insuficientes.
config__open_relay -- Reativar o formulário de configuração do relay
Registrado automaticamente a partir de mcp-core. No modo HTTP, retorna <PUBLIC_URL>/authorize para que o agente possa reabrir o formulário de configuração do navegador (por exemplo, após a expiração das credenciais); no modo stdio, retorna status: 'stdio_unsupported'.
Linha de comando
Executar better-code-review-graph sem argumentos inicia o servidor MCP via stdio (é isso que um cliente MCP lança). Um argumento posicional inicial roteia para um subcomando — útil para construir ou incorporar o grafo diretamente de um shell ou etapa de CI, antes que qualquer cliente MCP se conecte. Execute-os com uvx (ou uv run a partir de um checkout de código-fonte):
# Start the MCP server over stdio (default -- no subcommand)
uvx better-code-review-graph
# Build (or incrementally update) the graph for the current repo
uvx better-code-review-graph graph build
# Full re-parse of every file instead of a git-diff incremental
uvx better-code-review-graph graph build --full-rebuild
# Compute embeddings for semantic search (local ONNX by default)
uvx better-code-review-graph graph embed
| Comando | Descrição |
|---|---|
graph build | Construção de grafo completa ou incremental. --full-rebuild reanalisa cada arquivo; --base <ref> define a referência git para o diff incremental (padrão HEAD~1); --repo-root <path> substitui a raiz do repositório detectada automaticamente. |
graph embed | Calcula embeddings vetoriais para o grafo atual (ONNX local ou a cadeia em nuvem configurada). Aceita --repo-root. |
config status / config delete | Mostra ou remove a configuração de credenciais armazenada (--yes pula a confirmação de exclusão). |
doctor | Autoverificação do ambiente: versão do Python, backend de credenciais, capacidade de gravação do diretório de armazenamento, estado de configuração e relay. |
relay status / relay open / relay reset | Inspeciona, abre ou limpa a sessão de configuração do relay no navegador (modo HTTP). |
Os subcomandos graph build e graph embed imprimem um resultado JSON e saem com código não zero em caso de erro. Os subcomandos config, doctor e relay vêm da CLI compartilhada mcp-core.
Recursos
O que este fork corrige em relação ao code-review-graph upstream:
| Recurso | code-review-graph | better-code-review-graph |
|---|---|---|
| Busca de múltiplas palavras | Quebrado (substring literal) | Divisão de palavras com lógica AND |
| callers_of/callees_of | Resultados vazios (alvos de nome simples) | Resolução de nome qualificado + fallback simples |
| Embedding | sentence-transformers + torch (1.1 GB) | fastretrieval ONNX + nuvem (200 MB), modo duplo |
| Tamanho da saída | Ilimitado (500K+ caracteres) | Paginado (max_results, flag truncado) |
| Design de ferramentas | 9 ferramentas individuais | 7 ferramentas agrupadas: graph + query + review + config + security + help + config__open_relay |
| Ganchos de plugin | PostEdit/PostGit inválidos | PostToolUse válido |
Comparação
Como o better-code-review-graph se compara aos concorrentes diretos em cada pilar:
| Capacidade | better-code-review-graph | Greptile | Sourcegraph (Cody / MCP) | CodeGraph (colbymchenry) |
|---|---|---|---|---|
| Grafo de conhecimento do código | Sim (Tree-sitter, 14 linguagens, SQLite) | Sim (funções/classes/deps) | Sim (indexação precisa de código) | Sim (Tree-sitter, 20+ linguagens, SQLite) |
| Atualizações incrementais persistentes | Sim (git-diff + reanálise por hash de arquivo) | ? | Sim (indexação contínua) | Sim (observador de arquivos do SO com debounce) |
| Resolução de chamadas qualificadas (callers/callees) | Sim (resolução de chamada simples no mesmo arquivo + fallback) | ? | Sim (ir para definição / encontrar referências) | Sim (callers / callees / impacto) |
| Busca semântica / embeddings | Sim (registro local fastretrieval + nuvem Jina/Gemini/OpenAI/Cohere) | ? | Sim (semântica + palavra-chave + regex) | Não (somente texto completo FTS5) |
| Contexto de revisão otimizado por tokens | Sim (ferramenta review, escopo por git-diff) | Sim (comentários de revisão de PR) | Não (assistente de contexto de código) | Não (camada de contexto, não revisão) |
| Varredura de segurança | Sim (Semgrep p/auto + sobreposição de 3 regras, SARIF) | ? | ? | Não |
| Auto-hospedável | Sim (stdio padrão, vinculado à máquina) | Sim (Docker / K8s / air-gapped) | Sim (instância auto-hospedada) | Sim (100% local, sem chaves de API) |
| Gratuito / código aberto | Sim (Apache-2.0) | Não (SaaS proprietário; camada OSS gratuita) | Não (licença Enterprise, código-fonte privado) | Sim (MIT) |
Fontes: Greptile · Preços do Greptile · Sourcegraph MCP · CodeGraph. Células marcadas com ? são capacidades que o concorrente não documenta publicamente, não ausências confirmadas.
Segurança
- Fallbacks graciosos -- Falha de embedding em nuvem recai para ONNX local.
- Tratamento de erros -- Ferramentas retornam strings de erro com sugestões de correção, nunca travam.
- Montagem somente leitura -- O modo Docker monta o repositório como
:ro(somente leitura). - Endpoints protegidos contra SSRF -- URLs personalizadas
EMBEDDING_API_BASE/LLM_API_BASEsão validadas antes de qualquer chamada de saída.
Para relatar uma vulnerabilidade, consulte SECURITY.md.
Compilar a partir do código-fonte
git clone https://github.com/n24q02m/better-code-review-graph
cd better-code-review-graph
uv sync --group dev
uv run pytest
uv run better-code-review-graph
Requisitos: Python 3.13, uv.
Modelo de confiança
Este plugin implementa TC-Local (vinculado à máquina, principal de confiança único). Consulte o modelo de confiança do mcp-core para classificação completa.
| Modo | Banco de dados do grafo | Credenciais em nuvem | Quem pode ler seus dados? |
|---|---|---|---|
| stdio (padrão) | <repo>/.code-review-graph/graph.db (ignorado pelo git) | ~/.better-code-review-graph-mcp/config.json (AES-GCM, chave vinculada à máquina) | Somente o usuário do seu SO |
| HTTP auto-hospedado (multi-usuário) | Por usuário ~/.crg/subs/<sub>/graph.db | Por usuário ~/.crg/subs/<sub>/config.json | Somente o usuário autenticado |
Migração e changelog
A versão v2.0 adicionou colunas temporais (valid_from_sha / valid_to_sha em cada nó e aresta) além de um scanner de segurança opcional. A migração de esquema é aplicada automaticamente na primeira abertura de GraphStore, e um backup do banco de dados pré-2.0 é gravado em <graph_db>.pre-2.0.bak. Para fazer downgrade e restaurá-lo:
CRG_DOWNGRADE_TO_1_X=1 uvx better-code-review-graph
Lista completa de mudanças de esquema, alterações de comportamento e procedimento de rollback: BREAKING_CHANGES.md. Histórico versão por versão: CHANGELOG.md.
Documentação
Documentação completa em mcp.n24q02m.com/servers/better-code-review-graph/setup/:
- Configuração -- métodos de instalação para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
- Visão geral dos modos -- stdio / local-relay / remote-relay / remote-oauth
- Configuração multi-usuário -- modelo de credencial por JWT-sub
Use a ferramenta help de qualquer cliente MCP para referência inline por ferramenta.
Licença
Apache-2.0 -- Consulte LICENSE.