# vcihub-mcp

Cho **Claude Code** đọc và ghi issue trong [VCI Hub PM](https://app.vcijsc.com)
ngay từ terminal, ở bất kỳ thư mục nào. Hỏi bằng tiếng Việt bình thường, AI tự
chọn dự án và đề xuất việc tiếp theo.

> Đây là gói đã build sẵn. Mã nguồn nằm trong repo `vci-hub-erp`
> (`scripts/pm-mcp/`), phát hành bằng `npm run vcihub:publish`.

## Cài — một lệnh

Cần **Node.js ≥ 18** ([nodejs.org](https://nodejs.org)) và **Claude Code** đã mở
ít nhất một lần.

```bash
npx --yes github:cuongvci/vcihub-mcp
```

Lệnh hỏi **email + mật khẩu VCI Hub** của bạn (mật khẩu không được lưu, chỉ lưu
token trong `~/.vcihub/`), rồi đăng ký server `vcihub` cho Claude Code ở
**phạm vi user** — mọi thư mục đều dùng được, không phải cấu hình từng repo.

Xong thì **đóng hẳn Claude Code và mở lại**, gõ `/mcp` thấy `vcihub` là ổn.

| Lệnh | Việc |
|---|---|
| `npx --yes github:cuongvci/vcihub-mcp` | cài, hoặc cập nhật lên bản mới nhất |
| `… vcihub-mcp --check` | xem thiếu mảnh nào |
| `… vcihub-mcp --tu-cap-nhat` | bật tự cập nhật ngầm khi có bản mới |
| `… vcihub-mcp --dang-nhap-lai` | đăng nhập lại / đổi tài khoản |
| `… vcihub-mcp --go` | gỡ cài đặt (giữ token; thêm `--ca-token` để xoá luôn) |

## Dùng

Không cần nhớ tên tool, cứ hỏi:

```
dự án IMS còn bug nào đang mở chưa gán ai?
tình hình dự án thế nào?
ai là DEV, ai test trong dự án này?
IMS-3932 thuộc epic nào?
tôi vừa test màn phiếu chờ duyệt, phân trang nhảy về trang 1 khi đổi bộ lọc
đính ảnh loi.png vào IMS-4079
chuyển sang dự án WMS
```

**Chọn dự án:** bạn nêu tên hoặc key, hoặc đặt file `.vcihub.json` trong thư mục
làm việc (`{ "du_an": "IMS" }`), hoặc để AI đoán theo tên thư mục repo — nó sẽ
nói rõ đang dùng dự án nào. Đổi dự án giữa chừng thoải mái.

**Khi tạo hoặc sửa issue**, AI luôn nói trước và hỏi xác nhận. Nó tự kiểm trùng,
tự đặt Defect dưới đúng Task cha, gợi ý người phụ trách và tester theo lịch sử
phân công, và gắn nhãn `ai-test` để bạn lọc lại sau.

Quy ước đặt issue (Epic → Task → Sub-task/Defect, mẫu mô tả lỗi, severity) nằm
trong `skill/vci-pm/SKILL.md` — cũng chính là thứ AI đọc.

## Có bản mới thì sao

Sidecar tự hỏi phiên bản mới lúc khởi động. Có bản mới, Claude sẽ nhắc bạn ngay
lần hỏi đầu tiên:

```
[vcihub-mcp] Có bản mới v1.0.… (đang dùng …). Cập nhật: chạy npx --yes github:cuongvci/vcihub-mcp
```

Chạy lại lệnh cài là xong, token giữ nguyên. Muốn khỏi phải nhớ thì cài một lần
với `--tu-cap-nhat`.

## Sự cố thường gặp

| Hiện tượng | Làm gì |
|---|---|
| `/mcp` không thấy `vcihub` | Đã **mở lại** Claude Code chưa? Rồi thì chạy `npx --yes github:cuongvci/vcihub-mcp --check`, mảnh nào ✗ thì cài lại |
| `Token không còn hiệu lực` / đòi đăng nhập | `npx --yes github:cuongvci/vcihub-mcp --dang-nhap-lai` |
| `Không tìm thấy dự án … không phải thành viên` | Nhờ PM thêm bạn vào dự án trên VCI Hub |
| `~/.claude.json không phải JSON hợp lệ` | File cấu hình Claude Code hỏng từ trước; khôi phục từ `~/.claude.json.bak-vcihub` |
| Không tạo được issue, báo thiếu loại `Defect` | Dự án chưa bật loại đó — nhờ PM bật trong Cài đặt dự án |
| Muốn dùng tài khoản khác | `npx --yes github:cuongvci/vcihub-mcp --dang-nhap-lai` |

## Bảo mật

- **Không có khoá quản trị.** Mọi truy vấn chạy bằng tài khoản của chính bạn, đúng
  quyền bạn có trên web. Bạn thấy gì trên VCI Hub thì AI thấy đúng thế.
- **Không có lệnh xoá.** Bộ tool cố ý không thể xoá issue, không đổi dự án của
  issue, không tạo Epic/Task.
- **Không gửi mã nguồn đi đâu.** Sidecar chạy trên máy bạn, chỉ nói chuyện với
  Supabase của VCI Hub. File chỉ được tải lên khi bạn bảo nó đính kèm.
- Token nằm ở `~/.vcihub/`, ngoài mọi repo, nên không lỡ commit.

## Trong gói có gì

| File | Việc |
|---|---|
| `pm-mcp.mjs` | sidecar MCP, đã bundle sẵn |
| `install.mjs`, `vcihub-mcp.mjs` | cài / gỡ / kiểm tra |
| `login.mjs` | đăng nhập, ghi token |
| `config.json` | URL Supabase + anon key (khoá công khai phía client) |
| `skill/vci-pm/` | quy ước đặt issue cho AI |

Không chứa token, mật khẩu hay khoá quản trị của bất kỳ ai.