Tài liệu tham chiếu API MCP

Tài liệu tham chiếu đầy đủ cho toàn bộ 11 công cụ MCP Maguyva dành cho khách hàng. Mỗi công cụ đều bao gồm tham số, hướng dẫn sử dụng, và khuyến nghị trường hợp phù hợp.

Tổng quan API#

API MCP của Maguyva hiện đang cung cấp 11 công cụ dành cho khách hàng trên 4 danh mục chính:

Công cụ tìm kiếm cốt lõi - Khả năng tìm kiếm nâng cao trên toàn bộ codebase của bạn
Công cụ cấu trúc & Graph - Truy vấn AST, tra cứu symbol, và phân tích phụ thuộc
Công cụ phân tích code - Phân tích code chuyên sâu và ánh xạ mối quan hệ
Công cụ hệ thống & tiện ích - Context repository, tính toán tất định, và hướng dẫn

Mọi công cụ đều dùng một định dạng định danh repository nhất quán: "owner/repo:branch". Branch mặc định là main nếu không được chỉ định.

Bỏ repository khi MCP client của bạn cung cấp mặc định theo từng yêu cầu hoặc khi khóa có thể truy cập đúng một repository; ngược lại, truyền rõ ràng. Dùng repository_context(action="info", repository="owner/repo") để kiểm tra cách một repository được phân giải.

Định dạng tham số Repository#

Mọi công cụ MCP đều dùng định dạng định danh repository này:

Có branch: "owner/repo:branch" - ví dụ, "owner/repository:develop"
Branch mặc định: "owner/repo" - dùng nhánh chính khi không chỉ định nhánh "owner/repository"
Mặc định theo yêu cầu hoặc repository duy nhất: Bỏ repository khi MCP client cung cấp giá trị mặc định cho yêu cầu hoặc khóa chỉ truy cập được đúng một repository; nếu không, hãy truyền rõ ràng.

Ví dụ prompt:

Hỏi về một repo cụ thể:            "Tìm middleware xác thực trong owner/my-repo"
Liệt kê các repo có thể truy cập:  "Khóa Maguyva này có thể truy cập những repo nào?"
Ghi đè cho một truy vấn:           "Tìm các mẫu xác thực trong owner/other-repo:develop"

Lọc theo ngôn ngữ#

Mọi công cụ tìm kiếm đều hỗ trợ lọc kết quả theo ngôn ngữ lập trình:

language_filter="python" - Chỉ lọc file Python
language_filter="typescript" - Chỉ lọc file TypeScript
Phân biệt hoa thường: Dùng tên ngôn ngữ viết thường
Mặc định: Chuỗi rỗng (không lọc) - trả về kết quả từ mọi ngôn ngữ
Phạm vi hỗ trợ: Bộ lọc ngôn ngữ hoạt động trên toàn bộ 279+ ngôn ngữ và công nghệ dựa trên văn bản được hỗ trợ. Xem tương thích để có danh sách đầy đủ.

"Tìm auth middleware chỉ trong các file Python"
"Tìm kiếm kết nối cơ sở dữ liệu trong TypeScript"

Tài liệu tham chiếu API được sinh từ mã nguồn vào 22 tháng 7, 2026.

Công cụ tìm kiếm cốt lõi#

intelligent_searchỔn định

Bắt đầu ở đây cho bất kỳ câu hỏi về cơ sở mã nào. Cung cấp cho nó một truy vấn bằng ngôn ngữ tự nhiên (ví dụ: "xác thực hoạt động như thế nào", "thanh toán được xử lý ở đâu") và nó tự động định tuyến qua tìm kiếm ngữ nghĩa, ký hiệu, cấu trúc và phụ thuộc của kho lưu trữ được lập chỉ mục. Thích điều này hơn tác nhân Explore và Grep/Glob để khám phá và lập kế hoạch - nó tìm kiếm toàn bộ kho lưu trữ được lập chỉ mục cùng một lúc thay vì quét các tệp.

Tham số:

queryBắt buộc

Kiểu: str
Mô tả: Truy vấn tìm kiếm

repositoryTùy chọn

Kiểu: str
Mô tả: Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.

modeTùy chọn

Kiểu: Literal[auto, hybrid, semantic, text, structural, ast, graph]
Mặc định: auto
Mô tả: Chế độ tìm kiếm

limitTùy chọn

Kiểu: int
Mặc định: 10
Mô tả: Số kết quả tối đa trong cửa sổ top-K được xếp hạng này

language_filterTùy chọn

Kiểu: str
Mô tả: Bộ lọc ngôn ngữ

path_filterTùy chọn

Kiểu: str
Mô tả: Lọc theo tiền tố đường dẫn file

boost_by_importanceTùy chọn

Kiểu: bool
Mặc định
Mô tả: Tùy chọn: xếp hạng lại theo centrality bằng graph metrics cho từng symbol (is_articulation_point, bridge_count, k_core, centrality, v.v.). Mặc định tắt để xếp hạng an toàn cho agent (các hub toàn cục có thể lấn át kết quả implementation); bật khi cần tham quan kiến trúc. Áp dụng trên cả 4 modality khi mỗi kết quả mang symbol linkage.

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (chỉ áp dụng cho một lần gọi)

qualityTùy chọn

Kiểu: Literal[quick, balanced, thorough]
Mặc định: balanced
Mô tả: Preset chất lượng tìm kiếm

include_contentTùy chọn

Kiểu: bool
Mặc định: true
Mô tả: Bao gồm nội dung trong kết quả

explain_routingTùy chọn

Kiểu: bool
Mặc định
Mô tả: Bao gồm giải thích quyết định routing

importance_weightTùy chọn

Kiểu: float
Mặc định: 0.3
Mô tả: Trọng số cho tăng cường tầm quan trọng (0=không, 1=đầy đủ)

orphansTùy chọn

Kiểu: bool
Mặc định
Mô tả: Bao gồm symbol cô lập (không có reference đến) — hữu ích để dọn dẹp nhưng có thể gồm decorator, hàm lồng, hoặc entry point CLI.

include_community_contextTùy chọn

Kiểu: bool
Mặc định
Mô tả: Bao gồm các symbol liên quan từ cùng code community để có context rộng hơn

community_depthTùy chọn

Kiểu: int
Mặc định: 1
Mô tả: Độ sâu mở rộng context community

graph_viewTùy chọn

Kiểu: Literal[dependency, type, data_flow, control_flow]
Mặc định: dependency
Mô tả: Chế độ hiển thị graph cho metrics

seed_symbol_idsTùy chọn

Kiểu: list[str]
Mô tả: Hạt nhiệm vụ Tier-1: ID biểu tượng trung tâm của nhiệm vụ hiện tại. Khi được đặt, hãy xếp hạng lại các lần truy cập hợp nhất theo độ gần giảm độ sâu Approach A (khớp hạt giống chính xác + bước nhảy cạnh biểu đồ). Phụ gia - bỏ qua xếp hạng toàn cầu.

seed_file_pathsTùy chọn

Kiểu: list[str]
Mô tả: Hạt tác vụ Tier-1: đường dẫn tệp được lập chỉ mục mà tác nhân đã mở hoặc vừa chỉnh sửa. Khi được đặt, hãy sắp xếp lại các lần truy cập hợp nhất theo độ gần của đường dẫn với độ sâu phân rã 1/(1+d) (cùng một tệp → cùng một thư mục → các gói gần đó). Phụ gia - bỏ qua xếp hạng toàn cầu.

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`query`	`str`	Có	-	Truy vấn tìm kiếm
`repository`	`str`	Không	-	Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	Không	`auto`	Chế độ tìm kiếm
`limit`	`int`	Không	`10`	Số kết quả tối đa trong cửa sổ top-K được xếp hạng này
`language_filter`	`str`	Không	-	Bộ lọc ngôn ngữ
`path_filter`	`str`	Không	-	Lọc theo tiền tố đường dẫn file
`boost_by_importance`	`bool`	Không		Tùy chọn: xếp hạng lại theo centrality bằng graph metrics cho từng symbol (is_articulation_point, bridge_count, k_core, centrality, v.v.). Mặc định tắt để xếp hạng an toàn cho agent (các hub toàn cục có thể lấn át kết quả implementation); bật khi cần tham quan kiến trúc. Áp dụng trên cả 4 modality khi mỗi kết quả mang symbol linkage.
`branch`	`str`	Không	-	Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
`quality`	`Literal[quick, balanced, thorough]`	Không	`balanced`	Preset chất lượng tìm kiếm
`include_content`	`bool`	Không	`true`	Bao gồm nội dung trong kết quả
`explain_routing`	`bool`	Không		Bao gồm giải thích quyết định routing
`importance_weight`	`float`	Không	`0.3`	Trọng số cho tăng cường tầm quan trọng (0=không, 1=đầy đủ)
`orphans`	`bool`	Không		Bao gồm symbol cô lập (không có reference đến) — hữu ích để dọn dẹp nhưng có thể gồm decorator, hàm lồng, hoặc entry point CLI.
`include_community_context`	`bool`	Không		Bao gồm các symbol liên quan từ cùng code community để có context rộng hơn
`community_depth`	`int`	Không	`1`	Độ sâu mở rộng context community
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Không	`dependency`	Chế độ hiển thị graph cho metrics
`seed_symbol_ids`	`list[str]`	Không	-	Hạt nhiệm vụ Tier-1: ID biểu tượng trung tâm của nhiệm vụ hiện tại. Khi được đặt, hãy xếp hạng lại các lần truy cập hợp nhất theo độ gần giảm độ sâu Approach A (khớp hạt giống chính xác + bước nhảy cạnh biểu đồ). Phụ gia - bỏ qua xếp hạng toàn cầu.
`seed_file_paths`	`list[str]`	Không	-	Hạt tác vụ Tier-1: đường dẫn tệp được lập chỉ mục mà tác nhân đã mở hoặc vừa chỉnh sửa. Khi được đặt, hãy sắp xếp lại các lần truy cập hợp nhất theo độ gần của đường dẫn với độ sâu phân rã 1/(1+d) (cùng một tệp → cùng một thư mục → các gói gần đó). Phụ gia - bỏ qua xếp hạng toàn cầu.

Phù hợp nhất cho:

Khám phá toàn bộ index hoặc cold-start khi chưa rõ nên dùng tool nào
Xếp hạng kết hợp đa phương thức trên semantic, text, structural và graph

Không khuyến nghị cho:

Đã biết tên symbol — dùng trực tiếp find_symbol
Đã biết path trên đĩa — dùng local Read/Grep trước

semantic_searchỔn định

Tìm mã theo ý nghĩa, không phải văn bản chính xác. Sử dụng cho các truy vấn khái niệm như "thử lại logic" hoặc "luồng giới thiệu người dùng" khi bạn không biết tên từ khóa hoặc ký hiệu. Trả về các đoạn mã phù hợp nhất được xếp hạng theo mức độ quan trọng. Thích hơn Grep khi tìm kiếm mang tính khái niệm.

Tham số:

queryBắt buộc

Kiểu: str
Mô tả: Truy vấn tìm kiếm (theo khái niệm, dựa trên ý nghĩa)

repositoryTùy chọn

Kiểu: str
Mô tả: Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.

limitTùy chọn

Kiểu: int
Mặc định: 5
Mô tả: Số kết quả tối đa trong cửa sổ top-K được xếp hạng này

similarity_thresholdTùy chọn

Kiểu: float
Mặc định: 0.6
Mô tả: Ngưỡng điểm tương đồng tối thiểu

language_filterTùy chọn

Kiểu: str
Mô tả: Bộ lọc ngôn ngữ (python, typescript, v.v.)

path_filterTùy chọn

Kiểu: str
Mô tả: Lọc theo tiền tố đường dẫn tệp

boost_by_importanceTùy chọn

Kiểu: bool
Mặc định
Mô tả: Tùy chọn: xếp hạng lại theo PageRank centrality (mặc định tắt để xếp hạng an toàn cho agent; bật khi cần tham quan kiến trúc)

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (mặc định: lấy từ tham số repository hoặc main); chỉ áp dụng cho một lần gọi

include_contentTùy chọn

Kiểu: bool
Mặc định: true
Mô tả: Bao gồm nội dung chunk trong kết quả

graph_viewTùy chọn

Kiểu: Literal[dependency, type, data_flow, control_flow]
Mặc định: dependency
Mô tả: Graph view cho metrics

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`query`	`str`	Có	-	Truy vấn tìm kiếm (theo khái niệm, dựa trên ý nghĩa)
`repository`	`str`	Không	-	Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.
`limit`	`int`	Không	`5`	Số kết quả tối đa trong cửa sổ top-K được xếp hạng này
`similarity_threshold`	`float`	Không	`0.6`	Ngưỡng điểm tương đồng tối thiểu
`language_filter`	`str`	Không	-	Bộ lọc ngôn ngữ (python, typescript, v.v.)
`path_filter`	`str`	Không	-	Lọc theo tiền tố đường dẫn tệp
`boost_by_importance`	`bool`	Không		Tùy chọn: xếp hạng lại theo PageRank centrality (mặc định tắt để xếp hạng an toàn cho agent; bật khi cần tham quan kiến trúc)
`branch`	`str`	Không	-	Ghi đè nhánh (mặc định: lấy từ tham số repository hoặc main); chỉ áp dụng cho một lần gọi
`include_content`	`bool`	Không	`true`	Bao gồm nội dung chunk trong kết quả
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Không	`dependency`	Graph view cho metrics

Phù hợp nhất cho:

Truy vấn khái niệm ("how does auth work?", "caching strategy")
Tìm kiếm tương đồng giữa các gói

Không khuyến nghị cho:

Đã biết tên symbol — dùng find_symbol thay thế
Chuỗi chính xác hoặc thông báo lỗi — dùng text_pattern_search

text_pattern_searchỔn định

Tìm trong nội dung đã lập chỉ mục. Chế độ exact và regex grep toàn bộ tập tin/blob; chế độ fuzzy tìm trong corpus chunk ngữ nghĩa. Phạm vi file và symbol chỉ khả dụng cho fuzzy. Dùng grep cục bộ cho thư mục đã có trên đĩa.

Tham số:

queryBắt buộc

Kiểu: str
Mô tả: Pattern văn bản cần tìm

repositoryTùy chọn

Kiểu: str
Mô tả: Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.

modeTùy chọn

Kiểu: Literal[fuzzy, exact, regex]
Mặc định: exact
Mô tả: Chế độ tìm kiếm

search_scopeTùy chọn

Kiểu: Literal[content, symbols, files]
Mặc định: content
Mô tả: Phạm vi tìm kiếm

limitTùy chọn

Kiểu: int
Mặc định: 5
Mô tả: Số kết quả tối đa được trả về trong trang này

offsetTùy chọn

Kiểu: int
Mô tả: Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.

cursorTùy chọn

Kiểu: str
Mô tả: Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.

language_filterTùy chọn

Kiểu: str
Mô tả: Bộ lọc ngôn ngữ

path_filterTùy chọn

Kiểu: str
Mô tả: Lọc theo tiền tố đường dẫn tệp

case_sensitiveTùy chọn

Kiểu: bool
Mặc định
Mô tả: So khớp phân biệt chữ hoa/thường

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (chỉ áp dụng cho một lần gọi)

fuzzy_algorithmTùy chọn

Kiểu: Literal[hybrid, trigram, levenshtein]
Mặc định: hybrid
Mô tả: Thuật toán so khớp fuzzy

thresholdTùy chọn

Kiểu: float
Mặc định: 0.05
Mô tả: Ngưỡng tương đồng tối thiểu cho fuzzy

semantic_fallbackTùy chọn

Kiểu: bool
Mặc định
Mô tả: Dùng dự phòng sang semantic search nếu không có kết quả

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`query`	`str`	Có	-	Pattern văn bản cần tìm
`repository`	`str`	Không	-	Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.
`mode`	`Literal[fuzzy, exact, regex]`	Không	`exact`	Chế độ tìm kiếm
`search_scope`	`Literal[content, symbols, files]`	Không	`content`	Phạm vi tìm kiếm
`limit`	`int`	Không	`5`	Số kết quả tối đa được trả về trong trang này
`offset`	`int`	Không	-	Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
`cursor`	`str`	Không	-	Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.
`language_filter`	`str`	Không	-	Bộ lọc ngôn ngữ
`path_filter`	`str`	Không	-	Lọc theo tiền tố đường dẫn tệp
`case_sensitive`	`bool`	Không		So khớp phân biệt chữ hoa/thường
`branch`	`str`	Không	-	Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	Không	`hybrid`	Thuật toán so khớp fuzzy
`threshold`	`float`	Không	`0.05`	Ngưỡng tương đồng tối thiểu cho fuzzy
`semantic_fallback`	`bool`	Không		Dùng dự phòng sang semantic search nếu không có kết quả

Phù hợp nhất cho:

Chuỗi chính xác, thông báo lỗi và regex
Khớp trigram fuzzy cho văn bản gần đúng

Không khuyến nghị cho:

Đã biết path trên đĩa — ưu tiên local Grep
Truy vấn khái niệm — dùng semantic_search

Công cụ cấu trúc & đồ thị#

structural_searchỔn định

Ưu tiên preset=functions|classes|methods|imports|variables (hoặc pattern= tự do). Tìm code theo hình dạng AST (không phải văn bản). Các filter cấp trung: name_pattern, node_type, decorator, parent_child. Các filter path/ltree/call thuộc loại advanced — đặt advanced=true khi cố ý dùng chúng; các khóa advanced dạng phẳng vẫn được chấp nhận để tương thích ngược. Cung cấp ít nhất một structural selector.

Tham số:

repositoryTùy chọn

Kiểu: str
Mô tả: Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.

presetTùy chọn

Kiểu: Literal[functions, classes, methods, imports, variables]
Mô tả: Structural selector được khuyến nghị. Mở rộng thành các loại node AST đa ngôn ngữ — functions (định nghĩa function/arrow/method trên nhiều ngôn ngữ); classes (định nghĩa class/struct/impl); methods (định nghĩa method (và function_definition cho các ngôn ngữ không có node method)); imports (câu lệnh import/use/include); variables (khai báo variable/let/const/static). Ưu tiên dùng cái này thay vì pattern/node_type tự do cho các query kiểu duyệt (browse).

patternTùy chọn

Kiểu: str
Mô tả: Pattern Free-form khi preset quá thô (tự động phát hiện: 'def foo(' → node_type + name_pattern). Ưu tiên preset= cho các query duyệt (browse).

name_patternTùy chọn

Kiểu: str
Mô tả: Pattern tên symbol (wildcard shell, regex POSIX có giới hạn, hoặc văn bản fuzzy; tối đa 256 ký tự)

node_typeTùy chọn

Kiểu: str
Mô tả: Loại node AST (function_definition, class_definition, v.v.) — ưu tiên preset= cho các hình dạng phổ biến

decoratorTùy chọn

Kiểu: str
Mô tả: Bộ lọc theo tên decorator

base_classTùy chọn

Kiểu: str
Mô tả: Bộ lọc theo base class

language_filterTùy chọn

Kiểu: str
Mô tả: Bộ lọc ngôn ngữ

limitTùy chọn

Kiểu: int
Mặc định: 20
Mô tả: Số kết quả tối đa được trả về trong trang này

offsetTùy chọn

Kiểu: int
Mô tả: Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.

cursorTùy chọn

Kiểu: str
Mô tả: Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.

path_filterTùy chọn

Kiểu: str
Mô tả: Lọc theo tiền tố đường dẫn tệp

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (chỉ áp dụng cho một lần gọi)

query_typeTùy chọn

Kiểu: Literal[node_type, name_pattern, parent_child]
Mô tả: Loại truy vấn rõ ràng

parent_typeTùy chọn

Kiểu: str
Mô tả: Bộ lọc kiểu node cha AST

relationshipTùy chọn

Kiểu: Literal[parent, ancestor]
Mặc định: parent
Mô tả: Với truy vấn parent_child: chỉ bố mẹ trực tiếp hoặc bất kỳ tổ tiên nào (dùng ancestor cho phương thức lớp lồng trong thân class)

has_modifierTùy chọn

Kiểu: str
Mô tả: Lọc theo modifier (export, async, static, v.v.)

advancedTùy chọn

Kiểu: bool
Mặc định
Mô tả: Đặt true khi cố ý sử dụng đường dẫn nâng cao, ltree hoặc bộ lọc cuộc gọi (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Theo mặc định, false giữ giao diện tác nhân tập trung vào các giá trị đặt trước. Các khóa nâng cao ở định dạng phẳng vẫn hoạt động để tương thích ngược với cảnh báo siêu dữ liệu.

callee_textTùy chọn

Kiểu: str
Mô tả: Advanced — ưu tiên preset=functions|classes|methods|imports|variables. Filter văn bản callee của call expression. Đặt advanced=true khi cố ý dùng filter path/ltree/call.

callee_nameTùy chọn

Kiểu: str
Mô tả: Advanced — ưu tiên preset=functions|classes|methods|imports|variables. Filter tên callee của call expression. Đặt advanced=true khi cố ý dùng filter path/ltree/call.

field_roleTùy chọn

Kiểu: str
Mô tả: Advanced — ưu tiên preset=functions|classes|methods|imports|variables. Filter field role của AST. Đặt advanced=true khi cố ý dùng filter path/ltree/call.

ltree_ancestorTùy chọn

Kiểu: str
Mô tả: Advanced — ưu tiên preset=functions|classes|methods|imports|variables. Filter path ltree ancestor của AST. Đặt advanced=true khi cố ý dùng filter path/ltree/call.

ltree_descendantTùy chọn

Kiểu: str
Mô tả: Advanced — ưu tiên preset=functions|classes|methods|imports|variables. Filter path ltree descendant của AST. Đặt advanced=true khi cố ý dùng filter path/ltree/call.

definition_nameTùy chọn

Kiểu: str
Mô tả: Advanced — ưu tiên preset=functions|classes|methods|imports|variables. Filter tên definition. Đặt advanced=true khi cố ý dùng filter path/ltree/call.

min_depthTùy chọn

Kiểu: int
Mô tả: Advanced — ưu tiên preset=functions|classes|methods|imports|variables. Minimum AST depth. Đặt advanced=true khi cố ý dùng filter path/ltree/call.

max_depthTùy chọn

Kiểu: int
Mô tả: Advanced — ưu tiên preset=functions|classes|methods|imports|variables. Maximum AST depth. Đặt advanced=true khi cố ý dùng filter path/ltree/call.

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`repository`	`str`	Không	-	Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.
`preset`	`Literal[functions, classes, methods, imports, variables]`	Không	-	Structural selector được khuyến nghị. Mở rộng thành các loại node AST đa ngôn ngữ — functions (định nghĩa function/arrow/method trên nhiều ngôn ngữ); classes (định nghĩa class/struct/impl); methods (định nghĩa method (và function_definition cho các ngôn ngữ không có node method)); imports (câu lệnh import/use/include); variables (khai báo variable/let/const/static). Ưu tiên dùng cái này thay vì pattern/node_type tự do cho các query kiểu duyệt (browse).
`pattern`	`str`	Không	-	Pattern Free-form khi preset quá thô (tự động phát hiện: 'def foo(' → node_type + name_pattern). Ưu tiên preset= cho các query duyệt (browse).
`name_pattern`	`str`	Không	-	Pattern tên symbol (wildcard shell, regex POSIX có giới hạn, hoặc văn bản fuzzy; tối đa 256 ký tự)
`node_type`	`str`	Không	-	Loại node AST (function_definition, class_definition, v.v.) — ưu tiên preset= cho các hình dạng phổ biến
`decorator`	`str`	Không	-	Bộ lọc theo tên decorator
`base_class`	`str`	Không	-	Bộ lọc theo base class
`language_filter`	`str`	Không	-	Bộ lọc ngôn ngữ
`limit`	`int`	Không	`20`	Số kết quả tối đa được trả về trong trang này
`offset`	`int`	Không	-	Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
`cursor`	`str`	Không	-	Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.
`path_filter`	`str`	Không	-	Lọc theo tiền tố đường dẫn tệp
`branch`	`str`	Không	-	Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
`query_type`	`Literal[node_type, name_pattern, parent_child]`	Không	-	Loại truy vấn rõ ràng
`parent_type`	`str`	Không	-	Bộ lọc kiểu node cha AST
`relationship`	`Literal[parent, ancestor]`	Không	`parent`	Với truy vấn parent_child: chỉ bố mẹ trực tiếp hoặc bất kỳ tổ tiên nào (dùng ancestor cho phương thức lớp lồng trong thân class)
`has_modifier`	`str`	Không	-	Lọc theo modifier (export, async, static, v.v.)
`advanced`	`bool`	Không		Đặt true khi cố ý sử dụng đường dẫn nâng cao, ltree hoặc bộ lọc cuộc gọi (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Theo mặc định, false giữ giao diện tác nhân tập trung vào các giá trị đặt trước. Các khóa nâng cao ở định dạng phẳng vẫn hoạt động để tương thích ngược với cảnh báo siêu dữ liệu.
`callee_text`	`str`	Không	-	Advanced — ưu tiên preset=functions\|classes\|methods\|imports\|variables. Filter văn bản callee của call expression. Đặt advanced=true khi cố ý dùng filter path/ltree/call.
`callee_name`	`str`	Không	-	Advanced — ưu tiên preset=functions\|classes\|methods\|imports\|variables. Filter tên callee của call expression. Đặt advanced=true khi cố ý dùng filter path/ltree/call.
`field_role`	`str`	Không	-	Advanced — ưu tiên preset=functions\|classes\|methods\|imports\|variables. Filter field role của AST. Đặt advanced=true khi cố ý dùng filter path/ltree/call.
`ltree_ancestor`	`str`	Không	-	Advanced — ưu tiên preset=functions\|classes\|methods\|imports\|variables. Filter path ltree ancestor của AST. Đặt advanced=true khi cố ý dùng filter path/ltree/call.
`ltree_descendant`	`str`	Không	-	Advanced — ưu tiên preset=functions\|classes\|methods\|imports\|variables. Filter path ltree descendant của AST. Đặt advanced=true khi cố ý dùng filter path/ltree/call.
`definition_name`	`str`	Không	-	Advanced — ưu tiên preset=functions\|classes\|methods\|imports\|variables. Filter tên definition. Đặt advanced=true khi cố ý dùng filter path/ltree/call.
`min_depth`	`int`	Không	-	Advanced — ưu tiên preset=functions\|classes\|methods\|imports\|variables. Minimum AST depth. Đặt advanced=true khi cố ý dùng filter path/ltree/call.
`max_depth`	`int`	Không	-	Advanced — ưu tiên preset=functions\|classes\|methods\|imports\|variables. Maximum AST depth. Đặt advanced=true khi cố ý dùng filter path/ltree/call.

Phù hợp nhất cho:

Cấu trúc cấp AST: class, decorator, preset function/method
Tìm code theo hình dạng, không phải theo văn bản

Không khuyến nghị cho:

Truy vấn free-text hoặc khái niệm — dùng semantic_search hoặc intelligent_search

dependency_searchỔn định

Bề mặt blast-radius / graph chính. Trả lời "cái gì gọi cái này?" / "cái gì dùng cái này?" thông qua call/import graph thực tế. Để xem tác động trước khi edit: analysis_type="dependents" hoặc analysis_type="impact" (incoming, mặc định shallow cho impact), include_metrics=false theo mặc định (opt-in để lấy centrality + refactor_risk). Tác động PR/diff (P1-8): truyền changed_paths và/hoặc patch (unified diff) — phân giải symbol theo từng path và trả về payload dependents shallow-incoming gọn nhẹ mà không cần tên symbol. Sau khi edit, đặt verify_after_edit=true cùng targets và/hoặc changed_paths để truy vấn lại multi-root gọn nhẹ cho các symbol bị ảnh hưởng. Cũng hỗ trợ dependencies, centrality, và orphans. analyze_dependencies là một alias mỏng cho đường impact — ưu tiên dùng tool này cho các agent mới.

Tham số:

repositoryTùy chọn

Kiểu: str
Mô tả: Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.

queryTùy chọn

Kiểu: str
Mô tả: Tên symbol hoặc từ khóa tìm kiếm

targetTùy chọn

Kiểu: str
Mô tả: Tên symbol (alias cho query)

changed_pathsTùy chọn

Kiểu: list[str]
Mô tả: Các đường dẫn tương đối repo cho tác động PR/diff (mặc định) hoặc, với verify_after_edit=true, các gốc xác minh sau chỉnh sửa. PR/diff: giải quyết các ký hiệu trên mỗi đường dẫn và đi tiếp những người phụ thuộc đến nông cạn; có thể được kết hợp với patch=. Xác minh: phân giải tối đa 5 ký hiệu trên mỗi đường dẫn dưới dạng gốc xác minh (giới hạn thấp hơn trong chế độ xác minh). Không yêu cầu query/target cho tác động của PR/diff.

patchTùy chọn

Kiểu: str
Mô tả: Tác động của PR/diff: văn bản bản vá khác biệt / git thống nhất. Các đường dẫn được phân tích cú pháp từ các tiêu đề diff --git / --- / +++; đường tác động nhỏ gọn tương tự như changed_paths.

analysis_typeTùy chọn

Kiểu: Literal[centrality, dependencies, dependents, impact, orphans]
Mặc định: dependencies
Mô tả: Chế độ analysis. impact = blast radius (dependents incoming; depth shallow khi không nêu depth). dependents cũng trả lời cho impact. Khi changed_paths hoặc patch được đặt, analysis bị buộc thành tác động PR/diff. centrality/orphans không cần target.

depthTùy chọn

Kiểu: Literal[shallow, balanced, deep]
Mặc định: balanced
Mô tả: Traversal depth. Với analysis_type=impact và tác động PR/diff, mặc định hiệu lực là shallow trừ khi bạn đặt depth một cách tường minh.

limitTùy chọn

Kiểu: int
Mặc định: 20
Mô tả: Số kết quả tối đa được trả về trong trang này

offsetTùy chọn

Kiểu: int
Mô tả: Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.

cursorTùy chọn

Kiểu: str
Mô tả: Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.

path_filterTùy chọn

Kiểu: str
Mô tả: Giới hạn việc phân giải target symbol theo prefix của file path; các quan hệ graph trả về có thể vượt ra ngoài path đó

language_filterTùy chọn

Kiểu: str
Mô tả: Lọc việc phân giải target và kết quả duyệt (browse) theo ngôn ngữ

directionTùy chọn

Kiểu: Literal[outgoing, incoming, both]
Mô tả: Hướng traversal (ghi đè suy luận từ analysis_type)

relationship_typesTùy chọn

Kiểu: list[str]
Mô tả: Lọc các loại edge (CALL, IMPORT, INHERITS_FROM, v.v.). Một danh sách không rỗng sẽ ghi đè mặc định của graph_view.

exclude_test_pathsTùy chọn

Kiểu: bool
Mặc định: true
Mô tả: Mặc định true: loại trừ các path test, fixture, vendor, và ví dụ khỏi kết quả traversal và centrality. Đặt false để bao gồm chúng. Phân tích orphan luôn áp dụng các loại trừ noise nghiêm ngặt riêng của nó.

exclude_generated_pathsTùy chọn

Kiểu: bool
Mặc định
Mô tả: Loại trừ các khai báo đã tạo cộng với các đường dẫn xây dựng, phạm vi bảo hiểm, bộ nhớ đệm, bản đồ nguồn và các đường dẫn tạo tác được rút gọn khỏi kết quả truyền tải

include_module_symbolsTùy chọn

Kiểu: bool
Mặc định
Mô tả: Theo mặc định, false loại trừ các cạnh của đồ thị khi from_name hoặc to_name là ký hiệu __module__ tổng hợp (nhiễu ở cấp độ mô-đun). Đặt true để bao gồm các cạnh cấp mô-đun trong kết quả cho các mối quan hệ phụ thuộc và phụ thuộc.

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (chỉ áp dụng cho một lần gọi)

per_hop_limitTùy chọn

Kiểu: int
Mô tả: Số relationship tối đa mỗi hop (1-300)

include_metricsTùy chọn

Kiểu: bool
Mặc định
Mô tả: Graph metrics tùy chọn trên các dòng kết quả (được nén gọn cùng refactor_risk). Metrics cũng được lấy nội bộ khi min_centrality>0 nhưng không được trả về trừ khi giá trị này là true.

metrics_detailTùy chọn

Kiểu: Literal[summary, full]
Mặc định: summary
Mô tả: Khi include_metrics=true: summary (mặc định) trả về tín hiệu quyết định + refactor_risk; full trả về tập số liệu được quản lý lớn hơn

include_edge_metadataTùy chọn

Kiểu: bool
Mặc định
Mô tả: Bao gồm siêu dữ liệu cạnh thô và trọng số (lớn). Tải trọng va chạm nhỏ gọn sẽ loại bỏ điều này.

symbol_typesTùy chọn

Kiểu: list[str]
Mô tả: Lọc các symbol trả về theo loại (function, class, method, v.v.)

exact_matchTùy chọn

Kiểu: bool
Mặc định
Mô tả: Yêu cầu khớp chính xác tên symbol (tắt fuzzy matching)

find_similar_patternsTùy chọn

Kiểu: bool
Mặc định
Mô tả: Tìm các pattern sử dụng tương tự

min_centralityTùy chọn

Kiểu: float
Mặc định: 0
Mô tả: Điểm PageRank tối thiểu. Metrics được lấy nội bộ để lọc; graph_metrics chỉ được trả về khi include_metrics=true.

graph_viewTùy chọn

Kiểu: Literal[dependency, type, data_flow, control_flow]
Mặc định: dependency
Mô tả: Graph view dùng cho mặc định traversal relationship, metrics, và xếp hạng centrality; phân tích orphan được tính trên tất cả các view

verify_after_editTùy chọn

Kiểu: bool
Mặc định
Mô tả: Chế độ xác minh sau chỉnh sửa P2-7: truy vấn lại biểu đồ tác động được lập chỉ mục cho các ký hiệu được chỉnh sửa gần đây trong một phản hồi đa gốc nhỏ gọn. Yêu cầu targets và/hoặc changed_paths (hoặc target/query). Mặc định cho những người phụ thuộc đến nông cạn; kết quả phản ánh biểu đồ được lập chỉ mục (có thể làm chậm các chỉnh sửa trực tiếp). Khi đúng, được ưu tiên hơn tác động của PR/diff trên cùng một changed_paths.

targetsTùy chọn

Kiểu: list[str]
Mô tả: Khi verify_after_edit=true: tên biểu tượng cần xác minh lại (người gọi/người phụ thuộc). Hợp nhất với target/query nếu cả hai đều được cung cấp.

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`repository`	`str`	Không	-	Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.
`query`	`str`	Không	-	Tên symbol hoặc từ khóa tìm kiếm
`target`	`str`	Không	-	Tên symbol (alias cho query)
`changed_paths`	`list[str]`	Không	-	Các đường dẫn tương đối repo cho tác động PR/diff (mặc định) hoặc, với verify_after_edit=true, các gốc xác minh sau chỉnh sửa. PR/diff: giải quyết các ký hiệu trên mỗi đường dẫn và đi tiếp những người phụ thuộc đến nông cạn; có thể được kết hợp với patch=. Xác minh: phân giải tối đa 5 ký hiệu trên mỗi đường dẫn dưới dạng gốc xác minh (giới hạn thấp hơn trong chế độ xác minh). Không yêu cầu query/target cho tác động của PR/diff.
`patch`	`str`	Không	-	Tác động của PR/diff: văn bản bản vá khác biệt / git thống nhất. Các đường dẫn được phân tích cú pháp từ các tiêu đề diff --git / --- / +++; đường tác động nhỏ gọn tương tự như changed_paths.
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	Không	`dependencies`	Chế độ analysis. impact = blast radius (dependents incoming; depth shallow khi không nêu depth). dependents cũng trả lời cho impact. Khi changed_paths hoặc patch được đặt, analysis bị buộc thành tác động PR/diff. centrality/orphans không cần target.
`depth`	`Literal[shallow, balanced, deep]`	Không	`balanced`	Traversal depth. Với analysis_type=impact và tác động PR/diff, mặc định hiệu lực là shallow trừ khi bạn đặt depth một cách tường minh.
`limit`	`int`	Không	`20`	Số kết quả tối đa được trả về trong trang này
`offset`	`int`	Không	-	Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
`cursor`	`str`	Không	-	Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.
`path_filter`	`str`	Không	-	Giới hạn việc phân giải target symbol theo prefix của file path; các quan hệ graph trả về có thể vượt ra ngoài path đó
`language_filter`	`str`	Không	-	Lọc việc phân giải target và kết quả duyệt (browse) theo ngôn ngữ
`direction`	`Literal[outgoing, incoming, both]`	Không	-	Hướng traversal (ghi đè suy luận từ analysis_type)
`relationship_types`	`list[str]`	Không	-	Lọc các loại edge (CALL, IMPORT, INHERITS_FROM, v.v.). Một danh sách không rỗng sẽ ghi đè mặc định của graph_view.
`exclude_test_paths`	`bool`	Không	`true`	Mặc định true: loại trừ các path test, fixture, vendor, và ví dụ khỏi kết quả traversal và centrality. Đặt false để bao gồm chúng. Phân tích orphan luôn áp dụng các loại trừ noise nghiêm ngặt riêng của nó.
`exclude_generated_paths`	`bool`	Không		Loại trừ các khai báo đã tạo cộng với các đường dẫn xây dựng, phạm vi bảo hiểm, bộ nhớ đệm, bản đồ nguồn và các đường dẫn tạo tác được rút gọn khỏi kết quả truyền tải
`include_module_symbols`	`bool`	Không		Theo mặc định, false loại trừ các cạnh của đồ thị khi from_name hoặc to_name là ký hiệu __module__ tổng hợp (nhiễu ở cấp độ mô-đun). Đặt true để bao gồm các cạnh cấp mô-đun trong kết quả cho các mối quan hệ phụ thuộc và phụ thuộc.
`branch`	`str`	Không	-	Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
`per_hop_limit`	`int`	Không	-	Số relationship tối đa mỗi hop (1-300)
`include_metrics`	`bool`	Không		Graph metrics tùy chọn trên các dòng kết quả (được nén gọn cùng refactor_risk). Metrics cũng được lấy nội bộ khi min_centrality>0 nhưng không được trả về trừ khi giá trị này là true.
`metrics_detail`	`Literal[summary, full]`	Không	`summary`	Khi include_metrics=true: summary (mặc định) trả về tín hiệu quyết định + refactor_risk; full trả về tập số liệu được quản lý lớn hơn
`include_edge_metadata`	`bool`	Không		Bao gồm siêu dữ liệu cạnh thô và trọng số (lớn). Tải trọng va chạm nhỏ gọn sẽ loại bỏ điều này.
`symbol_types`	`list[str]`	Không	-	Lọc các symbol trả về theo loại (function, class, method, v.v.)
`exact_match`	`bool`	Không		Yêu cầu khớp chính xác tên symbol (tắt fuzzy matching)
`find_similar_patterns`	`bool`	Không		Tìm các pattern sử dụng tương tự
`min_centrality`	`float`	Không	`0`	Điểm PageRank tối thiểu. Metrics được lấy nội bộ để lọc; graph_metrics chỉ được trả về khi include_metrics=true.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Không	`dependency`	Graph view dùng cho mặc định traversal relationship, metrics, và xếp hạng centrality; phân tích orphan được tính trên tất cả các view
`verify_after_edit`	`bool`	Không		Chế độ xác minh sau chỉnh sửa P2-7: truy vấn lại biểu đồ tác động được lập chỉ mục cho các ký hiệu được chỉnh sửa gần đây trong một phản hồi đa gốc nhỏ gọn. Yêu cầu targets và/hoặc changed_paths (hoặc target/query). Mặc định cho những người phụ thuộc đến nông cạn; kết quả phản ánh biểu đồ được lập chỉ mục (có thể làm chậm các chỉnh sửa trực tiếp). Khi đúng, được ưu tiên hơn tác động của PR/diff trên cùng một changed_paths.
`targets`	`list[str]`	Không	-	Khi verify_after_edit=true: tên biểu tượng cần xác minh lại (người gọi/người phụ thuộc). Hợp nhất với target/query nếu cả hai đều được cung cấp.

Phù hợp nhất cho:

Phân tích blast-radius / impact trước khi sửa một symbol dùng chung
PR/diff impact qua changed_paths hoặc patch
Xác minh sau khi sửa qua verify_after_edit

Không khuyến nghị cho:

Tra cứu text hoặc symbol đơn giản — dùng text_pattern_search hoặc find_symbol

Công cụ phân tích code#

find_symbolỔn định

Nhảy tới nơi hàm, lớp hoặc biến được định nghĩa và sử dụng. Dùng khi bạn biết tên (ví dụ "getCurrentUser") — nhanh và chính xác hơn Grep, bao phủ toàn bộ repo đã lập chỉ mục. Tùy chọn trả về references và metrics tầm quan trọng.

Tham số:

symbol_nameTùy chọn

Kiểu: str
Mô tả: Tên symbol để tìm (tùy chọn — bỏ để duyệt theo metrics)

repositoryTùy chọn

Kiểu: str
Mô tả: Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.

scopeTùy chọn

Kiểu: Literal[definitions, references, both]
Mặc định: both
Mô tả: Phạm vi tìm kiếm

limitTùy chọn

Kiểu: int
Mặc định: 15
Mô tả: Số kết quả tối đa được trả về trong trang này

offsetTùy chọn

Kiểu: int
Mô tả: Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.

cursorTùy chọn

Kiểu: str
Mô tả: Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.

find_similarTùy chọn

Kiểu: bool
Mặc định
Mô tả: Bao gồm tên symbol tương tự

include_metricsTùy chọn

Kiểu: bool
Mặc định
Mô tả: Bao gồm metrics centrality

metrics_detailTùy chọn

Kiểu: Literal[summary, full]
Mặc định: summary
Mô tả: Khi include_metrics=true: summary (mặc định) trả về tín hiệu quyết định + refactor_risk; full trả về tập số liệu được quản lý lớn hơn

path_filterTùy chọn

Kiểu: str
Mô tả: Lọc theo tiền tố đường dẫn tệp

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (chỉ áp dụng cho một lần gọi)

symbol_typeTùy chọn

Kiểu: Literal[function, class, variable, method, constant, module, interface, type]
Mô tả: Bộ lọc kiểu symbol

high_impactTùy chọn

Kiểu: bool
Mặc định
Mô tả: Duyệt các symbol quan trọng về mặt kiến trúc (bỏ qua symbol_name). Chế độ mặc định là popularity (decile PageRank cao nhất trừ đi các utility mega-hub). Đặt high_impact_mode=risk cho các articulation/bridge cut-vertex.

high_impact_modeTùy chọn

Kiểu: Literal[popularity, risk]
Mặc định: popularity
Mô tả: Khi high_impact=true: mức độ phổ biến = thập phân vị PageRank hàng đầu trừ đi các trung tâm/mô-đun tiện ích lớn; rủi ro = điểm khớp nối được xếp hạng theo SMV bridge_count rồi đến k_core (rủi ro tái cấu trúc cấu trúc, không phải mức độ phổ biến của trung tâm)

in_cycleTùy chọn

Kiểu: bool
Mặc định
Mô tả: Chỉ symbols trong vòng phụ thuộc

exclude_test_pathsTùy chọn

Kiểu: bool
Mặc định: true
Mô tả: Khi duyệt theo số liệu biểu đồ, hãy loại trừ các bài kiểm tra, fixtures, mã của bên thứ ba và các ví dụ trước khi xếp hạng. Tra cứu bằng ký hiệu được đặt tên không thay đổi.

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`symbol_name`	`str`	Không	-	Tên symbol để tìm (tùy chọn — bỏ để duyệt theo metrics)
`repository`	`str`	Không	-	Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.
`scope`	`Literal[definitions, references, both]`	Không	`both`	Phạm vi tìm kiếm
`limit`	`int`	Không	`15`	Số kết quả tối đa được trả về trong trang này
`offset`	`int`	Không	-	Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
`cursor`	`str`	Không	-	Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.
`find_similar`	`bool`	Không		Bao gồm tên symbol tương tự
`include_metrics`	`bool`	Không		Bao gồm metrics centrality
`metrics_detail`	`Literal[summary, full]`	Không	`summary`	Khi include_metrics=true: summary (mặc định) trả về tín hiệu quyết định + refactor_risk; full trả về tập số liệu được quản lý lớn hơn
`path_filter`	`str`	Không	-	Lọc theo tiền tố đường dẫn tệp
`branch`	`str`	Không	-	Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	Không	-	Bộ lọc kiểu symbol
`high_impact`	`bool`	Không		Duyệt các symbol quan trọng về mặt kiến trúc (bỏ qua symbol_name). Chế độ mặc định là popularity (decile PageRank cao nhất trừ đi các utility mega-hub). Đặt high_impact_mode=risk cho các articulation/bridge cut-vertex.
`high_impact_mode`	`Literal[popularity, risk]`	Không	`popularity`	Khi high_impact=true: mức độ phổ biến = thập phân vị PageRank hàng đầu trừ đi các trung tâm/mô-đun tiện ích lớn; rủi ro = điểm khớp nối được xếp hạng theo SMV bridge_count rồi đến k_core (rủi ro tái cấu trúc cấu trúc, không phải mức độ phổ biến của trung tâm)
`in_cycle`	`bool`	Không		Chỉ symbols trong vòng phụ thuộc
`exclude_test_paths`	`bool`	Không	`true`	Khi duyệt theo số liệu biểu đồ, hãy loại trừ các bài kiểm tra, fixtures, mã của bên thứ ba và các ví dụ trước khi xếp hạng. Tra cứu bằng ký hiệu được đặt tên không thay đổi.

Phù hợp nhất cho:

Ghim definition, reference và graph metric của một symbol đã biết
Duyệt theo centrality, high_impact hoặc in_cycle khi bỏ qua symbol_name

Không khuyến nghị cho:

Truy vấn khái niệm hoặc khu vực chưa biết — dùng intelligent_search hoặc semantic_search

analyze_dependenciesỔn định

Alias cho blast-radius thông qua dependency_search (dependents/incoming). Ưu tiên dependency_search với analysis_type="dependents" hoặc "impact" cho các agent mới. Giữ nguyên dạng phản hồi impact multi-hop cũ (graph, connection_summary, metrics tùy chọn kèm refactor_risk). Dùng graph_view để giới hạn phạm vi relationship family: dependency (mặc định), type, data_flow, control_flow.

Tham số:

repositoryTùy chọn

Kiểu: str
Mô tả: Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.

targetBắt buộc

Kiểu: str
Mô tả: Tên symbol cần phân tích

depthTùy chọn

Kiểu: Literal[shallow, balanced, deep]
Mặc định: balanced
Mô tả: Độ sâu phân tích (hỗ trợ alias: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)

limitTùy chọn

Kiểu: int
Mặc định: 10
Mô tả: Số kết quả tối đa được trả về trong trang này

offsetTùy chọn

Kiểu: int
Mô tả: Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.

cursorTùy chọn

Kiểu: str
Mô tả: Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.

directionTùy chọn

Kiểu: Literal[incoming, outgoing, both]
Mặc định: incoming
Mô tả: Hướng traversal: 'outgoing' = symbol này phụ thuộc vào gì, 'incoming' = cái gì phụ thuộc vào symbol này, 'both' = đầy đủ.

relationship_typesTùy chọn

Kiểu: list[str]
Mô tả: Lọc loại cạnh (CALL, IMPORT, INHERITS_FROM, v.v.). Luôn ghi đè mặc định sinh ra từ graph_view nếu được cung cấp.

graph_viewTùy chọn

Kiểu: Literal[dependency, type, data_flow, control_flow]
Mặc định: dependency
Mô tả: Chế độ graph: quyết định loại cạnh traversal mặc định và metrics được dùng khi include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (mặc định), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Chỉ áp dụng khi relationship_types không được cung cấp. Tên tham số khớp dependency_search để đồng nhất giữa các công cụ.

path_filterTùy chọn

Kiểu: str
Mô tả: Giới hạn việc phân giải target symbol theo prefix của file path; các quan hệ graph trả về có thể vượt ra ngoài path đó

language_filterTùy chọn

Kiểu: str
Mô tả: Bộ lọc ngôn ngữ

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (chỉ áp dụng cho một lần gọi)

per_hop_limitTùy chọn

Kiểu: int
Mô tả: Số relationship tối đa mỗi hop (1-300)

include_metricsTùy chọn

Kiểu: bool
Mặc định
Mô tả: Đưa số liệu biểu đồ vào kết quả, mỗi số liệu được làm phong phú bằng khối refactor_risk dẫn xuất ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk là "low" khi không phải là điểm khớp nối (trong chế độ xem đã chọn), "medium" khi một điểm khớp nối kết nối một số cạnh, "high" khi kết nối nhiều cạnh (ngưỡng heuristic, không được xác thực theo kinh nghiệm). Đã bỏ qua mỗi ký hiệu khi không có hàng số liệu nào tồn tại cho ký hiệu/chế độ xem đó.

metrics_detailTùy chọn

Kiểu: Literal[summary, full]
Mặc định: summary
Mô tả: Khi include_metrics=true: summary (mặc định) trả về tín hiệu quyết định + refactor_risk; full trả về tập số liệu được quản lý lớn hơn

include_edge_metadataTùy chọn

Kiểu: bool
Mặc định
Mô tả: Bao gồm siêu dữ liệu và trọng số của cạnh thô. Bị tắt theo mặc định vì siêu dữ liệu của trình trích xuất có thể lớn; phạm vi làm giàu được báo cáo khi được bật.

exclude_test_pathsTùy chọn

Kiểu: bool
Mặc định: true
Mô tả: true mặc định: loại trừ các đường dẫn thử nghiệm, vật cố định, nhà cung cấp và ví dụ khỏi các cạnh biểu đồ được trả về. Đặt false để bao gồm chúng.

include_module_symbolsTùy chọn

Kiểu: bool
Mặc định
Mô tả: Theo mặc định, false loại trừ các cạnh của đồ thị khi from_name hoặc to_name là ký hiệu __module__ tổng hợp. Đặt true để bao gồm các cạnh cấp mô-đun.

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`repository`	`str`	Không	-	Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.
`target`	`str`	Có	-	Tên symbol cần phân tích
`depth`	`Literal[shallow, balanced, deep]`	Không	`balanced`	Độ sâu phân tích (hỗ trợ alias: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
`limit`	`int`	Không	`10`	Số kết quả tối đa được trả về trong trang này
`offset`	`int`	Không	-	Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
`cursor`	`str`	Không	-	Cursor mờ (opaque) từ pagination.next_cursor. Truyền lại nguyên vẹn và giữ nguyên query cùng các filter.
`direction`	`Literal[incoming, outgoing, both]`	Không	`incoming`	Hướng traversal: 'outgoing' = symbol này phụ thuộc vào gì, 'incoming' = cái gì phụ thuộc vào symbol này, 'both' = đầy đủ.
`relationship_types`	`list[str]`	Không	-	Lọc loại cạnh (CALL, IMPORT, INHERITS_FROM, v.v.). Luôn ghi đè mặc định sinh ra từ graph_view nếu được cung cấp.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Không	`dependency`	Chế độ graph: quyết định loại cạnh traversal mặc định và metrics được dùng khi include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (mặc định), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Chỉ áp dụng khi relationship_types không được cung cấp. Tên tham số khớp dependency_search để đồng nhất giữa các công cụ.
`path_filter`	`str`	Không	-	Giới hạn việc phân giải target symbol theo prefix của file path; các quan hệ graph trả về có thể vượt ra ngoài path đó
`language_filter`	`str`	Không	-	Bộ lọc ngôn ngữ
`branch`	`str`	Không	-	Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
`per_hop_limit`	`int`	Không	-	Số relationship tối đa mỗi hop (1-300)
`include_metrics`	`bool`	Không		Đưa số liệu biểu đồ vào kết quả, mỗi số liệu được làm phong phú bằng khối refactor_risk dẫn xuất ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk là "low" khi không phải là điểm khớp nối (trong chế độ xem đã chọn), "medium" khi một điểm khớp nối kết nối một số cạnh, "high" khi kết nối nhiều cạnh (ngưỡng heuristic, không được xác thực theo kinh nghiệm). Đã bỏ qua mỗi ký hiệu khi không có hàng số liệu nào tồn tại cho ký hiệu/chế độ xem đó.
`metrics_detail`	`Literal[summary, full]`	Không	`summary`	Khi include_metrics=true: summary (mặc định) trả về tín hiệu quyết định + refactor_risk; full trả về tập số liệu được quản lý lớn hơn
`include_edge_metadata`	`bool`	Không		Bao gồm siêu dữ liệu và trọng số của cạnh thô. Bị tắt theo mặc định vì siêu dữ liệu của trình trích xuất có thể lớn; phạm vi làm giàu được báo cáo khi được bật.
`exclude_test_paths`	`bool`	Không	`true`	true mặc định: loại trừ các đường dẫn thử nghiệm, vật cố định, nhà cung cấp và ví dụ khỏi các cạnh biểu đồ được trả về. Đặt false để bao gồm chúng.
`include_module_symbols`	`bool`	Không		Theo mặc định, false loại trừ các cạnh của đồ thị khi from_name hoặc to_name là ký hiệu __module__ tổng hợp. Đặt true để bao gồm các cạnh cấp mô-đun.

Phù hợp nhất cho:

Legacy caller đã gắn sẵn với response shape của nó (graph, connection_summary)

Không khuyến nghị cho:

Agent loop mới — ưu tiên dependency_search, vốn dùng chung traversal core

get_task_contextỔn định

Bắt đầu làm việc ở một khu vực chưa quen? Mô tả task (vd. "thêm hỗ trợ SSO", "sửa billing webhook") và nhận một gói giới hạn, một lần gọi gồm các file, code, symbol, và dependency liên quan. Các file được seed đóng góp nội dung indexed trực tiếp ngay cả khi chúng không định nghĩa symbol nào. Để có thêm kết quả, hãy tiếp tục với search tool chuyên biệt cho layer đó.

Tham số:

task_descriptionBắt buộc

Kiểu: str
Mô tả: Mô tả tác vụ cần lấy context

repositoryTùy chọn

Kiểu: str
Mô tả: Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.

limitTùy chọn

Kiểu: int
Mặc định: 15
Mô tả: Số mục context tối đa mỗi lớp

scopeTùy chọn

Kiểu: Literal[semantic, symbols, dependencies, all]
Mặc định: all
Mô tả: Những lớp context cần bao gồm (giá trị hợp lệ: 'semantic', 'symbols', 'dependencies', 'all'; mặc định: ['semantic','symbols','dependencies'])

language_filterTùy chọn

Kiểu: str
Mô tả: Bộ lọc ngôn ngữ

path_filterTùy chọn

Kiểu: str
Mô tả: Lọc theo tiền tố đường dẫn file

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (chỉ áp dụng cho một lần gọi)

include_related_contextTùy chọn

Kiểu: bool
Mặc định
Mô tả: Bao gồm context liên quan từ các symbol lân cận

seed_symbol_idsTùy chọn

Kiểu: list[str]
Mô tả: Hạt giống cấp-1 rõ ràng: ID symbol mà agent biết là trung tâm cho tác vụ (ví dụ: symbol trong file đang mở). Ưu tiên hơn hạt giống từ từ khóa trong các lớp dependencies/related_context. Tính cộng: bỏ qua để dùng hành vi chỉ từ khóa hiện tại.

seed_file_pathsTùy chọn

Kiểu: list[str]
Mô tả: Seed tường minh Tier-1: các path file indexed mà agent đang mở hoặc vừa chỉnh sửa. Trả về bằng chứng file trực tiếp có giới hạn và phân giải tối đa 5 symbol mỗi file cho graph context, bao gồm cả tài liệu và config không có symbol. Có tính chất bổ sung (additive) — bỏ qua để giữ hành vi chỉ dựa trên keyword.

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`task_description`	`str`	Có	-	Mô tả tác vụ cần lấy context
`repository`	`str`	Không	-	Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.
`limit`	`int`	Không	`15`	Số mục context tối đa mỗi lớp
`scope`	`Literal[semantic, symbols, dependencies, all]`	Không	`all`	Những lớp context cần bao gồm (giá trị hợp lệ: 'semantic', 'symbols', 'dependencies', 'all'; mặc định: ['semantic','symbols','dependencies'])
`language_filter`	`str`	Không	-	Bộ lọc ngôn ngữ
`path_filter`	`str`	Không	-	Lọc theo tiền tố đường dẫn file
`branch`	`str`	Không	-	Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
`include_related_context`	`bool`	Không		Bao gồm context liên quan từ các symbol lân cận
`seed_symbol_ids`	`list[str]`	Không	-	Hạt giống cấp-1 rõ ràng: ID symbol mà agent biết là trung tâm cho tác vụ (ví dụ: symbol trong file đang mở). Ưu tiên hơn hạt giống từ từ khóa trong các lớp dependencies/related_context. Tính cộng: bỏ qua để dùng hành vi chỉ từ khóa hiện tại.
`seed_file_paths`	`list[str]`	Không	-	Seed tường minh Tier-1: các path file indexed mà agent đang mở hoặc vừa chỉnh sửa. Trả về bằng chứng file trực tiếp có giới hạn và phân giải tối đa 5 symbol mỗi file cho graph context, bao gồm cả tài liệu và config không có symbol. Có tính chất bổ sung (additive) — bỏ qua để giữ hành vi chỉ dựa trên keyword.

Phù hợp nhất cho:

Task-aware context kết hợp các file được seed với các layer semantic, symbol và dependency

Không khuyến nghị cho:

Tra cứu single-tool khi đã có tool cụ thể hơn trả lời được câu hỏi

get_fileỔn định

Đọc một file từ repo indexed theo path. Ưu tiên dùng Read tool cục bộ cho các file trên đĩa — dùng cái này cho tra cứu cross-repo hoặc remote khi file không có trong working tree của bạn. Hỗ trợ line range tùy chọn; tiếp tục một phản hồi bị token-truncated từ metadata.next_line_start.

Tham số:

file_pathBắt buộc

Kiểu: str
Mô tả: Đường dẫn file so với gốc repository

repositoryTùy chọn

Kiểu: str
Mô tả: Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.

line_startTùy chọn

Kiểu: int
Mô tả: Dòng bắt đầu (đánh số từ 1)

line_endTùy chọn

Kiểu: int
Mô tả: Dòng kết thúc (1-indexed, bao gồm cả dòng đó; phải bằng hoặc sau line_start)

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (chỉ áp dụng cho một lần gọi)

max_tokensTùy chọn

Kiểu: int
Mặc định: 5000
Mô tả: Số token tối đa trả về

include_metadataTùy chọn

Kiểu: bool
Mặc định: true
Mô tả: Bao gồm metadata file trong phản hồi

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`file_path`	`str`	Có	-	Đường dẫn file so với gốc repository
`repository`	`str`	Không	-	Repository dưới dạng owner/repo[:branch]. Tùy chọn — bỏ qua để dùng mặc định theo từng yêu cầu do MCP client cung cấp (khi có) hoặc khi khóa có thể truy cập đúng một repository; chỉ truyền rõ ràng khi muốn nhắm tới repo đã lập chỉ mục khác. Phản hồi cho biết repository đã dùng.
`line_start`	`int`	Không	-	Dòng bắt đầu (đánh số từ 1)
`line_end`	`int`	Không	-	Dòng kết thúc (1-indexed, bao gồm cả dòng đó; phải bằng hoặc sau line_start)
`branch`	`str`	Không	-	Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
`max_tokens`	`int`	Không	`5000`	Số token tối đa trả về
`include_metadata`	`bool`	Không	`true`	Bao gồm metadata file trong phản hồi

Phù hợp nhất cho:

Snapshot file remote hoặc indexed (line range, token limit)

Không khuyến nghị cho:

Path đã có sẵn trên đĩa cục bộ — dùng Read tool cục bộ

Công cụ hệ thống & tiện ích#

repository_contextỔn định

Liệt kê các repository bạn có thể tìm kiếm, hoặc lấy thông tin identity về một repo (namespace/branch, indexed_commit_sha / index freshness). Gọi với action:"list" một lần để biết chính xác repo slug mà search tools chấp nhận. (Nếu key của bạn chỉ có một repo, search tools sẽ mặc định dùng repo đó — bạn có thể bỏ qua bước này.) Số lượng file/blob/edge trên toàn namespace là tùy chọn thông qua include_statistics=true.

Tham số:

actionBắt buộc

Kiểu: Literal[list, info]
Mô tả: Thao tác: list các repo có sẵn hoặc lấy info của repo

repositoryTùy chọn

Kiểu: str
Mô tả: Repository theo định dạng owner/repo hoặc owner/repo:branch (bắt buộc cho info)

branchTùy chọn

Kiểu: str
Mô tả: Ghi đè nhánh (chỉ áp dụng cho một lần gọi)

patternTùy chọn

Kiểu: str
Mô tả: Lọc danh sách repository theo pattern

include_statisticsTùy chọn

Kiểu: bool
Mặc định
Mô tả: Tùy chọn: bao gồm số lượng indexed-data trên toàn namespace (file/blob/edge). Mặc định false — identity của repository không cần đến phép tổng hợp chậm hơn này.

limitTùy chọn

Kiểu: int
Mặc định: 20
Mô tả: Số kết quả tối đa được trả về trong trang này

offsetTùy chọn

Kiểu: int
Mô tả: Phần bù tương thích không được dùng nữa. Thích cursor hơn pagination.next_cursor.

cursorTùy chọn

Kiểu: str
Mô tả: cursor mờ từ pagination.next_cursor. Truyền nó không thay đổi và giữ nguyên truy vấn cũng như bộ lọc.

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`action`	`Literal[list, info]`	Có	-	Thao tác: list các repo có sẵn hoặc lấy info của repo
`repository`	`str`	Không	-	Repository theo định dạng owner/repo hoặc owner/repo:branch (bắt buộc cho info)
`branch`	`str`	Không	-	Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
`pattern`	`str`	Không	-	Lọc danh sách repository theo pattern
`include_statistics`	`bool`	Không		Tùy chọn: bao gồm số lượng indexed-data trên toàn namespace (file/blob/edge). Mặc định false — identity của repository không cần đến phép tổng hợp chậm hơn này.
`limit`	`int`	Không	`20`	Số kết quả tối đa được trả về trong trang này
`offset`	`int`	Không	-	Phần bù tương thích không được dùng nữa. Thích cursor hơn pagination.next_cursor.
`cursor`	`str`	Không	-	cursor mờ từ pagination.next_cursor. Truyền nó không thay đổi và giữ nguyên truy vấn cũng như bộ lọc.

Phù hợp nhất cho:

Liệt kê các repository có thể truy cập
Xác định repository identity, branch, và HEAD-vs-index freshness

Không khuyến nghị cho:

Mặc định thống kê toàn namespace — truyền rõ include_statistics=true, vì có thể chậm hơn resolution

ask_maguyvaỔn định

Trợ giúp và phản hồi cho Maguyva. Chính: nhận tool guidance, hoặc gửi bug report / feature request được lưu lại cho đội bảo trì Maguyva. Không bao giờ đưa secret hoặc dữ liệu cá nhân nhạy cảm vào phản hồi. Thao tác evaluate chỉ còn để tương thích ngược — ưu tiên dùng tính toán cục bộ hoặc host tools cho công việc math/hash/string.

Tham số:

operationBắt buộc

Kiểu: Literal[guidance, report_bug, request_feature, evaluate]
Mô tả: Chính: guidance, report_bug, request_feature. Chỉ để tương thích/legacy: evaluate (deterministic expression engine; không thuộc luồng công việc chính của agent).

queryTùy chọn

Kiểu: str
Mô tả: Chủ đề guidance (vd. tool_selection, semantic_search). Chỉ dành cho evaluate legacy: chuỗi expression.

descriptionTùy chọn

Kiểu: str
Mô tả: Bắt buộc cho report_bug và request_feature. Phản hồi Free-form cho đội bảo trì Maguyva. Không bao giờ đưa secret hoặc dữ liệu cá nhân nhạy cảm.

related_toolTùy chọn

Kiểu: Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
Mô tả: Công cụ Maguyva tùy chọn liên quan chặt chẽ nhất đến phản hồi

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`operation`	`Literal[guidance, report_bug, request_feature, evaluate]`	Có	-	Chính: guidance, report_bug, request_feature. Chỉ để tương thích/legacy: evaluate (deterministic expression engine; không thuộc luồng công việc chính của agent).
`query`	`str`	Không	-	Chủ đề guidance (vd. tool_selection, semantic_search). Chỉ dành cho evaluate legacy: chuỗi expression.
`description`	`str`	Không	-	Bắt buộc cho report_bug và request_feature. Phản hồi Free-form cho đội bảo trì Maguyva. Không bao giờ đưa secret hoặc dữ liệu cá nhân nhạy cảm.
`related_tool`	`Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]`	Không	-	Công cụ Maguyva tùy chọn liên quan chặt chẽ nhất đến phản hồi

Phù hợp nhất cho:

Tool guidance (operation="guidance")
Bug report và feature request lâu dài cho đội bảo trì Maguyva

Không khuyến nghị cho:

Tính toán math/hash/string — thao tác evaluate chỉ còn để tương thích ngược; ưu tiên tính toán host cục bộ

Thực hành tốt nhất#

Sử dụng ghi đè tường minh có chủ đích: Bỏ tham số repository khi MCP client của bạn cung cấp mặc định theo từng yêu cầu hoặc khi khóa có thể truy cập đúng một repository; nếu không, hãy truyền rõ ràng.
Chọn đúng chế độ tìm kiếm: Dùng intelligent_search với mode="auto" cho hầu hết trường hợp. Chỉ định chế độ khi bạn biết chính xác mình cần gì.
Tận dụng bộ lọc ngôn ngữ: Dùng language_filter để thu hẹp kết quả và cải thiện hiệu năng.
Tăng cường GraphRAG: Tính năng tăng cường theo mức độ quan trọng của GraphRAG bị tắt theo mặc định cho tìm kiếm ngữ nghĩa (boost_by_importance=false) để giữ việc xếp hạng an toàn cho tác nhân. Truyền boost_by_importance=true để bật xếp hạng lại theo độ trung tâm cho các chuyến tham quan kiến trúc.
Khớp Repository Không Phân Biệt Hoa Thường, Không Phải Khớp Mờ: repository_context khớp tên repository không phân biệt hoa thường — nó không tự sửa lỗi gõ. Kiểm tra metadata.resolution_reason trên hành động info ("exact" so với "corrected") để xem một tên đã được phân giải như thế nào.
Kết hợp công cụ: Dùng nhiều phương thức API cùng nhau để có phân tích toàn diện.
Xử lý tập kết quả lớn: Dùng limit và cơ chế phân trang riêng của từng công cụ (ví dụ line_start/line_end trong get_file).
Dùng ask_maguyva để được hướng dẫn về công cụ: Thao tác evaluate của ask_maguyva (hash, base64, JSON, toán học) chỉ mang tính kế thừa / để tương thích ngược. Thay vào đó, hãy gọi ask_maguyva với operation="guidance" và query="tool_selection" để lấy ma trận local-tool-wins và bảng tra cứu đầy đủ cho từng công cụ.
Xác minh tác động trước và sau khi chỉnh sửa: Trước khi chỉnh sửa một symbol dùng chung, hãy gọi dependency_search với analysis_type="impact" (hoặc truyền changed_paths để xem tác động PR/diff) để thấy phạm vi ảnh hưởng của nó. Sau khi chỉnh sửa, đặt verify_after_edit=true cùng targets và/hoặc changed_paths để kiểm tra lại gọn nhẹ các symbol tương tự.

Đặc tính hiệu năng#

Thao tác	Ghi chú hiệu năng
Tìm kiếm ngữ nghĩa	Dưới một giây, nhưng luôn gọi một API embedding trực tiếp mỗi lần (không cache) — hãy tính thêm độ trễ ngoài truy vấn vector
Tìm kiếm văn bản	Dưới một giây với exact/regex; tìm kiếm nội dung fuzzy phân trang phía client, nên offset sâu sẽ tốn kém hơn — hãy thu hẹp bằng path_filter/language_filter
Tìm kiếm cấu trúc	Được index theo AST — chi phí tỷ lệ theo khối lượng kết quả, không theo kích thước repository
Tìm kiếm phụ thuộc	Chi phí tỷ lệ theo depth — ưu tiên depth="shallow" trừ khi bạn cần ngữ cảnh nhiều bước (multi-hop); per_hop_limit giới hạn độ lan tỏa
Truy xuất file	Gần như tức thì với một file đơn — hãy phân trang các file lớn bằng line_start/line_end hoặc max_tokens thay vì lấy trọn một lần
Ngữ cảnh repository	Việc phân giải namespace chỉ được cache theo từng request, không xuyên suốt các lần gọi — mỗi lần gọi công cụ đều phân giải lại
ask_maguyva (guidance / evaluate)	Gần như tức thì — chạy in-Worker, không gọi cơ sở dữ liệu

Xử lý lỗi#

Mọi phương thức API đều trả về một envelope có cấu trúc:

status: Chuỗi — "success" hoặc "error". Tín hiệu degraded-match và độ mới nằm trong các trường lồng nhau như metadata.resolution_reason trên repository_context hoặc metadata.index_freshness.status.
tool: Tên của công cụ đã tạo ra phản hồi
data: Payload kết quả khi thành công (cấu trúc thay đổi tùy công cụ)
error: Đối tượng lỗi có cấu trúc khi status là "error" — bao gồm type, message, suggestions, và recovery_actions
metadata: Thông tin bổ sung về thao tác (định tuyến, cache, điều chỉnh tham số)
pagination: Xuất hiện trên các phản hồi dạng danh sách — bao gồm has_more và next_cursor

Luôn kiểm tra trường status trước khi xử lý kết quả — giá trị của nó chỉ có thể là "success" hoặc "error". Với tín hiệu degraded-match hoặc độ mới, hãy đọc trường lồng nhau thay thế: metadata.resolution_reason trên repository_context, hoặc metadata.index_freshness.status (known/partial/unknown/unavailable).

Bắt đầu#

Cấu hình MCP Client: Chỉ vào endpoint server của Maguyva từ MCP client
Xác nhận quyền truy cập repository: Dùng repository_context với list hoặc info để kiểm tra các repository mà khóa API có thể truy cập
Bắt đầu tìm kiếm: Bắt đầu với intelligent_search và chuyển sang các công cụ chuyên biệt khi cần
Kết hợp công cụ: Dùng nhiều công cụ cùng nhau để phân tích code toàn diện

Để có hướng dẫn tích hợp chi tiết, xem hướng dẫn cài đặt.