# Engineering Intelligence MCP

Engineering Intelligence MCP là công cụ phân tích codebase Java bằng Knowledge Graph nội bộ. Mục tiêu là index cấu trúc dự án một lần, lưu node/edge vào SQLite, rồi để AI hoặc MCP client đọc graph có bằng chứng thay vì phải đọc từng file source.

Project này không cần API key AI và không cần graph database ngoài. Backend graph hiện tại là SQLite thông qua SQLAlchemy.

## Kiến Trúc

```mermaid
flowchart LR
    MCP[MCP Tools] --> Services[Application Services]
    Services --> Analyzer[Java / Spring / MyBatis / SQL / Git Analyzers]
    Services --> Repos[Repository Interfaces]
    Repos --> SQLite[(SQLite)]
    SQLite --> Graph[knowledge_nodes / knowledge_edges]
    Graph --> Context[Graph Context Cho AI]
```

SQLite lưu hai nhóm dữ liệu:

- Metadata vận hành: project, repository, index run, file hash, commit, task summary.
- Knowledge Graph: `knowledge_nodes` và `knowledge_edges`.

MCP tools chỉ là lớp giao tiếp. Logic phân tích nằm trong service/analyzer/repository, không nằm trực tiếp trong MCP tool.

## AI Được Tận Dụng Ở Đâu

Project không gọi AI API. Thay vào đó project tạo graph có cấu trúc để AI bên ngoài đọc qua MCP.

AI hoặc MCP client có thể gọi:

- `get_knowledge_schema`: đọc loại node/edge được hỗ trợ.
- `get_project_knowledge_map`: lấy bản đồ dự án rút gọn.
- `search_symbol`: tìm endpoint, class, method, mapper, table, requirement.
- `explain_endpoint_flow`: trace REST API tới method, mapper, SQL, table/column.
- `find_table_usage`: tìm API/code đang dùng table.
- `analyze_change_impact`: phân tích impact từ một node.
- `generate_semantic_summary_markdown`: tạo file `.md` tổng kết ngữ nghĩa local, không cần API key.

AI dùng kết quả JSON có `evidence`, `confidence`, `resolution`, `warnings` để giải thích. AI không tự sinh quan hệ chính.

## Cài Đặt Nhanh Trên Windows

Yêu cầu:

- Windows 10/11.
- Python 3.11 trở lên.
- JDK có `java` và `javac` nếu muốn index Java thật.
- Git nếu muốn phân tích task/commit.

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m pip install -e .
copy .env.example .env
python scripts\init_sqlite_storage.py
python -m engineering_mcp.main --check
pytest
```

Nếu đã xóa `data\engineering_intelligence.db`, chạy lại:

```powershell
python scripts\init_sqlite_storage.py
```

hoặc:

```powershell
python -m engineering_mcp.main --check
```

Project sẽ tạo lại SQLite schema. Path `sqlite:///data/engineering_intelligence.db` được neo theo thư mục project MCP.

## Cấu Hình

File `.env.example` tối thiểu:

```env
APP_ENV=development
LOG_LEVEL=INFO
SQLALCHEMY_DATABASE_URL=sqlite:///data/engineering_intelligence.db
GRAPH_BACKEND=sqlite
REPOSITORY_ALLOWED_ROOTS=.
MCP_TRANSPORT=stdio
```

Khi index project Java thật, thêm thư mục project vào allow-list:

```env
REPOSITORY_ALLOWED_ROOTS=.,C:\work\order-system
```

## Build Java Analyzer

Java analyzer là CLI nhỏ dùng JDK Compiler Tree API, không dùng Tree-sitter.

```powershell
tools\java-ast-indexer\build.bat
```

## Chạy Demo Local

Demo tạo sample Java project, sample git history, index graph vào SQLite và export UI HTML.

```powershell
python scripts\run_local_demo.py
```

Export UI demo tĩnh:

```powershell
python scripts\export_graph_ui.py --project-id order-system --demo --output-path data\graph-ui\order-system-demo-graph.html
```

Mở file:

```text
data\graph-ui\order-system-demo-graph.html
```

## Index Project Java Thật

Ví dụ:

```powershell
python scripts\index_repository.py `
  --project-id order-system `
  --repository-path C:\work\order-system `
  --repository-id order-system-backend `
  --repository-name backend
```

Sau khi index, export graph UI thật từ SQLite:

```powershell
python scripts\export_graph_ui.py --project-id order-system --output-path data\graph-ui\order-system-graph.html
```

Kiểm tra một node:

```powershell
python scripts\inspect_graph.py --node-id "endpoint:order-system:POST:/orders/{id}/approve" --trace --max-depth 8
```

## Chạy MCP Server

```powershell
python -m engineering_mcp.main
```

MCP client cấu hình command:

```json
{
  "command": "python",
  "args": ["-m", "engineering_mcp.main"],
  "cwd": "C:\\work\\engineering-intelligence-mcp"
}
```

## Tạo File Markdown Tổng Kết Ngữ Nghĩa

Sau khi build Java analyzer:

```powershell
python scripts\generate_markdown_summary.py `
  --project-id order-system `
  --repository-path C:\work\order-system `
  --output-path data\reports\order-system-semantic-summary.md
```

File Markdown được tạo từ phân tích deterministic, không gọi AI API.

## An Toàn Database Nghiệp Vụ

Project không sửa dữ liệu trong Tibero/Oracle hoặc database nghiệp vụ.

Các lớp bảo vệ hiện có:

- MCP không có tool chạy SQL tùy ý.
- Lệnh sync database chỉ đọc metadata schema/table/column bằng query cố định.
- JDBC connection phải bật được read-only mode; nếu bật thất bại thì sync dừng.
- Trước khi `cursor.execute`, SQL được kiểm tra và chỉ cho phép `SELECT` hoặc `WITH`.
- Các keyword ghi/chỉnh sửa như `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `ALTER`, `DROP`, `CREATE`, `TRUNCATE`, `CALL`, `EXEC`, `COMMIT`, `ROLLBACK` bị chặn.
- Nên dùng database account read-only, không dùng owner, DBA hoặc account ứng dụng có quyền ghi.

Project vẫn ghi vào SQLite local tại `data\engineering_intelligence.db`; đây là storage nội bộ để lưu metadata, Knowledge Graph, index run và cache báo cáo.

## Task Git

Tìm commit theo task:

```powershell
python scripts\summarize_task_changes.py `
  --project-id order-system `
  --repository-path C:\work\order-system `
  --task-id 001
```

Quy tắc quan trọng: project không lấy diff range lớn từ commit đầu tới commit cuối. Nó diff từng commit match task với parent trực tiếp, rồi aggregate lại để tránh lẫn commit không liên quan.

## Tài Liệu

- `docs/huong-dan-tung-buoc-cai-dat-mcp-ui.md`
- `docs/huong-dan-cai-dat-windows.md`
- `docs/huong-dan-sqlite-knowledge-graph.md`
- `docs/architecture.md`
- `docs/knowledge-model.md`
- `docs/indexing-pipeline.md`
- `docs/mcp-tools.md`
- `docs/graph-ui.md`
- `docs/java-analyzer.md`
- `docs/sql-analysis.md`
- `docs/git-task-analysis.md`
- `docs/tibero-setup.md`

## Giới Hạn Hiện Tại

- Không dùng Tree-sitter.
- Không dùng SQLGlot.
- Không gọi AI API.
- Không thực thi SQL tùy ý.
- Không sửa code tự động.
- Java semantic resolution ở mức MVP, không thay thế compiler/build đầy đủ.
- SQL analyzer là conservative parser; SQL phức tạp có thể trả `PARTIAL` hoặc `FAILED`.
# mcp-wibu