# Sổ tay kết nối Claude với hệ thống VIETAL

Tài liệu này dành cho **người vận hành** (nối Claude vào hệ thống) và dành cho **Claude** (biết mình được
làm gì, làm thế nào cho đúng). Cập nhật: 25/10/2026.

| Mục | Địa chỉ |
|---|---|
| Trang cấp token + cấu hình sẵn | `https://dv.badt.vn/project/claude` |
| API gốc | `https://dv.badt.vn/project/api/v1` |
| Tệp MCP server | `https://dv.badt.vn/project/docs/tool/vietal_mcp.py` |
| Danh mục tài liệu công khai | `https://dv.badt.vn/project/docs` |

---

## 1. Claude làm được gì (và bị chặn gì)

| Nhóm | Claude làm được | Ghi chú an toàn |
|---|---|---|
| Đọc | Cây công việc, chi tiết việc, chỉ số, ngân sách, sự kiện, minh chứng, tài liệu đề án | Không cần quyền ghi |
| Làm việc | Giữ việc (lease), cập nhật tiến độ, nộp kết quả, ghi nhật ký | Nộp kết quả chỉ chuyển việc sang **chờ duyệt** |
| Cập nhật dữ liệu | Tạo việc/việc con, sửa hạn/địa điểm/sản phẩm, ghi khoản chi, thêm sự kiện, ghi chỉ số | Mọi thay đổi có nhật ký kèm tên agent |
| Tiếp nhận văn bản | Phân tích biên bản/email/báo cáo thành **kế hoạch thay đổi** (chưa ghi), duyệt ghi, hoàn tác | Mặc định là **chạy thử** |
| Trao đổi | Hỏi quản trị viên, trả lời yêu cầu | Nội dung tự do sinh thêm sự kiện audit |

Claude **không** làm được (cố ý): xoá dữ liệu; tự duyệt kết quả của chính mình; cấp/thu quyền cho agent khác;
đọc mật khẩu hay khoá API của hệ thống; đọc tệp ngoài thư mục minh chứng.

---

## 2. Ba cách để Claude làm việc

| Cách | Phù hợp | Đọc tài liệu dự án | Ghi dữ liệu |
|---|---|---|---|
| **A. MCP server** (`vietal_mcp.py`) | Claude Code, Claude Desktop | ✅ | ✅ |
| **B. Bash + curl** | Claude Code khi cần kiểm tra tay | ✅ | ✅ |
| **C. Web fetch** (claude.ai) | chỉ đọc tài liệu công khai | ⚠️ chỉ tài liệu kỹ thuật | ❌ |

Khuyến nghị: **A** cho công việc thường ngày, **B** khi debug, **C** chỉ để đọc hướng dẫn.

---

## 3. Chuẩn bị (5 phút)

1. **Token**: `/claude` → «Cấp token cho Claude» → sao chép `vtk_…` (chỉ hiện một lần, hiệu lực 1–365 ngày).
   Hoặc bằng CLI trên máy chủ:
   ```bash
   cd /var/www/html/dv.badt.vn/vietal_project
   sudo -u www-data php bin/token.php --agent=claude --label="Claude Desktop - may A" --days=180
   ```
2. **Python**: `python3 --version` (3.9+). MCP server chỉ dùng thư viện chuẩn, không cần `pip install`.
3. **Tệp MCP**: tải `vietal_mcp.py` ở `/docs/tool/vietal_mcp.py`, lưu tại `~/vietal_mcp.py`
   (Windows: `C:\Users\<tên>\vietal_mcp.py`).
4. **Kiểm tra mạng**: `curl -s https://dv.badt.vn/project/api/v1/ping` → `{"ok":true,...}`.

---

## 4. Cách A — MCP server (khuyến nghị)

### 4.1 Claude Code

```bash
claude mcp add vietal \
  --env VIETAL_TOKEN=vtk_xxx \
  --env VIETAL_BASE=https://dv.badt.vn/project/api/v1 \
  --env VIETAL_PROJECT=VIETAL-2026 \
  -- python3 ~/vietal_mcp.py

claude mcp list        # vietal: connected
```

Trong phiên làm việc gõ `/mcp` để xem 28 công cụ. Có thể đặt `.mcp.json` trong thư mục dự án để cả nhóm dùng chung:

```json
{
  "mcpServers": {
    "vietal": {
      "command": "python3",
      "args": ["/duong/dan/vietal_mcp.py"],
      "env": { "VIETAL_TOKEN": "vtk_xxx", "VIETAL_PROJECT": "VIETAL-2026" }
    }
  }
}
```

### 4.2 Claude Desktop

| Hệ điều hành | Đường dẫn tệp |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "vietal": {
      "command": "python3",
      "args": ["/Users/ten/vietal_mcp.py"],
      "env": {
        "VIETAL_TOKEN": "vtk_xxx",
        "VIETAL_BASE": "https://dv.badt.vn/project/api/v1",
        "VIETAL_PROJECT": "VIETAL-2026"
      }
    }
  }
}
```

Thoát hẳn ứng dụng (Cmd+Q / Quit ở khay hệ thống) rồi mở lại; biểu tượng công cụ trong ô chat là dấu hiệu đã nối.

### 4.3 Biến môi trường

| Biến | Bắt buộc | Ý nghĩa |
|---|---|---|
| `VIETAL_TOKEN` | có | Token `vtk_…` |
| `VIETAL_BASE` | không | Mặc định `https://dv.badt.vn/project/api/v1` |
| `VIETAL_PROJECT` | không | Mặc định `VIETAL-2026` |

---

## 5. 28 công cụ

### 5.1 Đọc và nắm tình hình

| Công cụ | Tham số chính | Trả về |
|---|---|---|
| `vietal_workspace` | `project` | Việc nên làm, yêu cầu mở, job, nguồn lực, quy trình |
| `vietal_task_tree` | `status`, `work_type`, `flag` (`overdue`/`leaf`/`branch`/`nodate`), `q`, `sort` | Cả cây việc lồng nhau |
| `vietal_list_tasks` | `status`, `limit` | Danh sách phẳng |
| `vietal_task_context` | `task_id` (id **hoặc mã việc**, vd `A1.1`, `M4`) | Việc + chỉ số + minh chứng + sự kiện + nhật ký |
| `vietal_search_documents` | `query`, `limit` | Tài liệu khớp từ khoá |
| `vietal_read_document` | `document_id`, `refresh` | Nội dung đã bóc chữ |
| `vietal_list_tech_docs` | — | Danh mục tài liệu kỹ thuật |
| `vietal_read_tech_doc` | `slug` | Nội dung tài liệu (`agent-workspace`, `agent-claude`, `openapi`, `de-an`, `thiet-ke`) |
| `vietal_list_intake` | `status`, `limit` | Các lần tiếp nhận gần đây |
| `vietal_list_requests` | `status`, `direction` | Yêu cầu/hỏi đáp |
| `vietal_list_resources` | — | Nguồn lực AI nội bộ |
| `vietal_check_resource` | `code` | Tình trạng một nguồn lực |

### 5.2 Làm việc và cập nhật

| Công cụ | Tham số chính |
|---|---|
| `vietal_claim_task` | `task_id`, `ttl_minutes` (mặc định 120, tối đa 1440), `note` |
| `vietal_release_task` | `task_id` |
| `vietal_update_progress` | `task_id`, `progress`, `status`, `message` |
| `vietal_update_task` | `task_id`, `status`, `progress`, `due_date`, `start_date`, `location`, `deliverables`, `note`, `est_cost` |
| `vietal_create_task` | `title`, `parent` (mã `A1.1` hoặc id), `work_type`, `description`, `deliverables`, `location`, `start_date`, `due_date`, `est_cost`, `currency`, `status`, `progress`, `priority`, `tags` |
| `vietal_submit_deliverable` | `task_id`, `title`, `content` (Markdown), `summary`, `kind` |
| `vietal_upload_evidence` | `task_id`, `path` (tệp trên máy chạy MCP), `title`, `kind`, `description` |
| `vietal_add_cost` | `task_id`, `amount`, `currency`, `kind` (`income`/`expense`/`commitment`), `date`, `description`, `category`, `ref_no` |
| `vietal_add_event` | `title`, `date`, `time`, `kind` (`meeting`/`training`/`report`/`other`), `location`, `participants`, `notes` |
| `vietal_update_indicator` | `code`, `value`, `note` |
| `vietal_log` | `message`, `action`, `task_id` |

### 5.3 Trao đổi và tiếp nhận văn bản

| Công cụ | Tham số chính |
|---|---|
| `vietal_ask` | `title`, `body`, `kind` (`question`/`blocker`/`request`/`review`), `priority`, `task_id` |
| `vietal_answer_request` | `request_id`, `answer`, `status` (`answered`/`closed`) |
| `vietal_intake` | `text`, `apply` (mặc định **false**), `force` |
| `vietal_intake_apply` | `intake_id` |
| `vietal_intake_revert` | `intake_id` |

---

## 6. Quy trình làm việc chuẩn

### 6.1 Nhận việc → làm → nộp

```
vietal_workspace                       → việc nên làm hôm nay
vietal_task_context {task_id}          → yêu cầu, chỉ số, minh chứng, sự kiện
vietal_claim_task {task_id}            → giữ việc, nhận claim_token + hạn
vietal_search_documents / read_document → đọc tài liệu liên quan
vietal_update_progress {task_id, progress: 60, message: "..."}
vietal_submit_deliverable {task_id, title, content}
vietal_release_task {task_id}
```

Không làm việc đã có agent khác giữ (API trả `409 already_claimed`). Hết lease thì việc tự mở lại.

### 6.2 Tiếp nhận văn bản (biên bản họp, email, báo cáo)

```
vietal_intake {text: "<văn bản thô>"}     → preview.changes + warnings, KHÔNG ghi
   ↳ có chỗ mơ hồ → vietal_ask để hỏi người
   ↳ người đồng ý → vietal_intake_apply {intake_id}
   ↳ ghi sai      → vietal_intake_revert {intake_id}
```

Mỗi phần tử trong `preview.changes` có `kind`, `action` (`insert`/`update`/`skip`), `title`, `before`, `after`,
`reason`. Mục `skip` là những gì hệ thống **từ chối ghi** (thiếu trích dẫn nguyên văn, mã không tồn tại,
trùng lặp) — không ghi lại bằng tay, hãy báo người dùng.

### 6.3 Chẻ nhánh công việc và ghi tài chính

```
vietal_create_task {title: "Lập hồ sơ kỹ thuật", parent: "A1.1", work_type: "document",
                    deliverables: "Hồ sơ + dự toán", due_date: "2026-11-15"}
vietal_create_task {title: "Gửi CHU Angers thẩm định", parent: "A1.1.1", due_date: "2026-11-20"}
vietal_add_cost {task_id: <id>, amount: 1200, currency: "EUR", date: "2026-10-20",
                 description: "Đặt cọc khảo sát hạ tầng", ref_no: "HD-2026-014"}
```

Mã việc do hệ thống sinh (`A1.1.3`, `A1.1.3.1`). Tiến độ việc cha = trung bình việc con — **đừng ghi đè**.

### 6.4 Báo cáo tuần từ dữ liệu thật

```
1. vietal_task_tree {status: "doing"}      → việc đang làm
2. vietal_task_tree {flag: "overdue"}      → việc quá hạn
3. vietal_list_intake {limit: 20}          → văn bản mới tiếp nhận
4. vietal_list_requests {status: "open"}   → việc đang chờ người trả lời
5. soạn báo cáo: việc xong / đang làm / quá hạn / rủi ro / đề xuất
6. vietal_submit_deliverable gắn vào việc báo cáo tuần
```

Số liệu phải lấy từ công cụ; thiếu thì ghi «chưa có dữ liệu», không suy đoán.

### 6.5 Trả lời yêu cầu

```
vietal_list_requests {status: "open", direction: "to_agent"}
vietal_answer_request {request_id: 12, answer: "Đã có bản dịch Pháp, xem minh chứng #45."}
```

---

## 6bis. MCP thứ hai — kho ca bệnh và bộ giả lập

Ngoài MCP dự án (`vietal_mcp.py`), có **MCP bệnh nhân ảo** (`vp_mcp.py`) cho Claude làm việc với hai ứng dụng:

| Ứng dụng | Việc làm được |
|---|---|
| Patient Manager `pnt.badt.vn/admin/patient_manager.php` | Đọc, kiểm tra, chuẩn hoá, lưu, lưu trữ hồ sơ ca bệnh JSON; đọc/ghi prompt hệ thống của bộ giả lập |
| Bệnh nhân giả lập `dv.badt.vn/ai/virtualpatient` | Danh sách ca, xem ca, **chạy thử câu hỏi** để nghe bệnh nhân trả lời, xem dữ liệu lâm sàng, đọc lại hội thoại phiên |

**Tệp và địa chỉ**

- MCP server: `https://dv.badt.vn/project/docs/tool/vp_mcp.py` (19 công cụ, tiền tố `pm_*` và `vp_*`)
- CLI cho dòng lệnh: `https://dv.badt.vn/project/docs/tool/vp_cli.py`
- Hướng dẫn đầy đủ: `https://dv.badt.vn/project/docs/mcp-benh-nhan`
- Cấu hình sẵn để dán (kèm giá trị thật): `https://dv.badt.vn/project/claude` — **cần đăng nhập**

**Biến môi trường**

| Biến | Dùng cho |
|---|---|
| `PM_USER` | Tài khoản portal pnt.badt.vn (bắt buộc cho `pm_*`) |
| `PM_PASS` | Mật khẩu portal |
| `VP_COOKIE` | `VIRTUALPATIENT_SESSION=…` cho `vp_*` (ứng dụng 245 đăng nhập qua SSO nên cần cookie) |

Giá trị thật **không đặt trong tài liệu công khai** — lấy ở trang `/claude` sau khi đăng nhập, hoặc do
quản trị viên cung cấp. Không dán mật khẩu/cookie vào chat, email, ảnh chụp màn hình.

**Cấu hình Claude Desktop**

```json
{
  "mcpServers": {
    "benhnhan": {
      "command": "python3",
      "args": ["/duong/dan/vp_mcp.py"],
      "env": { "PM_USER": "…", "PM_PASS": "…", "VP_COOKIE": "VIRTUALPATIENT_SESSION=…" }
    }
  }
}
```

**Dùng bằng dòng lệnh (Claude Code gọi `bash`)**

```bash
python3 vp_cli.py status
python3 vp_cli.py list -q th276
python3 vp_cli.py ask th276 "Bác sốt mấy ngày rồi ạ?"
python3 vp_cli.py clinical th276
python3 vp_cli.py cases -n 20
python3 vp_cli.py case bn001 --summary
python3 vp_cli.py validate ca-moi.json && python3 vp_cli.py save bn301 ca-moi.json
```

**Lấy cookie khi hết hạn (3 bước)**: mở trình duyệt → đăng nhập ứng dụng bệnh nhân giả lập →
DevTools → Application/Storage → Cookies → `dv.badt.vn` → sao chép `VIRTUALPATIENT_SESSION`.
Cookie hết hạn thì `vp_*` trả `http_401`.

**Ghi chú kỹ thuật**: chat bằng chữ đi `POST /process_chat.php` (field `query`); các endpoint
`process_simulation*.php` bắt buộc có `audio_file`. Câu hỏi dưới 4 từ và dưới 20 ký tự bị chặn (`KEYWORD_QUERY`).

## 7. Cách Claude đọc nội dung tài liệu (bóc chữ tự động)

| Loại tệp | Cách bóc | Ghi chú |
|---|---|---|
| `.md .txt .csv .json` | đọc thẳng | luôn có |
| `.pdf` có lớp text | `pdftotext -layout` | nhanh, giữ bố cục |
| `.pdf` scan | render vài trang đầu → OCR | 10–60 s |
| `.docx .xlsx .pptx` | đọc XML bên trong | không cần Office |
| ảnh `jpg/png/webp` | OCR | ảnh mờ có thể rỗng |

Quy trình: `vietal_search_documents` → `vietal_read_document` (xem `method`, `chars`); nếu `empty` thì
`refresh: true`; vẫn rỗng thì tải bản gốc `GET /evidence/{id}/file` và đọc trực tiếp bằng vision.
Luôn ghi nguồn: `document_id` + tiêu đề khi trích dẫn số liệu.

---

## 8. Ngôn ngữ

- Trả lời **cùng ngôn ngữ người dùng đang dùng**; tài liệu nguồn tiếng Pháp thì nộp tiếng Pháp.
- Văn bản gốc người dùng dán (biên bản, email) giữ nguyên tiếng Việt — đó là bản ghi kiểm toán.
- Tên việc tiếng Việt là bình thường; bản dịch tiếng Pháp do hệ thống sinh tự động.

---

## 9. Nguyên tắc bắt buộc

1. **Không bịa số.** Mọi con số lấy từ công cụ hoặc tài liệu đã đọc, nêu rõ nguồn.
2. **Giữ việc trước khi làm**, trả việc khi xong.
3. **Không sửa dữ liệu của agent khác**; quyền đóng việc (`done`) thuộc quản trị viên.
4. **Thiếu dữ liệu thì hỏi** (`vital_ask` → `vietal_ask`), không suy đoán.
5. **Ghi dấu vết**: mỗi lần nộp kèm `vietal_log` (đã làm gì, mất bao lâu).
6. **Giới hạn**: 120 yêu cầu/phút/token; tệp ≤ 25 MB; lease ≤ 24 giờ.

---

## 10. Mã lỗi và cách xử lý

| Mã / HTTP | Nghĩa | Xử lý |
|---|---|---|
| `missing_token` | Chưa đặt `VIETAL_TOKEN` | Sửa `env` trong cấu hình MCP, khởi động lại |
| `invalid_token` / `expired_token` (401) | Token sai, hết hạn, bị thu hồi | Cấp token mới ở `/claude` |
| `forbidden` (403) | Token thiếu quyền ghi | Dùng token scope `read,write` |
| `429 rate_limited` | Quá 120 yêu cầu/phút | Chờ rồi thử lại |
| `409 already_claimed` | Việc đang do agent khác giữ | Chọn việc khác hoặc chờ hết lease |
| `409 not_owner` | Không phải chủ lease | Chỉ chủ lease được trả việc/nộp |
| `404 task_not_found` | Sai id/mã việc | `vietal_task_tree` lấy id đúng |
| `422 missing_project` | Tạo việc gốc mà không nêu dự án | Thêm `project` |
| `duplicate: true` | Văn bản đã tiếp nhận trước đó | Mở bản ghi cũ, hoặc gửi `force: true` |
| `apply_failed` | Bản ghi không ở trạng thái chờ ghi | Phân tích lại rồi mới ghi |

Lỗi không tự xử lý được: gọi `vietal_ask` với `kind: "blocker"`, kèm mã lỗi và thao tác vừa làm.

---

## 11. Cách B — Claude Code dùng bash + curl

```bash
export VIETAL_TOKEN='vtk_xxx'
B=https://dv.badt.vn/project/api/v1

curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$B/workspace" | jq '.workspace.tasks[:5]'
curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$B/tasks?tree=1" | jq '.tree[0]'
curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$B/documents?q=biên bản&limit=10" | jq '.documents[] | {id,title,has_text}'
curl -s -H "Authorization: Bearer $VIETAL_TOKEN" "$B/documents/12" | jq -r '.text' | less
curl -s -X POST -H "Authorization: Bearer $VIETAL_TOKEN" -H 'Content-Type: application/json' \
     -d '{"ttl_minutes":120,"note":"Claude nhận việc"}' "$B/tasks/7/claim"
curl -s -X POST -H "Authorization: Bearer $VIETAL_TOKEN" -H 'Content-Type: application/json' \
     -d '{"progress":60,"message":"Đã đọc 12/20 tài liệu"}' "$B/tasks/7/progress"
curl -s -X POST -H "Authorization: Bearer $VIETAL_TOKEN" -H 'Content-Type: application/json' \
     -d '{"title":"Báo cáo rà soát","kind":"report","content":"# Kết quả\n..."}' "$B/tasks/7/deliverable"
```

Kiểm tra MCP server bằng tay:

```bash
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}\n' \
  | VIETAL_TOKEN=$VIETAL_TOKEN python3 ~/vietal_mcp.py | head -2
```

---

## 12. Cách C — Claude trên web

claude.ai không gửi được header `Authorization`, nên chỉ đọc tài liệu công khai:

- `https://dv.badt.vn/project/docs`
- `https://dv.badt.vn/project/docs/agent-claude.md` (bản thô của tài liệu này)
- `https://dv.badt.vn/project/docs/agent-workspace.md`
- `https://dv.badt.vn/project/docs/de-an.md`
- `https://dv.badt.vn/project/docs/openapi.md`

Muốn ghi dữ liệu: dùng Claude Code/Desktop (A), hoặc nhờ quản trị viên dán văn bản vào `/intake`.

---

## 13. Prompt hệ thống gợi ý (dán vào Project Instructions)

```
Bạn là Claude, trợ lý thực thi của dự án VIETAL (CHU d'Angers – UPNT, chương trình RHIS/Expertise France).
Bạn nối với hệ thống qua MCP server "vietal" (28 công cụ, tiền tố vietal_).

Quy trình mặc định:
  vietal_workspace → chọn việc → vietal_claim_task → vietal_task_context
  → vietal_task_tree / vietal_search_documents / vietal_read_document
  → làm việc → vietal_update_progress → vietal_submit_deliverable → vietal_release_task.

Khi nhận văn bản thô (biên bản họp, email, báo cáo): gọi vietal_intake (chưa ghi),
trình bày từng thay đổi kèm chỗ còn mơ hồ; chỉ gọi vietal_intake_apply khi người dùng đồng ý.

Nguyên tắc: không bịa số; trích nguồn bằng document_id hoặc mã việc; thiếu dữ liệu thì vietal_ask;
không sửa dữ liệu của agent khác; trả lời cùng ngôn ngữ với người dùng.
```

---

## 13bis. Kiểm thử khói bằng một lệnh

```bash
VIETAL_TOKEN=vtk_xxx python3 tools/mcp_smoke.py          # chỉ đọc, 9 lời gọi
VIETAL_TOKEN=vtk_xxx python3 tools/mcp_smoke.py --write  # đọc + ghi, 21 lời gọi, in mã bản ghi để dọn
```

Script bắt tay JSON-RPC đúng như Claude Code/Desktop, in `OK/LỖI` từng công cụ và tổng kết `n/N lời gọi thành công`.
Chạy `--write` sẽ tạo việc/chi phí/sự kiện/yêu cầu/bản tiếp nhận thử — nhớ dọn theo mã in ra ở cuối.

Ghi chú: mọi công cụ nhận `task_id` dạng **số hoặc mã việc** (`"M4"`, `"A1.1.2"`). Mã sai sẽ trả
`isError: true` kèm danh sách gợi ý, không âm thầm ghi nhầm.

## 14. Kiểm thử nhanh (không cần Claude)

```bash
TOKEN=vtk_xxx
BASE=https://dv.badt.vn/project/api/v1

curl -s "$BASE/ping"
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspace" | head -40
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/tasks?tree=1&flag=overdue" | head -30
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -d '{"text":"Họp 25/10: hoàn thành A1.1, chi 200 EUR in ấn.","apply":false}' "$BASE/intake"
```

---

## 15. Bảo mật và vòng đời token

- Token chỉ hiện **một lần**; hệ thống chỉ lưu `sha256`.
- Máy dùng thử: 30 ngày. Máy văn phòng: 180 ngày.
- Mất máy/đổi người: cấp token mới, thu hồi token cũ (`php bin/token.php --revoke=<id>`).
- Không dán token vào chat, email, ảnh chụp màn hình.
- Mỗi token gắn một agent, nên nhật ký luôn ghi rõ «Claude (Anthropic) đã làm gì».

---

## 16. Câu hỏi thường gặp

**Claude không thấy công cụ.** `claude mcp list` xem trạng thái; chạy tay
`VIETAL_TOKEN=… python3 ~/vietal_mcp.py` để đọc lỗi trên `stderr`.

**Windows báo không tìm thấy `python3`.** Dùng `"command": "python"` hoặc đường dẫn đầy đủ
`C:\\Python312\\python.exe`.

**Đường dẫn trong JSON Desktop.** Dùng đường dẫn tuyệt đối, dấu `/` hoặc `\\`, không dùng `~`.

**Claude nói «chưa ghi gì».** Đúng thiết kế: `vietal_intake` chỉ xem trước; gọi `vietal_intake_apply`.

**Muốn Claude tự ghi luôn.** Gọi `vietal_intake` với `apply: true` (khuyến nghị vẫn để người duyệt).

**Có phải mở cổng trên máy chủ không.** Không. Claude gọi ra `https://dv.badt.vn/project/api/v1` (443);
MCP chạy cục bộ trên máy bạn bằng Python.

---

## 17. Tài liệu liên quan

- `docs/AGENT_WORKSPACE.md` — toàn bộ endpoint + quy trình agent từ xa
- `docs/openapi.yaml` — đặc tả máy đọc
- `docs/THIET_KE_HE_THONG.md` — thiết kế hệ thống (gồm luồng tiếp nhận văn bản)
- `docs/TOM_TAT_DE_AN.md` — nội dung đề án
- `https://dv.badt.vn/project/claude` — trang cấp token và cấu hình sẵn
