Magento Spec & Standards (SSOT & MCP Server)

Repo này là Thư viện tri thức trung tâm (Single Source of Truth - SSOT) về chuẩn Magento 2.4.8-p5 / PHP 8.3, tích hợp sẵn MCP Server Stdio.

Repo này không chứa quy trình hay quản lý task/feature. Bạn có thể kết nối MCP Server này vào bất kỳ dự án Magento nào để AI Agent ở dự án đó tham chiếu chuẩn kỹ thuật.

---

📌 Cấu trúc

• config/ — Nguồn sự thật:
  • constitution.md — Chuẩn kỹ thuật PHP 8.3 & Magento core.
  • checklist.md — Tiêu chí Review Gate & DoD.
  • magento-patterns.md — Bản đồ thiết kế (Plugin, Event, GraphQL, REST, Admin...).
  • references/ — Hướng dẫn mẫu code chi tiết cho từng component.
  • glossary.md — Thuật ngữ Magento core.
• examples/ — Blueprint mã mẫu theo chủ đề (vào examples/INDEX.md để chọn).
• src/index.js — MCP Server (stdio).

---

⚡ Cấu hình kết nối MCP Server

Claude Code (khuyến nghị scope user để available ở mọi project):

claude mcp add magento-spec -s user -- node /path/to/spec/src/index.js

Cursor (~/.cursor/mcp.json), Antigravity (~/.gemini/antigravity/mcp_config.json) và các client khác:

{
  "mcpServers": {
    "magento-spec": {
      "command": "node",
      "args": ["/path/to/spec/src/index.js"]
    }
  }
}

SPEC_ROOT (env) là tùy chọn — mặc định server tự lấy thư mục gốc của repo. Chỉ set khi bạn đặt repo ở nơi khác và muốn ghi đè.

---

🛠️ MCP Tools cung cấp cho AI

Tool	Mô tả
get_team_standards	Nạp nhanh Constitution, Checklist & Pattern index.
get_pattern_reference	Lấy chi tiết mẫu code theo tên (VD: core/plugin-patterns.md). Không truyền path → list tất cả references.
search_standards	Tìm kiếm chuẩn/quy tắc/blueprint theo từ khóa trong config/ + examples/.
get_review_gate	Nạp checklist kiểm tra chất lượng code trước khi hoàn thành.
read_spec_file	Đọc bất kỳ file tài liệu nào trong repo (config/, examples/, ...).

---

🔄 Quy trình khuyến nghị cho AI Agent

1. Trước code: get_team_standards → nạp Constitution + Checklist + Pattern index.
2. Khi implement: get_pattern_reference / search_standards / read_spec_file để tra cứu pattern — không đoán từ memory.
3. Trước khi báo done: get_review_gate → qua §12 Review Gate trong checklist.md.