Tài liệu Grapuco

Mọi thứ bạn cần để cài đặt, lập chỉ mục và truy vấn codebase của bạn.

rocket_launch

1. Bắt đầu nhanh

1. Lấy API Key

Đăng ký và tạo một API Key để xác thực CLI hoặc công cụ MCP.

2. Cài đặt CLI

Grapuco CLI là công cụ giúp quét mã nguồn cục bộ. Hãy chạy lệnh sau trên máy bạn để cài đặt trọn gói:

npm install -g @bitsness/grapuco-cli

3. Ingest Data

Tại thư mục gốc dự án của bạn, hãy gõ lệnh dưới đây. Động cơ đồ thị sẽ quét toàn bộ kiến trúc và tải chúng lên Cloud trong chớp mắt.

grapuco ingest
account_tree

2. Đồ thị Kiến trúc (Architecture Graph)

Ngay khi phân tích xong, codebase của bạn biến thành một Đồ thị Tri thức trực quan. Cách đọc bản đồ như sau:

Filters (Bộ lọc)

Cho phép cấu hình hiển thị bản đồ tuỳ ý. Bạn có thể bật tắt hiển thị theo loại File (API, DB, Giao diện) hoặc dọn dẹp các nhánh phụ / utility folder để tập trung vào luồng chính.

Explorer (Duyệt đồ thị)

Điều hướng xuyên suốt dự án một cách trực quan. Nhấp vào bất kỳ điểm ảnh nào để mở rộng các luồng liên đới, kiểm tra thuộc tính hoặc các đường nối tới/về nội bộ.

Flows (Tiến trình)

Danh sách các nhánh nghiệp vụ được hệ thống biên dịch tự động phát hiện. Bấm chọn vào 1 API Endpoint bất kì để kích hoạt hiệu ứng phát sáng xuyên suốt từ Controller xuống tận dưới CSDL.

hub

3. Tích hợp MCP Server

MCP (Model Context Protocol) là chuẩn mở cho phép các trợ lý AI lập trình như Claude, Cursor và Windsurf kết nối trực tiếp tới nguồn dữ liệu bên ngoài. Khi bạn kết nối Grapuco làm MCP Server, trợ lý AI của bạn sẽ hiểu trọn vẹn cấu trúc codebase - nắm bắt chuỗi gọi hàm, dò luồng dữ liệu, và phân tích tác động trước khi viết bất kỳ dòng code nào.

Kết nối AI Agent của bạn

codeAntigravity / Cursor / Windsurf

Dán khối JSON này vào phần cấu hình MCP Server Raw Config (Settings → MCP Servers):

{
  "mcpServers": {
    "grapuco": {
      "url": "https://api.grapuco.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
terminalClaude Code (CLI)

Chạy lệnh sau trong Terminal để đăng ký Grapuco làm nguồn MCP:

claude mcp add --transport http grapuco https://api.grapuco.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

Thay YOUR_API_KEY bằng khoá API từ trang API Keys trong Grapuco Dashboard.

Các công cụ MCP được cung cấp

Sau khi kết nối, trợ lý AI sẽ tự động gọi các công cụ phù hợp. Bạn không cần gõ lệnh thủ công - chỉ cần hỏi AI bất kỳ câu hỏi nào về codebase và nó sẽ tự chọn công cụ đúng.

folder_open

list_repositories

Liệt kê tất cả repository bạn đã lập chỉ mục trên Grapuco. Đây là bước khởi đầu - AI sẽ gọi lệnh này trước tiên để tìm đúng Repository ID trước khi chạy bất kỳ công cụ nào khác.

manage_search

search_code

Tìm kiếm hàm, lớp hoặc phương thức theo tên chính xác trong đồ thị mã nguồn. Giống như tính năng tìm kiếm thông minh của IDE, nhưng hoạt động xuyên suốt toàn bộ bản đồ kiến trúc - không chỉ dò text đơn thuần.

psychology

semantic_search

Tìm kiếm codebase bằng tiếng Việt hoặc tiếng Anh tự nhiên thay vì từ khóa chính xác. Ví dụ: hỏi "chỗ nào xác thực JWT token?" và Grapuco sẽ trả về các symbol liên quan nhất thông qua so sánh vector (cosine similarity).

device_hub

get_dependencies

Cho một hàm hoặc lớp cụ thể, công cụ này trả về toàn bộ cây phụ thuộc: những gì nó GỌI (CALLS), những gì nó NHẬP (IMPORTS), và những gì nó KẾ THỪA (EXTENDS). Lý tưởng để hiểu một đoạn code kết nối sâu đến đâu.

account_tree

get_architecture

Trả về toàn bộ bản đồ kiến trúc của repository - mọi điểm (hàm, lớp, endpoint) và mọi đường kết nối (gọi, nhập, kế thừa). AI sẽ dùng công cụ này để nắm bắt bức tranh tổng thể trước khi thực hiện thay đổi.

auto_awesome

get_context

Truy xuất ngữ cảnh thông minh bằng AI. Đặt tên tính năng như "luồng xác thực người dùng" và nó sẽ trả về các symbol liên quan, chuỗi gọi hàm và tài liệu. Tiêu tốn 5 AI credit mỗi lần truy vấn. Phù hợp nhất khi mới onboard vào codebase xa lạ.

route

get_data_flows

Dò vết toàn bộ luồng thực thi đầu-cuối: từ HTTP API Endpoint qua Service rồi xuống tới thao tác cơ sở dữ liệu. Cho thấy chính xác cách một request di chuyển qua hệ thống - lý tưởng cho việc debug và hiểu logic nghiệp vụ.

warning

get_impact_analysis

Trình phát hiện "Bán kính Công phá" (Blast Radius). Chỉ vào bất kỳ file nào và nó sẽ phơi bày mọi API endpoint, thao tác database và workflow sẽ bị ảnh hưởng nếu file đó thay đổi. Không thể thiếu trước khi refactor hoặc deploy thay đổi rủi ro cao.

terminal

4. Hướng dẫn CLI chi tiết

Grapuco CLI chạy hoàn toàn trên máy cá nhân của bạn. Nó phân tích AST (Cây cú pháp trừu tượng) của codebase và chỉ trích xuất siêu dữ liệu cấu trúc - tên hàm, quan hệ gọi hàm, bản đồ import. Tuyệt đối không có dòng mã nguồn nào rời khỏi máy bạn.

key

grapuco login

Xác thực CLI với Grapuco cloud. Bạn có thể truyền API key trực tiếp qua cờ --api-key, hoặc chạy lệnh không có tham số để nhập thủ công theo hình thức tương tác. Thông tin đăng nhập được lưu an toàn tại ~/.grapuco/credentials.json.

grapuco login --api-key YOUR_API_KEY
--api-key <key> - Truyền API key trực tiếp (bỏ qua hỏi tương tác)
--server <url> - URL server tuỳ chỉnh (mặc định: https://api.grapuco.com)
folder_open

grapuco init

Khởi tạo dự án Grapuco mới tại thư mục hiện tại. CLI tự động nhận diện ngôn ngữ lập trình và framework (NestJS, Next.js, Django, Spring Boot...), tạo file .grapuco/config.json và đăng ký repository mới trên server.

grapuco init
--name <name> - Tên repository tuỳ chỉnh (mặc định: tên thư mục)
--link <repoId> - Liên kết tới repository đã tồn tại thay vì tạo mới
--server <url> - URL server tuỳ chỉnh
cloud_upload

grapuco ingest

Lệnh cốt lõi. Quét toàn bộ file trong dự án, xây dựng bản phân tích AST cục bộ, sau đó chỉ tải lên siêu dữ liệu (nodes + edges) lên Grapuco cloud. Đây là đồng bộ toàn phần - dùng cho lần chạy đầu tiên hoặc khi bạn muốn làm mới hoàn toàn.

grapuco ingest
--embeddings - Bật vector embeddings cho tìm kiếm ngữ nghĩa
--flows - Bật phân tích Data Flow (API → Service → DB)
--all - Bật tất cả tính năng
--dry-run - Chỉ phân tích cục bộ, không tải lên server
sync

grapuco push

Đồng bộ gia tăng thông minh. So sánh hash file với lần push trước và chỉ phân tích lại các file đã thay đổi (thêm mới, sửa đổi hoặc xóa). Nhanh hơn đáng kể so với ingest toàn phần - lý tưởng cho quy trình phát triển hàng ngày.

grapuco push
--force - Bỏ qua cache delta, ingest lại toàn bộ
--enrich-flows - Chạy lại phân tích Data Flow cho các file đã thay đổi
visibility

grapuco watch

Trình theo dõi file thời gian thực. Giám sát thư mục dự án bằng chokidar và tự động kích hoạt delta push mỗi khi bạn lưu file. Cấu hình khoảng thời gian debounce để kiểm soát tần suất đồng bộ. Nhấn Ctrl+C để dừng.

grapuco watch
--debounce <ms> - Khoảng thời gian debounce tính bằng mili giây (mặc định: 2000)
preview

grapuco inspect

Công cụ minh bạch. Phân tích dự án cục bộ và hiển thị chính xác dữ liệu nào sẽ được gửi tới server - mà không thực sự gửi. Hoàn hảo cho kiểm toán bảo mật hoặc xác minh rằng không có mã nguồn nào bị bao gồm trong payload.

grapuco inspect --json
--json - Xuất JSON đầy đủ thay vì tóm tắt
info

grapuco status

Dashboard ngay trong Terminal. Hiển thị cấu hình dự án, ngôn ngữ/framework đã phát hiện, các cờ tính năng (embeddings, data flows), thời gian push cuối cùng, số file đã cache và trạng thái repository từ xa (số node/edge).

grapuco status