🧠 Understand-Anything MCP Server

MCP Server giúp trợ lý AI hiểu sâu bất kỳ codebase nào thông qua Knowledge Graph.

Giới thiệu

MCP Server này tải các Knowledge Graph được tạo bởi Understand-Anything và cung cấp chúng dưới dạng các tool có thể truy vấn cho bất kỳ trợ lý AI tương thích MCP nào (Gemini CLI, Claude Desktop, Cursor, v.v.).

Server hỗ trợ hai loại đồ thị đồng thời cho mỗi dự án:

Hỗ trợ đa dự án — Tải N dự án cùng lúc và truy vấn bất kỳ dự án nào. AI tự động nhận diện dự án phù hợp dựa trên ngữ cảnh workspace.

Tính năng nổi bật

• 🔍 Tìm kiếm mờ (Fuzzy search) — Tìm kiếm có trọng số (tên 3x > mô tả 1.5x > tags 1x) sử dụng rapidfuzz

• 🏗️ Tầng kiến trúc — Truy vấn theo layer (controller, service, repository, v.v.)

• 🌊 Truy vết chuỗi gọi hàm — Duyệt BFS theo các lời gọi hàm

• 💥 Phân tích vùng ảnh hưởng — Tìm tất cả node bị ảnh hưởng khi thay đổi một node (BFS ngược)

• 🎯 Phát hiện entry point — Nhận diện API endpoint và các hàm không được gọi bởi hàm khác

• 🏢 Tri thức nghiệp vụ — Domains, flows, steps, thực thể và quy tắc nghiệp vụ

• 📖 Trích xuất mã nguồn đa ngôn ngữ — Đọc source code thực tế của bất kỳ node nào, hỗ trợ trích xuất symbol-level cho Java, Kotlin, TypeScript, JavaScript, Python, Go, Rust, C#

• 🔗 Tìm đường ngắn nhất — BFS vô hướng giữa hai node bất kỳ trong đồ thị

• 🏛️ Cây kế thừa — Truy vết extends/implements lên và xuống toàn bộ hệ thống phân cấp class

• 📁 Tìm kiếm theo đường dẫn — Tìm tất cả node theo package/module/thư mục path (O(P) qua path index)

• 🌉 Domain↔Code Cross-reference — Tự động bridge từ domain step → code node qua _nodes_by_path index O(1), semantic ranking khi prefix match (penalize boilerplate, ưu tiên class liên quan theo tên/mô tả/tags)

• 🔄 Tự động tải lại — Phát hiện khi file graph thay đổi trên đĩa và tự động reload

• ✅ Phân tích độ mới — So sánh commit hash của graph với HEAD hiện tại qua git diff

• ⚡ Edge Resolution Layer — Class và function node tự động kế thừa quan hệ từ file cha, tra cứu O(degree) qua edge index

• 🧪 59 unit tests — Bộ test toàn diện bảo vệ regressions, chạy trong <0.1s

• 📚 Skill kèm theo — codebase-explain: hướng dẫn AI giải thích sâu file/symbol/module/business flow bằng evidence read-only từ server (output có cấu trúc, gắn freshness, không bịa node ID)

Related MCP server: PT-MCP (Paul Test Man Context Protocol)

Bắt đầu nhanh

Yêu cầu

• Python ≥ 3.12

• Trình quản lý package uv

• Một dự án đã được tạo graph bởi Understand-Anything (thư mục .understand-anything/)

Cài đặt & Chạy

# Clone repository
git clone https://github.com/VIethoangnguyenle/Understand-Anything-MCP.git
cd Understand-Anything-MCP

# Cài đặt dependencies
uv sync

# Chạy với MCP Inspector (để test/debug)
PROJECT_ROOTS=/đường/dẫn/tới/dự-án npx @modelcontextprotocol/inspector uv run server.py

# Chạy MCP dev server
PROJECT_ROOTS=/đường/dẫn/tới/dự-án mcp dev server.py

Đa dự án

Đặt PROJECT_ROOTS là danh sách đường dẫn phân cách bằng dấu phẩy:

PROJECT_ROOTS=/đường/dẫn/dự-án-a,/đường/dẫn/dự-án-b uv run server.py

Mỗi tool đều nhận tham số project tùy chọn. Nếu chỉ có một dự án được tải, nó sẽ được sử dụng tự động.

Chạy bằng Docker

Repo kèm sẵn Dockerfile và compose.example.yaml để chạy server trong container — không cần cài Python hay uv trên máy, và dự án được mount chỉ đọc.

Dựng ảnh

docker build -t ua-mcp:local .

Chạy một lần

Server nói MCP qua stdio, không mở cổng nào. Vì vậy phải chạy với -i, và đừng docker compose up -d — container sẽ khởi động rồi thoát ngay vì không ai nối vào stdin.

docker run -i --rm \
  -v /đường/dẫn/dự-án:/data/du-an:ro \
  -e PROJECT_ROOTS=/data/du-an \
  -e GIT_CONFIG_COUNT=1 \
  -e GIT_CONFIG_KEY_0=safe.directory \
  -e GIT_CONFIG_VALUE_0='*' \
  ua-mcp:local

Hoặc chép compose.example.yaml thành compose.yaml, sửa đường dẫn, rồi:

docker compose run --rm -T ua-mcp

Nối vào MCP client

Trỏ client thẳng vào docker, thay vì uv:

{
  "mcpServers": {
    "understand-anything": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/đường/dẫn/dự-án:/data/du-an:ro",
        "-e", "PROJECT_ROOTS=/data/du-an",
        "-e", "GIT_CONFIG_COUNT=1",
        "-e", "GIT_CONFIG_KEY_0=safe.directory",
        "-e", "GIT_CONFIG_VALUE_0=*",
        "ua-mcp:local"
      ]
    }
  }
}

Hai cái bẫy khiến FRESHNESS luôn UNKNOWN

Cả hai đều fail trong im lặng — server chạy bình thường, tool trả lời bình thường, chỉ có FRESHNESS âm thầm về UNKNOWN mãi mãi. Nhìn từ ngoài giống hệt như dự án không phải git checkout, nên rất dễ bỏ qua.

1. Ảnh phải có git. check_freshness gọi git rev-parse HEAD và git diff bên trong thư mục dự án. Base python:3.12-slim không kèm git; thiếu nó thì FileNotFoundError bị nuốt và mọi dự án đều báo UNKNOWN. Dockerfile trong repo đã cài sẵn.

2. Phải khai báo safe.directory. Dự án mount vào container thường thuộc uid khác với user chạy trong container, git từ chối với dubious ownership và mọi lệnh đều fail. Dùng biến môi trường GIT_CONFIG_COUNT / GIT_CONFIG_KEY_0 / GIT_CONFIG_VALUE_0 thay vì ghi ~/.gitconfig — container chạy read_only nên không ghi file config được.

Kiểm nhanh sau khi dựng ảnh:

docker run --rm ua-mcp:local git --version

Rồi gọi get_graph_stats và xem mục FRESHNESS có thoát khỏi UNKNOWN không.

Ghi chú bảo mật

compose.example.yaml mặc định bật read_only: true, cap_drop: ALL, no-new-privileges, và chạy bằng uid không phải root (1001). Server chỉ đọc graph rồi trả lời truy vấn nên không cần ghi gì; chỉ khi bật usage metrics mới cần đúng một mount ghi được.

Cấu hình MCP Client

Gemini CLI / Antigravity

Thêm vào ~/.gemini/antigravity/mcp_config.json:

{
  "understand-anything": {
    "command": "uv",
    "args": ["--directory", "/đường/dẫn/tuyệt/đối/tới/Understand-Anything-MCP", "run", "server.py"],
    "env": {
      "PROJECT_ROOTS": "/đường/dẫn/tới/dự-án-a,/đường/dẫn/tới/dự-án-b"
    }
  }
}

Claude Desktop

Thêm vào claude_desktop_config.json:

{
  "mcpServers": {
    "understand-anything": {
      "command": "uv",
      "args": ["--directory", "/đường/dẫn/tuyệt/đối/tới/Understand-Anything-MCP", "run", "server.py"],
      "env": {
        "PROJECT_ROOTS": "/đường/dẫn/tới/dự-án"
      }
    }
  }
}

Cursor / Các MCP Client khác

Sử dụng cùng cấu trúc — đặt command là uv, truyền đường dẫn server qua --directory, và cấu hình PROJECT_ROOTS trong env.

Danh sách Tools (17 tools)

Khám phá & Tổng quan

Truy vấn Code Graph

Truy vấn nâng cao

Truy vấn Domain Graph

Skills

Thư mục skills/ chứa các Claude Code skill tương tác với server này.

codebase-explain

Giải thích sâu một file, symbol, module, class, function hoặc business flow bằng evidence read-only từ server — không đọc source local, không bịa node ID/path/line.

/codebase-explain [project-name] [file-path|symbol|module|business-flow]

Skill quy định:

• Freshness gate — luôn kiểm tra get_graph_stats và gán FRESH|STALE|UNKNOWN trước mọi claim quan trọng.

• Exact-match validation — kết quả fuzzy chỉ là candidate; phải khớp đúng path/symbol/flow name mới được deep dive, nếu không chuyển sang ambiguity review.

• 9-section output — output tiếng Việt có cấu trúc, mọi claim gắn Source/Project/Freshness/Tool/Claim.

• Ambiguity gate — target mơ hồ sinh file review HTML thay vì đoán.

Skill là markdown thuần — thêm vào .claude/skills/ của project hoặc cài làm plugin để dùng /codebase-explain.

Kiến trúc

flowchart TD
    Client["MCP Client<br/>Gemini CLI · Claude · Cursor"]

    subgraph Server["server.py"]
        FastMCP["FastMCP · 17 tools<br/>list_projects · query_nodes · find_impact<br/>find_path · get_class_hierarchy · get_domain_flow_detail · ..."]
        Registry["Multi-Project Registry<br/>cache theo mtime · tự động reload · resolve"]
    end

    subgraph Loader["kg_loader.py"]
        direction TB
        DataLayer["Tầng Dữ liệu<br/>Node · Edge · LayerInfo · TourStop<br/>DomainNode · DomainEdge · ProjectGraph"]
        EdgeRes["Edge Resolution Layer<br/>class/function → file edge inheritance<br/>O(1) node index · O(degree) edge index"]
        Query["Query Engine<br/>fuzzy search · BFS traversal · impact analysis<br/>shortest path · class hierarchy · path search"]
        Source["Source Extraction<br/>brace-counting Java/Kotlin/TS/JS/Go/Rust/C#<br/>indent-tracking Python"]
        DataLayer --> EdgeRes --> Query --> Source
    end

    subgraph UA[".understand-anything/"]
        KG["knowledge-graph.json<br/>đồ thị code-level"]
        DG["domain-graph.json<br/>đồ thị nghiệp vụ"]
        Meta["meta.json<br/>metadata phân tích"]
    end

    Client -->|"stdio · MCP Protocol"| Server
    FastMCP --> Registry
    Registry --> DataLayer
    Source -->|"đọc JSON"| KG
    Source -.->|"đọc JSON"| DG
    Source -.->|"đọc JSON"| Meta

Cấu trúc tệp

Understand-Anything-MCP/
├── server.py          # MCP server — định nghĩa 17 tools, registry đa dự án
├── kg_loader.py       # Bộ tải graph & query engine — data models, search, traversal, resolution
├── metrics.py         # Usage metrics — 1 JSON line / tool call, rotating file, fail-safe
├── pyproject.toml     # Cấu hình dự án — dependencies: mcp[cli], rapidfuzz, pytest (dev)
├── Dockerfile         # Build đa tầng, chạy non-root, có sẵn git cho check_freshness
├── compose.example.yaml  # Mẫu compose — chép thành compose.yaml rồi sửa đường dẫn
├── .dockerignore      # Loại .venv/, tests/, cache ra khỏi build context
├── scripts/           # Bộ script vận hành — clone, pull, re-index, gitignore
│   ├── clone-repos.sh       # Clone repo từ manifest CSV vào REPO_ROOT (idempotent)
│   ├── git-pull.sh          # Pull toàn bộ repo + report JSON
│   ├── git-pull-run.sh      # Wrapper systemd: lưu JSON, alert webhook
│   ├── sync-graph.sh        # Re-index graph incremental bằng claude agent trong docker
│   ├── sync-graph-run.sh    # Wrapper cron: pull + sync + alert
│   ├── check-graph-ignore.sh    # Kiểm tra .understand-anything/ được ignore đúng
│   ├── revert-gitignore-graph.sh  # Hoán .gitignore sang .git/info/exclude
│   └── test/                  # Harness test (git repo giả + docker giả)
├── skills/            # Claude Code skills
│   └── codebase-explain/
│       └── SKILL.md           # Giải thích sâu codebase bằng evidence read-only
├── tests/             # Bộ test tự động
│   ├── test_kg_loader.py    # Unit tests cho core loader, query engine & cross-ref
│   ├── test_graph_metadata.py  # Tests cho get_graph_metadata
│   ├── test_path_safety.py     # Tests cho path containment
│   ├── test_metrics.py         # Unit tests cho metrics writer
│   ├── test_metrics_integration.py  # Wiring metrics vào FastMCP tool surface
│   ├── test_symbol_coverage.py # Tests cho compute_symbol_coverage
│   └── fixtures/            # Dữ liệu test JSON mẫu
│       ├── knowledge-graph.json
│       └── domain-graph.json
├── uv.lock            # Dependencies đã khóa phiên bản
└── README.md

Biến môi trường

Usage Metrics

Module metrics.py đo usage của tool surface — 1 JSON line cho mỗi tool call, append vào file rotating có size cap. Dữ liệu trả lời ba câu hỏi:

1. Adoption — ua-mcp có thực sự được dùng không? Tool nào được gọi, bao nhiêu lần?

2. Điểm yếu — Chỗ nào trả về kết quả rỗng, lỗi, hay tool nào không ai gọi (dead tool)?

3. Hỏi lặp — Cùng một caller có đang hỏi cùng một câu hỏi không? (detection qua caller + arg_hash trong time window)

Thiết kế an toàn

Hard rule: ghi metrics không bao giờ được phá tool call. Mọi failure path đều được swallow (file không ghi được, disk full, JSON không serialize được), và writer tự disable vĩnh viễn sau 5 lần lỗi liên tiếp — không còn retry, không còn log spam, tool call chạy tiếp bình thường.

• Caller key — hash ip + user_agent, không lưu IP raw (tránh PII)

• Arg hash — SHA-256 của (tool, args), args dài được truncate trước khi ghi nhưng hash vẫn tính trên bản đầy đủ

• Outcome classification — phân loại ok / empty / error / exception dựa trên giá trị trả về

• Rotating file — size cap, không tăng vô hạn

Kích hoạt

# Mặc định: metrics TẮT (không ghi gì)
PROJECT_ROOTS=/đường/dẫn/dự-án uv run server.py

# Bật metrics: set UA_MCP_METRICS_FILE
UA_MCP_METRICS_FILE=/var/log/ua-mcp/metrics.jsonl \
PROJECT_ROOTS=/đường/dẫn/dự-án uv run server.py

Wiring

server.py gọi metrics.install(mcp) trước tool đầu tiên được khai báo bằng @mcp.tool(). Vì decorator chạy khi import theo thứ tự source, tool nào khai báo trên dòng install sẽ không bị đo — test test_every_registered_tool_is_instrumented bảo vệ invariant này.

# Chạy test metrics
uv sync --group dev
uv run pytest tests/test_metrics.py tests/test_metrics_integration.py -v

Cách hoạt động

1. Khi khởi động, server quét PROJECT_ROOTS và tải knowledge-graph.json + domain-graph.json từ thư mục .understand-anything/ của mỗi dự án.

2. Index được xây dựng trong bộ nhớ:

   • _node_index: tra cứu node theo ID — O(1)

   • _edges_by_source / _edges_by_target: tra cứu edge — O(degree)

   • _domain_edges_by_source: index riêng cho domain graph

   • _nodes_by_path: ánh xạ file_path → nodes — O(1), dùng cho cross-ref và path search

   • Layer enrichment: gán layer vào từng node dựa trên ánh xạ layer

3. Edge Resolution Layer — Khi truy vấn quan hệ của class/function node:

   • Resolve tới parent file qua edge contains

   • Kế thừa outgoing edges từ file cha (imports, contains, v.v.)

   • Loại bỏ self-reference và deduplicate

4. Khi một tool được gọi, server kiểm tra mtime của file graph trên đĩa và tự động tải lại nếu cần.

5. Tìm kiếm mờ sử dụng rapidfuzz với điểm số có trọng số — kết quả khớp tên được đánh trọng số cao gấp 3 lần so với khớp mô tả, kèm bonus cho khớp chính xác chuỗi con.

6. Trích xuất mã nguồn đa ngôn ngữ — Tự động nhận diện ngôn ngữ qua extension và chọn chiến lược phù hợp:

   • Brace-counting: Java, Kotlin, TypeScript, JavaScript, Go, Rust, C#

   • Indent-tracking: Python (word-boundary regex, shallowest-indent preferred)

7. Domain↔Code Cross-reference — resolve_domain_to_code() bridge domain steps tới code nodes:

   • Strategy 1: Exact file_path match qua _nodes_by_path index (O(1))

   • Strategy 2: Directory prefix match với semantic ranking — khi filePath trỏ vào package directory:

     • Collect tất cả class/file nodes trong package (không early exit)

     • Scoring: +20 cho tên token khớp summary, +15 khớp step name, +10 khớp tags, +50 cho full class name match

     • Penalty: −50 cho boilerplate patterns (Application, Config, Interceptor, Test, Utils, v.v.)

     • Bonus: +2/level cho files nằm sâu trong subdirectory (thường cụ thể hơn)

   • Priority: class > file > function

8. Domain edge type constants — DOMAIN_REL_CONTAINS_FLOW, DOMAIN_REL_FLOW_STEP, v.v. — single source of truth, tránh typo

9. Kiểm tra độ mới chạy lệnh git diff <commit_phân_tích>..HEAD để phát hiện số lượng file code đã thay đổi kể từ lần tạo graph gần nhất.

Vận hành đồ thị (scripts/)

Bộ script trong scripts/ giúp vận hành graph ở quy mô nhiều repo trên một server — clone, pull, re-index, và giữ git status sạch. Tất cả script:

• Mặc định dry-run khi cần ghi — phải truyền --apply mới thực thi.

• JSON ra stdout, log người đọc ra stderr — parse được bằng jq, log tail -f được.

• Không ghi gì vào repo sản phẩm — graph là runtime state, ignore qua .git/info/exclude (per-clone, sống qua mọi lần pull).

• Chạy được trên macOS (bash 3.2) và Linux — harness test trong scripts/test/ không cần VM, docker thật, hay LLM.

Kịch bản điển hình

# 1. Clone repo theo manifest CSV vào REPO_ROOT
./scripts/clone-repos.sh --apply

# 2. Pull toàn bộ repo (git-pull.sh) rồi re-index graph incremental (sync-graph.sh)
./scripts/sync-graph-run.sh

# 3. Kiểm tra .understand-anything/ được ignore đúng cách
./scripts/check-graph-ignore.sh --fix

Các script

Biến môi trường chính

Harness test

scripts/test/sync-graph-test.sh tạo repo git giả + docker giả (trong scripts/test/bin/) để chạy hết các nhánh kết quả của sync-graph.sh không cần VM, container thật, hay LLM. Các case tương ứng các sự cố thực tế đã gặp (agent thoát 0 nhưng không ghi meta, stderr lẫn vào stream-json, timeout, bước domain bị bỏ trong báo cáo).

./scripts/test/sync-graph-test.sh   # pass=N fail=0

Ví dụ sử dụng

Sau khi kết nối với MCP client, AI có thể sử dụng các tool một cách tự nhiên:

Người dùng: "Luồng xác thực hoạt động như thế nào?"

AI sử dụng: query_nodes(query="authentication") → tìm các node liên quan
AI sử dụng: get_domain_detail(domain_name="authentication") → lấy thông tin domain đầy đủ
AI sử dụng: trace_call_chain(start_node_id="...loginUser") → truy vết cây gọi hàm

Người dùng: "Nếu tôi thay đổi PaymentService thì ảnh hưởng gì?"

AI sử dụng: query_nodes(query="PaymentService") → tìm node
AI sử dụng: find_impact(node_id="...PaymentService") → phân tích vùng ảnh hưởng

Người dùng: "PaymentService kế thừa từ class nào?"

AI sử dụng: query_nodes(query="PaymentService") → tìm node
AI sử dụng: get_class_hierarchy(class_id="class:PaymentService", direction="up") → cây kế thừa

Người dùng: "AuthService và PaymentGateway liên quan thế nào?"

AI sử dụng: find_path(source_id="class:AuthService", target_id="class:PaymentGateway") → đường đi ngắn nhất

Người dùng: "Tất cả file trong package transfer?"

AI sử dụng: search_by_file_path(path_pattern="transfer", node_type="file") → danh sách file

Người dùng: "Luồng xử lý lương chi tiết thế nào?"

AI sử dụng: get_domain_flow_detail(flow_name="payroll") → entry point, ordered steps, code refs

Phát triển

# Cài đặt dependencies
uv sync

# Chạy unit tests
uv run pytest tests/ -v

# Chạy test với MCP Inspector
PROJECT_ROOTS=/đường/dẫn/tới/dự-án npx @modelcontextprotocol/inspector uv run server.py

# Log được ghi ra stderr (stdout được dành riêng cho MCP stdio protocol)

Giấy phép

MIT

Được xây dựng cho hệ sinh thái Understand-Anything

Giúp trợ lý AI hiểu sâu bất kỳ codebase nào 🚀