Kivgraph

Kivgraph ist ein lokaler repository-übergreifender Code-Intelligence-MCP-Server für KI-Codierungsagenten. Er erstellt einen kanonischen semantischen Codegraphen über mehrere registrierte Repositories hinweg und beantwortet Fragen zu Symbolen, Repository-Beziehungen, Aufrufern, Abhängigkeiten und Änderungsauswirkungen.

Er indexiert ein Korpus einmal und bedient einen unveränderlichen Graphen: Die Kanten werden von go/types, dem TypeScript-Checker und rust-analyzer aufgelöst, nicht durch Namensabgleich. Das ist der Unterschied zu einem Suchwerkzeug, und genau das macht eine leere Antwort wertvoll – eine leere Referenzliste bedeutet niemand ruft es auf, nicht dass nichts gefunden wurde, und grep kann diese Fälle nicht unterscheiden.

Kivgraph konzentriert sich auf semantische Codebeziehungen, nicht auf die automatische Erkennung jedes HTTP-, gRPC-, Kafka- oder Datenbank-Laufzeitflusses zwischen Diensten.

Dokumentation

Lesen Sie die Kivgraph-Benutzerdokumentation für Installation, MCP-Clients, Code-Intelligenz, Repository-Beziehungen und Workspace-Codegraphen. Die veröffentlichte Website wird getrennt vom Release-Bundle konfiguriert; dieser Link bleibt in jedem Checkout gültig.

Related MCP server: MCP Indexer

Was jedes Werkzeug beantwortet

Zehn schreibgeschützte Werkzeuge, plus eine zustimmungspflichtige Mutation (index_project), die ein Client autorisieren muss, bevor er ein Repository registrieren oder eine Generation veröffentlichen kann.

Jede Zeile, die ein Symbol nennt, enthält Repository, Pfad, qualifizierten Namen und Zeilenbereich, sodass es ohne einen zweiten Aufruf geöffnet werden kann, und jedes Werkzeug akzeptiert dieses Tripel anstelle eines undurchsichtigen Schlüssels.

Wo es verliert. Ein seltener Name in einem kleinen Repository ist mit grep billiger, und das Indexieren einer kleinen Datei kostet mehr als das Lesen. Es gewinnt bei häufigen Namen, bei transitiven Auswirkungen, bei Konsumenten in einem anderen Repository und beim Nachweis einer Abwesenheit. Gemessen über 29 Fragen an einem Korpus aus 37 Repositories (benchmarks/graph-tools-comparison/results-all.json, Commit 954b9eb, Tokenizer o200k_base): 35,961 Token für Kivgraph gegenüber 267,980 für grep plus Lesen, beide bei 28 der 29 exakt, Median 5.95x pro Frage zugunsten von Kivgraph. grep ist bei 5 dieser 29 billiger, alle mit vollständigem Recall auf beiden Seiten: T1_go_trivial fragt nach einem Namen, den das Korpus zweimal deklariert, und dort kostet grep 0.53x dessen, was Kivgraph kostet.

Ein zweiter Prüfstand, benchmarks/mcp-token-cost, vergleicht mit der wörtlich erfassten eigenen Werkzeugausgabe des Hosts, läuft aber auf Kivgraphs eigenem einzelnen Repository mit 13.222 Symbolen: 7.64x bei den Antworten selbst und 1.60x über eine ganze Sitzung, gegenüber einer 2.41x-Untergrenze, die durch die Quelltexte gesetzt wird, die beide Seiten bezahlen.

Status

Veröffentlicht und im Einsatz. kivgraph version meldet die veröffentlichte Version; das Backlog und das Abnahmekriterium jeder Phase stehen in TASKS.md.

• Sprachen: Go, TypeScript, Rust, Python und Dart. Python verwendet den gebündelten AST-Worker im Fallback-Modus; diese abgeleiteten Referenzen sind CANDIDATE, nie EXACT. Der exakte Python-Modus verwendet den gebündelten Pyright-LSP-Adapter mit einem installierten Pyright/BasedPyright-Server. Dart verwendet den Dart Analysis Server aus dem Dart- oder Flutter-SDK.

• Semantische Abhängigkeiten: Python- und Dart-Importe können eine Paketabhängigkeit veröffentlichen, wenn genau ein registrierter Anbieter das angefragte Paket besitzt; symbolübergreifende Cross-Repository-Kanten erfordern eine explizite Anbieteridentität.

• Oberfläche: zehn schreibgeschützte Werkzeuge über STDIO, plus eine zustimmungspflichtige Mutation (index_project). Der Vertrag ist docs/protocol/mcp-surface-v3.md.

• Speicherung: LadybugDB ist kanonisch; Abfragen werden aus einem unveränderlichen HotSnapshot bedient, der atomar veröffentlicht wird, nie aus der Datenbank.

• Plattformen: linux/amd64, darwin/arm64 und windows/amd64.

• Viewer: kivgraph ui bedient eine schreibgeschützte 3D-Ansicht des veröffentlichten Graphen.

Voraussetzungen

• Go 1.26 oder neuer, um aus dem Quellcode zu bauen. Der Indexer führt die Typprüfung mit dem in die Binärdatei eingebundenen go/types durch und kann daher nur Repositories und Abhängigkeiten lesen, die für seine eigene Sprachversion oder älter geschrieben wurden; kivgraph doctor meldet diese Obergrenze.

• Zum Indexieren von Rust werden cargo und rust-analyzer benötigt. Das Release-Bundle enthält den Analyzer; es enthält keine Rust-Toolchain.

• Zum Indexieren von TypeScript wird Node.js 22 oder neuer für den Worker benötigt.

• Zum Indexieren von Python wird Python 3.10 oder neuer für den gebündelten Worker benötigt. Es ist ein syntaxbewusster Fallback und meldet dynamische oder unaufgelöste Namen explizit; der exakte Modus erfordert zusätzlich einen Pyright-kompatiblen Sprachserver.

• Zum Indexieren von Dart wird die ausführbare Datei dart benötigt; eine Flutter-Installation liefert sie. Der Loader verwendet das Analysis-Server-Protokoll und verändert das Flutter-Projekt nicht.

Installation

Den MCP mit einem Skript installieren

Das Installationsprogramm erkennt die Plattform, lädt das neueste veröffentlichte MCP-Release dafür herunter, verifiziert sowohl das Release-Archiv als auch die Bundle-Prüfsummen und installiert es ohne Go oder pnpm. Das Release enthält den Go-Server, die festgepinnte LadybugDB-Bibliothek, den TypeScript-Worker, den gebündelten Python-AST-Worker, den festgepinnten rust-analyzer, das Grammatik-Manifest und den Web-Viewer, dessen Assets 2,3 MB des Bundles ausmachen. scripts/build-bundle.sh --mcp-only erzeugt für alle, die es möchten, ein Bundle ohne den Viewer.

Veröffentlichte Bundles: Linux amd64 und macOS arm64.

Laufzeitvoraussetzungen: Bash, Node.js 22 oder neuer, Python 3.10 oder neuer beim Indexieren von Python, curl, tar und sha256sum oder shasum. Das Bundle enthält sein eigenes rust-analyzer; zum Indexieren von Rust-Repositories wird zusätzlich cargo im PATH benötigt, und zum Indexieren von Dart wird das Dart- oder Flutter-SDK benötigt.

Unter macOS sind die Binärdateien nicht notarisiert. Ein mit curl heruntergeladenes Release ist nicht quarantänisiert und läuft; eine mit einem Browser heruntergeladene Kopie benötigt xattr -dr com.apple.quarantine. Siehe docs/development/macos.md.

Installieren Sie das neueste Release mit einem Befehl:

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

Von einem Checkout aus kann dasselbe Installationsprogramm direkt ausgeführt werden:

./scripts/install.sh

Um ein bestimmtes Release anstelle des neuesten zu installieren:

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

Das Skript installiert das Bundle in ~/.local/opt/kivgraph und legt Starter in ~/.local/bin ab. Es verändert nie ein registriertes Repository, erstellt keinen Index und ersetzt keine Konfigurationsdateien. Um einen anderen Speicherort zu verwenden, setzen Sie KIVGRAPH_INSTALL_ROOT und KIVGRAPH_BIN_DIR.

Fügen Sie das Starter-Verzeichnis zur aktuellen Shell hinzu und überprüfen Sie beide Laufzeiten:

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

Prüfen Sie auf ein neueres Release oder aktualisieren Sie das installierte Bundle:

kivgraph update --check
kivgraph update

Das Update ist atomar, bewahrt die Konfiguration und den Graphzustand, verifiziert die Release- und Bundle-Prüfsummen und ersetzt nur das installierte Bundle. Starten Sie den MCP-Client nach dem Update neu, damit er die neue Binärdatei startet.

Wenn kivgraph ohne Befehl aus einem interaktiven Terminal aufgerufen wird, prüft es mit einem Timeout von 800 ms und einem 24-Stunden-Cache im Plattform-Cache-Verzeichnis ($XDG_CACHE_HOME unter Linux und $HOME/Library/Caches unter macOS) unter kivgraph/update-check.json auf ein neueres Release. Die optionale Prüfung blockiert den Befehl nie, wenn das Netzwerk nicht verfügbar ist.

Die interaktive Befehlsausgabe verwendet semantische ANSI-Farben, wenn das Ziel ein Terminal ist. Setzen Sie NO_COLOR oder leiten Sie die Ausgabe um, um sie schlicht zu halten.

Einen MCP-Client konfigurieren und das Skill installieren

Das Release-Installationsprogramm bearbeitet die Client-Konfiguration nicht automatisch. Führen Sie nach der Installation von Kivgraph die Integrationsbefehle ohne --target aus, um die auf diesem Rechner vorhandenen Codierungsagenten zu erkennen und einen oder mehrere davon auszuwählen:

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

Kivgraph prüft die bekannten lokalen Konfigurations- oder Installationswurzeln jedes Clients und markiert erkannte Agenten. Verwenden Sie ↑/↓ (oder j/k) zum Bewegen, Leertaste zum Umschalten eines Agenten, a zum Auswählen aller, n zum Auswählen keines, Enter zum Bestätigen und q oder Esc zum Abbrechen. Wenn keiner erkannt wird, startet der Selektor ohne ausgewählte Agenten. Verwenden Sie --target nur für skriptgesteuerte, nicht-interaktive Installationen.

Unterstützte MCP-Ziele sind claude-code, claude-desktop, codex, opencode und oh-my-pi. Unterstützte Skill-Ziele sind claude-code, codex, opencode und oh-my-pi; Claude Desktop hat kein lokales Skill-Ziel. Der Standardbereich ist user; verwenden Sie --scope project für projektlokale Konfiguration. Verwenden Sie --dry-run, um einen Plan ohne Schreiben zu prüfen. Vorhandene inkompatible Einträge stoppen mit einem Fehler; --force ist erforderlich, um einen zu ersetzen oder zu entfernen. Vorhandene Dateien werden atomar mit Modus 0600 geschrieben und erhalten vor dem Ersetzen oder Entfernen ein *.kivgraph.bak-Backup.

Eine Registrierung explizit anzeigen oder entfernen:

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

Initialisieren und veröffentlichen Sie einen Graphen, bevor Sie den MCP-Server starten:

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

init schreibt eine eigenständige Konfiguration: Wenn --config auf ein anderes Verzeichnis zeigt, hängen Zustand, Cache und Registry an diesem Verzeichnis, sodass ein Wegwerf-Index nie den echten berührt. index --full veröffentlicht atomar neu – ein Fehler in jeder Phase lässt die vorherige Generation weiter bedienen. Ein bereits laufender Server folgt der neuen Generation von selbst.

Im Alltag:

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 bindet standardmäßig eine Nicht-Loopback-Adresse, weil der Graph dort indexiert wird, wo die Repositories liegen, und von anderswo betrachtet wird; es gibt keine Authentifizierung, daher protokolliert es genau, was es offenlegt, und --addr schränkt es ein.

logs und tool-stats lesen einen Append-only-Datensatz im Zustandsverzeichnis, statt einen Server zu fragen, weshalb sie überhaupt antworten können: Die Pro-Werkzeug-Zähler, die ein serve führt, werden beim Start erzeugt und sind beim Stoppen verschwunden. Das Lesen der Datei lässt die Antwort außerdem jeden Server umfassen, der je gelaufen ist.

Konfigurieren Sie einen beliebigen MCP-Client, um den Server über STDIO zu starten:

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

kivgraph serve startet, bevor ein Graph existiert: Ohne veröffentlichte Generation schließt es den Handshake ab, veröffentlicht kein Abfragewerkzeug und legt den Rebuild-Befehl in instructions ab. Ein Client startet den Prozess selbst, sodass ein Beenden wie ein Absturz wirken würde. Es schreibt MCP-Framing ausschließlich nach stdout und protokolliert nach stderr.

Was der Graph trägt und was er ablehnt

Eine Kante ist nur mit ausreichenden Belegen und der richtigen Herkunft EXACT. Sie wird nie aus einem Namen, einem Pfad, einem Alias oder einem einzelnen Kandidaten erzeugt, und eine Referenz, die nicht aufgelöst werden kann, wird als UNRESOLVED mit Grund, Repository und Sprache veröffentlicht, statt verworfen zu werden. graph_status meldet beides, aufgeschlüsselt.

Deshalb sind manche Antworten Abwesenheiten statt Kanten. Mit indexierter Rust-Standardbibliothek wird impl Add for u32 von einem Makro erzeugt und existiert in keinem Quellbereich, daher wird jede Verwendung davon einmal pro Symbol als PROVIDER_DEFINITION_NOT_INDEXED deklariert, statt zu einer Kante zu werden, die niemand öffnen könnte.

Die Anbieter, die Kivgraph von der Maschine ableitet – heute die Rust-Standardbibliothek, benannt rust:1.96.1 nach der Toolchain – werden standardmäßig aus Leseergebnissen zurückgehalten: Eine Toolchain umfasst etwa zwanzigtausend Symbole, und eine Suche nach Clone würde mit core antworten. include_derived fragt nach ihnen, und graph_status schlüsselt auf, was sie beitragen, damit die Summen lesbar bleiben.

Entwicklung

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

make test-ladybug ist die einzige unterstützte Möglichkeit, das Tag auszuführen, das die festgelegte native Bibliothek linkt. Die Beitragskonventionen sind in AGENTS.md festgehalten, auf das CLAUDE.md verlinkt.

make semantic-coverage ist das Release-Gate für Go, TypeScript, Python und Dart. Es validiert die maschinenlesbare Matrix in testdata/semantic-coverage/manifest.json, führt die exakten TypeScript-, Go- und Dart-Suiten aus und erfordert einen Pyright-kompatiblen Language Server für die exakte Python-Suite. Eine Sprache gilt nicht als vollständig, wenn eine Fähigkeit zwar eine Fixture, aber keinen ausführbaren Regressionstest besitzt.

Speicher- und Graph-Benchmarks

Die LadybugDB-Qualifizierung, der Generator für synthetische Korpora, die Last- und Abfrage-Benchmarks sowie die Befehle doctor, rebuild, rollback und snapshot sind in docs/development/storage-benchmarks.md dokumentiert. Die Dokumentation endet mit ACCEPT_LADYBUGDB_WITH_LIMITS.

Die öffentliche Website

landing/ enthält die Landing Page und die Benutzerdokumentation. Es wird in keinem Release-Bundle ausgeliefert, mit make landing-check und make landing-build verifiziert und auf Port 6767 bereitgestellt. Was es veröffentlicht, wie die MCP-Referenz erfasst wurde und was noch offen ist, ist in docs/development/landing-site.md festgehalten.

Struktur

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.

Lizenz

Kivgraph wird unter der Apache License 2.0 vertrieben.

Lizenzen Dritter

Hinweise und Lizenzen für Abhängigkeiten, die mit Kivgraph vertrieben werden, sind in THIRD_PARTY_NOTICES.md festgehalten. Die Liste wird aktualisiert, sobald eine Abhängigkeit zum verteilbaren Produkt hinzugefügt wird.