Kivgraph

Kivgraph

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.

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

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 em relação a uma ferramenta de busca, e é o que torna uma resposta vazia algo valioso — uma lista de referências vazia significa 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 runtime HTTP, gRPC, Kafka ou banco de dados entre serviços.

Documentação

Leia a documentação do usuário 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 pergunta	a ferramenta
quem chama isso, o que referencia isso	find_references
o que quebra se eu mudar isso	get_blast_radius
o que isso alcança externamente	trace_dependencies
quem usa isso de outro repositório	find_cross_repo_consumers
onde isso é declarado	find_symbol
o que é declarado neste pacote	get_file_outline
me dê o código desses símbolos	get_source
tudo sobre este símbolo	get_symbol
o que está indexado, e o grafo está atualizado	list_repositories, graph_status

Dez ferramentas somente leitura, mais uma mutação com consentimento (index_project) que um cliente precisa autorizar antes de 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 cada 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 5.95x por pergunta a favor de Kivgraph. grep é mais barato em 5 dessas 29, todas com recall completo em ambos os lados: T1_go_trivial pede um nome que o corpus declara duas vezes, e lá grep custa 0.53x o que Kivgraph faz.

Um segundo harness, benchmarks/mcp-token-cost, compara contra 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 embutido em modo fallback; essas referências inferidas são CANDIDATE, nunca EXACT. O modo Python exato usa o adaptador LSP Pyright embutido 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: dez ferramentas somente leitura sobre STDIO, mais uma mutação com consentimento (index_project). O contrato é 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 bundle, e 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 embutido, o rust-analyzer fixado, o manifesto de gramática e o visualizador web, cujos ativos são 2,3 MB do bundle. scripts/build-bundle.sh --mcp-only produz um bundle 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, que é 46,3 MB empacotado contra 24,9 MB. Ele não baixa nada depois, então esse bundle lê Rust apenas onde a máquina já tem um analisador em seu PATH.

Bundles publicados: Linux amd64 e macOS arm64.

Requisitos de runtime: Bash, Node.js 22 ou posterior, Python 3.10 ou posterior ao indexar Python, curl, tar, e sha256sum ou shasum. O bundle 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 macOS os binários não são notarizados. Um lançamento baixado com curl não é colocado em quarentena e roda; 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:

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

De um checkout, o mesmo instalador pode ser executado diretamente:

./scripts/install.sh

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

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

O script instala o bundle em ~/.local/opt/kivgraph e coloca lançadores em ~/.local/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 runtimes:

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 bundle instalado:

kivgraph update --check
kivgraph update

A atualização é atômica, preserva a configuração e o estado do grafo, verifica as somas de verificação do lançamento e do bundle, e substitui apenas o bundle instalado. Reinicie o cliente MCP após atualizar para que ele inicie o novo binário.

Quando kivgraph é invocado sem um comando de um terminal interativo, ele verifica se há um lançamento mais recente com um timeout 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 interativa do comando usa cores ANSI semânticas quando o destino é um terminal. Defina NO_COLOR ou redirecione a saída para mantê-la simples.

Configure um cliente MCP e instale a skill

O instalador de lançamento não edita a configuração do cliente automaticamente. Após instalar Kivgraph, execute os comandos de integração sem --target para detectar os agentes de codificação presentes nesta máquina e selecione um ou mais deles:

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

Kivgraph verifica as raízes de configuração ou instalação locais conhecidas de cada cliente e marca os agentes detectados. 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. Se nenhum for detectado, o seletor inicia sem agentes selecionados. Use --target apenas para instalação não interativa via script.

Os alvos MCP suportados são claude-code, claude-desktop, codex, opencode, e oh-my-pi. Os alvos de skill suportados são claude-code, codex, opencode, e oh-my-pi; Claude Desktop não tem alvo de skill local. O escopo padrão é user; use --scope project para configuração local do projeto. Use --dry-run para inspecionar um plano sem escrever. Entradas incompatíveis existentes param com um erro; --force é necessário para substituir ou remover uma. Arquivos existentes são escritos atomicamente com modo 0600 e recebem um backup *.kivgraph.bak antes da substituição ou remoção.

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

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 escreve 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 servindo. Um servidor já em execução segue a nova geração por conta própria.

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     # 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 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 anexação no diretório de estado em vez de perguntar a um servidor, que é por que eles conseguem responder: os contadores por ferramenta que um serve mantém são cunhados quando ele inicia e somem quando para. Ler o arquivo também faz a resposta abranger todos os servidores que já rodaram.

Configure qualquer cliente MCP para iniciar o servidor sobre 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 ele mesmo, então sair seria lido como um crash. Ele escreve enquadramento MCP exclusivamente para stdout e registra em stderr.

Requisitos

• Go 1.26 ou posterior para compilar 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 reporta esse teto.
• Indexar Rust precisa de cargo e rust-analyzer. O bundle de lançamento carrega o analisador; ele não carrega um toolchain Rust.
• Indexar TypeScript precisa de Node.js 22 ou posterior para o worker.
• Indexar Python precisa de Python 3.10 ou posterior para o worker embutido. É um fallback ciente de sintaxe e reporta nomes dinâmicos ou não resolvidos explicitamente; o modo exato adicionalmente requer um servidor de linguagem compatível com Pyright.
• Indexar Dart precisa do 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

Uma aresta é EXACT apenas com evidência suficiente e a proveniência certa. Ela nunca é criada a partir de um nome, um caminho, um alias ou um único candidato, e uma referência que não pode ser resolvida é publicada como UNRESOLVED com sua razão, repositório e linguagem em vez de ser descartada. graph_status reporta ambos, detalhados. É por isso que algumas respostas são ausências em vez de arestas. Com a biblioteca padrão do 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 conseguiria abrir.

Os provedores que o Kivgraph deriva da máquina — hoje a biblioteca padrão do Rust, nomeada rust:1.96.1 após o toolchain — são omitidos 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 forma suportada de executar a tag que vincula a biblioteca nativa fixada. As convenções de contribuição estão em AGENTS.md, ao qual CLAUDE.md faz referência.

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 exige 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 estã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 acompanha 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 do MCP foi capturada e o que ainda está em aberto estã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 estão registrados em THIRD_PARTY_NOTICES.md. A lista é atualizada sempre que uma dependência é adicionada ao produto distribuível.