mcp-spec-nav
MCP chạy local · Mã nguồn mở

Cho agent
một bản đồ code.

Logic bạn cần có thể đã tồn tại. Giúp AI tìm, hiểu và kiểm tra những phần bị ảnh hưởng trước khi sửa.

Bắt đầu →Khám phá repo ↗
Chạy local / Claude Code + Claude Desktop / MIT
spec-nav / phiên mô phỏng
// Trước khi viết thêm hàm tính phí…

agent → spec_nav_find_functions
{ "query": "calculate order fees" }
↳ Tìm implementation có sẵn
services/billing/src/fees.ts

calculateFee(order)
Đọc code. Kiểm tra phụ thuộc. Quyết định.
agent → spec_nav_callers
{ "symbol": "calculateFee",
  "file": "services/billing/src/fees.ts" }

// Kiểm tra callers trước khi đổi signature.
sẵn sàng ▌
TRÊN TOÀN BỘ CODEBASE
TypeScriptJavaScriptPythonGoJavaKotlinSwift+ xem thêm ↗
01 / Tìm hiểu trước khi sửa

Bớt phỏng đoán.
Hiểu code rõ hơn.

Giúp agent kiểm tra repo trước khi chọn cách triển khai.

⌕

Tìm logic để dùng lại.

Tìm trên nhiều service theo từ khóa, hàm được gọi hoặc độ giống bản nháp. Kết quả được xếp hạng và giải thích vì sao khớp.

spec_nav_find_functions
{ }

Đọc đầy đủ ngữ cảnh.

Đọc implementation, signature, tài liệu và import liên quan trước khi quyết định sử dụng — tối đa 10 hàm trong một lần gọi.

spec_nav_read_function
↳

Kiểm tra nơi gọi hàm.

Kiểm tra callers, lời gọi động và tham chiếu chưa xác định trước khi sửa signature hoặc hành vi hàm.

spec_nav_callers
Thử quy trình

Một task.
Điểm bắt đầu rõ hơn.

YÊU CẦU MẪU → ĐẦU VÀO TOOL

“Trước khi thêm cách tính phí đơn hàng, tìm implementation có sẵn trên các service và đọc ứng viên phù hợp nhất.”

spec_nav_find_functions
{ "query": "calculate order fees", "limit": 20 }

Đọc các hàm tìm được và kiểm tra ranh giới service trước khi import. Agent quyết định hàm nào phù hợp.

Xem tất cả tool trong README ↗
Xem demo / Cùng task. Cùng rule.

Grep + rule.
MCP + rule.

Theo dõi một yêu cầu về phí đơn hàng từ prompt đến tìm code, sửa, test và bàn giao. Cả hai agent theo cùng rule.

spec_nav_servicesspec_nav_functionsspec_nav_find_functionsspec_nav_read_functionspec_nav_similar_functionsspec_nav_callersspec_nav_mapspec_nav_trace_flow
Một yêu cầu · Từ đầu đến cuối

Qua billing, checkout, orders, invoicing và shipping: thêm tùy chọn miễn phí xử lý, đổi phí tập trung từ 5 lên 7, dùng lại hàm tính tổng thay vì viết trùng, cập nhật callers, kiểm tra mọi cách viết của phí và test tổng tiền thường/miễn phí. Cùng tuân theo rule tái sử dụng và kiểm tra callers.

RULE CHUNG · CLAUDE.md / RULE.md / HƯỚNG DẪN CLIENTTrước khi viết: tìm hàm có sẵn, đọc và dùng lại nếu phù hợp.
Trước khi sửa: kiểm tra code liên quan và callers, rồi cập nhật các vị trí bị ảnh hưởng.
01 / Map các service trước khi làm
Grep + ruleAgent tự gom thông tin
Lượt khám phá trong demo · mô phỏng0
ILLUSTRATIVE COMMANDS & OUTPUT
rg --files -g 'package.json' services/ packages/ \
  && cat package.json services/*/package.json
Identify billing, checkout, orders, invoicing and shipping. Agent combines file lists and project configuration.
1 Bash call shown: list projects and read their manifests together.
spec-nav + ruleTool tổ chức thông tin
Lượt khám phá trong demo · mô phỏng0
ILLUSTRATIVE COMMANDS & OUTPUT
spec_nav_services
{}
Repository root + discovered projects Source coverage + file/function counts Inspect excluded or unsupported files.
1 discovery call shown: project map and coverage together.
✓ LỢI THẾ CỦA MCPBắt đầu với bản đồ repo thay vì gom từng danh sách file.spec_nav_services gom project, số lượng và coverage. Cả hai agent vẫn kiểm tra root và ranh giới trước khi sửa.
Rule hướng dẫn quy trình. Grep và đọc file vẫn làm tốt khi agent chọn đúng truy vấn và lần theo tham chiếu cẩn thận.
MCP bổ sung cấu trúc. Ứng viên được xếp hạng, ngữ cảnh hàm, bằng chứng callers và kết quả kèm hàm chứa chúng.

Walkthrough task lớn minh họa: 11 lượt Grep/Read và 9 lượt spec-nav cho phần khám phá; phía Grep gộp nhiều lệnh tìm và đọc vào một lần gọi Bash như agent thật. Đây là số lượt theo kịch bản, không phải đo agent thực tế. Sửa, test và phân trang cần thêm lượt. Benchmark Immich đo trung bình 146,9 so với 117,7 tổng lượt/session lớn; không chứng minh cả task xong trong vài lượt hay tool MCP chạy nhanh hơn.

02 / Kết nối agent

Cấu hình gọn.
Khởi đầu tốt hơn.

Cần Node.js 18+, npm/npx, Git và bản clone local của repo muốn quét.

  1. Thêm cấu hình này vào .mcp.json trong repo muốn quét.
  2. Thay SPEC_NAV_ROOT bằng đường dẫn tuyệt đối tới codebase.
  3. Khởi động lại Claude Code, chạy /mcp, và kiểm tra spec-nav đã kết nối.
Dùng Claude Desktop? Cài extension ↗
.mcp.json
{
  "mcpServers": {
    "spec-nav": {
      "command": "npx",
      "args": [
        "-y",
        "github:khoitd-voyager/mcp-spec-nav"
      ],
      "env": {
        "SPEC_NAV_ROOT": "/absolute/path/to/your-repo"
      }
    }
  }
}
Dùng thư mục gốc monorepo để quét nhiều service.
03 / Xem bằng chứng

Benchmark có thể
đọc và chạy lại.

So sánh spec-nav với Grep/Read/Edit ở việc dùng lại code, tìm callers và khảo sát thay đổi.

Xem phương pháp đo ↗
Session LLM thật · 8 PR GrafanaClaude Sonnet 5.5
Monorepo đa ngôn ngữ giả lậpbench/run.mjs
Đánh giá trên repo thậtbench/real.mjs
Hiệu năng trên repo lớnbench/perf.mjs

Chạy thật: Claude Code (Claude Sonnet 5.5) trên 8 PR của Grafana, bản trơn so với một cấu hình spec-nav không chỉ có MCP: MCP + hướng dẫn + hook ép gọi spec-nav. Cả hai đều pass mọi test ẩn; chênh lệch chất lượng nằm trong mức nhiễu và cấu hình bị ép tốn thêm khoảng 58% mỗi session. Cấu hình chỉ có MCP chưa được đo. Các benchmark còn lại dùng chính sách agent tất định, token là ước lượng. Đọc phương pháp và giới hạn trước khi trích dẫn.

Xem báo cáo chạy LLM thật ↗
Xem kết quả đã chạy ↗
Số liệu đo / Kết quả benchmark đã lưu

Xem khác biệt qua số liệu.

immich@cc7fd67 · 10 session lớn · Đã lưu 2026-10-13

Baseline: Grep / Read / Editspec-nav + Read / Edit

Session đúng hoàn toàn

Cao hơn tốt hơn
Baseline
0%
spec-nav
30%
0

Dùng lại được hàm có sẵn

Cao hơn tốt hơn
Baseline
40%
spec-nav
93%
0

Token context pha tìm kiếm

Thấp hơn tốt hơn · ước lượng
Baseline
67,345
spec-nav
21,188
0

Token context cuối session

Thấp hơn tốt hơn · ước lượng
Baseline
302,494
spec-nav
226,515
0

Số chỗ sửa nhầm mỗi session

Thấp hơn tốt hơn · số liệu đo
Baseline
14.4
spec-nav
2.4
0

Số tool call mỗi session

Thấp hơn tốt hơn · số liệu đo
Baseline
146.9
spec-nav
117.7
0
Đánh đổi: chi phí cold start của MCP.

Thời gian tool trung bình gồm khởi động MCP mới ở mỗi session. Không gồm thời gian model suy nghĩ; đây không phải độ trễ LLM từ đầu tới cuối.

Đọc báo cáo đầy đủ của bộ dữ liệu ↗

Agent theo chính sách tất định, không chạy LLM thật. Số liệu trung bình mỗi session. Token ước lượng 3,5 ký tự/token. Session lớn gộp 3 feature. Immich chỉ là một repo thật; không đại diện mọi dự án.

Giới hạn: tìm kiếm vẫn theo từ vựng; callers được kiểm tra kiểu ở TS/JS/Vue/Svelte/Astro và dựa trên bằng chứng ở ngôn ngữ khác. Có thể còn thiếu coverage. Sửa đơn giản trong một file có thể ít hưởng lợi.

Tìm. Đọc. Kiểm tra.

Hàm bạn định viết
có thể đã có sẵn.

Cho agent nơi để tìm trước khi bắt đầu viết code.

Kết nối spec-nav →Feedback & issues ↗