Kivgraph

MCP local de código aberto para gráfico de código para agentes de codificação, com descoberta de código baseada em intenção, relacionamentos resolvidos por analisador e navegação entre repositórios.

GitHub
22

Documentação

Kivgraph

kivgraph MCP server

[!NOTE] Kivgraph começou como um projeto de pesquisa. Ele explorou se um grafo de código semântico local poderia reduzir a quantidade de contexto que agentes de codificação precisam inspecionar.

A ferramenta resultante continua útil para navegação estruturada de código, relacionamentos entre repositórios e análise de impacto. No entanto, a pesquisa não demonstrou uma economia líquida confiável de tokens em conversas longas e de ponta a ponta com agentes. Embora algumas consultas isoladas possam usar substancialmente menos tokens do que grep mais leituras de arquivos, essas economias não se traduziram consistentemente em menor uso de tokens em fluxos de trabalho realistas e de longa duração com agentes.

Os resultados dos benchmarks e suas limitações estão preservados em benchmarks/, incluindo o benchmark de agente de ponta a ponta.

Kivgraph é um servidor MCP local de inteligência de código entre repositórios para agentes de codificação de IA. Ele constrói um grafo de código semântico canônico em vários repositórios registrados e responde perguntas sobre símbolos, relacionamentos entre repositórios, chamadores, dependências e impacto de mudanças.

Kivgraph graph viewer preview

Assista ao vídeo de demonstração da interface do Kivgraph

kivgraph ui — visualização 3D somente leitura do grafo publicado.

Ele indexa um corpus uma vez e serve um grafo imutável: as arestas são resolvidas por go/types, o verificador TypeScript e rust-analyzer, não por correspondência de nomes. Essa é a diferença de uma ferramenta de busca, e é o que torna uma resposta vazia algo valioso — uma lista de referências vazia significa que ninguém chama isso, não que nada foi encontrado, e grep não consegue distinguir essas situações.

Kivgraph é focado em relacionamentos semânticos de código, não na descoberta automática de todos os fluxos de tempo de execução HTTP, gRPC, Kafka ou banco de dados entre serviços.

Documentação

Leia a documentação do usuário do Kivgraph para instalação, clientes MCP, inteligência de código, relacionamentos entre repositórios e grafos de código de workspace. As mesmas páginas são a fonte de landing/src/content/docs neste checkout, que é o que um leitor em um fork ou sem rede ainda possui.

O que cada ferramenta responde

a perguntaa ferramenta
quem chama isso, o que referencia issofind_references
quem implementa um tipo ou métodofind_implementations
o que quebra se eu mudar issoget_blast_radius
o que isso alcança para foratrace_dependencies
quem usa isso de outro repositóriofind_cross_repo_consumers
onde isso é declaradofind_symbol
não sei como isso se chama, quais arquivos abrirfind_by_intent
o que é declarado neste pacoteget_file_outline
me dê o código desses símbolosget_source
tudo sobre este único símbologet_symbol
o que está indexado e o grafo está atualizadolist_repositories, graph_status
como está progredindo uma indexação assíncronaget_index_status

Treze ferramentas somente leitura, mais duas mutações com consentimento (index_project e start_index_project) que um cliente precisa autorizar antes que qualquer uma possa registrar um repositório ou publicar uma geração.

Cada linha que nomeia um símbolo carrega seu repositório, caminho, nome qualificado e intervalo de linhas, para que possa ser aberta sem uma segunda chamada, e toda ferramenta aceita essa tríade no lugar de uma chave opaca.

Onde ele perde. Um nome raro em um pequeno repositório é mais barato com grep, e indexar um arquivo pequeno custa mais do que lê-lo. Ele vence em nomes comuns, em impacto transitivo, em consumidores em outro repositório e em provar uma ausência. Medido em 29 perguntas contra um corpus de 37 repositórios (benchmarks/graph-tools-comparison/results-all.json, commit 954b9eb, tokenizador o200k_base): 35,961 tokens para Kivgraph contra 267,980 para grep mais leitura, ambos exatos em 28 das 29, mediana de 5.95x por pergunta a favor de Kivgraph. grep é mais barato em 5 dessas 29, todas com recall total em ambos os lados: T1_go_trivial pede um nome que o corpus declara duas vezes, e lá grep custa 0.53x do que Kivgraph faz.

Um segundo harness, benchmarks/mcp-token-cost, compara com a saída da própria ferramenta do host capturada literalmente, mas roda no repositório único do próprio Kivgraph de 13.222 símbolos: 7.64x nas próprias respostas e 1.60x em uma sessão inteira, contra um piso de 2.41x definido pelos corpos-fonte que ambos os lados pagam.

Status

Lançado e em uso. kivgraph version reporta o lançamento publicado; o backlog e o portão de aceitação de cada fase estão em TASKS.md.

  • Linguagens: Go, TypeScript, Rust, Python e Dart. Python usa o worker AST empacotado em modo de fallback; essas referências inferidas são CANDIDATE, nunca EXACT. O modo Python exato usa o adaptador LSP Pyright empacotado com um servidor Pyright/BasedPyright instalado. Dart usa o Dart Analysis Server fornecido pelo SDK Dart ou Flutter.
  • Dependências semânticas: imports Python e Dart podem publicar uma dependência de pacote quando exatamente um provedor registrado possui o pacote solicitado; arestas entre repositórios no nível de símbolo exigem uma identidade de provedor explícita.
  • Superfície: treze ferramentas somente leitura via STDIO, mais duas mutações com consentimento (index_project e start_index_project). O contrato está em docs/protocol/mcp-surface-v3.md.
  • Armazenamento: LadybugDB é canônico; consultas são servidas de um HotSnapshot imutável publicado atomicamente, nunca do banco de dados.
  • Plataformas: linux/amd64, darwin/arm64 e windows/amd64.
  • Visualizador: kivgraph ui serve uma visualização 3D somente leitura do grafo publicado.

Instalação

Instale o MCP com um script

O instalador detecta a plataforma, baixa o lançamento MCP publicado mais recente para ela, verifica tanto o arquivo de lançamento quanto as somas de verificação do pacote e o instala sem exigir Go ou pnpm. O lançamento contém o servidor Go, a biblioteca LadybugDB fixada, o worker TypeScript, o worker Python AST empacotado, o rust-analyzer fixado, o manifesto de gramática e o visualizador web, cujos ativos são 2,3 MB do pacote. scripts/build-bundle.sh --mcp-only produz um pacote sem o visualizador para quem quiser. --slim vai além para quem empacota um .mcpb: ele deixa de fora o rust-analyzer fixado e todo símbolo que um depurador leria, o que é 46,3 MB empacotados contra 24,9 MB. Ele não baixa nada depois, então esse pacote lê Rust somente onde a máquina já tem um analisador em seu PATH.

Pacotes publicados: Linux amd64, macOS arm64 e Windows amd64.

Requisitos de tempo de execução: Bash no Linux e macOS ou PowerShell 5.1 ou posterior no Windows, Node.js 22 ou posterior, Python 3.10 ou posterior ao indexar Python e, nas plataformas POSIX, curl, tar e sha256sum ou shasum. O pacote carrega seu próprio rust-analyzer; indexar repositórios Rust adicionalmente precisa de cargo no PATH, e indexar Dart precisa do SDK Dart ou Flutter. No Windows, o instalador também instala o redistribuível Visual C++, sem o qual kivgraph.exe não inicia.

No macOS, os binários não são notarizados. Um lançamento baixado com curl não é colocado em quarentena e executa; uma cópia baixada com um navegador precisa de xattr -dr com.apple.quarantine. Veja docs/development/macos.md.

Instale o lançamento mais recente em um comando. No Linux e macOS, a mesma linha cobre ambos, porque o instalador lê uname e escolhe seu próprio arquivo:

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

No Windows, onde install.sh não pode executar porque não há shell POSIX:

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

install.ps1 é uma segunda implementação das mesmas verificações de pré-extração, e internal/release/install_parity_test.go falha quando qualquer script ganha uma verificação que o outro não tem. Canalizá-lo para Invoke-Expression transforma seu #Requires -Version 5.1 em um comentário; baixe-o para um arquivo e execute-o como um para manter essa proteção.

A partir de um checkout, qualquer instalador pode ser executado diretamente:

./scripts/install.sh

Para instalar um lançamento específico em vez do mais recente:

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

O script instala o pacote em ~/.local/opt/kivgraph e coloca lançadores em ~/.local/bin; no Windows é %LOCALAPPDATA%\Programs\kivgraph e %LOCALAPPDATA%\Programs\kivgraph-bin. Ele nunca modifica um repositório registrado, cria um índice ou substitui arquivos de configuração. Para usar um local diferente, defina KIVGRAPH_INSTALL_ROOT e KIVGRAPH_BIN_DIR.

Adicione o diretório de lançadores ao shell atual e verifique ambos os tempos de execução:

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

Verifique se há um lançamento mais recente ou atualize o pacote instalado:

kivgraph update --check
kivgraph update

A substituição do pacote é atômica, preserva a configuração e o estado do grafo, verifica as somas de verificação do lançamento e do pacote e substitui o pacote instalado. A atualização de tempo de execução pós-instalação pode concluir parcialmente, falhar e fazer o comando sair com código não zero. Ela também reinicia um daemon supervisionado instalado e atualiza hooks de usuário, habilidades e registros MCP gerenciados pelo Kivgraph. Um supervisor obsoleto retorna um erro e não é reiniciado. Integrações ausentes, estrangeiras e com escopo de projeto são deixadas em paz. Processos serve e ui de propriedade do cliente ainda precisam de uma reinicialização, ou --stop, para usar o novo binário.

Builds de desenvolvimento usam um canal de pré-lançamento separado. Instale um explicitamente e selecione esse canal para verificações 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 um binário de pré-lançamento, omitir --channel já segue dev; instalações estáveis continuam seguindo o canal estável. KIVGRAPH_UPDATE_CHANNEL pode ser usado em vez da flag, inclusive para o aviso de atualização interativo.

Para remover o pacote instalado e os lançadores sem excluir configuração, registros de repositório ou estado do 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 uma remoção não interativa. Usuários do Windows podem executar o uninstall.ps1 correspondente com PowerShell.

Quando kivgraph é invocado sem um comando de um terminal interativo, ele verifica se há um lançamento mais recente com um tempo limite de 800 ms e um cache de 24 horas no diretório de cache da plataforma ($XDG_CACHE_HOME no Linux e $HOME/Library/Caches no macOS), sob kivgraph/update-check.json. A verificação opcional nunca bloqueia o comando quando a rede está indisponível.

A saída de comando interativa usa cores ANSI semânticas quando o destino é um terminal. Defina NO_COLOR ou redirecione a saída para mantê-la simples.

Configure o Kivgraph e seus agentes de codificação

Após uma instalação de lançamento interativa, o instalador pergunta se deve executar esta mesma configuração guiada. Execute-a depois ou diretamente de um checkout:

kivgraph configure

configure abre um seletor para os agentes de codificação detectados nesta máquina e instala cada superfície com escopo de usuário que o agente selecionado suporta. Ele também adiciona instruções do Kivgraph no nível de usuário para cada agente selecionado. Ele inicializa a configuração vazia do Kivgraph quando necessário, mas não registra um repositório nem executa um índice. Repita --target TARGET para configuração por script; omita-o para abrir o seletor.

Use ↑/↓ (ou j/k) para mover, space para alternar um agente, a para selecionar todos, n para selecionar nenhum, Enter para confirmar e q ou Esc para cancelar. O daemon é oferecido uma vez após a seleção; --daemon o exige sem perguntar e --stdio mantém um processo serve por cliente. --dry-run pré-visualiza cada superfície sem gravar. Os alvos MCP suportados são claude-code, claude-desktop, codex, opencode, e oh-my-pi. Os alvos de habilidade suportados são claude-code, codex, opencode, e oh-my-pi; o Claude Desktop não possui alvo de habilidade local. Os comandos autônomos usam user por padrão; use --scope project para configuração local do projeto. Use --dry-run para inspecionar um plano sem gravar. Entradas incompatíveis existentes param com um erro; --force é necessário para substituir ou remover uma. Os arquivos existentes são gravados atomicamente com o modo 0600 e recebem um backup *.kivgraph.bak antes da substituição ou remoção.

O portão de pré-uso de ferramenta suporta claude-code, claude-desktop, codex, opencode e oh-my-pi. O Oh My Pi recebe uma extensão nativa sob ~/.omp/agent/extensions/ para o escopo do usuário ou .omp/extensions/ para o escopo do projeto. O portão é de abertura automática quando sua consulta de grafo não pode ser respondida. Pesquisas encapsuladas como rtk rg ... ou rtk proxy rg ... são classificadas pelo seu comando interno, enquanto os comandos próprios do RTK são deixados intactos.

Adicionar Kivgraph às instruções do agente do usuário

Adicione as regras de navegação do Kivgraph ao contexto do usuário carregado por um agente de codificação:

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

Sem --agent ou --file, o seletor interativo permite que você escolha um ou mais agentes de codificação. Cada instalação possui um prompt KIVGRAPH.md ao lado da configuração do cliente. Codex (~/.codex/AGENTS.md), Claude Code/Desktop (~/.claude/CLAUDE.md) e Oh My Pi (~/.omp/agent/AGENTS.md) recebem apenas uma pequena referência de caminho absoluto gerenciada para KIVGRAPH.md. O OpenCode, em vez disso, adiciona seu caminho canônico à lista nativa instructions de ~/.config/opencode/opencode.json; ele não modifica o AGENTS.md do OpenCode. O seletor deduplica destinos compartilhados. As instruções existentes são preservadas, a referência gerenciada é idempotente e --dry-run visualiza a alteração. Um prompt ou referência do Kivgraph editado requer --force para substituir. --file é mantido para compatibilidade e seleciona todos os clientes globais correspondentes; prefira --agent para novas automações. O comando nunca altera as instruções do repositório. Use configure quando você quiser essas instruções e as integrações de cliente compatíveis em um único fluxo; os comandos individuais permanecem disponíveis para alterações explícitas.

Quando definido, CODEX_HOME substitui ~/.codex e PI_CODING_AGENT_DIR substitui ~/.omp/agent, correspondendo às raízes de configuração que esses clientes usam.

Inspecione ou remova um registro explicitamente:

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

Inicialize e publique um grafo antes de iniciar o servidor MCP:

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

init grava uma configuração autocontida: com --config apontando para outro lugar, seu estado, cache e registro dependem desse diretório, então um índice descartável nunca toca o real. index --full republica atomicamente — uma falha em qualquer estágio deixa a geração anterior em serviço. Um servidor já em execução segue a nova geração por conta própria.

Quando você está dentro de um projeto, kivgraph index detecta suas linguagens suportadas, cria ou reutiliza .kivgraph/, registra o projeto atual como project em seu registro local e executa a mesma reconstrução completa. Sem --config nem --repositories, ele não altera o registro de usuário compartilhado; essas substituições selecionam intencionalmente a configuração e o registro a serem atualizados. Use kivgraph index --full quando você quiser o fluxo de trabalho explícito de repositórios registrados; ambas as formas preservam o contrato de indexação completa. O comando não instala toolchains de linguagem implicitamente; kivgraph doctor relata qualquer pré-requisito ausente no host. Analisadores opcionais podem ser gerenciados explicitamente pelo Kivgraph:

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

toolchain install pyright fixa e instala o Pyright sob o estado do Kivgraph, então ativa a análise exata de Python na configuração selecionada. Para uma configuração local do projeto, passe --config .kivgraph/config.yaml. Removê-lo requer uma confirmação explícita e restaura o fallback de Python empacotado quando a configuração selecionada usa o analisador gerenciado:

kivgraph toolchain remove pyright --yes

A primeira instalação requer npm e acesso à rede. Verificações de status posteriores e a reutilização de uma versão instalada funcionam offline.

A família de comandos é intencionalmente agnóstica em relação à linguagem; mais analisadores gerenciados podem usá-la sem fazer index mutar o host ou um repositório.

No dia a dia:

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 um endereço não-loopback por padrão, porque o grafo é indexado onde os repositórios estão e visualizado de outro lugar; não há autenticação, então ele registra exatamente o que expõe e --addr o restringe.

logs e tool-stats leem um registro somente de acréscimo no diretório de estado em vez de perguntar a um servidor, que é por que eles podem responder de qualquer forma: os contadores por ferramenta que um serve mantém são cunhados quando ele inicia e desaparecem quando ele para. Ler o arquivo também faz a resposta abranger todos os servidores que já rodaram.

logs renderiza uma tabela de colunas fixas. As linhas de ferramenta incluem um resumo de consulta limitado e na lista de permissões: find_by_intent registra seu intent exato e qualquer keywords, enquanto cursores opacos, sinalizadores de consentimento, chaves estáveis e caminhos absolutos de projeto ficam fora do registro. --json preserva os registros individuais somente de acréscimo. SYMBOL_NOT_FOUND é renderizado como o status neutro NOT_FOUND com zero resultados, não como uma falha operacional.

Configure qualquer cliente MCP para iniciar o servidor via STDIO:

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

kivgraph serve inicia antes de um grafo existir: sem uma geração publicada, ele completa o handshake, não publica nenhuma ferramenta de consulta e coloca o comando de reconstrução em instructions. Um cliente inicia o processo por conta própria, então sair seria lido como uma falha. Ele grava o enquadramento MCP exclusivamente em stdout e registra em stderr.

Requisitos

  • Go 1.26 ou posterior para compilar a partir do código-fonte. O indexador verifica tipos com o go/types vinculado ao binário, então ele só pode ler repositórios e dependências escritos para sua própria versão de linguagem ou mais antiga; kivgraph doctor relata esse teto.
  • Indexar Rust requer cargo e rust-analyzer. O pacote de lançamento carrega o analisador; ele não carrega um toolchain Rust.
  • Indexar TypeScript requer Node.js 22 ou posterior para o worker.
  • Indexar Python requer Python 3.10 ou posterior para o worker empacotado. É um fallback ciente de sintaxe e relata nomes dinâmicos ou não resolvidos explicitamente; o modo exato requer adicionalmente um servidor de linguagem compatível com Pyright.
  • Indexar Dart requer o executável dart; uma instalação Flutter o fornece. O carregador usa o protocolo Analysis Server e não modifica o projeto Flutter.

O que o grafo carrega e o que ele se recusa a carregar

Uma aresta é EXACT apenas com evidência suficiente e a proveniência correta. Ela nunca é criada a partir de um nome, caminho, alias ou um único candidato, e uma referência que não pode ser resolvida é publicada como UNRESOLVED com seu motivo, repositório e linguagem em vez de ser descartada. graph_status relata ambos, detalhados.

É por isso que algumas respostas são ausências em vez de arestas. Com a biblioteca padrão Rust indexada, impl Add for u32 é gerado por uma macro e não existe em nenhum intervalo de código-fonte, então cada uso dele é declarado PROVIDER_DEFINITION_NOT_INDEXED uma vez por símbolo em vez de se tornar uma aresta que ninguém poderia abrir.

Os provedores que o Kivgraph deriva da máquina — hoje a biblioteca padrão Rust, nomeada rust:1.96.1 após o toolchain — são retidos dos resultados de leitura por padrão: um toolchain tem cerca de vinte mil símbolos, e uma busca por Clone responderia com core. include_derived os solicita, e graph_status detalha o que eles contribuem para que os totais permaneçam legíveis.

Desenvolvimento

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

make test-ladybug é a única maneira suportada de executar a tag que vincula a biblioteca nativa fixada. As convenções de contribuição estão em AGENTS.md, que CLAUDE.md vincula.

make semantic-coverage é o portão de lançamento para Go, TypeScript, Python e Dart. Ele valida a matriz legível por máquina em testdata/semantic-coverage/manifest.json, executa as suítes exatas de TypeScript, Go e Dart, e requer um servidor de linguagem compatível com Pyright para a suíte exata de Python. Uma linguagem não é considerada completa quando uma capacidade tem um fixture, mas nenhum teste de regressão executável.

Benchmarks de armazenamento e grafo

A qualificação LadybugDB, o gerador de corpus sintético, os benchmarks de carga e consulta, e os comandos doctor, rebuild, rollback e snapshot são documentados em docs/development/storage-benchmarks.md. Ele conclui com ACCEPT_LADYBUGDB_WITH_LIMITS.

O site público

landing/ carrega a página inicial e a documentação do usuário. Ele não é enviado em nenhum pacote de lançamento, é verificado com make landing-check e make landing-build, e é servido na porta 6767. O que ele publica, como a referência MCP foi capturada e o que ainda está aberto são registrados em docs/development/landing-site.md.

Estrutura

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.

Licença

O Kivgraph é distribuído sob a Apache License 2.0.

Licenças de terceiros

Avisos e licenças para dependências distribuídas com o Kivgraph são registrados em THIRD_PARTY_NOTICES.md. A lista é atualizada sempre que uma dependência é adicionada ao produto distribuível.