← Danh mục tài liệu · raw markdown

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 Managerhttps://pnt.badt.vn/admin/patient_manager.phpSoạ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ậphttps://dv.badt.vn/ai/virtualpatientXem 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

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

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

Claude Code:

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_statusKiểm tra đăng nhập + số ca hiện có
pm_list_patientsDanh sách ca (id, tên, dung lượng, ngày sửa)
pm_search_patientsTìm theo mã/tên
pm_get_patientĐọc toàn bộ JSON của một ca
pm_patient_summaryCấu trúc ca (khoá, kiểu dữ liệu, dung lượng) — đọc nhanh trước khi sửa
pm_validate_caseKiể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_caseChuẩn hoá JSON (thụt lề, có thể sắp xếp khoá) trước khi lưu
pm_save_caseLưu thành patient_data/patients/<id>.json; ghi đè phải nêu rõ overwrite: true
pm_archive_patientXoá 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_promptGhi prompt mới (tối đa 20.000 ký tự)
pm_reset_promptKhô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_statusKiểm tra phiên
vp_use_cookieNạp cookie phiên trong lúc chạy
vp_list_patientsDanh sách ca trong ứng dụng (mã, tên, độ khó, giọng, trạng thái)
vp_get_patientThông tin một ca (theo id số hoặc mã bn001)
vp_simulate_questionChạ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_dataDấ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ượngNguyên nhânCách xử lý
missing_credentialsThiếu PM_USER/PM_PASSĐặt biến môi trường, khởi động lại Claude
login_failedSai mật khẩu portalKiểm tra lại; đổi mật khẩu thì cập nhật biến
exists: trueFile 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ápDùng pm_validate_case để xem dòng/cột lỗi
need_vp_cookieChưa nạp cookievp_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:

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

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

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

Lệnh thường dùng:

LệnhViệc
vp_cli.py statusKiểm tra cả hai ứng dụng đã đăng nhập chưa
vp_cli.py list -q th276 -n 10Tìm ca trong bộ giả lập
vp_cli.py show th276Thô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-01Hỏ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 th276Dấu hiệu sinh tồn, xét nghiệm
vp_cli.py cases -n 20Danh sách 300 hồ sơ JSON
vp_cli.py case bn001 --summaryCấu trúc hồ sơ trước khi sửa
vp_cli.py case bn001In toàn bộ JSON
vp_cli.py validate ca-moi.jsonKiểm tra JSON (mã thoát 1 nếu sai)
vp_cli.py save bn301 ca-moi.jsonLưu (tự kiểm tra trước khi lưu)
vp_cli.py save bn301 ca-moi.json --overwriteGhi đè bản đang có
vp_cli.py archive bn301Lư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

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

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

vì endpoint đó bắt buộc có audio_file.

— hãy hỏi thành câu đầy đủ.

dùng chế độ sandbox của ứng dụng.