# 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

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

{
  "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"
    }
  }
}

{
  "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"
      }
    }
  }
}

┌─────────────────────────────────────────────────────┐
│                   MCP Client                        │
│          (Gemini CLI, Claude, Cursor...)             │
└────────────────────┬────────────────────────────────┘
                     │ stdio (MCP Protocol)
┌────────────────────▼────────────────────────────────┐
│                server.py                            │
│  ┌──────────────────────────────────────────────┐   │
│  │           FastMCP (17 tools)                 │   │
│  │  list_projects · query_nodes · find_impact   │   │
│  │  find_path · get_class_hierarchy             │   │
│  │  get_domain_flow_detail · ...                │   │
│  └──────────────────┬───────────────────────────┘   │
│                     │                               │
│  ┌──────────────────▼───────────────────────────┐   │
│  │       Multi-Project Registry                 │   │
│  │   cache theo mtime · tự động reload · resolve│   │
│  └──────────────────┬───────────────────────────┘   │
└─────────────────────┼───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│              kg_loader.py                           │
│  ┌────────────────────────────────────────────────┐ │
│  │  Tầng Dữ liệu (Data Layer)                    │ │
│  │  Node · Edge · LayerInfo · TourStop            │ │
│  │  DomainNode · DomainEdge · ProjectGraph        │ │
│  ├────────────────────────────────────────────────┤ │
│  │  Edge Resolution Layer                         │ │
│  │  class/function → file edge inheritance        │ │
│  │  O(1) node index · O(degree) edge index        │ │
│  ├────────────────────────────────────────────────┤ │
│  │  Query Engine                                  │ │
│  │  fuzzy search · BFS traversal · impact analysis│ │
│  │  shortest path · class hierarchy · path search │ │
│  ├────────────────────────────────────────────────┤ │
│  │  Source Extraction (đa ngôn ngữ)               │ │
│  │  brace-counting (Java/Kotlin/TS/JS/Go/Rust/C#) │ │
│  │  indent-tracking (Python)                      │ │
│  └────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────┘
                      │ đọc JSON
┌─────────────────────▼───────────────────────────────┐
│     .understand-anything/                           │
│     ├── knowledge-graph.json  (đồ thị code-level)   │
│     ├── domain-graph.json     (đồ thị nghiệp vụ)    │
│     └── meta.json             (metadata phân tích)   │
└─────────────────────────────────────────────────────┘

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
├── pyproject.toml     # Cấu hình dự án — dependencies: mcp[cli], rapidfuzz
├── tests/             # Bộ test tự động
│   ├── test_kg_loader.py    # 59 unit tests cho core loader, query engine & cross-ref
│   └── 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

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

# 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)