Magento Skills MCP

MCP server cung cấp 45 skill Magento 2 / Hyvä từ 5 nguồn upstream cho AI trong IDE. Server hỗ trợ tìm skill, đọc hướng dẫn và lấy tài liệu, template, mã script đi kèm, kèm URL nguồn và commit cụ thể.

Server chạy local qua stdio, sử dụng MCP SDK chính thức. GitHub lưu mã nguồn để người dùng clone về chạy; không đóng vai trò máy chủ MCP đang hoạt động. Server này cung cấp kiến thức phát triển, không kết nối cửa hàng Magento hoặc thực thi lệnh Magento.

Cài đặt

Yêu cầu: Node.js 22 trở lên, npm, Git và kết nối GitHub ở bước tải nguồn. Cài sẵn Claude Code hoặc Codex nếu dùng các lệnh kết nối bên dưới.

Các lệnh dưới đây dành cho terminal Linux/macOS hoặc WSL. Chạy MCP và client trong cùng môi trường để client truy cập được đường dẫn local.

Clone thangpham0906/magento-mcp vào vị trí bạn muốn giữ lâu dài, rồi cài đặt:

git clone https://github.com/thangpham0906/magento-mcp.git
cd magento-mcp
npm ci
npm run setup

Nếu đã có bản clone trên máy, mở terminal tại thư mục đó và chỉ chạy hai lệnh npm. Setup thành công sẽ có dòng Verified 45 selected skills from 5 pinned sources. Có thể chạy thêm npm test để kiểm thử server.

npm run setup tải các repository được khai báo trong skills/catalog.json, checkout đúng commit và kiểm tra skill. Chạy lại lệnh này sẽ giữ nguyên những bản clone đã đúng phiên bản. Nếu thư mục nguồn có thay đổi local, sai origin hoặc khác commit, lệnh sẽ báo lỗi để bạn xử lý, không tự reset dữ liệu.

Thư mục node_modules và các bản clone upstream được bỏ qua bằng .gitignore. Người dùng clone project từ GitHub cần chạy setup; không cần commit các repository con hoặc tạo submodule. Không có script cài đặt tự động tải upstream khi chạy npm ci.

Sau setup, MCP hoạt động offline và không cần API key. Server tra cứu đường dẫn theo vị trí mã nguồn, nên có thể được IDE khởi chạy từ thư mục làm việc khác.

Related MCP server: SkillPort

Kết nối Claude Code

Từ thư mục gốc magento-mcp vừa cài đặt, chạy:

claude mcp add --transport stdio --scope user magento-skills -- \
  node "$PWD/src/index.js"

--scope user đăng ký server cho tài khoản hiện tại để dùng trong nhiều project. $PWD được shell thay bằng đường dẫn tuyệt đối khi chạy lệnh. Giữ nguyên vị trí thư mục sau khi đăng ký; nếu di chuyển, cập nhật lại cấu hình MCP.

Mở một phiên Claude Code mới trong project Magento của bạn và nhập:

/mcp

Kiểm tra magento-skills đã kết nối. Sau đó gửi yêu cầu:

Dùng magento_list_skills liệt kê toàn bộ skill và cho biết tổng số.

Kết quả mong đợi là 45 skill. Tiếp theo có thể yêu cầu:

Dùng magento_get_skill đọc magento-code-reviewer, rồi áp dụng để review module tôi chỉ định.

Claude Code tự khởi động server; không cần chạy npm start ở terminal riêng. Xem hướng dẫn MCP của Claude Code.

Kết nối Codex CLI hoặc extension

Nếu dùng Codex, từ thư mục gốc magento-mcp chạy:

codex mcp add magento-skills -- node "$PWD/src/index.js"
codex mcp list

codex mcp list xác nhận server đã được đăng ký, chưa phải kiểm thử gọi tool. Khởi động lại extension Codex hoặc mở phiên CLI mới, rồi gửi yêu cầu liệt kê skill như ví dụ phía trên để kiểm tra kết nối thực tế. Trong Codex CLI có thể dùng /mcp để xem các server đang kết nối.

Codex CLI và extension chia sẻ cấu hình MCP trên cùng host. Xem hướng dẫn MCP của OpenAI.

Kết nối client khác bằng JSON

Thêm cấu hình sau vào phần cấu hình MCP của client hỗ trợ stdio. Thay đường dẫn bằng đường dẫn tuyệt đối đến bản clone của bạn:

{
  "mcpServers": {
    "magento-skills": {
      "command": "node",
      "args": ["/absolute/path/magento-mcp/src/index.js"]
    }
  }
}

Nếu IDE không tìm được Node trong PATH, thay node bằng đường dẫn tuyệt đối đến executable Node. Một số client dùng cấu trúc cấu hình riêng; nhập cùng command và args trong giao diện cấu hình MCP của client đó.

IDE sẽ quản lý tiến trình MCP. Khi chạy thủ công bằng npm start, server chờ dữ liệu giao thức trên stdin; không có trang web hoặc cổng HTTP. Khi cấu hình client, gọi trực tiếp node src/index.js như ví dụ để stdout chỉ chứa dữ liệu MCP.

Xử lý lỗi kết nối

Có thể kiểm tra riêng thư viện nguồn bằng npm run skills:check, hoặc kiểm tra giao thức stdio bằng npm test, từ thư mục gốc MCP.

Công cụ

Ví dụ quy trình để AI xử lý một component Hyvä:

1. Gọi magento_list_skills với {"query":"alpine","source":"hyva-ai-tools"}.

2. Gọi magento_get_skill với {"name":"hyva-alpine-component"}.

3. Đọc file hỗ trợ bằng magento_read_skill_file nếu cần, dùng đúng đường dẫn trong trường files.

Tìm kiếm dùng các từ khóa tiếng Anh trong tên và mô tả upstream, không phải tìm kiếm ngữ nghĩa. Các từ trong query đều phải xuất hiện trong tên, mô tả hoặc mã nguồn repository của kết quả.

Các tool chỉ đọc thư viện. Script được trả về dưới dạng văn bản, không được server chạy. Client sử dụng nội dung skill trong phạm vi công việc được người dùng yêu cầu.

Resources và prompt

• magento-skills://catalog: danh mục cùng thông tin nguồn dưới dạng JSON.

• magento-skills://skill/<name>: nội dung Markdown của từng skill.

• Prompt magento_use_skill: nhận name và task để đưa skill phù hợp vào ngữ cảnh tác vụ.

MCP chỉ công bố các skill trong manifest, kể cả khi upstream chứa nhiều skill khác. Đọc file giới hạn trong thư mục skill, chặn đường dẫn đi ra ngoài và symlink vượt phạm vi; chỉ hỗ trợ file UTF-8 tối đa 1 MiB. Nội dung chính và danh mục được tải khi server khởi động. Hãy dừng server trước khi thay đổi nguồn và khởi động lại sau khi kiểm tra xong.

Quản lý nguồn

skills/README.md ghi rõ tác giả, giấy phép, phiên bản và liên kết tới từng skill. skills/catalog.json là manifest mà server và lệnh setup sử dụng, gồm:

• id: tên thư mục nguồn dưới skills/.

• repository: URL GitHub của tác giả.

• revision: commit SHA đầy đủ để tái tạo phiên bản.

• skills: các tên skill được phép cung cấp.

Để nâng phiên bản, kiểm tra thay đổi upstream, cập nhật bản clone và revision trong manifest cùng nhau, sau đó chạy:

npm run skills:check
npm test

Server từ chối khởi động nếu thiếu nguồn, sai commit, nguồn có thay đổi local hoặc metadata skill không hợp lệ. Khi thêm/bỏ skill, cập nhật cả manifest, danh sách trong skills/README.md và số lượng kỳ vọng trong test.

Kiểm thử

npm test kiểm tra đọc catalog, lọc skill, nguồn bị thiếu hoặc thay đổi, giới hạn file và chặn traversal/symlink. Bài kiểm thử tích hợp khởi chạy server bằng MCP client qua stdio từ một thư mục khác và gọi tools, resources, prompt thực tế. Các test cần chạy sau npm run setup.

Workflow GitHub Actions trong .github/workflows/ci.yml chạy setup và test trên Node 22 và 24. Việc kiểm tra này xác nhận MCP cung cấp nội dung đúng giao thức; không xác nhận mọi hướng dẫn upstream đều đúng với mọi phiên bản Magento.