GitNexus Là Gì? Hướng Dẫn Cài Đặt MCP Knowledge Graph Cho AI Agent

TL;DR

Quick Answer Box (Google Search Featured Snippet):

• GitNexus là gì? GitNexus là công cụ mã nguồn mở index toàn bộ codebase thành một Knowledge Graph (đồ thị tri thức) lưu trong cơ sở dữ liệu KùzuDB và expose qua giao thức MCP (Model Context Protocol), giúp các AI coding agent (Cursor, Claude Code, Windsurf) thấu hiểu toàn diện cấu trúc dự án.
• GitNexus giải quyết vấn đề gì? Chấm dứt triệt để lỗi “refactor mù”: tính toán trước bán kính ảnh hưởng (blast radius), chuỗi phụ thuộc (call chains) và luồng thực thi (execution flows) để AI không làm vỡ code ở các file chưa từng mở.
• Cách cài đặt nhanh: Cài đặt CLI npm install -g gitnexus, chạy gitnexus analyze để index dự án, rồi tích hợp MCP vào editor.
• Kho lưu trữ GitHub: abhigyanpatwari/GitNexus.

GitNexus là công cụ MCP giúp AI agent hiểu cấu trúc codebase, không chỉ từng file riêng lẻ. Nó cũng có giao diện trực quan hoá dạng đồ thị khi bạn muốn khám phá mà không cần gắn vào editor.

• Nó giải quyết gì: Xây dựng knowledge graph của codebase và expose qua MCP tools để AI agents hiểu impact của mỗi thay đổi
• Tại sao quan trọng: Nếu không có nó, AI refactor code bề ngoài tốt nhưng vô tình break 47 functions phụ thuộc mà nó không thấy
• Dùng cho ai: Developers dùng Cursor, Claude Code, Windsurf hay bất kỳ AI coding assistant nào
• Khác biệt chính: Tính toán trước graph intelligence (clustering, execution flow, blast radius) thay vì hy vọng LLM dò đủ

---

Bản Đồ Cho Người Mới

Đừng đọc GitNexus như bảy MCP tools rời rạc. Hãy đọc theo một đường: index một lần vào KuzuDB, truy vấn nhiều lần qua MCP.

1. Lượt 1: Phần 1 - pattern refactor mù (UserService.validate()).
2. Lượt 2: Phần 2 - xem scene năm beat; nhớ analyze → KuzuDB → MCP.
3. Lượt 3: Phần 3 - tools theo thứ tự quan trọng (impact trước, rồi context, query, …).
4. Lượt 4: Phần 4 - chạy bài tập thực hành bên dưới trên repo bạn đang sửa.

Thử thách thực hành (Student First Assignment)

Sau npx gitnexus analyze và npx gitnexus setup ở Phần 4, mở Cursor hoặc Claude Code và hỏi:

“Trước khi refactor UserService, dùng GitNexus impact để liệt kê upstream dependents kèm confidence score.”

Nếu agent trả về bản đồ blast radius có cấu trúc thay vì grep tên file, beat 3 trong scene Phần 2 vừa trở thành thực tế - phần còn lại của bài chỉ là chi tiết cho các mũi tên bạn đã xem animate.

Mở rộng: sau khi sửa file, nhờ agent chạy detect_changes trước khi commit. Vòng lặp đó nối impact ở beat 3 với lưới an toàn pre-commit ở Phần 3.

---

Phần 1: Nền Tảng - Mô Hình Tư Duy

Tưởng tượng bạn là bác sĩ phẫu thuật chuẩn bị mổ. Bạn có X-quang thấy xương, nhưng không thấy dây thần kinh, mạch máu, hay cách chúng kết nối. Bạn cắt một nhát - và trúng động mạch mà không ai đề cập.

Đó chính xác là điều xảy ra khi AI agents chỉnh sửa code ngày nay.

Các tool như Cursor, Claude Code, Windsurf, và Cline là những trình soạn thảo code cực kỳ mạnh. Nhưng chúng có chung một điểm mù cốt lõi: chúng không thực sự hiểu cấu trúc codebase của bạn. Chúng thấy files, thấy functions, nhưng không thấy mạng lưới dependencies vô hình kết nối mọi thứ.

Đây là pattern thất bại điển hình:

1. Bạn yêu cầu AI refactor UserService.validate()
2. AI chỉnh sửa hoàn hảo - trong phạm vi riêng lẻ
3. AI không biết 47 functions phụ thuộc vào return type của nó
4. Breaking changes được push lên production

GitNexus giải quyết vấn đề này bằng cách xây dựng một knowledge graph hoàn chỉnh của codebase - mọi function call, import, class inheritance, và execution flow - rồi expose qua smart tools thông qua Model Context Protocol (MCP).

Hình dung thế này:

Không có GitNexus: AI agent của bạn di chuyển trong codebase như khách du lịch với bản đồ tên đường.

Có GitNexus: AI agent di chuyển như dân địa phương biết mọi đường tắt, ngõ cụt, và đường một chiều.

Ẩn dụ đó mô tả đúng khoảng trống - nhưng vẫn còn trừu tượng. Phần 2 biến nó thành một đường đi cụ thể: từ refactor mù ở beat 1, qua npx gitnexus analyze dựng graph trong KuzuDB, đến lúc agent gọi impact() trước khi chạm vào UserService.

---

Phần 2: Khám Phá - GitNexus Xây Dựng “Bộ Não” Như Thế Nào

Phần 1 đặt tên cho điểm mù. Phần 2 cho thấy GitNexus lấp nó bằng cách nào.

Ở mức cao, GitNexus làm ba việc theo thứ tự:

1. Index - duyệt repo qua pipeline sáu giai đoạn và lưu knowledge graph vào KuzuDB
2. Expose - phục vụ graph đó cho editor qua MCP tools (impact, context, query, …)
3. Deliver - chạy cùng một “bộ não” trên CLI (local), Web UI (browser), hoặc nối hai phía bằng gitnexus serve

Danh sách bullet trong README che mất trình tự đó. Trước khi mở từng giai đoạn pipeline, từng MCP tool và lệnh setup, hãy xem GitNexus biến đổi refactor mù thành thực thi AST chính xác tuyệt đối qua ba beat:

1. Indexing AST & Cấu Trúc - gitnexus analyze parse toàn bộ codebase với Tree-sitter vào KùzuDB
2. Truy Vấn Graph Siêu Chuẩn Qua MCP - AI agent truy vấn callers và blast radius trong vài mili-giây
3. Refactor An Toàn Tuyệt Đối - Cập nhật symbol trên toàn bộ repository với zero hallucination

Xương sống cốt lõi cần nhớ: analyze → KùzuDB → MCP → agent tools. Indexer dựng graph một lần; trong quá trình code, agent truy vấn cấu trúc đã tính sẵn thay vì đoán mò từ tên file.

Pipeline Index Đa Giai Đoạn

Beat 2 trong scene trên chính là pipeline này đang chạy. Khi bạn gõ npx gitnexus analyze, GitNexus xử lý codebase qua sáu giai đoạn - sơ đồ ASCII bên dưới là cùng một đường đi, với tên giai đoạn ghi rõ để tra cứu:

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  1. Structure │───▶│  2. Parsing   │───▶│ 3. Resolution│
│  File tree +  │    │  Tree-sitter  │    │  Cross-file   │
│  folder map   │    │  AST extract  │    │  imports      │
└──────────────┘    └──────────────┘    └──────────────┘
        │                                        │
        ▼                                        ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  6. Search    │◀───│ 5. Processes  │◀───│ 4. Clustering │
│  Hybrid index │    │  Execution    │    │  Community    │
│  BM25+Vector  │    │  flow tracing │    │  detection    │
└──────────────┘    └──────────────┘    └──────────────┘

Giai đoạn 1 - Structure: Map file tree và quan hệ thư mục. Đây là bộ khung xương.

Giai đoạn 2 - Parsing: Sử dụng Tree-sitter để trích xuất mọi function, class, method, và interface từ 11 ngôn ngữ: TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, và Swift.

Giai đoạn 3 - Resolution: “Phép thuật” xảy ra ở đây. GitNexus resolve imports và function calls xuyên files với logic nhận diện ngôn ngữ. Nó không chỉ biết auth.ts tồn tại - nó biết handleLogin() trong auth.ts gọi validate() trong user.ts với độ tin cậy 90%.

Giai đoạn 4 - Clustering: Nhóm các symbols liên quan thành communities chức năng sử dụng graph algorithms qua Graphology. Các auth functions, database layer, và API routes tự nhiên cluster với nhau.

Giai đoạn 5 - Processes: Trace execution flows từ entry points xuyên suốt call chains. Nó map ra “LoginFlow” là process 7 bước từ route handler → validation → database → response.

Giai đoạn 6 - Search: Xây dựng hybrid search index kết hợp BM25 (keyword), semantic embeddings (qua HuggingFace transformers.js), và Reciprocal Rank Fusion để truy xuất nhanh.

Mỗi node animate ở beat 2 khớp trực tiếp với một giai đoạn:

Đổi Mới Cốt Lõi: Precomputed Intelligence

Đó là lý do beat 3 trong scene trả lời gần như tức thì: phần nặng đã xong lúc index.

Các cách tiếp cận Graph RAG truyền thống đổ raw graph edges cho LLM rồi hy vọng nó dò đủ. GitNexus tính toán trước ngay khi index - clustering, tracing, confidence scoring - để mỗi tool call trả về context hoàn chỉnh trong một query duy nhất.

Điều này có nghĩa:

• LLM không thể bỏ sót context - nó đã sẵn trong tool response
• Tiết kiệm tokens - không cần chuỗi 10 queries để hiểu một function
• Dân chủ hóa models - LLM nhỏ hơn cũng hoạt động tốt vì tools lo phần nặng

Tech Stack

GitNexus chạy ở hai chế độ, mỗi cái với tech phù hợp:

Mọi thứ lưu trong KuzuDB, embedded graph database có hỗ trợ vector - không cần database server bên ngoài. Một kho lưu trữ duy nhất đó là nguồn mà CLI, Web UI và MCP cùng đọc trong beat 3-4 của scene.

Bảng trên là beat 4 ở dạng tĩnh: stack native trên nhánh CLI, stack WASM trên browser, cùng một hình dạng graph.

---

Phần 3: Chẩn Đoán - GitNexus Thực Sự Làm Gì Cho Developers

Phần 2 kết thúc với graph trong KuzuDB. Phần 3 là beat 3 đi vào thực chiến: agent làm gì với graph đó sau khi MCP đã kết nối.

Scene đã demo ba lệnh - impact, context, và query. GitNexus cung cấp bảy MCP tools. Dùng bảng tóm tắt trước, rồi cuộn xem output mẫu từng tool.

Quy trình agent khuyến nghị (khớp thứ tự gọi ở beat 3):

1. impact - trước khi sửa: upstream nào sẽ vỡ?
2. context - trên symbol sắp chạm: callers, callees, processes
3. Edit - để agent refactor với context từ graph
4. detect_changes - trước commit: mức rủi ro và processes bị ảnh hưởng
5. rename - khi đổi tên symbol phối hợp nhiều file, không phải sửa một dòng

Các tool không có trong scene (detect_changes, rename, cypher, list_repos) vẫn đọc cùng graph KuzuDB mà beat 2 dựng - chúng là bề mặt tùy chọn trên cùng xương sống.

7 Tools Cho AI Agents “Tia X” Xuyên Code

1. impact - Phân Tích Blast Radius

Trước khi chạm vào code, hỏi: “Cái gì sẽ vỡ?”

impact({target: "UserService", direction: "upstream", minConfidence: 0.8})

TARGET: Class UserService (src/services/user.ts)

UPSTREAM (phụ thuộc vào nó):
  Depth 1 (SẼ VỠ):
    handleLogin [CALLS 90%] -> src/api/auth.ts:45
    handleRegister [CALLS 90%] -> src/api/auth.ts:78
    UserController [CALLS 85%] -> src/controllers/user.ts:12
  Depth 2 (CÓ THỂ ẢNH HƯỞNG):
    authRouter [IMPORTS] -> src/routes/auth.ts

Giống như có một senior engineer đã thuộc lòng toàn bộ codebase nói: “Nếu bạn thay đổi UserService, 4 thứ này SẼ vỡ, và 2 thứ này CÓ THỂ vỡ.”

2. context - Góc Nhìn 360° Về Symbol

Lấy bức tranh toàn diện của bất kỳ symbol nào - ai gọi nó, nó gọi gì, và tham gia processes nào:

context({name: "validateUser"})

incoming:
  calls: [handleLogin, handleRegister, UserController]
  imports: [authRouter]

outgoing:
  calls: [checkPassword, createSession]

processes:
  - name: LoginFlow (step 2/7)
  - name: RegistrationFlow (step 3/5)

3. query - Tìm Kiếm Theo Process

Không chỉ “tìm files chứa X”, mà “tìm các processes và execution flows liên quan đến X”:

query({query: "authentication middleware"})

processes:
  - summary: "LoginFlow"
    priority: 0.042
    symbol_count: 4
    process_type: cross_community
    step_count: 7

process_symbols:
  - name: validateUser
    type: Function
    filePath: src/auth/validate.ts
    process_id: proc_login
    step_index: 2

4. detect_changes - Lưới An Toàn Trước Commit

Trước khi commit, hiểu tác động thực sự của thay đổi:

detect_changes({scope: "all"})

summary:
  changed_count: 12
  affected_count: 3
  risk_level: medium

affected_processes: [LoginFlow, RegistrationFlow]

5. rename - Rename Phối Hợp Multi-File

Không phải find-and-replace đơn giản, mà rename nhận biết graph - phân biệt giữa function tên validate và comment chứa từ “validate”:

rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true})

files_affected: 5
total_edits: 8
graph_edits: 6     (độ tin cậy cao)
text_search_edits: 2  (cần review cẩn thận)

6 & 7. cypher và list_repos

Raw Cypher graph queries cho power users, và khám phá repository cho multi-repo setups.

Use Case Thực Tế: Python Developers

Tưởng tượng bạn đang làm việc trên dự án Django với 200+ models. Bạn cần rename một model field. Không có GitNexus, bạn sẽ:

1. grep tên field (bắt luôn comments, strings, matches không liên quan)
2. Trace thủ công serializers, views, và templates
3. Hy vọng không bỏ sót queryset filter nào đó

Với GitNexus: impact({target: "User.email", direction: "upstream"}) → bản đồ dependency hoàn chỉnh tức thì. Đó chính là mũi tên impact bạn thấy ở beat 3 - giờ gắn với ví dụ Django quy mô lớn.

---

Phần 4: Giải Pháp - Bắt Đầu Như Thế Nào

Bạn đã có mô hình tư duy (Phần 1), pipeline (Phần 2) và tools (Phần 3). Phần 4 là beat 4: dựng index trên CLI, cắm MCP vào editor, xem nhanh trên browser, hoặc nối hai phía bằng gitnexus serve.

CLI Quick Start (Khuyến Nghị)

Đây là nhánh trái của beat 4 - Dev → Analyze → KuzuDB trên đường native:

# Index repository (chạy từ root repo)
npx gitnexus analyze

# Vậy thôi! Lệnh này làm tất cả:
# - Index codebase
# - Cài đặt agent skills
# - Đăng ký Claude Code hooks
# - Tạo files AGENTS.md / CLAUDE.md

Kết Nối Với Editor

Khi graph đã có, đây là cách vẽ mũi tên Editor → MCP trên máy bạn:

# Tự động cấu hình MCP cho tất cả editors phát hiện được
npx gitnexus setup

# Hoặc thủ công cho Cursor (~/.cursor/mcp.json):
{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Ma Trận Hỗ Trợ Editor

Web UI (Khám Phá Nhanh)

Đây là nhánh phải của beat 4 - Dev → WebUI → KuzuDB mà không cần cài local:

Không cần cài đặt - chỉ cần truy cập gitnexus.vercel.app. Upload repo hoặc paste GitHub URL. Mọi thứ chạy trong browser - không có code nào gửi tới server.

Bridge Mode

Đây là mũi tên Analyze ~> WebUI trong beat 4 - index CLI một lần, duyệt mọi nơi:

Chạy gitnexus serve để kết nối CLI và Web:

# Start local server
gitnexus serve

# Web UI tự phát hiện - duyệt tất cả repos đã index bằng CLI
# không cần upload hay index lại

Wiki Generation

Sau beat 4, bạn có thể biến graph đã index thành tài liệu đọc được - hữu ích cho onboarding hoặc mô tả PR:

gitnexus wiki
gitnexus wiki --model gpt-4o
gitnexus wiki --force  # Tạo lại hoàn toàn

Coi wiki như export mô hình tư duy của beat 5 thành prose mà team có thể đọc mà không cần mở editor.

Khi Nào Cần Re-Index

Graph là snapshot. Chạy lại npx gitnexus analyze khi:

• Bạn merge refactor lớn hoặc đổi public API xuyên nhiều file
• Thêm ngôn ngữ hoặc module tree mà index chưa từng thấy
• MCP tools trả path cũ sau khi shuffle thư mục lớn

Sửa code hàng ngày không cần re-index đầy đủ - detect_changes hoạt động trên diff hiện tại.

---

Kiến Trúc Hạ Tầng AI & Coding Agent Bổ Trợ

Nếu bạn đang phát triển môi trường coding agent tự trị, hãy tham khảo các bài phân tích kỹ thuật bổ trợ:

• Bộ Sưu Tập System Prompt Của Các AI Model (700+ Items): Khám phá kiến trúc loop và quy tắc lazy diff của Cursor, Manus, Devin.
• Pi Mono Explained: Kiến Trúc Coding Agent Tự Trị Đơn Luồng & Bộ Nhớ: Khám phá kiến trúc subagent, loop phản hồi và hệ thống tools thực chiến.
• OmniRoute Explained: AI Gateway Hợp Nhất 290+ Provider: Proxy điều phối lưu lượng AI cục bộ, tự động fallback chống rate limit HTTP 429 và nén token.
• Ego Lite: Trình Duyệt AI Tận Dụng Cookie Thật Cho Coding Agent: Tự động hóa duyệt web có đăng nhập trực tiếp trong Claude Code và Cursor với session thật.
• Strix AI: Công Cụ Pentest & Red-Team Tự Động Mã Nguồn Mở Trên GitHub: Khám phá đội ngũ agent pentest tự động tìm kiếm, khai thác và chứng minh lỗ hổng bảo mật.
• Kỹ Năng Coding Agent Cho Lập Trình Viên ADHD: Tự động hoá ghi nhớ và neo giữ luồng làm việc chống phân tâm.

---

Câu Hỏi Thường Gặp Về GitNexus (FAQ)

1. GitNexus là gì và hoạt động ra sao?

GitNexus là một công cụ mã nguồn mở giúp phân tích codebase bằng Tree-sitter, index các symbol, hàm, class và luồng thực thi vào cơ sở dữ liệu đồ thị KùzuDB cục bộ, đồng thời cung cấp 7 tool Model Context Protocol (MCP) cho AI coding agent (Cursor, Claude Code, Windsurf). Thay vì ép AI dò tìm văn bản qua grep hoặc tìm kiếm vector mơ hồ, GitNexus cung cấp dữ liệu đồ thị xác định để tính toán chính xác chuỗi gọi hàm và bán kính ảnh hưởng.

2. GitNexus khác gì so với tìm kiếm vector (RAG)?

Tìm kiếm vector truyền thống (RAG) chỉ đo độ tương đồng ngữ nghĩa của đoạn văn bản, rất dễ bỏ sót các quan hệ phụ thuộc liên file, kế thừa class hoặc chuỗi call-graph phức tạp. GitNexus xây dựng đồ thị tri thức dựa trên AST thực tế, đảm bảo AI agent biết chính xác 100% file nào sẽ bị ảnh hưởng trước khi sửa code.

3. GitNexus hỗ trợ những editor và công cụ AI nào?

GitNexus tương thích với mọi môi trường hỗ trợ Model Context Protocol (MCP), bao gồm Cursor, Claude Code, Windsurf, OpenCode, và các framework agent tự chế. Ngoài ra, bạn có thể dùng giao diện web trực quan (gitnexus.vercel.app) để khám phá repo trên trình duyệt mà không cần cài đặt gì.

4. GitNexus có an toàn cho codebase doanh nghiệp nội bộ không?

Hoàn toàn bảo mật và chạy 100% local. Mọi thao tác parse AST, sinh đồ thị KùzuDB và truy vấn MCP đều diễn ra hoàn toàn trên máy cục bộ của bạn. Không một dòng code hay siêu dữ liệu nào bị gửi lên bất kỳ máy chủ bên thứ ba nào.

---

Mô Hình Tư Duy Cuối Cùng

Beat 5 ở scene Phần 2 chính là bảng này dưới dạng hình - toàn bộ stack gom lại một chỗ. Giữ nó như “checksum” sau khi đã đi qua chi tiết:

Kết Luận

• Vấn đề: AI agent sửa symbol trong phạm vi lẻ và bỏ sót code phụ thuộc chưa từng mở.
• Cơ chế: Index một lần (analyze → KuzuDB), truy vấn nhiều lần (MCP tools với graph intelligence tính sẵn).
• Lợi ích: Ít refactor gây vỡ hơn, rename nhận biết graph, kiểm tra rủi ro trước commit - không gửi codebase lên cloud indexer.

GitNexus không thay thế AI coding assistant. Nó cho assistant trí nhớ kiến trúc để ánh đỏ beat 1 không bao giờ lên production.

GitHub: github.com/abhigyanpatwari/GitNexus