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

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.

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:

python scripts\init_sqlite_storage.py

hoặc:

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:

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:

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.

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.

python scripts\run_local_demo.py

Export UI demo tĩnh:

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

Mở file:

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

Index Project Java Thật

Ví dụ:

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:

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:

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

Chạy MCP Server

python -m engineering_mcp.main

MCP client cấu hình command:

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

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:

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