Kivgraph

Servidor MCP local de código abierto para agentes de codificación con descubrimiento de código basado en intención, relaciones resueltas por analizador y navegación entre repositorios.

GitHub
22

Documentación

Kivgraph

kivgraph MCP server

[!NOTE] Kivgraph comenzó como un proyecto de investigación. Exploraba si un grafo de código semántico local podría reducir la cantidad de contexto que los agentes de codificación necesitan inspeccionar.

La herramienta resultante sigue siendo útil para la navegación estructurada de código, las relaciones entre repositorios y el análisis de impacto. Sin embargo, la investigación no demostró un ahorro neto fiable de tokens en conversaciones largas de extremo a extremo con agentes. Aunque algunas consultas aisladas pueden usar sustancialmente menos tokens que grep más lecturas de archivos, esos ahorros no se tradujeron de manera consistente en un menor uso de tokens en flujos de trabajo realistas de agentes de larga duración.

Los resultados de las pruebas comparativas y sus limitaciones se conservan en benchmarks/, incluida la prueba comparativa de agentes de extremo a extremo.

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 en múltiples repositorios registrados y responde preguntas sobre símbolos, relaciones entre repositorios, llamadores, dependencias e impacto de cambios.

Kivgraph graph viewer preview

Ver el video de demostración de la interfaz de Kivgraph

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 coincidiendo 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 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, 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 todavía tiene.

Qué responde cada herramienta

la preguntala herramienta
quién llama a esto, qué referencia a estofind_references
quién implementa un tipo o métodofind_implementations
qué se rompe si lo cambioget_blast_radius
qué alcanza esto hacia afueratrace_dependencies
quién lo usa desde otro repositoriofind_cross_repo_consumers
dónde está declaradofind_symbol
no sé cómo se llama, qué archivos abrirfind_by_intent
qué está declarado en este paqueteget_file_outline
dame el código de estos símbolosget_source
todo sobre este símbologet_symbol
qué está indexado y si el grafo está actualizadolist_repositories, graph_status
cómo progresa una indexación asíncronaget_index_status

Trece herramientas de solo lectura, más dos mutaciones con consentimiento (index_project y start_index_project) que un cliente debe autorizar antes de que cualquiera pueda 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, por lo que se puede abrir 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 herramienta del propio 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 brazos 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 Servidor de Análisis de Dart 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 posee el paquete solicitado; las aristas entre repositorios a nivel de símbolo requieren una identidad de proveedor explícita.
  • Superficie: trece herramientas de solo lectura sobre STDIO, más dos mutaciones con consentimiento (index_project y start_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

Instalar el MCP con un 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 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 paquete. scripts/build-bundle.sh --mcp-only produce un paquete sin el visor para quien lo desee. --slim va más allá para cualquiera que empaquete un .mcpb: omite el rust-analyzer fijado y cada símbolo que un depurador leería, que es 46.3 MB empaquetado frente a 24.9 MB. No descarga nada más tarde, por lo que ese paquete lee Rust solo donde la máquina ya tiene un analizador en su PATH.

Paquetes publicados: Linux amd64, macOS arm64 y Windows amd64.

Requisitos de ejecución: Bash en Linux y macOS o PowerShell 5.1 o posterior en Windows, Node.js 22 o posterior, Python 3.10 o posterior al indexar Python, y en las plataformas POSIX curl, tar y sha256sum o shasum. El paquete 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 Windows el instalador también instala el redistribuible de Visual C++, sin el cual kivgraph.exe no se inicia.

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 en un comando. En Linux y macOS la misma línea cubre ambos, porque el instalador lee uname y elige su propio archivo:

curl -fsSL https://kivgraph.dev/install.sh | bash

En Windows, donde install.sh no puede ejecutarse porque no hay shell POSIX:

irm https://kivgraph.dev/install.ps1 | iex

install.ps1 es una segunda implementación de las mismas comprobaciones previas a la extracción, y internal/release/install_parity_test.go falla cuando cualquiera de los scripts agrega una comprobación que el otro no tiene. Canalizarlo hacia Invoke-Expression convierte su #Requires -Version 5.1 en un comentario; descárguelo a un archivo y ejecútelo como uno solo para mantener esa protección.

Desde un checkout, cualquiera de los instaladores se puede ejecutar directamente:

./scripts/install.sh

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

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

El script instala el paquete en ~/.local/opt/kivgraph y coloca los lanzadores en ~/.local/bin; en Windows es %LOCALAPPDATA%\Programs\kivgraph y %LOCALAPPDATA%\Programs\kivgraph-bin. Nunca modifica un repositorio registrado, crea un índice ni reemplaza archivos de configuración. Para usar una ubicación diferente, establezca KIVGRAPH_INSTALL_ROOT y KIVGRAPH_BIN_DIR.

Agregue el directorio de lanzadores al shell actual y verifique ambos tiempos 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

El reemplazo del paquete es atómico, conserva la configuración y el estado del grafo, verifica las sumas de verificación de la versión y del paquete, y reemplaza el paquete instalado. La actualización del tiempo de ejecución posterior a la instalación puede completarse parcialmente, fallar y hacer que el comando salga con un código distinto de cero. También reinicia un daemon supervisado instalado y actualiza los hooks de usuario, habilidades y registros MCP gestionados por Kivgraph. Un supervisor obsoleto devuelve un error y no se reinicia. Las integraciones faltantes, externas y de ámbito de proyecto se dejan intactas. Los procesos serve y ui propiedad del cliente aún necesitan un reinicio, o --stop, para usar el nuevo binario.

Las compilaciones de desarrollo usan un canal de prelanzamiento separado. Instale una explícitamente, luego seleccione ese canal para comprobaciones posteriores:

release=vX.Y.Z-dev.N
curl -fsSL \
  "https://github.com/Luqueee/kivgraph/releases/download/$release/install.sh" |
  KIVGRAPH_VERSION="$release" bash
kivgraph update --channel dev

Para un binario de prelanzamiento, omitir --channel ya sigue a dev; las instalaciones estables continúan siguiendo el canal estable. KIVGRAPH_UPDATE_CHANNEL se puede usar en lugar de la bandera, incluso para el aviso de actualización interactivo.

Para eliminar el paquete instalado y los lanzadores sin borrar la configuración, los registros de repositorios o el estado del grafo:

uninstall_url=https://github.com/Luqueee/kivgraph/releases/latest/download/uninstall.sh
curl -fsSL "$uninstall_url" -o /tmp/kivgraph-uninstall.sh
bash /tmp/kivgraph-uninstall.sh

Use bash /tmp/kivgraph-uninstall.sh --yes para una eliminación no interactiva. Los usuarios de Windows pueden ejecutar el uninstall.ps1 correspondiente con PowerShell.

Cuando kivgraph se invoca 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), bajo kivgraph/update-check.json. La comprobación opcional nunca bloquea el comando cuando la red no está disponible.

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

Configurar Kivgraph y sus agentes de codificación

Después de una instalación interactiva de la versión, el instalador pregunta si debe ejecutar esta misma configuración guiada. Ejecútela más tarde, o ejecútela directamente desde un checkout:

kivgraph configure

configure abre un selector para los agentes de codificación detectados en esta máquina e instala cada superficie de ámbito de usuario que el agente seleccionado soporta. También agrega instrucciones de Kivgraph a nivel de usuario para cada agente seleccionado. Inicializa la configuración vacía de Kivgraph cuando es necesario, pero no registra un repositorio ni ejecuta un índice. Repita --target TARGET para una configuración mediante script; omítalo para abrir el selector.

Use ↑/↓ (o j/k) para moverse, space para alternar un agente, a para seleccionar todos, n para seleccionar ninguno, Enter para confirmar y q o Esc para cancelar. El daemon se ofrece una vez después de la selección; --daemon lo requiere sin preguntar y --stdio mantiene un proceso serve por cliente. --dry-run previsualiza cada superficie sin escribir. Los objetivos MCP compatibles son claude-code, claude-desktop, codex, opencode, y oh-my-pi. Los objetivos de habilidades compatibles son claude-code, codex, opencode, y oh-my-pi; Claude Desktop no tiene un objetivo de habilidades local. Los comandos independientes usan user por defecto; use --scope project para la configuración local del proyecto. Use --dry-run para inspeccionar un plan sin escribirlo. Las entradas incompatibles existentes se detienen con un error; se requiere --force para reemplazar o eliminar una. Los archivos existentes se escriben atómicamente con el modo 0600 y reciben una copia de seguridad *.kivgraph.bak antes del reemplazo o la eliminación.

La compuerta previa al uso de herramientas admite claude-code, claude-desktop, codex, opencode y oh-my-pi. Oh My Pi recibe una extensión nativa en ~/.omp/agent/extensions/ para el ámbito de usuario o .omp/extensions/ para el ámbito de proyecto. La compuerta es de apertura por fallo cuando su consulta de grafo no puede responderse. Las búsquedas envueltas como rtk rg ... o rtk proxy rg ... se clasifican por su comando interno, mientras que los comandos propios de RTK se dejan intactos.

Agregar Kivgraph a las instrucciones del agente de usuario

Agregue las reglas de navegación de Kivgraph al contexto de usuario cargado por un agente de codificación:

kivgraph instructions install
# The selector can install one or more coding-agent destinations.
kivgraph instructions install --agent codex
kivgraph instructions install --agent claude
kivgraph instructions install --agent omp

Sin --agent ni --file, el selector interactivo le permite elegir uno o más agentes de codificación. Cada instalación posee un mensaje KIVGRAPH.md junto a la configuración del cliente. Codex (~/.codex/AGENTS.md), Claude Code/Desktop (~/.claude/CLAUDE.md) y Oh My Pi (~/.omp/agent/AGENTS.md) reciben solo una pequeña referencia administrada de ruta absoluta a KIVGRAPH.md. OpenCode, en cambio, agrega su ruta canónica a la lista nativa instructions de ~/.config/opencode/opencode.json; no modifica el AGENTS.md de OpenCode. El selector deduplica los destinos compartidos. Las instrucciones existentes se conservan, la referencia administrada es idempotente y --dry-run previsualiza el cambio. Un mensaje o referencia de Kivgraph editado requiere --force para reemplazarlo. --file se conserva por compatibilidad y selecciona cada cliente global coincidente; prefiera --agent para la nueva automatización. El comando nunca cambia las instrucciones del repositorio. Use configure cuando quiera estas instrucciones y las integraciones de cliente compatibles en un solo flujo; los comandos individuales permanecen disponibles para cambios explícitos.

Cuando se establece, CODEX_HOME reemplaza a ~/.codex y PI_CODING_AGENT_DIR reemplaza a ~/.omp/agent, coincidiendo con las raíces de configuración que usan esos clientes.

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
kivgraph hook status --target claude-code --scope user
kivgraph hook 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, por lo que un índice descartable nunca toca el real. index --full republica atómicamente: una falla en cualquier etapa deja la generación anterior en servicio. Un servidor que ya está en ejecución sigue la nueva generación por sí mismo.

Cuando está dentro de un proyecto, kivgraph index detecta sus lenguajes compatibles, crea o reutiliza .kivgraph/, registra el proyecto actual como project en su registro local y ejecuta la misma reconstrucción completa. Sin --config ni --repositories, no altera el registro de usuario compartido; esas anulaciones seleccionan intencionalmente la configuración y el registro a actualizar. Use kivgraph index --full cuando quiera el flujo de trabajo explícito de repositorios registrados; ambas formas conservan el contrato de indexación completa. El comando no instala cadenas de herramientas de lenguaje implícitamente; kivgraph doctor informa cualquier requisito previo que falte en el host. Los analizadores opcionales pueden gestionarse explícitamente mediante Kivgraph:

kivgraph toolchain status
kivgraph toolchain install pyright
kivgraph index --full

toolchain install pyright fija e instala Pyright bajo el estado de Kivgraph, luego activa el análisis exacto de Python en la configuración seleccionada. Para una configuración local de proyecto, pase --config .kivgraph/config.yaml. Eliminarlo requiere una confirmación explícita y restaura la alternativa de Python incluida cuando la configuración seleccionada usa el analizador gestionado:

kivgraph toolchain remove pyright --yes

La primera instalación requiere npm y acceso a la red. Las comprobaciones de estado posteriores y la reutilización de una versión instalada funcionan sin conexión.

La familia de comandos es intencionalmente independiente del lenguaje; más analizadores gestionados pueden usarla sin hacer que index mute el host o un repositorio.

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     # aligned history of what it indexed, served and queried
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 vincula una dirección que no sea de bucle local por defecto, porque el grafo está indexado 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 anexión en el directorio de estado en lugar de preguntar a un servidor, por lo que pueden responder en absoluto: los contadores por herramienta que mantiene un serve se acuñan cuando se inicia y desaparecen cuando se detiene. Leer el archivo también hace que la respuesta abarque todos los servidores que alguna vez se ejecutaron.

logs renderiza una tabla de columnas fijas. Las filas de herramientas incluyen un resumen de consulta acotado y de lista permitida: find_by_intent registra su intent exacto y cualquier keywords, mientras que los cursores opacos, las banderas de consentimiento, las claves estables y las rutas absolutas de proyecto permanecen fuera del registro. --json conserva los registros individuales de solo anexión. SYMBOL_NOT_FOUND se renderiza como el estado neutral NOT_FOUND con cero resultados, no como una falla operativa.

Configure cualquier cliente MCP para iniciar el servidor a través de STDIO:

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

kivgraph serve se inicia antes de que exista un grafo: sin una generación publicada, completa el protocolo de enlace, no publica ninguna herramienta de consulta y coloca el comando de reconstrucción en instructions. Un cliente inicia el proceso por sí mismo, por lo que salir se leería como un bloqueo. Escribe el marco 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 escritas para su propia versión de lenguaje o anterior; kivgraph doctor informa ese límite.
  • Indexar Rust necesita cargo y rust-analyzer. El paquete de lanzamiento incluye el analizador; no incluye una cadena de herramientas 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 una alternativa 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 proporciona. El cargador usa el protocolo del servidor de análisis y no modifica el proyecto Flutter.

Lo que el grafo lleva, y lo que 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 solo candidato, y una referencia que no puede resolverse se publica como UNRESOLVED con su motivo, repositorio y lenguaje en lugar de descartarse. graph_status informa 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 según la cadena de herramientas — se retienen de los resultados de lectura por defecto: 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 compuerta 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.

Almacenamiento y benchmarks de grafos

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/ lleva 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á abierto 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 agrega una dependencia al producto distribuible.