better-code-review-graph
Grafo de conocimiento para revisiones de código eficientes en tokens con análisis Tree-sitter, incrustación de modo dual (ONNX + LiteLLM) y análisis de radio de explosión mediante herramientas MCP.
Documentación
Mejor Gráfico de Revisión de Código
mcp-name: io.github.n24q02m/better-code-review-graph
Grafo de conocimiento para revisiones de código eficientes en tokens: búsqueda semántica y resolución de grafo de llamadas en todo tu código base.
Proyectos hermanos de n24q02m (clic para expandir)
| Proyecto | Eslogan | Etiqueta |
|---|---|---|
| agent-chat-plugin | Agentes de IA pares que chatean en una carpeta compartida: sin relevo humano, sin orquestador, tra... | Herramientas |
| better-code-review-graph | Grafo de conocimiento para revisiones de código eficientes en tokens: búsqueda semántica y resolu... | MCP |
| better-drive | Sincronización bidireccional de Google Drive con filtro .driveignore: motor rclone, bandeja de Windows | Herramientas |
| better-email-mcp | Correo IMAP/SMTP para agentes de IA: leer, enviar, organizar carpetas y gestionar archivos adj... | MCP |
| better-godot-mcp | Servidor MCP compuesto para Godot Engine: 17 herramientas compuestas para desarrollo de juegos as... | MCP |
| better-notion-mcp | Notion centrado en Markdown para agentes de IA: páginas, bases de datos, bloques y comentarios... | MCP |
| better-semantic-release | Bifurcación directa de python-semantic-release con protecciones de seguridad de lanzamiento integradas (orp...) | Herramientas |
| better-telegram-mcp | Telegram para agentes de IA: mensajes, chats, medios y contactos en ambas cuen... | MCP |
| better-workspace-mcp | Servidor MCP de Google Workspace (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...) | MCP |
| claude-plugins | Mercado de plugins de Claude Code para los servidores MCP de n24q02m: instala búsqueda web se... | Mercado |
| imagine-mcp | Comprensión y generación de imágenes y videos para agentes de IA: en Gemini, Op... | MCP |
| jules-task-archiver | Extensión de Chrome para operaciones masivas en tareas de Jules mediante la API batchexecute: a... | Herramientas |
| mcp-core | Base compartida para construir servidores MCP: transporte HTTP Streamable, OAut... | MCP |
| mnemo-mcp | Memoria persistente de IA con búsqueda híbrida y sincronización integrada. Abierta, gratuita, sin lími... | MCP |
| fastretrieval | Tiempo de ejecución rápido de recuperación multimodelo para embeddings ONNX y GGUF, reranking y contratos de modelos | Biblioteca |
| skret | Secretos sin el servidor. | CLI |
| tacet | Una cascada neuro-simbólica autodestilante que amortiza el costo de LLM en el conocimie... | Herramientas |
| web-core | Paquete compartido de infraestructura web para búsqueda, scraping, seguridad HTTP y al... | Biblioteca |
| wet-mcp | Servidor MCP de código abierto para agentes de IA: búsqueda web, extracción de contenido y bib... | MCP |
Un servidor MCP que analiza tu código base con Tree-sitter, construye un grafo estructural de funciones/clases/importaciones y le da a Claude (o a cualquier cliente MCP) contexto preciso para que lea solo lo que importa en lugar de todo el árbol. La búsqueda semántica se ejecuta a través del registro local de modelos ONNX de fastretrieval de forma predeterminada (cero configuración, sin clave API), con una cadena opcional de embeddings en la nube. Bifurcación de code-review-graph con búsqueda de múltiples palabras corregida, resolución calificada de llamadas, embeddings de doble modo, paginación de salida y CI/CD de producción.
Migración a v2.0 (ROMPE CAMBIOS)
v2.0 agrega columnas temporales (valid_from_sha / valid_to_sha en cada nodo y arista) y un escáner de seguridad opcional. La migración del esquema se aplica automáticamente en la primera apertura de GraphStore, y se guarda una copia de seguridad de la base de datos anterior a 2.0 en <graph_db>.pre-2.0.bak para que puedas revertir. Consulta BREAKING_CHANGES.md para ver la lista completa de cambios de esquema, cambios de comportamiento, requisitos de entorno y el procedimiento de degradación (CRG_DOWNGRADE_TO_1_X=1 uv run better-code-review-graph).
Tabla de contenidos
- Migración a v2.0 (ROMPE CAMBIOS)
- Instalación
- Smithery
- Configuración
- Herramientas
- CLI
- Características
- Comparación
- Seguridad
- Compilar desde el código fuente
- Modelo de confianza
- Migración y registro de cambios
- Documentación
- Licencia
Instalación
El servidor se ejecuta sobre stdio de forma predeterminada y funciona con cualquier cliente MCP. El
lanzador recomendado es uvx (sin paso de instalación:
obtiene y ejecuta el paquete publicado en un entorno aislado):
{
"mcpServers": {
"better-code-review-graph": {
"command": "uvx",
"args": ["--python", "3.13", "better-code-review-graph"],
"env": { "MCP_TRANSPORT": "stdio" }
}
}
}
O instálalo como paquete de Python:
uvx better-code-review-graph # run without installing
pip install better-code-review-graph
El motor opcional de Semgrep para análisis de seguridad más profundos es un extra separado:
pip install 'better-code-review-graph[security]'
Instala con un agente de IA: pega esto a tu agente de codificación de IA:
Instala el servidor MCP
better-code-review-graphsiguiendo los pasos en https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-code-review-graph/setup-with-agent.md
La configuración completa por cliente (Claude Code, Codex, Gemini CLI, Cursor, Windsurf,
mcp.json sin procesar) está en
mcp.n24q02m.com/servers/better-code-review-graph/setup/.
Smithery
El repositorio incluye un smithery.yaml para que el servidor se pueda compilar y
ejecutar a través de Smithery. Se implementa sobre stdio y no
necesita configuración de inicio: el esquema de configuración está vacío, y cualquier clave
opcional de embeddings/resúmenes en la nube se proporciona en tiempo de ejecución a través del propio flujo
de configuración del servidor (consulta Configuración a continuación). El comando de lanzamiento es la misma
invocación de uvx que una instalación local:
startCommand:
type: stdio
commandFunction: |-
(config) => ({ command: 'uvx', args: ['--python', '3.13', 'better-code-review-graph'] })
Configuración
Todo funciona listo para usar con cero configuración: la búsqueda semántica
usa el registro local de ONNX de fastretrieval
(Qwen3-Embedding-0.6B es la entrada de referencia integrada actual, ~570 MB
descargados en el primer graph embed). Esta entrada de referencia no es un límite exclusivo de Qwen:
cualquier ID de registro integrado o manifiesto de artefacto válido que no sea Qwen sigue
el mismo resolvedor. Todas las variables de entorno a continuación son opcionales y solo se necesitan
para embeddings en la nube, resúmenes de LLM o un artefacto local BYO explícito.
Cadenas de modelos
Los embeddings y los resúmenes se manejan cada uno mediante una cadena de modelos ordenada: un
CSV de entradas provider/model donde el orden es el orden de respaldo de litellm
(la primera entrada es el modelo activo). El proveedor se infiere del prefijo
del modelo, por lo que el <PROVIDER>_API_KEY correspondiente es todo lo que necesitas agregar.
| Variable | Propósito | Vacío (predeterminado) |
|---|---|---|
EMBEDDING_MODELS | Cadena de embeddings en la nube, p. ej., jina_ai/jina-embeddings-v5-text-small,gemini/gemini-embedding-001 | Registro local de fastretrieval |
SUMMARY_MODELS | Cadena de resúmenes para graph(action="summarize"), p. ej., gemini/gemini-2.5-flash,openai/gpt-4o-mini | Resúmenes deshabilitados |
Todos los vectores se almacenan en 768 dimensiones fijas (truncamiento MRL), por lo que el esquema de la tabla de embeddings sigue siendo válido entre proveedores. Cambiar el modelo de embeddings cambia el espacio vectorial; los embeddings se rastrean por proveedor y un cambio de proveedor activa un re-embedding en lugar de mezclar vectores incomparables.
Claves API de proveedores
Los modelos en la nube necesitan la clave del proveedor para los prefijos que aparezcan en tus cadenas. Sin ninguna clave en la nube, el servidor permanece en ONNX local. Los resumidores deben exponer una API de chat-completion (por lo que Jina y Cohere son solo de embeddings).
| Prefijo de modelo | Variable de entorno de clave API | Obtener una clave |
|---|---|---|
jina_ai/ | JINA_AI_API_KEY | https://jina.ai/api-key |
gemini/ | GEMINI_API_KEY (o GOOGLE_API_KEY) | https://aistudio.google.com/apikey |
openai/ (o text-embedding-* simple) | 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 |
Cualquier otro proveedor de litellm funciona mediante
su <PROVIDER>_API_KEY estándar.
Avanzado
| Variable | Propósito |
|---|---|
EMBEDDING_API_BASE | URL base personalizada compatible con OpenAI para embeddings en la nube (protegida contra SSRF) |
LLM_API_BASE | URL base personalizada compatible con OpenAI para el resumidor (protegida contra SSRF) |
DISABLE_LOCAL_EMBED | Omitir la descarga local de ONNX; el embedding no está disponible a menos que se configure una cadena en la nube |
LOCAL_EMBEDDING_MODEL | ID de modelo integrado de fastretrieval, o un directorio local que contenga fastretrieval-manifest.json |
LOCAL_EMBEDDING_DIM | Dimensión requerida para un ID de modelo externo sin manifiesto |
LOCAL_EMBEDDING_MODEL_FILE | Ruta del archivo ONNX dentro de un directorio de artefactos respaldado por manifiesto |
LOCAL_EMBEDDING_POOLING | Pooling explícito para un ID externo sin manifiesto: CLS, MEAN, LAST_TOKEN o DISABLED |
LOCAL_EMBEDDING_NORMALIZE | Normalización L2 explícita para un ID externo sin manifiesto |
CRG_DATA_DIR | Anular el directorio de datos por usuario (predeterminado ~/.crg) usado para grafos y credenciales por usuario en modo HTTP multiusuario |
EMBEDDING_BACKEND / EMBEDDING_MODEL / SUMMARY_MODEL | Variables singulares obsoletas, respetadas durante una versión con una advertencia: migra a las cadenas *_MODELS |
CRG intencionalmente no expone configuraciones de reranker local porque este servidor no
tiene una ruta de reranker local. Un ID de embedding externo personalizado sin manifiesto debe
proporcionar LOCAL_EMBEDDING_DIM; un directorio de artefactos local debe proporcionar un
fastretrieval-manifest.json válido; de lo contrario, el inicio falla de forma segura.
Ejemplo: embeddings en la nube + resúmenes
{
"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..."
}
}
}
}
También puedes configurar claves en la nube de forma interactiva en modo HTTP mediante el
formulario de configuración del relay (config(action="setup_start") devuelve la URL del navegador). Consulta la
descripción general de modos y la
configuración multiusuario.
Nombre de usuario del espacio de trabajo (formulario de configuración HTTP)
El formulario de configuración del relay tiene un campo opcional de nombre de usuario del espacio de trabajo. Ingresar el
mismo nombre de usuario siempre te lleva al mismo bucket por sub, por lo que tus claves y
grafo permanecen accesibles a través de una reautorización y entre dispositivos, en lugar de
estar vinculados al sujeto único emitido para cada ida y vuelta de /authorize.
Dejarlo en blanco mantiene el comportamiento anterior por autorización.
Límite de confianza: cuando el formulario está protegido por un MCP_RELAY_PASSWORD compartido, el
nombre de usuario es una clave de partición, no un secreto: cualquiera que conozca esa contraseña puede
escribir cualquier nombre de usuario y llegar a ese bucket. Eso está bien para un grupo de confianza; un
despliegue multiusuario no confiable necesita un secreto por usuario o OAuth delegado
en su lugar.
Migración única: los usuarios existentes deben volver a ingresar sus credenciales una vez después de este cambio. No se elimina nada; las credenciales almacenadas bajo el sujeto aleatorio anterior simplemente ya no se abordan.
Herramientas
Siete herramientas, cada una agrupando acciones relacionadas para mantener pequeña la superficie de herramientas.
graph: ciclo de vida del grafo
Acciones: build | update | stats | embed | export | summarize
| Acción | Descripción |
|---|---|
build | Construcción de grafo completa o incremental. Establece full_rebuild=true para volver a analizar todos los archivos; pasa roots para federar directorios de repositorio adicionales en un único grafo. |
update | Alias de build con full_rebuild=false (incremental). |
stats | Tamaño del grafo, lenguajes, desglose de nodos/aristas, número de embeddings. |
embed | Calcula embeddings vectoriales para búsqueda semántica. Modo dual: ONNX local o cadena en la nube. |
export | Exporta el grafo como graphml / json-ld / dot / cypher. En línea o a output_path. |
summarize | Docstrings de un párrafo generados por LLM para nodos Function (mediante la cadena SUMMARY_MODELS; sin efecto cuando no hay clave de proveedor configurada). Con límite de coste vía max_nodes. |
query -- Consultas de grafo
Acciones: query | search | impact | large_functions | spot_check | renamed_in_diff | diff
| Acción | Descripción |
|---|---|
query | Patrones predefinidos: callers_of, callees_of, imports_of, importers_of, children_of, tests_for, inheritors_of, file_summary. |
search | Busca entidades de código por nombre/palabra clave o similitud semántica. |
impact | Radio de impacto de archivos modificados. Detección automática a partir del git diff. Paginado con max_results. |
large_functions | Encuentra funciones/clases que superan un umbral de número de líneas. |
spot_check | Fragmentos aleatorios de puntos de llamada del último resultado de callers_of/callees_of/inheritors_of/importers_of. |
renamed_in_diff | Símbolos cuya línea de punto de llamada cambió respecto a una referencia base. |
diff | Nodos añadidos/eliminados/modificados entre dos SHAs de commit (from_sha, to_sha). |
La mayoría de las acciones de lectura aceptan as_of=<sha> para instantáneas temporales (punto en el tiempo)
y repo=<repo_id> para acotar un grafo federado de múltiples repositorios.
review -- Contexto de revisión de código
Acciones: context (predeterminada) | delta
Contexto de revisión optimizado en tokens con resumen estructural, nodos afectados, fragmentos
de código fuente y orientación de revisión. context detecta automáticamente los archivos modificados a partir del
git diff; delta (con from_sha/to_sha, show_line_shifts opcional)
muestra movimientos de refactorización entre dos commits.
config -- Configuración del servidor y configuración de credenciales
Acciones: status | set | cache_clear | setup_status | setup_start | setup_skip | setup_reset | setup_complete
| Acción | Descripción |
|---|---|
status | Información del servidor: versión, ruta del grafo, recuentos de nodos/aristas, backend de embeddings, número de embeddings. |
set | Actualiza un ajuste en tiempo de ejecución (key=log_level). |
cache_clear | Elimina todos los embeddings calculados. |
setup_status | Muestra el estado actual de credenciales, proveedores configurados y URL de configuración. |
setup_start | Inicia la configuración de relay para configurar claves API mediante navegador (modo HTTP). |
setup_skip | Establece el modo local (omite el relay permanentemente, usa solo ONNX). |
setup_reset | Borra las credenciales y restablece el estado. |
setup_complete | Vuelve a resolver las credenciales a partir de variables de entorno. |
security -- Escaneo de seguridad
Acciones: scan | report | suppress | rule_list
| Acción | Descripción |
|---|---|
scan | Ejecuta un escaneo de seguridad (engine='heuristic' predeterminado = 5 reglas regex, o 'semgrep'). Los hallazgos persisten en nodes.security_tags. |
report | Reemite los hallazgos en caché como JSON (format='json') o SARIF v2.1.0 (format='sarif'). |
suppress | Suprime un hallazgo por rule_id (o remove=true para anular la supresión). |
rule_list | Lista las reglas disponibles para un motor. |
El motor semgrep requiere el extra [security] y ejecuta el paquete de registro
p/auto de Semgrep más una capa adicional curada de 3 reglas.
help -- Documentación completa
Temas: graph | query | review | config | security | recipes
Devuelve la documentación completa de cada herramienta. Úsala cuando las descripciones comprimidas anteriores sean insuficientes.
config__open_relay -- Re-activar el formulario de configuración del relay
Registrado automáticamente desde mcp-core.
En modo HTTP devuelve <PUBLIC_URL>/authorize para que el agente pueda reabrir el
formulario de configuración del navegador (p. ej., tras la caducidad de credenciales); en modo stdio devuelve
status: 'stdio_unsupported'.
CLI
Ejecutar better-code-review-graph sin argumentos inicia el servidor MCP
a través de stdio (esto es lo que lanza un cliente MCP). Un argumento posicional inicial
enruta a un subcomando en su lugar -- útil para construir o incrustar el grafo
directamente desde un shell o un paso de CI, antes de que se conecte cualquier cliente MCP. Ejecútalos con
uvx (o uv run desde un checkout del código fuente):
# 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 | Descripción |
|---|---|
graph build | Construcción de grafo completa o incremental. --full-rebuild vuelve a analizar cada archivo; --base <ref> establece la referencia git para el diff incremental (predeterminado HEAD~1); --repo-root <path> anula la raíz del repositorio detectada automáticamente. |
graph embed | Calcula embeddings vectoriales para el grafo actual (ONNX local o la cadena en la nube configurada). Acepta --repo-root. |
config status / config delete | Muestra o elimina la configuración de credenciales almacenada (--yes omite la confirmación de borrado). |
doctor | Autocomprobación del entorno: versión de Python, backend de credenciales, capacidad de escritura del directorio de almacenamiento, estado de configuración y relay. |
relay status / relay open / relay reset | Inspecciona, abre o borra la sesión de configuración del relay del navegador (modo HTTP). |
Los subcomandos graph build y graph embed imprimen un resultado JSON y salen
con código distinto de cero en caso de error. Los subcomandos config, doctor y relay provienen del
CLI compartido mcp-core.
Características
Lo que corrige este fork frente al code-review-graph original:
| Característica | code-review-graph | better-code-review-graph |
|---|---|---|
| Búsqueda de varias palabras | Rota (subcadena literal) | División de palabras con lógica AND |
| callers_of/callees_of | Resultados vacíos (objetivos de nombre simple) | Resolución de nombre calificado + respaldo de nombre simple |
| Embeddings | sentence-transformers + torch (1.1 GB) | fastretrieval ONNX + nube (200 MB), modo dual |
| Tamaño de salida | Sin límite (más de 500K caracteres) | Paginado (max_results, indicador truncado) |
| Diseño de herramientas | 9 herramientas individuales | 7 herramientas agrupadas: graph + query + review + config + security + help + config__open_relay |
| Hooks de plugin | PostEdit/PostGit inválidos | PostToolUse válido |
Comparación
Cómo se posiciona better-code-review-graph frente a competidores directos en cada pilar:
| Capacidad | better-code-review-graph | Greptile | Sourcegraph (Cody / MCP) | CodeGraph (colbymchenry) |
|---|---|---|---|---|
| Grafo de conocimiento del código | Sí (Tree-sitter, 14 lenguajes, SQLite) | Sí (funciones/clases/deps) | Sí (indexación precisa de código) | Sí (Tree-sitter, más de 20 lenguajes, SQLite) |
| Actualizaciones incrementales persistentes | Sí (git-diff + re-análisis por hash de archivo) | ? | Sí (indexación continua) | Sí (observador de archivos del SO con debounce) |
| Resolución de llamadas calificadas (callers/callees) | Sí (resolución de llamadas simples en el mismo archivo + respaldo) | ? | Sí (ir a definición / buscar referencias) | Sí (callers / callees / impacto) |
| Búsqueda semántica / embeddings | Sí (registro local fastretrieval + Jina/Gemini/OpenAI/Cohere en la nube) | ? | Sí (semántica + palabra clave + regex) | No (solo texto completo FTS5) |
| Contexto de revisión optimizado en tokens | Sí (herramienta review, acotado por git-diff) | Sí (comentarios de revisión de PR) | No (asistente de contexto de código) | No (capa de contexto, no de revisión) |
| Escaneo de seguridad | Sí (Semgrep p/auto + capa adicional de 3 reglas, SARIF) | ? | ? | No |
| Autoalojable | Sí (stdio predeterminado, vinculado a la máquina) | Sí (Docker / K8s / aislado de red) | Sí (instancia autoalojada) | Sí (100 % local, sin claves API) |
| Gratuito / código abierto | Sí (Apache-2.0) | No (SaaS propietario; nivel OSS gratuito) | No (licencia Enterprise, código privado) | Sí (MIT) |
Fuentes: Greptile · Precios de Greptile · Sourcegraph MCP · CodeGraph. Las celdas marcadas con ? son capacidades que el competidor no documenta públicamente, no ausencias confirmadas.
Seguridad
- Alternativas elegantes -- El fallo de embeddings en la nube recurre al ONNX local.
- Manejo de errores -- Las herramientas devuelven cadenas de error con sugerencias de corrección, nunca se bloquean.
- Montaje de solo lectura -- El modo Docker monta el repositorio como
:ro(solo lectura). - Endpoints protegidos contra SSRF -- Las URLs personalizadas de
EMBEDDING_API_BASE/LLM_API_BASEse validan antes de cualquier llamada saliente.
Para informar de una vulnerabilidad, consulta SECURITY.md.
Compilar desde el código fuente
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 confianza
Este plugin implementa TC-Local (vinculado a la máquina, un único principal de confianza). Consulta el modelo de confianza de mcp-core para la clasificación completa.
| Modo | Base de datos del grafo | Credenciales en la nube | ¿Quién puede leer tus datos? |
|---|---|---|---|
| stdio (predeterminado) | <repo>/.code-review-graph/graph.db (ignorado por git) | ~/.better-code-review-graph-mcp/config.json (AES-GCM, clave vinculada a la máquina) | Solo tu usuario del SO |
| HTTP autoalojado (multiusuario) | ~/.crg/subs/<sub>/graph.db por usuario | ~/.crg/subs/<sub>/config.json por usuario | Solo el usuario autenticado |
Migración y registro de cambios
La versión v2.0 añadió columnas temporales (valid_from_sha / valid_to_sha
en cada nodo y arista) además de un escáner de seguridad opcional. La migración
del esquema se aplica automáticamente en la primera apertura de GraphStore, y se escribe una copia de seguridad de la base de datos anterior a 2.0 en
<graph_db>.pre-2.0.bak. Para degradar la versión y restaurarla:
CRG_DOWNGRADE_TO_1_X=1 uvx better-code-review-graph
Lista completa de cambios de esquema, cambios de comportamiento y procedimiento de reversión: BREAKING_CHANGES.md. Historial versión por versión: CHANGELOG.md.
Documentación
Documentación completa en mcp.n24q02m.com/servers/better-code-review-graph/setup/:
- Configuración -- métodos de instalación para Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
- Resumen de modos -- stdio / relay local / relay remoto / oauth remoto
- Configuración multiusuario -- modelo de credenciales por sub de JWT
Usa la herramienta help desde cualquier cliente MCP para obtener la referencia en línea de cada herramienta.
Licencia
Apache-2.0 -- Consulta LICENSE.