B38 Code Graph & AST MCP Server — Hướng Dẫn & Kiến Trúc Kỹ Thuật

🐳

Cấu Hình Docker Compose (DCP_PRODUCTION)

Dịch vụ B38 được mount mã nguồn ở chế độ chỉ đọc (:ro) để đảm bảo an toàn tuyệt đối, đồng thời bind-mount thư mục data/ để dữ liệu SQLite không bị mất khi restart container.

# docker-compose.yml (DCP_PRODUCTION)
lotus_code_graph:
  container_name: lotus_code_graph
  build:
    context: ${DCP_ROOT}/B38_Code_Graph
  image: lotus/code_graph:1.0
  hostname: CODE_GRAPH
  volumes:
    - ${DCP_ROOT}/B38_Code_Graph/app:/app/app:ro
    - ${DCP_ROOT}/B38_Code_Graph/data:/app/data
    - ${REPO_ROOT}:/workspace:ro
  environment:
    - CODE_GRAPH_DB=/app/data/code_graph.sqlite
    - WORKSPACE_DIR=/workspace
    - PROJECT_NAME=GreatLotus_Workspace
  ports:
    - "20380:8080"
  networks:
    GreatLotus_Net:
      ipv4_address: '114.114.114.38'

💾

Mô Hình Dữ Liệu SQLite Đồ Thị

Cơ sở dữ liệu được tối ưu với PRAGMA journal_mode=WAL và các chỉ mục đa cột (composite indexes) cho phép tra cứu ký hiệu và liên kết gọi hàm dưới 5ms.

-- Bảng quản lý tập tin
CREATE TABLE files (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id INTEGER NOT NULL,
    path TEXT UNIQUE NOT NULL,
    mtime REAL NOT NULL,
    size INTEGER NOT NULL,
    hash TEXT NOT NULL,
    lang TEXT NOT NULL
);

-- Bảng ký hiệu AST (Class, Function, Method, Async)
CREATE TABLE symbols (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_id INTEGER NOT NULL,
    name TEXT NOT NULL,
    full_name TEXT NOT NULL,
    kind TEXT NOT NULL,
    line_start INTEGER,
    line_end INTEGER,
    signature TEXT,
    docstring TEXT
);

-- Bảng liên kết cuộc gọi & phụ thuộc (Calls, Imports, Inherits)
CREATE TABLE edges (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_id INTEGER NOT NULL,
    source_symbol TEXT NOT NULL,
    target_name TEXT NOT NULL,
    edge_type TEXT NOT NULL,
    line_number INTEGER
);

🔄

Cơ Chế Quét Gia Tăng (Incremental Scanning) & Invalidation

1. Kiểm Tra mtime & Hash

So sánh thời gian sửa đổi (mtime) và MD5 hash. File không thay đổi sẽ được bỏ qua trong 0.01ms, giúp quét 10.000 file chỉ trong 1-2 giây.

2. Cascade Invalidation

Khi một file bị sửa đổi, toàn bộ symbols và edges cũ của file đó trong SQLite sẽ được xóa sạch trong một transaction trước khi nạp AST mới.

3. Dọn Rác File Đã Xóa

Hàm delete_missing_files() tự động phát hiện các file hoặc thư mục đã bị xóa khỏi workspace và purge sạch khỏi DB, tránh bóng ma dữ liệu.

🤖

Danh Sách 7 Công Cụ MCP Cho Agent

code_graph_search_symbol
Tra cứu Class, Function, Method, Async Function theo tên kèm số dòng & chữ ký hàm.
code_graph_get_callers
Tìm mọi vị trí trong toàn bộ workspace gọi đến một hàm/phương thức cụ thể.
code_graph_get_callees
Trích xuất danh sách tất cả các hàm con được gọi bên trong một hàm chỉ định.
code_graph_get_dependencies
Phân tích quan hệ phụ thuộc: File này import ai và những file nào import file này.
code_graph_get_structure
Lấy toàn bộ cây cấu trúc outline (classes, functions) trong 1 file.
code_graph_scan_project
Kích hoạt quét gia tăng hoặc quét toàn bộ workspace để cập nhật SQLite.
code_graph_stats
Xem tổng quan số file, số ký hiệu, số quan hệ gọi hàm và phân bố ngôn ngữ.

⚙️

Cấu Hình MCP & Lệnh CLI Nhanh

Cấu hình trong /root/.gemini/config/mcp_config.json hoặc ~/.claude.json:

{
  "mcpServers": {
    "lotus-code-graph": {
      "command": "python3",
      "args": [
        "/root/BUDDHA/.../B38_Code_Graph/app/mcp_stdio.py"
      ],
      "env": {
        "CODE_GRAPH_DB": ".../code_graph.sqlite",
        "WORKSPACE_DIR": "/root/BUDDHA/..."
      }
    }
  }
}

Dòng lệnh CLI tra cứu trực tiếp từ terminal:

# Quét gia tăng / toàn bộ workspace
python3 app/cli.py scan [--full]

# Tra cứu ký hiệu & nơi gọi
python3 app/cli.py search get_callers
python3 app/cli.py callers WorkspaceScanner

# Xem quan hệ phụ thuộc & outline cấu trúc
python3 app/cli.py deps app/server.py
python3 app/cli.py struct app/graph_engine.py

Tiêu Chí So Sánh	Grep / Ripgrep Truyền Thống ❌	AST Code Graph (B38) ✅	Ưu Thế Vượt Trội
Lượng Token Tiêu Thụ	50,000 – 150,000 tokens (đọc cả file/đoạn dài)	200 – 500 tokens (chỉ đúng symbol & chữ ký)	Tiết kiệm 95% chi phí API
Độ Chính Xác Ngữ Nghĩa	Thấp (dễ dính comment, chuỗi string, file log)	Tuyệt đối 100% (AST phân giải chính xác cú pháp)	Không bị ảo giác hoặc kết quả rác
Tốc Độ Truy Vấn	Quét đĩa hàng trăm file (100ms – 2000ms)	Truy vấn B-Tree Index SQLite (1 – 5ms)	Nhanh gấp 100 lần
Truy Vết Callers & Callees	Gần như không thể (chỉ tìm thấy từ khóa)	Trích xuất toàn bộ quan hệ gọi hàm chính xác	Hỗ trợ Refactor an toàn tuyệt đối

🧮 Bảng Tính Ước Lượng Tiết Kiệm Token Cho Agent

Kéo thanh trượt bên dưới để xem lượng token và chi phí tiết kiệm được trong một ngày làm việc của Claude Code / Antigravity:

            10 lượt tra cứu
            100 lượt tra cứu/ngày
            500 lượt tra cứu
          

Grep Truyền Thống

6,000,000

Tokens nạp vào context

Code Graph (B38)

40,000

Tokens nạp vào context

Tiết Kiệm Ròng

5,960,000 (99.3%)

Tránh tràn context window

Quy Trình Quản Lý Đa Dự Án (Thêm / Xóa Dự Án Vào B38)

B38 hỗ trợ quản lý nhiều repository / workspace độc lập trong cùng một cơ sở dữ liệu SQLite duy nhất. Dưới đây là hướng dẫn từng bước chi tiết để gắn thêm một dự án mới hoặc xóa sạch một dự án cũ ra khỏi hệ thống.

CƠ CHẾ BẢO VỆ DỮ LIỆU

ON DELETE CASCADE

Cô lập hoàn toàn theo Project ID

🏛️

Kiến Trúc Cô Lập Dữ Liệu Đa Dự Án (Data Isolation)

Trong B38, mỗi dự án được định danh bằng một bản ghi trong bảng projects. Toàn bộ file mã nguồn, symbols (hàm/class) và quan hệ liên kết (edges) đều gắn chặt với project_id thông qua ràng buộc khóa ngoại có tính năng Cascade Delete. Khi quét nhiều dự án, các ký hiệu trùng tên giữa các repo không bao giờ bị xung đột.

projects (id, name, root_path)
─── 1:N ───►
files (id, project_id, path, hash)
─── 1:N ───►
symbols & edges (file_id, name, calls)

💡

Nguyên Lý Mapping Thư Mục: REPO_ROOT (/workspace) vs Dự Án Bên Ngoài

Hiểu đúng cơ chế đường dẫn container để thao tác chính xác

Cơ chế Volume mặc định: Trong docker-compose.yml, B38 đã mount ${REPO_ROOT}:/workspace:ro. Do đó, mọi thư mục con trong kho lưu trữ hiện tại khi đứng từ trong container B38 đều có tiền tố là /workspace/....

📁

Kịch Bản 1: Dự Án Thuộc REPO_ROOT

Áp dụng cho các dự án con (ví dụ: Application/APP_5..., Library/...).

                  Host: .../PRODUCTION_HOST_PC/Application/APP_5

                  ➔ Container Path: /workspace/Application/APP_5

✅ Thao tác: 100% trên Web Portal (Nhập đường dẫn dạng /workspace/...). Không cần sửa docker-compose.

🌐

Kịch Bản 2: Dự Án Nằm Ngoài REPO_ROOT

Áp dụng khi bạn có repo độc lập khác (ví dụ: /root/OTHER_REPO).

                  Bước 1: Mount volume vào docker-compose:

                  - /root/OTHER_REPO:/workspace_other:ro

                  Bước 2: Lên Web nhập: /workspace_other

⚠️ Bắt buộc: Phải map volume vào docker-compose.yml trước, chạy docker compose up -d lotus_code_graph, rồi mới lên Web quét!

Quy Trình Thêm Dự Án Mới Chi Tiết

Map Volume (Nếu Ngoài Repo)

Chỉ cần khi dự án nằm ngoài REPO_ROOT

Nếu dự án nằm ngoài ${REPO_ROOT}, thêm dòng sau vào docker-compose.yml:

# docker-compose.yml (lotus_code_graph)
volumes:
  - ${REPO_ROOT}:/workspace:ro
  # Map dự án bên ngoài:
  - /root/OTHER_REPO:/workspace_other:ro

Chạy docker compose up -d lotus_code_graph để cập nhật container.

Lên Web Nhập Đường Dẫn

Tab ⚙️ Cấu Hình & Dự Án

Mở http://172.16.10.220:20380/ ➔ Bấm ➕ Thêm Dự Án Mới:

Tên Dự Án: Ví dụ APP_5_GPM_CLIENT hoặc OTHER_PROJECT
Đường Dẫn Container: /workspace/Application/APP_5_GPM_CLIENT_PRO (nếu trong repo) hoặc /workspace_other (nếu ngoài repo).

Kích Hoạt Quét & Sử Dụng

AI Agent & Explorer

Bấm 🚀 Thêm Dự Án & Quét:

Backend phân tích toàn bộ file mã nguồn AST trong vài giây.
Lập tức hiển thị số liệu lên Dashboard.
AI Agent tự động tìm kiếm được các hàm, class của dự án mới qua MCP mà không cần sửa file mcp_config.json.

Quy Trình 1-Click Xóa Dự Án Trên Giao Diện Web

🗑️

1 Click Xóa Sạch Khỏi Database (Web Action)

Xóa vĩnh viễn AST symbols, edges & files

Không cần gõ lệnh SQL hay dòng lệnh phức tạp:

Tại bảng danh sách dự án của Tab ⚙️ Cấu Hình & Dự Án, tìm dự án cần xóa.
Bấm nút 🗑️ Xóa màu đỏ bên cạnh dự án.
Xác nhận trong hộp thoại popup cảnh báo an toàn.
Cơ chế ON DELETE CASCADE của SQLite tự động quét sạch 100% files, symbols, calls liên quan trong 0.1 giây.

🐳

Gỡ Volume Docker (Chỉ áp dụng nếu là Thư mục Ngoài)

docker-compose.yml

Nếu trước đây bạn từng thêm volume riêng biệt cho dự án đó trong docker-compose.yml:

# docker-compose.yml (Xóa hoặc comment dòng volume cũ)
volumes:
  - ${DCP_ROOT}/B38_Code_Graph/app:/app/app:ro
  - ${DCP_ROOT}/B38_Code_Graph/data:/app/data
  - ${REPO_ROOT}:/workspace:ro
  # - /root/PATH_PROJ_NGOAI:/workspace_ngoai:ro (Đã xóa)

* Nếu dự án nằm sẵn trong thư mục /workspace mặc định thì KHÔNG CẦN làm bước này!

❓

Các Câu Hỏi Kỹ Thuật Thường Gặp (FAQs)

Q1: Khi thêm dự án trên Web, tôi có cần khởi động lại container B38 không?

Trả lời: Không cần khởi động lại. Backend FastAPI sẽ nhận request và kích hoạt tiến trình quét ngầm ngay lập tức, tự động ghi nhận vào SQLite và cập nhật số liệu lên Dashboard.

Q2: Trong file mcp_config.json của IDE / Claude Code có cần cấu hình thêm gì cho dự án thứ 2 không?

Trả lời: Hoàn toàn không cần cấu hình thêm. MCP server lotus-code-graph kết nối trực tiếp vào file SQLite chung. Tất cả các tool như code_graph_search_symbol, code_graph_get_callers đều tự động nhận diện và tra cứu trên toàn bộ các dự án đã được scan trong DB.

Q3: Nút 'Quét Nhanh (Incremental)' và 'Full Scan' trên Web khác nhau thế nào?

Trả lời: Quét Nhanh sẽ kiểm tra thời gian sửa đổi (mtime) và MD5 hash của từng file, chỉ phân tích lại các file vừa thay đổi (thời gian quét chỉ 1-3 giây). Full Scan sẽ xóa bộ nhớ đệm và phân tích lại toàn bộ 100% các file từ đầu.

🌐 Cổng Quản Trị Web Portal & Dashboard Đa Dự Án (Port 20380)

Giao diện Web đồ họa trực quan giúp Developer và DevOps quản lý toàn bộ hệ thống Code Graph mà không cần đụng tới dòng lệnh CLI: theo dõi số liệu real-time, thêm/xóa/quét dự án 1-click, và lấy mẫu prompt tối ưu cho AI Agent.

🚀 Mở Web Portal (:20380) Real-time Metrics 1-Click Scan & Manage

🎯

3 Phân Hệ Chính Trên Giao Diện Web Portal B38

📊

1. Dashboard Thống Kê

Hiển thị số lượng dự án, tổng files, symbols, graph edges. Cung cấp danh sách dự án với thời điểm Full Scan và Update gần nhất, phân bố ngôn ngữ, top 10 ký hiệu được gọi nhiều nhất và nhật ký tần suất truy vấn real-time.

⚙️

2. Cấu Hình & Dự Án GUI

Thêm dự án mới qua Modal (nhập Tên & Thư mục nguồn, tự động Full Scan). Nút ⚡ Full Scan và 🔄 Quét Nhanh cho từng dự án, nút 🗑️ Xóa Dự Án (CASCADE) 1-click an toàn, kèm trợ lý cấu hình Docker Volume.

📖

3. Hướng Dẫn & AI Prompts

Tổng hợp bảng so sánh tiết kiệm token giữa Code Graph vs Grep thô. Cung cấp sẵn mẫu câu System Prompt tối ưu cho Claude Code (CLAUDE.md) và Gemini/Antigravity (GEMINI.md) để ép AI ưu tiên dùng Code Graph.

💻

Cách Truy Cập & Thao Tác Nhanh Trên Web Portal

Đường Dẫn Truy Cập Web Trực Tiếp:

Trong mạng nội bộ LAN: http://172.16.10.220:20380/
Trên máy chủ HP1 localhost: http://127.0.0.1:20380/
Trực tiếp qua noVNC B35 Chrome: mở tab mới và gõ http://114.114.114.38:8080/

Quy Trình 1-Click Thêm Dự Án Mới Trên Giao Diện Web:

Bấm tab ⚙️ Cấu Hình & Dự Án trên thanh điều hướng đầu trang.
Bấm nút ➕ Thêm Dự Án Mới.
Điền tên dự án (ví dụ: APP_5_GPM_CLIENT) và đường dẫn thư mục trong workspace (ví dụ: /workspace/Application/APP_5_GPM_CLIENT_PRO).
Tích chọn "Tự động quét Full Scan ngay sau khi thêm" và bấm 🚀 Thêm Dự Án & Quét.
Hệ thống tự động kích hoạt tiến trình nền, phân tích toàn bộ AST và cập nhật chỉ số lên Dashboard ngay lập tức!

B38 Code Graph & AST Engine

Kiến Trúc Tổng Thể Dịch Vụ B38