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.

Indexa un corpus una vez y sirve un grafo inmutable: las aristas se resuelven mediante go/types, el comprobador de TypeScript y rust-analyzer, no mediante la 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 haya encontrado nada, y grep no puede distinguir ambas cosas.

Kivgraph se centra en las relaciones semánticas de código, no en el descubrimiento automático de todos los flujos de ejecución HTTP, gRPC, Kafka o de base de datos entre servicios.

Documentación

Lea la documentación de usuario de Kivgraph para la instalación, los clientes MCP, la inteligencia de código, las relaciones entre repositorios y los grafos de código del espacio de trabajo. El sitio publicado se configura por separado del paquete de lanzamiento; este enlace sigue siendo válido desde cualquier clon.

Related MCP server: MCP Indexer

Qué responde cada herramienta

Diez herramientas de solo lectura, más una mutación controlada por 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 incluye su repositorio, ruta, nombre cualificado y rango de líneas, de modo que se puede abrir sin una segunda llamada, y todas las herramientas aceptan ese trío en lugar de una clave opaca.

Dónde pierde. Un nombre poco común en un repositorio pequeño es más barato con grep, e indexar un archivo pequeño cuesta más que leerlo. Gana con nombres comunes, con el impacto transitivo, con los consumidores de otro repositorio y con la demostración de una ausencia. Medido en 29 preguntas sobre 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 ahí grep cuesta 0.53x lo que Kivgraph.

Un segundo banco de pruebas, benchmarks/mcp-token-cost, compara con la salida de las herramientas del propio host capturada textualmente, pero se ejecuta sobre el único repositorio de Kivgraph, de 13,222 símbolos: 7.64x en las respuestas mismas y 1.60x en una sesión completa, frente a un mínimo de 2.41x impuesto por los cuerpos de código fuente que ambas partes pagan.

Estado

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

• Lenguajes: Go, TypeScript, Rust, Python y Dart. Python usa el worker AST incluido en modo de respaldo; esas referencias inferidas son CANDIDATE, nunca EXACT. El modo Python exacto usa el adaptador LSP de Pyright incluido con un servidor Pyright/BasedPyright instalado. Dart usa el Dart Analysis Server proporcionado 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 es el propietario del 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 controlada por 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.

Requisitos

• Go 1.26 o posterior para compilar desde el código fuente. El indexador comprueba tipos con el go/types enlazado en el binario, por lo que solo puede leer repositorios y dependencias escritos para su propia versión de lenguaje o anterior; kivgraph doctor informa de ese límite.

• Indexar Rust necesita cargo y rust-analyzer. El paquete de lanzamiento incluye el analizador; no incluye un toolchain de Rust.

• Indexar TypeScript necesita Node.js 22 o posterior para el worker.

• Indexar Python necesita Python 3.10 o posterior para el worker incluido. Es un modo de respaldo consciente de la sintaxis e informa explícitamente de nombres dinámicos o no resueltos; el modo exacto requiere además un servidor de lenguaje compatible con Pyright.

• Indexar Dart necesita el ejecutable dart; una instalación de Flutter lo proporciona. El cargador usa el protocolo del Analysis Server y no modifica el proyecto Flutter.

Instalación

Instalar el MCP con un solo script

El instalador detecta la plataforma, descarga la última versión MCP publicada para ella, verifica tanto el archivo de la versión como las sumas de verificación del paquete, y lo instala sin requerir Go ni pnpm. La versión contiene el servidor Go, la biblioteca LadybugDB fijada, el worker de TypeScript, el worker AST de Python incluido, el rust-analyzer fijado, el manifiesto de gramáticas y el visor web, cuyos recursos son 2.3 MB del paquete. scripts/build-bundle.sh --mcp-only produce un paquete sin el visor para quien lo quiera.

Paquetes publicados: Linux amd64 y macOS arm64.

Requisitos de ejecución: Bash, Node.js 22 o posterior, Python 3.10 o posterior al indexar Python, curl, tar y sha256sum o shasum. El paquete incluye su propio rust-analyzer; indexar repositorios Rust requiere además 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. Consulte docs/development/macos.md.

Instale la última versión con un solo comando:

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

Desde un clon, el mismo instalador se puede ejecutar directamente:

./scripts/install.sh

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

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

El script instala el paquete 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 otra ubicación, establezca KIVGRAPH_INSTALL_ROOT y KIVGRAPH_BIN_DIR.

Añada el directorio de lanzadores al shell actual y verifique ambos entornos de ejecución:

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

Compruebe si hay una versión más reciente o actualice el paquete instalado:

kivgraph update --check
kivgraph update

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

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

La salida interactiva de los comandos usa colores ANSI semánticos cuando el destino es una terminal. Establezca NO_COLOR o redirija la salida para mantenerla sin formato.

Configurar un cliente MCP e instalar la skill

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

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

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

Los objetivos MCP compatibles son claude-code, claude-desktop, codex, opencode y oh-my-pi. Los objetivos de skill compatibles son claude-code, codex, opencode y oh-my-pi; Claude Desktop no tiene objetivo de skill local. El ámbito predeterminado es user; use --scope project para la configuración local al proyecto. Use --dry-run para inspeccionar un plan sin escribir. Las entradas incompatibles existentes detienen con un error; se requiere --force 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.

Inspeccione o elimine 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

Inicialice y publique 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 dependen de ese directorio, de modo que un índice desechable nunca toca el real. index --full republica atómicamente: un fallo en cualquier etapa deja sirviendo a la generación anterior. Un servidor ya en ejecución sigue la nueva generación por sí solo.

En el 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 que no es de loopback por defecto, porque el grafo se indexa donde están los repositorios y se consulta 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 añadir en el directorio de estado en lugar de preguntar a un servidor, que es por lo que pueden responder: los contadores por herramienta que mantiene un serve se crean cuando arranca y desaparecen cuando se detiene. Leer el archivo también hace que la respuesta abarque todos los servidores que hayan ejecutado alguna vez.

Configure 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 arranca 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 fallo. Escribe el encuadre MCP exclusivamente en stdout y los registros en stderr.

Lo que el grafo contiene y lo que rechaza

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 único candidato, y una referencia que no se puede resolver se publica como UNRESOLVED con su motivo, repositorio y lenguaje en lugar de descartarse. graph_status informa de ambos, desglosados.

Por eso 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 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 por el toolchain — se omiten de los resultados de lectura por defecto: un toolchain 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 admitida de ejecutar la etiqueta que enlaza la biblioteca nativa fijada. Las convenciones de contribución están en AGENTS.md, al que enlaza CLAUDE.md.

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 exactamente las suites de TypeScript, Go y Dart, y requiere un servidor de lenguaje compatible con Pyright para ejecutar exactamente la suite de Python. Un lenguaje no se considera completo cuando una capacidad tiene un fixture pero no una prueba de regresión ejecutable.

Pruebas de referencia de almacenamiento y grafos

La cualificación de LadybugDB, el generador de corpus sintético, las pruebas de referencia 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 aterrizaje y la documentación de usuario. No se distribuye 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 sigue pendiente están registrados 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 Apache License 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.