Kivgraph

Kivgraph 是一个本地的面向 AI 编码代理的跨仓库代码智能 MCP 服务器。它跨多个已注册仓库构建一个规范的语义代码图，并回答关于符号、仓库关系、调用者、依赖和变更影响的问题。

它只对语料库索引一次，并提供不可变的图：边由 go/types、TypeScript 检查器和 rust-analyzer 解析，而不是通过名称匹配。这就是它与搜索工具的区别，也是让空答案有价值的原因——空的引用列表意味着没有人调用它，而不是没有找到任何东西，而 grep 无法区分这两种情况。

Kivgraph 专注于语义代码关系，而不是自动发现服务之间的每个 HTTP、gRPC、Kafka 或数据库运行时流程。

文档

阅读 Kivgraph 用户文档 了解安装、MCP 客户端、代码智能、仓库关系和工作区代码图。发布站点与发布包分开配置；此链接在任何检出中均保持有效。

Related MCP server: MCP Indexer

每个工具回答什么

十个只读工具，外加一个需要同意才能执行的变更操作（index_project），客户端必须先授权，才能注册仓库或发布一代。

每一行只要提到符号，都会带上它的仓库、路径、限定名和行范围，因此无需第二次调用即可打开；每个工具都接受这个三元组来代替不透明的键。

它的劣势。 在单个小仓库中查找一个罕见名称，用 grep 更便宜；索引一个小文件的成本也高于读取它。它在常见名称、传递影响、另一个仓库中的消费者以及证明“不存在”方面占优。针对 37 个仓库的语料库、29 个问题进行的测量（benchmarks/graph-tools-comparison/results-all.json，提交 954b9eb，分词器 o200k_base）：Kivgraph 花费 35,961 个 token，而 grep 加读取花费 267,980 个 token；29 个问题中双方在 28 个上完全一致，每个问题的中位数是 Kivgraph 占优 5.95x。在这 29 个问题中，grep 在 5 个上更便宜，且这 5 个双方都达到了完全召回：T1_go_trivial 询问的是语料库声明了两次的名称，在那里 grep 的成本是 Kivgraph 的 0.53x。

第二个测试工具 benchmarks/mcp-token-cost 与逐字捕获的宿主自身工具输出进行比较，但它在 Kivgraph 自己的单一仓库（13,222 个符号）上运行：答案本身为 7.64x，整个会话为 1.60x，而双方都要支付的源代码正文设定了 2.41x 的下限。

状态

已发布并投入使用。kivgraph version 报告已发布的版本；每个阶段的待办事项和验收门都在 TASKS.md 中。

• 语言： Go、TypeScript、Rust、Python 和 Dart。Python 在回退模式下使用内置的 AST worker；那些推断出的引用是 CANDIDATE，绝不会是 EXACT。精确 Python 模式使用内置的 Pyright LSP 适配器，并配合已安装的 Pyright/BasedPyright 服务器。Dart 使用 Dart 或 Flutter SDK 提供的 Dart Analysis Server。

• 语义依赖： 当且仅当一个已注册的提供者拥有所请求的包时，Python 和 Dart 的导入可以发布包依赖；符号级的跨仓库边需要显式的提供者身份。

• 接口： 通过 STDIO 提供十个只读工具，外加一个需要同意才能执行的变更操作（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 或更高版本才能运行 worker。

• 索引 Python 需要 Python 3.10 或更高版本才能运行内置 worker。它是一个语法感知的回退实现，并显式报告动态或无法解析的名称；精确模式还需要一个与 Pyright 兼容的语言服务器。

• 索引 Dart 需要 dart 可执行文件；Flutter 安装会提供它。加载器使用 Analysis Server 协议，并且不会修改 Flutter 项目。

安装

用一个脚本安装 MCP

安装程序会检测平台，下载该平台最新的已发布 MCP 版本，验证发布归档和包校验和，并在不需要 Go 或 pnpm 的情况下完成安装。发布内容包含 Go 服务器、固定版本的 LadybugDB 库、TypeScript worker、内置的 Python AST worker、固定版本的 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。

用一条命令安装最新版本：

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。

将启动器目录添加到当前 shell，并验证两个运行时：

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

检查是否有新版本，或更新已安装的包：

kivgraph update --check
kivgraph update

更新是原子的，保留配置和图状态，验证发布和包校验和，并且只替换已安装的包。更新后请重启 MCP 客户端，以便它启动新的二进制文件。

当 kivgraph 在交互式终端中不带命令调用时，它会以 800 ms 超时检查是否有新版本，并在平台缓存目录（Linux 上是 $XDG_CACHE_HOME，macOS 上是 $HOME/Library/Caches）下的 kivgraph/update-check.json 中缓存 24 小时。当网络不可用时，这个可选检查绝不会阻塞命令。

当输出目标是终端时，交互式命令输出会使用语义化的 ANSI 颜色。设置 NO_COLOR 或重定向输出可以保持纯文本。

配置 MCP 客户端并安装技能

发布安装程序不会自动编辑客户端配置。安装 Kivgraph 后，不带 --target 运行集成命令，以检测本机上存在的编码代理并选择其中一个或多个：

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 由宏生成，不存在于任何源码范围中，因此它的每次使用都会按符号声明为 PROVIDER_DEFINITION_NOT_INDEXED，而不是变成一条任何人都无法打开的边。

Kivgraph 从机器上派生的提供者——目前是以工具链命名的 Rust 标准库 rust:1.96.1——默认从读取结果中隐藏：一个工具链大约有两万个符号，搜索 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 套件，并且需要与 Pyright 兼容的语言服务器来运行确切的 Python 套件。当某项能力只有 fixture 而没有可执行的回归测试时，该语言不被视为已完成。

存储与图基准测试

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 中。每当有依赖项添加到可分发产品中时，该列表都会更新。