Kivgraph

Kivgraphは、AIコーディングエージェント向けのローカルなクロスリポジトリコードインテリジェンスMCPサーバーです。複数の登録済みリポジトリにわたって正規のセマンティックコードグラフを構築し、シンボル、リポジトリ間の関係、呼び出し元、依存関係、変更影響に関する質問に答えます。

コーパスを一度インデックス化し、不変のグラフを提供します。エッジはgo/types、TypeScriptチェッカー、rust-analyzerによって解決され、名前の一致によるものではありません。これが検索ツールとの違いであり、空の回答に価値をもたらす理由です。空の参照リストは誰も呼び出していないことを意味し、何も見つからなかったわけではありません。grepはこの2つを区別できません。

Kivgraphはセマンティックなコード関係に焦点を当てており、サービス間のあらゆるHTTP、gRPC、Kafka、データベースのランタイムフローを自動的に発見するものではありません。

ドキュメント

インストール、MCPクライアント、コードインテリジェンス、リポジトリ関係、ワークスペースコードグラフについては、Kivgraphユーザードキュメントをお読みください。公開サイトはリリースバンドルとは別に設定されています。このリンクはすべてのチェックアウトから有効です。

Related MCP server: MCP Indexer

各ツールが答える質問

10個の読み取り専用ツールに加え、クライアントがリポジトリを登録したりジェネレーションを公開したりする前に承認が必要な、同意ゲート付きの1つの変更操作（index_project）があります。

シンボルを名指しするすべての行には、リポジトリ、パス、修飾名、行範囲が含まれているため、追加の呼び出しなしで開くことができます。また、すべてのツールは不透明なキーの代わりにその3つ組を受け入れます。

不利な点。 1つの小さなリポジトリ内の稀な名前はgrepの方が安価で、小さなファイルのインデックス化は読み取りよりもコストがかかります。一般的な名前、推移的な影響、別のリポジトリのコンシューマー、不在の証明では有利です。37リポジトリのコーパスに対する29の質問で測定した結果（benchmarks/graph-tools-comparison/results-all.json、コミット954b9eb、トークナイザーo200k_base）：Kivgraphは35,961トークン、grep＋読み取りは267,980トークンで、29問中28問で両方とも正確、中央値で質問あたり5.95xKivgraphが有利でした。grepは29問中5問で安価で、そのすべてが両側で完全再現率でした：T1_go_trivialはコーパスが2回宣言する名前を尋ねるもので、そこではgrepはKivgraphの0.53xのコストです。

2つ目のハーネスbenchmarks/mcp-token-costは、ホスト自身のツール出力を逐語的にキャプチャしたものと比較しますが、13,222シンボルのKivgraph自身の単一リポジトリで実行されます：回答自体では7.64x、セッション全体では1.60xで、両方のアームが支払うソースボディによって設定された2.41xの下限に対してです。

ステータス

リリース済みで使用中です。kivgraph versionは公開されたリリースを報告します。各フェーズのバックログと受け入れゲートはTASKS.mdにあります。

• 言語: Go、TypeScript、Rust、Python、Dart。PythonはフォールバックモードでバンドルされたASTワーカーを使用します。推論された参照はCANDIDATEであり、決してEXACTではありません。正確なPythonモードでは、インストールされたPyright/BasedPyrightサーバーとともにバンドルされたPyright LSPアダプターを使用します。DartはDartまたはFlutter SDKが提供するDart Analysis Serverを使用します。

• セマンティック依存関係: PythonとDartのインポートは、要求されたパッケージを所有する登録済みプロバイダーがちょうど1つある場合にパッケージ依存関係を公開できます。シンボルレベルのクロスリポジトリエッジには明示的なプロバイダーIDが必要です。

• サーフェス: STDIO上の10個の読み取り専用ツールに加え、同意ゲート付きの1つの変更操作（index_project）。契約はdocs/protocol/mcp-surface-v3.mdにあります。

• ストレージ: LadybugDBが正規のストレージです。クエリはアトミックに公開された不変のHotSnapshotから提供され、データベースからは決して提供されません。

• プラットフォーム: linux/amd64、darwin/arm64、windows/amd64。

• ビューア: kivgraph uiは公開されたグラフの読み取り専用3Dビューを提供します。

要件

• ソースからビルドするにはGo 1.26以降。インデクサーはバイナリにリンクされたgo/typesで型チェックするため、自身の言語バージョン以前で書かれたリポジトリと依存関係のみを読み取れます。kivgraph doctorがその上限を報告します。

• Rustのインデックス化にはcargoとrust-analyzerが必要です。リリースバンドルにはアナライザーが含まれていますが、Rustツールチェーンは含まれていません。

• TypeScriptのインデックス化には、ワーカー用にNode.js 22以降が必要です。

• Pythonのインデックス化には、バンドルされたワーカー用にPython 3.10以降が必要です。これは構文認識型のフォールバックであり、動的または未解決の名前を明示的に報告します。正確なモードではさらにPyright互換の言語サーバーが必要です。

• Dartのインデックス化にはdart実行可能ファイルが必要です。Flutterインストールがそれを提供します。ローダーはAnalysis Serverプロトコルを使用し、Flutterプロジェクトを変更しません。

インストール

1つのスクリプトでMCPをインストール

インストーラーはプラットフォームを検出し、そのプラットフォーム向けの最新の公開MCPリリースをダウンロードし、リリースアーカイブとバンドルのチェックサムの両方を検証して、Goやpnpmを必要とせずにインストールします。リリースにはGoサーバー、固定されたLadybugDBライブラリ、TypeScriptワーカー、バンドルされたPython ASTワーカー、固定されたrust-analyzer、グラマーマニフェスト、Webビューアが含まれ、そのアセットはバンドルの2.3 MBを占めます。scripts/build-bundle.sh --mcp-onlyは、ビューアなしのバンドルを生成します。

公開バンドル: Linux amd64およびmacOS arm64。

ランタイム要件: Bash、Node.js 22以降、Pythonインデックス化時のPython 3.10以降、curl、tar、sha256sumまたはshasum。バンドルは独自のrust-analyzerを同梱しています。Rustリポジトリのインデックス化にはさらにPATH上のcargoが必要で、Dartのインデックス化にはDartまたはFlutter SDKが必要です。

macOSではバイナリは公証されていません。curlでダウンロードしたリリースは検疫されずに実行されます。ブラウザでダウンロードしたコピーはxattr -dr com.apple.quarantineが必要です。docs/development/macos.mdを参照してください。

最新リリースを1つのコマンドでインストール:

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

チェックアウトから、同じインストーラーを直接実行できます:

./scripts/install.sh

最新ではなく特定のリリースをインストールする場合:

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

スクリプトはバンドルを~/.local/opt/kivgraphにインストールし、ランチャーを~/.local/binに配置します。登録済みリポジトリを変更したり、インデックスを作成したり、設定ファイルを置き換えたりすることはありません。別の場所を使用するには、KIVGRAPH_INSTALL_ROOTとKIVGRAPH_BIN_DIRを設定してください。

ランチャーディレクトリを現在のシェルに追加し、両方のランタイムを検証:

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

新しいリリースを確認するか、インストール済みバンドルを更新:

kivgraph update --check
kivgraph update

更新はアトミックで、設定とグラフ状態を保持し、リリースとバンドルのチェックサムを検証し、インストール済みバンドルのみを置き換えます。更新後はMCPクライアントを再起動して、新しいバイナリが起動されるようにしてください。

kivgraphが対話型ターミナルからコマンドなしで呼び出されると、800 msのタイムアウトと24時間のキャッシュで新しいリリースを確認します。キャッシュはプラットフォームのキャッシュディレクトリ（Linuxでは$XDG_CACHE_HOME、macOSでは$HOME/Library/Caches）のkivgraph/update-check.jsonにあります。このオプションのチェックは、ネットワークが利用できない場合にコマンドをブロックすることはありません。

対話型コマンドの出力は、宛先がターミナルの場合にセマンティックANSIカラーを使用します。NO_COLORを設定するか、出力をリダイレクトするとプレーンなままになります。

MCPクライアントを設定し、スキルをインストール

リリースインストーラーはクライアント設定を自動的に編集しません。Kivgraphをインストールした後、--targetなしで統合コマンドを実行して、このマシンに存在するコーディングエージェントを検出し、1つ以上を選択します:

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

Kivgraphは各クライアントの既知のローカル設定またはインストールルートをチェックし、検出されたエージェントをマークします。↑/↓（またはj/k）で移動、spaceでエージェントを切り替え、aで全て選択、nで全て選択解除、Enterで確定、qまたはEscでキャンセルします。何も検出されない場合、セレクターはエージェントが選択されていない状態で開始します。--targetはスクリプト化された非対話型インストールにのみ使用してください。

サポートされているMCPターゲットはclaude-code、claude-desktop、codex、opencode、oh-my-piです。サポートされているスキルターゲットはclaude-code、codex、opencode、oh-my-piです。Claude Desktopにはローカルスキルターゲットがありません。デフォルトのスコープはuserです。プロジェクトローカル設定には--scope projectを使用してください。--dry-runで書き込まずにプランを確認できます。既存の互換性のないエントリはエラーで停止します。置き換えまたは削除には--forceが必要です。既存ファイルはモード0600でアトミックに書き込まれ、置き換えまたは削除の前に*.kivgraph.bakバックアップが作成されます。

登録を明示的に検査または削除:

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

MCPサーバーを起動する前にグラフを初期化して公開:

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

initは自己完結型の設定を書き込みます。--configが別の場所を指している場合、その状態、キャッシュ、レジストリはそのディレクトリにぶら下がるため、使い捨てのインデックスが本物に触れることはありません。index --fullはアトミックに再公開します。どの段階で失敗しても、前のジェネレーションがサービスを継続します。すでに実行中のサーバーは新しいジェネレーションに自動的に追従します。

日常的に:

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はデフォルトで非ループバックアドレスにバインドします。グラフはリポジトリがある場所でインデックス化され、別の場所から閲覧されるためです。認証はないため、公開する内容を正確にログに記録し、--addrで制限します。

logsとtool-statsはサーバーに問い合わせるのではなく、状態ディレクトリの追記専用レコードを読み取ります。これが回答できる理由です。serveが保持するツールごとのカウンターは、起動時に作成され、停止時に消えます。ファイルを読み取ることで、回答はこれまで実行されたすべてのサーバーにわたります。

任意のMCPクライアントをSTDIOでサーバーを起動するように設定:

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

kivgraph serveはグラフが存在する前に起動します。公開されたジェネレーションがない場合、ハンドシェイクを完了し、クエリツールを公開せず、再構築コマンドをinstructionsに配置します。クライアントがプロセス自体を起動するため、終了はクラッシュとして読み取られます。MCPフレーミングはstdoutにのみ書き込み、ログはstderrに書き込みます。

グラフが保持するものと、保持しないもの

エッジは、十分な証拠と正しい来歴がある場合にのみEXACTになります。名前、パス、エイリアス、単一の候補から作成されることは決してなく、解決できない参照は破棄されるのではなく、理由、リポジトリ、言語とともにUNRESOLVEDとして公開されます。graph_statusは両方を内訳付きで報告します。

そのため、一部の回答はエッジではなく不在になります。Rust標準ライブラリがインデックス化されている場合、impl Add for u32はマクロによって生成され、ソース範囲に存在しないため、その使用箇所は誰も開けないエッジになる代わりに、シンボルごとに1回PROVIDER_DEFINITION_NOT_INDEXEDとして宣言されます。

Kivgraphがマシンから導出するプロバイダー（現在はツールチェーンにちなんでrust:1.96.1と名付けられたRust標準ライブラリ）は、デフォルトでは読み取り結果から除外されます。1つのツールチェーンは約2万シンボルであり、Cloneの検索はcoreと答えることになるためです。include_derivedでそれらを要求でき、graph_statusはそれらの貢献を内訳として表示するため、合計は読みやすいままです。

開発

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

make test-ladybug は、固定されたネイティブライブラリをリンクするタグを実行するための唯一のサポート対象方法です。コントリビューション規約は AGENTS.md にあり、CLAUDE.md がそこにリンクしています。

make semantic-coverage は、Go、TypeScript、Python、Dart のリリースゲートです。これは testdata/semantic-coverage/manifest.json 内の機械可読なマトリックスを検証し、正確な TypeScript、Go、Dart のスイートを実行し、正確な Python スイートには Pyright 互換の言語サーバーを必要とします。ある機能にフィクスチャはあるが実行可能な回帰テストがない場合、その言語は完全とは見なされません。

ストレージとグラフのベンチマーク

LadybugDB の認定、合成コーパスジェネレーター、ロードおよびクエリのベンチマーク、そして doctor、rebuild、rollback、snapshot コマンドは、docs/development/storage-benchmarks.md に文書化されています。これは ACCEPT_LADYBUGDB_WITH_LIMITS で締めくくられています。

公開サイト

landing/ にはランディングページとユーザードキュメントが含まれています。これはリリースバンドルには含まれず、make landing-check と make landing-build で検証され、ポート 6767 で提供されます。そこで公開される内容、MCP リファレンスがどのように取得されたか、そしてまだ未解決の事項は、docs/development/landing-site.md に記録されています。

構造

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.

ライセンス

Kivgraph は Apache License 2.0 の下で配布されています。

サードパーティライセンス

Kivgraph とともに配布される依存関係の通知とライセンスは、THIRD_PARTY_NOTICES.md に記録されています。このリストは、配布可能な製品に依存関係が追加されるたびに更新されます。