# TomGPM MCP — Ra lệnh tiếng Việt, agent mở profile GPMLogin dùm

<p align="center"><strong>STDIO MCP · Python 3.12 · Windows | 69/69 tests</strong></p>

![version](https://img.shields.io/badge/version-0.1.0a1-blue?style=for-the-badge) ![python](https://img.shields.io/badge/Python-3.12-green?style=for-the-badge) ![platform](https://img.shields.io/badge/Platform-Windows-lightgrey?style=for-the-badge) ![mcp](https://img.shields.io/badge/MCP-STDIO-orange?style=for-the-badge) ![tests](https://img.shields.io/badge/Tests-69%2F69-brightgreen?style=for-the-badge)

Repo: [tqduc013/tomgpm-mcp](https://github.com/tqduc013/tomgpm-mcp)

[English](README.en.md) · [Setup Windows](docs/windows-setup.md) · [Tools](docs/tools.md) · [Test report](docs/test-report.md) · [Live smoke](docs/live-smoke-2026-09-30.md)

---
## 📥 Cài đặt

Mở PowerShell trong `D:\Projects\tomgpm-mcp`.

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
```

Bật GPMLogin trước. Không cần `Activate.ps1`, gọi thẳng exe trong venv.

## 🚀 Chạy

Check kết nối. Thay port theo app thực tế.

```powershell
$env:GPM_BASE_URL = "http://127.0.0.1:19995"
$env:GPM_API_FLAVOR = "gpm-v3"
.\.venv\Scripts\tomgpm-mcp.exe doctor
```

Global v1 thì đổi `http://127.0.0.1:9495` + `global-v1`.

Nối Claude Desktop. Thoát Claude hoàn toàn trước.

```powershell
.\scripts\configure-claude.ps1 -Executable ".\.venv\Scripts\python.exe" -Kind python -Flavor gpm-v3 -Port 19995
```

Hoặc copy `examples/claude-desktop.python.json`, merge vào `mcpServers`, không ghi đè server khác. Mở lại Claude, prompt thử:

> Kiểm tra kết nối GPMLogin, rồi liệt kê 5 profiles. Chưa thay đổi gì.

Chẩn đoán ổn mới sửa `TOMGPM_READ_ONLY` thành `"false"`, restart client.

Client khác lấy file trong `examples/`: `cursor.mcp.json`, `clients/vscode.mcp.json`, `windsurf.mcp.json`, `cline.mcp.json`, `gemini.settings.json`, `antigravity.mcp_config.json`, `clients/opencode.json`, `qoder.settings.json`, `codex.config.toml`, `claude-code.commands.txt`. ChatGPT web xem `chatgpt-bridge.readme.txt`.

Nhập proxy. Không paste password vào chat.

```powershell
.\.venv\Scripts\tomgpm-mcp.exe proxy add us-01
.\.venv\Scripts\tomgpm-mcp.exe proxy list
```

## 🧩 Tính năng

| Tính năng | ✅ |
|---|---|
| Health check, không mở browser | ✅ |
| List/search profiles, phân trang, lấy ID | ✅ |
| Get profile đã lọc, không trả credentials/fingerprint/path | ✅ |
| Tạo 1 profile bằng proxy alias + `operation_id` | ✅ |
| Rename, chỉ đổi tên | ✅ |
| Start/stop 1 profile đúng ID | ✅ |
| Lịch sử start/stop trong process | ✅ |
| Delete preview + approve local + stop gần đây | ✅ |
| Proxy alias trong Credential Manager | ✅ |
| 2 flavor `gpm-v3` 19995 và `global-v1` 9495 | ✅ |

Xóa chạy 3 bước: `dry_run=true` lấy `approval_id` → terminal gõ `tomgpm-mcp approve` + `DELETE ID` → agent `stop` rồi execute cùng ID/mode/approval trong 60 giây.

## 🔄 Cơ chế

```text
Agent → MCP stdio → tomgpm-mcp → GPM Local API → browser
```

Create journal theo `operation_id` trong SQLite. Trùng ID khác payload thì báo conflict. Unknown thì giữ pending, không tạo ID mới để retry. Per-profile lock + 1 server / 1 data dir.

## 📁 Cấu trúc

```text
src/tomgpm_mcp/server.py      transport MCP
src/tomgpm_mcp/tools.py       10 tools + dispatch
src/tomgpm_mcp/adapters.py    gpm-v3 / global-v1
src/tomgpm_mcp/service.py     lock, journal, approval
src/tomgpm_mcp/proxy.py       Credential Manager
examples/                     config từng client
docs/live-smoke-2026-09-30.md bằng chứng chạy thật
```

## 🧪 Test

| Check | Kết quả |
|---|---|
| `unittest discover -s tests` | ✅ 69/69 |
| `ruff check .` | ✅ |
| `doctor` v3 + global live | ✅ reachable |
| Create → approve → stop → delete rác | ✅ `vendor_reported_deleted` |

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -m ruff check .
```

## ⚠️ Lưu ý

- Mặc định `READ_ONLY=true`, `ENABLE_DELETE=false`. Muốn ghi/xóa thì mở tay.
- Approval hết hạn 10 phút, xài 1 lần. Không cấp terminal cho agent tự approve.
- Tên profile trùng thì hỏi lại, không đoán ID. Alias US không chứng minh IP ở US.
- Không chạy v3 + global chung 1 `TOMGPM_DATA_DIR`.
- Không có browser automation / Playwright. GPM Automate không có API nên bản này skip.
- Không liên kết Anthropic hay GPMLogin. License GPM áp dụng độc lập. [MIT](LICENSE).

## Author

**tqduc013** — tool nội bộ GPM sale.