# MCP BỆNH NHÂN ẢO — cho Claude soạn và kiểm thử ca bệnh

MCP server thứ hai, tách khỏi MCP dự án (`vietal_mcp.py`). Nó cho Claude làm việc trực tiếp với
**kho ca bệnh** và **bộ máy giả lập**, thay vì mở trình duyệt bấm tay.

| Ứng dụng | Địa chỉ | MCP dùng để |
|---|---|---|
| Patient Manager | `https://pnt.badt.vn/admin/patient_manager.php` | Soạn, kiểm tra, chuẩn hoá, lưu, lưu trữ hồ sơ ca bệnh (JSON) và sửa prompt hệ thống của simulator |
| Bệnh nhân giả lập | `https://dv.badt.vn/ai/virtualpatient` | Xem danh sách ca, chạy thử câu hỏi để nghe bệnh nhân trả lời, xem dữ liệu lâm sàng |

Tệp server: `tools/vp_mcp.py` — chỉ dùng thư viện chuẩn Python, không cần `pip install`.
Tải về: `https://dv.badt.vn/project/docs/tool/vp_mcp.py`

---

## 1. Cấu hình

```bash
export PM_USER='saber.aloui@chu-angers.fr'    # tài khoản portal pnt.badt.vn
export PM_PASS='********'                     # mật khẩu portal
export PM_BASE='https://pnt.badt.vn'          # tuỳ chọn
export VP_COOKIE='VIRTUALPATIENT_SESSION=...' # tuỳ chọn, cho ứng dụng 245
python3 vp_mcp.py
```

Claude Desktop (`claude_desktop_config.json`, thêm một mục cạnh `vietal`):

```json
{
  "mcpServers": {
    "benhnhan": {
      "command": "python3",
      "args": ["/duong/dan/vp_mcp.py"],
      "env": {
        "PM_USER": "saber.aloui@chu-angers.fr",
        "PM_PASS": "********"
      }
    }
  }
}
```

Claude Code:

```bash
claude mcp add benhnhan \
  --env PM_USER=saber.aloui@chu-angers.fr \
  --env PM_PASS='********' \
  -- python3 ~/vp_mcp.py
```

**Không** đặt mật khẩu vào tài liệu, ảnh chụp màn hình hay chat. Nếu lộ, đổi mật khẩu portal rồi cập nhật biến môi trường.

---

## 2. 19 công cụ

### Nhóm Patient Manager — `pm_*` (chạy được ngay bằng tài khoản portal)

| Công cụ | Việc |
|---|---|
| `pm_status` | Kiểm tra đăng nhập + số ca hiện có |
| `pm_list_patients` | Danh sách ca (id, tên, dung lượng, ngày sửa) |
| `pm_search_patients` | Tìm theo mã/tên |
| `pm_get_patient` | Đọc toàn bộ JSON của một ca |
| `pm_patient_summary` | Cấu trúc ca (khoá, kiểu dữ liệu, dung lượng) — đọc nhanh trước khi sửa |
| `pm_validate_case` | Kiểm tra JSON bằng đúng bộ kiểm tra của hệ thống (`validate_patient_json.py`), trả lỗi kèm dòng/cột |
| `pm_normalize_case` | Chuẩn hoá JSON (thụt lề, có thể sắp xếp khoá) trước khi lưu |
| `pm_save_case` | Lưu thành `patient_data/patients/<id>.json`; ghi đè phải nêu rõ `overwrite: true` |
| `pm_archive_patient` | Xoá mềm: chuyển vào `patient_data/archive_txt`, không xoá vĩnh viễn |
| `pm_get_prompt` | Đọc prompt hệ thống của simulator (ảnh hưởng mọi ca) |
| `pm_save_prompt` | Ghi prompt mới (tối đa 20.000 ký tự) |
| `pm_reset_prompt` | Khôi phục prompt mặc định |

### Nhóm ứng dụng giả lập — `vp_*` (cần cookie phiên)

| Công cụ | Việc |
|---|---|
| `vp_status` | Kiểm tra phiên |
| `vp_use_cookie` | Nạp cookie phiên trong lúc chạy |
| `vp_list_patients` | Danh sách ca trong ứng dụng (mã, tên, độ khó, giọng, trạng thái) |
| `vp_get_patient` | Thông tin một ca (theo id số hoặc mã `bn001`) |
| `vp_simulate_question` | Chạy thử một câu hỏi như sinh viên → nhận câu trả lời của bệnh nhân ảo |
| `vp_clinical_data` | Dấu hiệu sinh tồn và xét nghiệm của ca |
| `vp_chat_history` | Đọc lại hội thoại của một phiên luyện tập |

---

## 3. Quy trình chuẩn

### 3.1 Sửa một ca đang có (an toàn)

```
pm_patient_summary {id: "bn001"}      → xem cấu trúc trước
pm_get_patient     {id: "bn001"}      → đọc toàn bộ
(sửa nội dung)
pm_validate_case   {content}          → phải valid: true
pm_normalize_case  {content}          → lấy bản chuẩn hoá
pm_save_case       {patient_id: "bn001", content, overwrite: true}
```

Luôn đọc – sửa – kiểm tra – mới lưu. Không lưu khi `valid: false`.

### 3.2 Tạo ca mới

```
pm_list_patients                      → xem mã đã dùng tới đâu (bn001…)
pm_validate_case {content}             → kiểm tra
pm_save_case {patient_id: "bn301", content}   → lần đầu, overwrite mặc định false
```

### 3.3 Kiểm thử ca sau khi sửa (cần cookie)

```
vp_use_cookie {cookie: "VIRTUALPATIENT_SESSION=..."}
vp_simulate_question {patient_id: "bn301.txt", question: "Bác thấy khó chịu ở đâu?"}
vp_simulate_question {patient_id: "bn301.txt", question: "Đau từ khi nào?"}
vp_clinical_data {patient_id: "bn301"}
```

Đọc câu trả lời để phát hiện: bệnh nhân tự nói ra chẩn đoán, trả lời lan man, lộ thông tin không có trong hồ sơ.

---

## 4. Vì sao nhóm `vp_*` cần cookie

Ứng dụng `dv.badt.vn/ai/virtualpatient` đăng nhập **chung với bsgdtphcm.vn** (SSO Chamilo). Tài khoản
cấp qua SSO không đăng nhập được bằng mật khẩu ở chế độ dự phòng (`?local=1`), vì hệ thống chỉ cho
tài khoản cục bộ dùng mật khẩu. Muốn dùng nhóm `vp_*`:

1. Mở trình duyệt, đăng nhập ứng dụng bệnh nhân giả lập như bình thường.
2. Mở công cụ nhà phát triển → Application/Storage → Cookies → `dv.badt.vn` → sao chép giá trị
   `VIRTUALPATIENT_SESSION`.
3. Gọi `vp_use_cookie {cookie: "VIRTUALPATIENT_SESSION=..."}` (dùng một lần trong phiên) hoặc đặt biến
   môi trường `VP_COOKIE` (dùng lâu dài, tới khi cookie hết hạn ~30 ngày).

Cookie hết hạn thì các công cụ `vp_*` trả `http_401` — đăng nhập lại và nạp cookie mới.

---

## 5. Nguyên tắc an toàn

1. **Xoá là xoá mềm**: `pm_archive_patient` chuyển file vào `archive_txt`, phục hồi được.
2. **Ghi đè phải nêu rõ**: mặc định `overwrite: false`, hệ thống trả `exists: true` để Claude xin ý kiến.
3. **Prompt hệ thống ảnh hưởng mọi ca** — sửa prompt phải có lý do và nên đọc lại sau khi đổi.
4. **Không đưa mật khẩu vào nội dung ca bệnh**; không đưa dữ liệu bệnh nhân thật vào ca mô phỏng.
5. Mỗi lần sửa xong nên chạy `vp_simulate_question` 2–3 câu để chắc ca vẫn trả lời đúng vai.

---

## 6. Xử lý sự cố

| Hiện tượng | Nguyên nhân | Cách xử lý |
|---|---|---|
| `missing_credentials` | Thiếu `PM_USER`/`PM_PASS` | Đặt biến môi trường, khởi động lại Claude |
| `login_failed` | Sai mật khẩu portal | Kiểm tra lại; đổi mật khẩu thì cập nhật biến |
| `exists: true` | File ca đã tồn tại | Đọc lại ca, rồi `overwrite: true` nếu thật sự muốn thay |
| `JSON không hợp lệ` | Nội dung sai cú pháp | Dùng `pm_validate_case` để xem dòng/cột lỗi |
| `need_vp_cookie` | Chưa nạp cookie | `vp_use_cookie` hoặc `VP_COOKIE` |
| `http_401` ở `vp_*` | Cookie hết hạn | Đăng nhập lại, nạp cookie mới |

---

*Liên quan: `docs/AGENT_CLAUDE.md` (MCP dự án VIETAL), `docs/THIET_KE_HE_THONG.md` (thiết kế hệ thống).*

---

## 7. Làm việc bằng dòng lệnh (Claude Code, terminal, cron)

Có ba cách, chọn theo việc:

### 7.1 Cách gọn nhất — `vp_cli.py`

Tải: `https://dv.badt.vn/project/docs/tool/vp_cli.py`. Cấu hình một lần:

```bash
export PM_USER='saber.aloui@chu-angers.fr'
export PM_PASS='********'
export VP_COOKIE='VIRTUALPATIENT_SESSION=...'
```

hoặc tạo `~/.config/vpcli/cred.json`:

```json
{"user": "saber.aloui@chu-angers.fr", "pass": "********", "cookie": "VIRTUALPATIENT_SESSION=..."}
```

Lệnh thường dùng:

| Lệnh | Việc |
|---|---|
| `vp_cli.py status` | Kiểm tra cả hai ứng dụng đã đăng nhập chưa |
| `vp_cli.py list -q th276 -n 10` | Tìm ca trong bộ giả lập |
| `vp_cli.py show th276` | Thông tin ca (mã, độ khó, giọng, trạng thái) |
| `vp_cli.py ask th276 "Bác sốt mấy ngày rồi ạ?"` | Hỏi thử như sinh viên, nhận câu trả lời của bệnh nhân |
| `vp_cli.py ask th276 "Bác có ho không?" -s phien-01` | Hỏi tiếp trong cùng phiên (giữ ngữ cảnh) |
| `vp_cli.py history phien-01 th276.txt` | Đọc lại hội thoại của phiên |
| `vp_cli.py clinical th276` | Dấu hiệu sinh tồn, xét nghiệm |
| `vp_cli.py cases -n 20` | Danh sách 300 hồ sơ JSON |
| `vp_cli.py case bn001 --summary` | Cấu trúc hồ sơ trước khi sửa |
| `vp_cli.py case bn001` | In toàn bộ JSON |
| `vp_cli.py validate ca-moi.json` | Kiểm tra JSON (mã thoát 1 nếu sai) |
| `vp_cli.py save bn301 ca-moi.json` | Lưu (tự kiểm tra trước khi lưu) |
| `vp_cli.py save bn301 ca-moi.json --overwrite` | Ghi đè bản đang có |
| `vp_cli.py archive bn301` | Lưu trữ (xoá mềm) |
| `vp_cli.py prompt` / `prompt --set p.txt` / `prompt --reset` | Đọc / ghi / khôi phục prompt hệ thống |

Thêm `--json` cho bất kỳ lệnh nào để lấy JSON thô (dễ đưa sang công cụ khác).

**Dùng trong Claude Code:** chỉ cần bảo Claude chạy lệnh, ví dụ
«chạy `python3 vp_cli.py ask th276 "Bác sốt mấy ngày rồi ạ?"` rồi nhận xét câu trả lời có đúng vai bệnh nhân 3 tuổi không».
Claude Code gọi được `bash` nên không cần cấu hình MCP.

### 7.2 Cách có cấu trúc — MCP `benhnhan`

```bash
claude mcp add benhnhan \
  --env PM_USER=saber.aloui@chu-angers.fr \
  --env PM_PASS='********' \
  --env VP_COOKIE='VIRTUALPATIENT_SESSION=...' \
  -- python3 ~/vp_mcp.py
```

Dùng MCP khi muốn Claude tự chọn công cụ, tự chuỗi nhiều bước, và hiện kết quả có cấu trúc trong hội thoại.

### 7.3 Cách thô — gọi JSON-RPC trực tiếp

```bash
printf '%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"vp_list_patients","arguments":{"limit":5}}}' \
 | VP_COOKIE="$VP_COOKIE" python3 vp_mcp.py
```

### 7.4 Ghi chú kỹ thuật

- Câu hỏi văn bản đi qua `POST /process_chat.php` (field `query`), **không** dùng `process_simulation.php`
  vì endpoint đó bắt buộc có `audio_file`.
- Câu hỏi quá ngắn (dưới 4 từ và dưới 20 ký tự, không có dấu ?) bị hệ thống chặn với mã `KEYWORD_QUERY`
  — hãy hỏi thành câu đầy đủ.
- Mỗi lượt hỏi được ghi vào `chat_logs` gắn với tài khoản đang dùng cookie; muốn thử mà không ghi log thì
  dùng chế độ sandbox của ứng dụng.
- Cookie hết hạn (~30 ngày) thì `vp_*` trả `http_401`: đăng nhập lại, lấy cookie mới.
