Sổ tay công thức

Các hướng dẫn thực hành cho công việc Maguyva MCP hằng ngày. Mỗi hướng dẫn nêu rõ công cụ và trình tự sử dụng — không phải tài liệu tham chiếu đầy đủ về tham số. Xem tham số công cụ trong Tham khảo MCP API. Nếu thiết lập lần đầu, hãy xem Bắt đầu nhanh.

Các khối JSON là dữ liệu đầu vào cho MCP tools/call. Thay owner/repo, tên nhánh và tên ký hiệu bằng các giá trị trong kho mã của bạn.

Hầu hết câu hỏi bắt đầu bằng một lần gọi công cụ. Chỉ chuyển sang bước chuyên sâu hơn khi câu trả lời đầu tiên quá rộng hoặc thiếu thông tin.

• intelligent_search — bắt đầu tại đây với câu hỏi về mã nguồn bằng ngôn ngữ tự nhiên. Chế độ mặc định auto/balanced chuyển các truy vấn được nhận diện chắc chắn là hỏi về định nghĩa sang tìm kiếm cấu trúc, truy vấn về tham chiếu hoặc tác động sang đồ thị, và truy vấn cần khớp chính xác sang tìm kiếm văn bản. Các truy vấn khác dùng ngữ nghĩa và văn bản đã lập chỉ mục. Dùng mode=hybrid hoặc auto với quality=thorough để yêu cầu cả bốn phương thức tìm kiếm; chế độ được chỉ định rõ có ưu tiên cao hơn quality.
• find_symbol - bạn đã biết hàm, lớp hoặc tên biến.
• dependency_search — phạm vi ảnh hưởng: các hàm gọi, thành phần phụ thuộc vào đoạn code này hoặc tác động trước (và sau) khi chỉnh sửa.
• get_task_context — khu vực chưa quen thuộc; một gói có giới hạn gồm tệp, symbol và quan hệ phụ thuộc ứng với mô tả nhiệm vụ.
• repository_context — liệt kê các repository có thể truy cập hoặc kiểm tra cách phân giải tên repository.
• ask_maguyva với operation="guidance" — trợ giúp cục bộ về lựa chọn công cụ và cách sử dụng Maguyva (không thay đổi repo).

Đưa Maguyva vào MCP client của bạn và xác nhận kết nối với danh sách kho lưu trữ thực.

1. Tạo khóa API trong app.maguyva.ai (các khóa bắt đầu bằng mgv_).
2. Kết nối và lập chỉ mục ít nhất một kho lưu trữ GitHub mà bạn đã hiểu.
3. Kết nối client theo Hướng dẫn cài đặt (plugin Claude Code, hoặc cấu hình kết nối từ xa trực tiếp cho Cursor, VS Code, Devin Desktop, Zed và các client khác).
4. Hỏi agent của bạn "Tôi đã kết nối những kho lưu trữ nào?" — bước này kiểm tra xác thực và repository_context từ đầu đến cuối.
5. Đặt một câu hỏi thực tế về repo đó mà bạn có thể đánh giá câu trả lời. Kết quả phải kèm đường dẫn tệp và số dòng trong cây mã đã lập chỉ mục.

{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}

Gặp vấn đề với khóa API, cầu nối hoặc repo bị thiếu? Xem Khắc phục sự cố.

Lập bản đồ symbol và phạm vi ảnh hưởng trước khi thay đổi mã dùng chung. Công cụ Maguyva không sửa repository của bạn — chúng cung cấp thông tin cho việc chỉnh sửa mà client thực hiện cục bộ.

1. Nếu bạn biết tên symbol, hãy gọi find_symbol để tìm hiểu định nghĩa và cách sử dụng.
2. Nếu bạn chỉ có mô tả nhiệm vụ ("thêm SSO", "sửa webhook thanh toán"), hãy bắt đầu với get_task_context hoặc intelligent_search.
3. Trước khi chỉnh sửa một symbol dùng chung, gọi dependency_search với chế độ phân tích dependents/impact (các thành phần phụ thuộc vào nó/tác động của thay đổi), hoặc truyền đường dẫn đã thay đổi để phân tích tác động theo kiểu PR, qua đó biết phạm vi ảnh hưởng.
4. Mở các tệp được trích dẫn (đọc cục bộ cho các tệp trên đĩa; get_file cho các đường dẫn từ xa/repo chéo) và xác nhận kế hoạch dựa trên mã thực.
5. Sau khi chỉnh sửa, kiểm tra lại các ký hiệu đó bằng dependency_search với verify_after_edit=true và targets hoặc changed_paths. Công cụ đọc đồ thị đã lập chỉ mục, không đọc thay đổi cục bộ chưa được commit: hãy kiểm tra indexed_commit_sha và độ cập nhật của chỉ mục trước khi coi kết quả là bằng chứng cho phiên bản mới, đồng thời chạy kiểm thử cục bộ.

{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}

Thông số đầy đủ: Tham khảo MCP API.

Quy trình agent mặc định: khám phá → xác định symbol → chỉnh sửa dựa trên bằng chứng.

1. Bắt đầu với intelligent_search và một truy vấn bằng ngôn ngữ đơn giản ("thời gian hết hạn phiên hoạt động như thế nào", "logic thử lại ở đâu").
2. Thu hẹp kết quả bằng bộ lọc ngôn ngữ hoặc đường dẫn nếu cửa sổ kết quả đầu tiên có nhiều thông tin không liên quan. language_filter loại đồ thị khỏi auto/hybrid; truy vấn auto được chuyển riêng tới đồ thị sẽ quay về tìm kiếm ngữ nghĩa và văn bản. Yêu cầu bị từ chối nếu chỉ định rõ chế độ đồ thị cùng với language_filter. Xem routing_decision.modalities_used để biết kế hoạch tìm kiếm đã chọn; warnings chỉ xuất hiện khi máy chủ đưa ra cảnh báo.
3. Dùng find_symbol hoặc dependency_search để tìm hiểu sâu hơn các kết quả triển vọng, thay vì lặp lại cùng một câu hỏi mơ hồ.
4. Chỉ sử dụng get_file khi bạn cần một đường dẫn được lập chỉ mục cụ thể không có trên đĩa.
5. Chỉnh sửa bằng các công cụ thông thường trong client của bạn. Maguyva dùng để khám phá và xác minh — không dùng để ghi.

{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}

Tại sao vòng lặp này hoạt động: Nó hoạt động như thế nào.

Khi công cụ không trả về kết quả hữu ích, hãy sửa việc phân giải repository và lập chỉ mục trước khi cứ viết lại truy vấn mãi.

1. Xác nhận kho lưu trữ đã được kết nối và lập chỉ mục xong trong app.maguyva.ai.
2. Kiểm tra chuỗi repository: "owner/repo" dùng nhánh mặc định; "owner/repo:branch" chỉ định một nhánh. So khớp không phân biệt chữ hoa chữ thường, nhưng không phải so khớp gần đúng — lỗi chính tả không được tự sửa.
3. Gọi repository_context với action="info" và kiểm tra metadata phân giải (ví dụ metadata.resolution_reason).
4. Chỉ bỏ repository khi MCP client cung cấp giá trị mặc định cho yêu cầu hoặc khóa có thể truy cập đúng một repository; nếu không, hãy truyền tham số này rõ ràng.
5. Thử lại bằng một truy vấn cụ thể hơn, tên symbol đã biết qua find_symbol hoặc bộ lọc ngôn ngữ/đường dẫn. Nếu kết nối bị hỏng, hãy sử dụng Khắc phục sự cố.

{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}

Lỗi thiết lập: Khắc phục sự cố.

Nhắm mục tiêu kho lưu trữ được lập chỉ mục phù hợp khi một khóa có thể nhìn thấy nhiều kho lưu trữ.

1. Gọi repository_context với action="list" một lần để biết chính xác các slug repository mà khóa của bạn có thể tìm kiếm.
2. Truyền repository một cách rõ ràng trên các công cụ tìm kiếm và symbol khi bạn cần một kho lưu trữ không mặc định (ví dụ: "owner/other-repo" hoặc "owner/other-repo:develop").
3. Giữ một câu hỏi = một kho lưu trữ trừ khi bạn cố tình so sánh giữa các kho lưu trữ trong các lệnh gọi riêng biệt.
4. Sử dụng get_file khi tệp nằm trong kho lưu trữ được lập chỉ mục không phải là cây làm việc hiện tại của bạn.
5. Hãy nhớ: các công cụ không bao giờ ghi lại vào GitHub — multi-repo context chỉ dành cho việc đọc và lập kế hoạch.

Chi tiết định dạng kho lưu trữ: Tham khảo MCP API.

• Bắt đầu nhanh — khóa API, chỉ mục, kết nối, câu trả lời đầu tiên được kiểm chứng
• Hướng dẫn cài đặt — cấu hình MCP cho từng client
• Tham khảo MCP API — mọi công cụ, tham số theo tham số
• Khắc phục sự cố — sự cố khóa API, cầu nối và repository