Kivgraph

Kivgraph는 로컬 AI 코딩 에이전트를 위한 저장소 간 코드 인텔리전스 MCP 서버입니다. 여러 등록된 저장소에 걸쳐 표준 의미론적 코드 그래프를 구축하고 심볼, 저장소 관계, 호출자, 의존성 및 변경 영향에 대한 질문에 답합니다.

코퍼스를 한 번 인덱싱하고 불변 그래프를 제공합니다. 엣지는 이름 매칭이 아니라 go/types, TypeScript 체커 및 rust-analyzer에 의해 해석됩니다. 이것이 검색 도구와의 차이점이며, 빈 답변에 가치를 부여하는 이유입니다 — 빈 참조 목록은 아무것도 찾지 못했다는 뜻이 아니라 아무도 호출하지 않는다는 뜻이며, grep은 이 둘을 구분할 수 없습니다.

Kivgraph는 서비스 간 모든 HTTP, gRPC, Kafka 또는 데이터베이스 런타임 흐름의 자동 발견이 아니라 의미론적 코드 관계에 초점을 맞춥니다.

문서

설치, MCP 클라이언트, 코드 인텔리전스, 저장소 관계 및 워크스페이스 코드 그래프에 대해서는 Kivgraph 사용자 문서를 읽으십시오. 게시된 사이트는 릴리스 번들과 별도로 구성됩니다. 이 링크는 모든 체크아웃에서 유효합니다.

Related MCP server: MCP Indexer

각 도구가 답하는 것

읽기 전용 도구 10개와, 클라이언트가 저장소를 등록하거나 세대를 게시하기 전에 승인해야 하는 동의 게이트 변형 작업(index_project) 하나가 있습니다.

심볼을 명명하는 모든 행은 저장소, 경로, 정규화된 이름 및 줄 범위를 포함하므로 추가 호출 없이 열 수 있으며, 모든 도구는 불투명한 키 대신 그 세 가지를 받아들입니다.

어디에서 약한가. 하나의 작은 저장소에 있는 희귀한 이름은 grep이 더 저렴하며, 작은 파일을 인덱싱하는 것은 읽는 것보다 비용이 더 듭니다. Kivgraph는 흔한 이름, 전이적 영향, 다른 저장소의 소비자, 그리고 부재 증명에서 우위를 점합니다. 37개 저장소 코퍼스에 대한 29개 질문으로 측정했을 때(benchmarks/graph-tools-comparison/results-all.json, 커밋 954b9eb, 토크나이저 o200k_base): Kivgraph는 35,961 토큰, grep 및 읽기는 267,980 토큰으로, 29개 중 28개에서 양쪽 모두 정확했으며, 질문당 중앙값 5.95x로 Kivgraph가 유리했습니다. grep은 29개 중 5개에서 더 저렴했으며, 모두 양쪽 모두 완전 재현율을 보였습니다: T1_go_trivial은 코퍼스가 두 번 선언하는 이름을 요청하며, 거기서 grep은 Kivgraph 비용의 0.53x입니다.

두 번째 하네스인 benchmarks/mcp-token-cost는 호스트 자체 도구 출력을 그대로 캡처하여 비교하지만, 13,222개 심볼의 Kivgraph 자체 단일 저장소에서 실행됩니다: 양쪽 모두가 부담하는 소스 본문이 설정한 2.41x 하한선을 기준으로 답변 자체에서는 7.64x, 전체 세션에서는 1.60x입니다.

상태

출시되어 사용 중입니다. 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 가져오기는 요청된 패키지를 정확히 하나의 등록된 제공자가 소유할 때 패키지 의존성을 게시할 수 있습니다. 심볼 수준의 교차 저장소 엣지는 명시적 제공자 ID가 필요합니다.

• 표면: STDIO를 통한 10개의 읽기 전용 도구와 하나의 동의 게이트 변형 작업(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 프로젝트를 수정하지 않습니다.

설치

하나의 스크립트로 MCP 설치

설치 프로그램은 플랫폼을 감지하고 해당 플랫폼용 최신 게시 MCP 릴리스를 다운로드하고 릴리스 아카이브와 번들 체크섬을 모두 검증한 후 Go나 pnpm 없이 설치합니다. 릴리스에는 Go 서버, 고정된 LadybugDB 라이브러리, TypeScript 워커, 번들된 Python AST 워커, 고정된 rust-analyzer, 문법 매니페스트 및 웹 뷰어가 포함되며, 뷰어 자산은 번들에서 2.3MB를 차지합니다. 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에서 바이너리는 공증(notarization)되지 않았습니다. 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을 설정하십시오.

실행기 디렉터리를 현재 셸에 추가하고 두 런타임을 모두 확인합니다:

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

최신 릴리스가 있는지 확인하거나 설치된 번들을 업데이트합니다:

kivgraph update --check
kivgraph update

업데이트는 원자적이며 구성과 그래프 상태를 보존하고 릴리스 및 번들 체크섬을 검증하며 설치된 번들만 교체합니다. 업데이트 후 MCP 클라이언트를 다시 시작하여 새 바이너리를 실행하십시오.

kivgraph가 대화형 터미널에서 명령 없이 호출되면 800ms 타임아웃과 24시간 캐시로 최신 릴리스를 확인하며, 캐시는 플랫폼 캐시 디렉터리(Linux의 $XDG_CACHE_HOME 및 macOS의 $HOME/Library/Caches)의 kivgraph/update-check.json에 저장됩니다. 선택적 확인은 네트워크를 사용할 수 없을 때 명령을 차단하지 않습니다.

대화형 명령 출력은 대상이 터미널일 때 의미론적 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:1.96.1이라는 Rust 표준 라이브러리 — 는 기본적으로 읽기 결과에서 제외됩니다. 하나의 툴체인은 약 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_LADYDB_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에 기록되어 있습니다. 이 목록은 배포 가능한 제품에 종속성이 추가될 때마다 업데이트됩니다.