Kivgraph

Kivgraph

Kivgraph es un servidor MCP local de inteligencia de código entre repositorios para agentes de codificación de IA. Construye un grafo de código semántico canónico a través de múltiples repositorios registrados y responde preguntas sobre símbolos, relaciones entre repositorios, llamadores, dependencias e impacto de cambios.

https://github.com/user-attachments/assets/b8410905-323d-4caf-9d7b-57c50ffca48c

kivgraph ui — vista 3D de solo lectura del grafo publicado.

Indexa un corpus una vez y sirve un grafo inmutable: las aristas se resuelven mediante go/types, el verificador de TypeScript y rust-analyzer, no mediante coincidencia de nombres. Esa es la diferencia con una herramienta de búsqueda, y es lo que hace que una respuesta vacía valga algo — una lista de referencias vacía significa que nadie lo llama, no que no se encontró nada, y grep no puede distinguir entre ambos casos.

Kivgraph se centra en relaciones semánticas de código, no en el descubrimiento automático de cada flujo de runtime HTTP, gRPC, Kafka o base de datos entre servicios.

Documentación

Lee la documentación de usuario de Kivgraph para instalación, clientes MCP, inteligencia de código, relaciones entre repositorios y grafos de código de espacios de trabajo. Las mismas páginas son la fuente de landing/src/content/docs en este checkout, que es lo que un lector en un fork o sin red aún tiene.

Qué responde cada herramienta

la pregunta	la herramienta
quién llama a esto, qué referencia a esto	find_references
qué se rompe si lo cambio	get_blast_radius
qué alcanza esto hacia afuera	trace_dependencies
quién lo usa desde otro repositorio	find_cross_repo_consumers
dónde está declarado	find_symbol
qué está declarado en este paquete	get_file_outline
dame el código de estos símbolos	get_source
todo sobre este símbolo	get_symbol
qué está indexado y si el grafo está actualizado	list_repositories, graph_status

Diez herramientas de solo lectura, más una mutación con consentimiento (index_project) que un cliente debe autorizar antes de poder registrar un repositorio o publicar una generación.

Cada fila que nombra un símbolo lleva su repositorio, ruta, nombre calificado y rango de líneas, para que pueda abrirse sin una segunda llamada, y cada herramienta acepta ese triple en lugar de una clave opaca.

Dónde pierde. Un nombre raro en un repositorio pequeño es más barato con grep, e indexar un archivo pequeño cuesta más que leerlo. Gana en nombres comunes, en impacto transitivo, en consumidores en otro repositorio y en demostrar una ausencia. Medido en 29 preguntas contra un corpus de 37 repositorios (benchmarks/graph-tools-comparison/results-all.json, commit 954b9eb, tokenizador o200k_base): 35,961 tokens para Kivgraph frente a 267,980 para grep más lectura, ambos exactos en 28 de las 29, mediana de 5.95x por pregunta a favor de Kivgraph. grep es más barato en 5 de esas 29, todas con recuperación completa en ambos lados: T1_go_trivial pide un nombre que el corpus declara dos veces, y allí grep cuesta 0.53x lo que hace Kivgraph.

Un segundo arnés, benchmarks/mcp-token-cost, compara contra la salida de la propia herramienta del host capturada textualmente, pero se ejecuta en el único repositorio de Kivgraph de 13,222 símbolos: 7.64x en las respuestas mismas y 1.60x en una sesión completa, contra un piso de 2.41x establecido por los cuerpos fuente que ambos lados pagan.

Estado

Publicado y en uso. kivgraph version informa la versión publicada; el backlog y la puerta de aceptación de cada fase están en TASKS.md.

• Lenguajes: Go, TypeScript, Rust, Python y Dart. Python usa el trabajador AST incluido en modo de respaldo; esas referencias inferidas son CANDIDATE, nunca EXACT. El modo exacto de Python usa el adaptador LSP de Pyright incluido con un servidor Pyright/BasedPyright instalado. Dart usa el Dart Analysis Server suministrado por el SDK de Dart o Flutter.
• Dependencias semánticas: las importaciones de Python y Dart pueden publicar una dependencia de paquete cuando exactamente un proveedor registrado posee el paquete solicitado; las aristas entre repositorios a nivel de símbolo requieren una identidad de proveedor explícita.
• Superficie: diez herramientas de solo lectura sobre STDIO, más una mutación con consentimiento (index_project). El contrato está en docs/protocol/mcp-surface-v3.md.
• Almacenamiento: LadybugDB es canónico; las consultas se sirven desde un HotSnapshot inmutable publicado atómicamente, nunca desde la base de datos.
• Plataformas: linux/amd64, darwin/arm64 y windows/amd64.
• Visor: kivgraph ui sirve una vista 3D de solo lectura del grafo publicado.

Instalación

Instala el MCP con un script

El instalador detecta la plataforma, descarga la última versión publicada del MCP para ella, verifica tanto el archivo de la versión como las sumas de verificación del bundle, y lo instala sin requerir Go o pnpm. La versión contiene el servidor Go, la biblioteca LadybugDB fijada, el trabajador TypeScript, el trabajador AST de Python incluido, el rust-analyzer fijado, el manifiesto de gramática y el visor web, cuyos activos son 2.3 MB del bundle. scripts/build-bundle.sh --mcp-only produce un bundle sin el visor para quien lo quiera. --slim va más allá para cualquiera que empaquete un .mcpb: deja fuera el rust-analyzer fijado y cada símbolo que un depurador leería, que son 46.3 MB empaquetados frente a 24.9 MB. No descarga nada después, por lo que ese bundle lee Rust solo donde la máquina ya tiene un analizador en su PATH.

Bundles publicados: Linux amd64 y macOS arm64.

Requisitos de runtime: Bash, Node.js 22 o posterior, Python 3.10 o posterior al indexar Python, curl, tar y sha256sum o shasum. El bundle lleva su propio rust-analyzer; indexar repositorios Rust adicionalmente necesita cargo en el PATH, e indexar Dart necesita el SDK de Dart o Flutter.

En macOS los binarios no están notarizados. Una versión descargada con curl no está en cuarentena y se ejecuta; una copia descargada con un navegador necesita xattr -dr com.apple.quarantine. Consulta docs/development/macos.md.

Instala la última versión en un comando:

curl -fsSL https://github.com/Luqueee/kivgraph/releases/latest/download/install.sh | bash

Desde un checkout, el mismo instalador puede ejecutarse directamente:

./scripts/install.sh

Para instalar una versión específica en lugar de la última:

KIVGRAPH_VERSION=v0.9.2 ./scripts/install.sh

El script instala el bundle en ~/.local/opt/kivgraph y coloca los lanzadores en ~/.local/bin. Nunca modifica un repositorio registrado, crea un índice ni reemplaza archivos de configuración. Para usar una ubicación diferente, establece KIVGRAPH_INSTALL_ROOT y KIVGRAPH_BIN_DIR.

Agrega el directorio de lanzadores al shell actual y verifica ambos runtimes:

export PATH="$HOME/.local/bin:$PATH"
kivgraph version
kivgraph-ts-worker <<'EOF'
hello
EOF

Verifica si hay una versión más reciente o actualiza el bundle instalado:

kivgraph update --check
kivgraph update

La actualización es atómica, preserva la configuración y el estado del grafo, verifica las sumas de verificación de la versión y del bundle, y reemplaza solo el bundle instalado. Reinicia el cliente MCP después de actualizar para que lance el nuevo binario.

Cuando kivgraph se invoca sin un comando desde una terminal interactiva, verifica si hay una versión más reciente con un tiempo de espera de 800 ms y un caché de 24 horas en el directorio de caché de la plataforma ($XDG_CACHE_HOME en Linux y $HOME/Library/Caches en macOS), bajo kivgraph/update-check.json. La verificación opcional nunca bloquea el comando cuando la red no está disponible.

La salida interactiva de comandos usa colores ANSI semánticos cuando el destino es una terminal. Establece NO_COLOR o redirige la salida para mantenerla simple.

Configura un cliente MCP e instala la habilidad

El instalador de la versión no edita la configuración del cliente automáticamente. Después de instalar Kivgraph, ejecuta los comandos de integración sin --target para detectar los agentes de codificación presentes en esta máquina y seleccionar uno o más de ellos:

kivgraph mcp install --scope user
kivgraph skill install --scope user

Kivgraph verifica las raíces de configuración o instalación locales conocidas de cada cliente y marca los agentes detectados. Usa ↑/↓ (o j/k) para moverte, space para alternar un agente, a para seleccionar todos, n para seleccionar ninguno, Enter para confirmar y q o Esc para cancelar. Si no se detecta ninguno, el selector comienza sin agentes seleccionados. Usa --target solo para instalación no interactiva mediante scripts.

Los objetivos MCP compatibles son claude-code, claude-desktop, codex, opencode y oh-my-pi. Los objetivos de habilidad compatibles son claude-code, codex, opencode y oh-my-pi; Claude Desktop no tiene objetivo de habilidad local. El alcance predeterminado es user; usa --scope project para configuración local del proyecto. Usa --dry-run para inspeccionar un plan sin escribir. Las entradas incompatibles existentes detienen con un error; --force es necesario para reemplazar o eliminar una. Los archivos existentes se escriben atómicamente con modo 0600 y reciben una copia de seguridad *.kivgraph.bak antes del reemplazo o la eliminación.

Inspecciona o elimina un registro explícitamente:

kivgraph mcp status --target claude-code --scope user
kivgraph mcp remove --target claude-code --scope user
kivgraph skill status --target claude-code --scope user
kivgraph skill remove --target claude-code --scope user

Inicializa y publica un grafo antes de iniciar el servidor MCP:

kivgraph init \
  --repository project=/absolute/path/to/project \
  --languages go,typescript,rust
kivgraph doctor
kivgraph index --full

init escribe una configuración autocontenida: con --config apuntando a otro lugar, su estado, caché y registro cuelgan de ese directorio, por lo que un índice desechable nunca toca el real. index --full republica atómicamente — una falla en cualquier etapa deja la generación anterior sirviendo. Un servidor ya en ejecución sigue la nueva generación por sí mismo.

Día a día:

kivgraph graph status      # what is published, and whether a tree has moved
kivgraph doctor            # toolchains, storage, and the type-checking ceiling
kivgraph ui                # read-only 3D viewer, default 0.0.0.0:7777
kivgraph logs --follow     # what it indexed, served and answered, as it happens
kivgraph tool-stats        # per-tool cost, calls, and failures
kivgraph stop              # terminate this user's serve and ui, never an index
kivgraph clean --keep-active

kivgraph ui se vincula a una dirección no loopback por defecto, porque el grafo se indexa donde están los repositorios y se mira desde otro lugar; no hay autenticación, por lo que registra exactamente lo que expone y --addr lo restringe.

logs y tool-stats leen un registro de solo anexión en el directorio de estado en lugar de preguntar a un servidor, que es por lo que pueden responder en absoluto: los contadores por herramienta que un serve mantiene se acuñan cuando comienza y desaparecen cuando se detiene. Leer el archivo también hace que la respuesta abarque cada servidor que haya ejecutado.

Configura cualquier cliente MCP para iniciar el servidor sobre STDIO:

{
  "mcpServers": {
    "kivgraph": {
      "command": "/home/user/.local/bin/kivgraph",
      "args": [
        "serve",
        "--config",
        "/home/user/.config/kivgraph/config.yaml"
      ]
    }
  }
}

kivgraph serve comienza antes de que exista un grafo: sin una generación publicada completa el handshake, no publica ninguna herramienta de consulta y coloca el comando de reconstrucción en instructions. Un cliente lanza el proceso por sí mismo, por lo que salir se leería como un bloqueo. Escribe el enmarcado MCP exclusivamente en stdout y registra en stderr.

Requisitos

• Go 1.26 o posterior para compilar desde el código fuente. El indexador verifica tipos con el go/types vinculado al binario, por lo que solo puede leer repositorios y dependencias escritos para su propia versión de lenguaje o anterior; kivgraph doctor informa ese límite.
• Indexar Rust necesita cargo y rust-analyzer. El bundle de la versión lleva el analizador; no lleva un toolchain de Rust.
• Indexar TypeScript necesita Node.js 22 o posterior para el trabajador.
• Indexar Python necesita Python 3.10 o posterior para el trabajador incluido. Es un respaldo consciente de sintaxis e informa nombres dinámicos o no resueltos explícitamente; el modo exacto además requiere un servidor de lenguaje compatible con Pyright.
• Indexar Dart necesita el ejecutable dart; una instalación de Flutter lo suministra. El cargador usa el protocolo del Analysis Server y no modifica el proyecto Flutter.

Qué lleva el grafo, y qué se niega a llevar

Una arista es EXACT solo con evidencia suficiente y la procedencia correcta. Nunca se crea a partir de un nombre, una ruta, un alias o un candidato único, y una referencia que no puede resolverse se publica como UNRESOLVED con su razón, repositorio y lenguaje en lugar de descartarse. graph_status informa ambos, desglosados. Esa es la razón por la que algunas respuestas son ausencias en lugar de aristas. Con la biblioteca estándar de Rust indexada, impl Add for u32 se genera mediante una macro y no existe en ningún rango de código fuente, por lo que cada uso de ella se declara PROVIDER_DEFINITION_NOT_INDEXED una vez por símbolo en lugar de convertirse en una arista que nadie podría abrir.

Los proveedores que Kivgraph deriva de la máquina — hoy la biblioteca estándar de Rust, llamada rust:1.96.1 según la cadena de herramientas — se omiten de los resultados de lectura de forma predeterminada: una cadena de herramientas tiene alrededor de veinte mil símbolos, y una búsqueda de Clone respondería con core. include_derived los solicita, y graph_status desglosa lo que aportan para que los totales sigan siendo legibles.

Desarrollo

make build
make test
make semantic-coverage
make test-ladybug

make test-ladybug es la única forma compatible de ejecutar la etiqueta que vincula la biblioteca nativa fijada. Las convenciones de contribución están en AGENTS.md, al que CLAUDE.md enlaza.

make semantic-coverage es la puerta de lanzamiento para Go, TypeScript, Python y Dart. Valida la matriz legible por máquina en testdata/semantic-coverage/manifest.json, ejecuta las suites exactas de TypeScript, Go y Dart, y requiere un servidor de lenguaje compatible con Pyright para la suite exacta de Python. Un lenguaje no se considera completo cuando una capacidad tiene un fixture pero no una prueba de regresión ejecutable.

Benchmarks de almacenamiento y grafo

La calificación de LadybugDB, el generador de corpus sintético, los benchmarks de carga y consulta, y los comandos doctor, rebuild, rollback y snapshot están documentados en docs/development/storage-benchmarks.md. Concluye con ACCEPT_LADYBUGDB_WITH_LIMITS.

El sitio público

landing/ contiene la página de inicio y la documentación de usuario. No se incluye en ningún paquete de lanzamiento, se verifica con make landing-check y make landing-build, y se sirve en el puerto 6767. Lo que publica, cómo se capturó la referencia MCP y lo que aún está pendiente se registran en docs/development/landing-site.md.

Estructura

cmd/kivgraph/   Main executable.
internal/        Kivgraph internal packages.
ts-worker/        TypeScript worker.
web/              Graph viewer served by `kivgraph ui`.
landing/          Landing page and documentation site (not part of any release).
testdata/         Test fixtures and corpora.
benchmarks/       Benchmark results.
docs/             Documentation and ADRs.
scripts/          Auxiliary automation.

Licencia

Kivgraph se distribuye bajo la Licencia Apache 2.0.

Licencias de terceros

Los avisos y licencias de las dependencias distribuidas con Kivgraph se registran en THIRD_PARTY_NOTICES.md. La lista se actualiza cada vez que se añade una dependencia al producto distribuible.