# 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](https://github.com/modelcontextprotocol/typescript-sdk). 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](https://github.com/thangpham0906/magento-mcp) vào vị trí bạn muốn giữ lâu dài, rồi cài đặt:

```sh
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](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.

## Kết nối Claude Code

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

```sh
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:

```text
/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](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server).

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

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

```sh
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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

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

```json
{
  "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

| Hiện tượng | Cách xử lý |
| --- | --- |
| Không tìm thấy `claude` hoặc `codex` | Cài CLI tương ứng và kiểm tra `PATH` của terminal. |
| Client không tìm thấy `node` hoặc báo `ENOENT` | Chạy `command -v node`, rồi thay `node` trong cấu hình MCP bằng đường dẫn tuyệt đối vừa nhận được. |
| Báo `Missing source` | Chạy `npm run setup` từ thư mục gốc `magento-mcp`. |
| Báo `Cannot find module` | Kiểm tra đường dẫn `src/index.js` và chạy `npm ci` trong bản clone MCP. |
| Báo `Revision mismatch` hoặc `local changes` | Xem phần quản lý nguồn bên dưới; đối chiếu commit và thay đổi local trước khi khởi động lại. |
| Đã đăng ký nhưng chưa thấy tool | Mở phiên client mới hoặc khởi động lại extension, kiểm tra trạng thái MCP và log lỗi khởi động. |
| Chạy `npm start` thấy terminal chờ | Đây là server stdio chờ client, không phải web server. Dừng bằng Ctrl+C và để client khởi động bằng cấu hình MCP. |

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ụ

| Tool | Đầu vào | Kết quả |
| --- | --- | --- |
| `magento_list_skills` | `query?`, `source?` | Tên, mô tả, nguồn, commit và URI của skill phù hợp |
| `magento_get_skill` | `name` | Toàn bộ `SKILL.md`, nguồn và danh sách file hỗ trợ |
| `magento_read_skill_file` | `name`, `path` | Nội dung UTF-8 của file trong skill đã chọn |

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](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](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:

```sh
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](.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.