monacloud-mcp

# monacloud-mcp

`monacloud-mcp` là MCP hợp nhất của MONA Cloud: cài một lần, đăng nhập một MONA Pass và dùng chung ví VND để quản lý tài khoản, chạy app/VPS, tạo Base beta thay Supabase, tích hợp MONA Pay, gửi email giao dịch bằng MONA Mail và đọc catalog MONA Agent ngay trong Claude Code, Codex hoặc Cursor.

Human đăng ký MONA Pass một lần, duyệt chi phí, thêm DNS khi cần, quét QR nạp ví do AI tạo và cung cấp OTP/KYC khi bắt buộc. Các bước tạo yêu cầu nạp, tạo tài nguyên, đọc trạng thái, cấu hình webhook, test và deploy được thiết kế để AI agent làm qua MCP.

## 0.8.1 — luật nạp ví đứng đầu instructions

Codex chỉ chắc chắn đọc 512 ký tự đầu của `instructions` MCP, nên luật "ví thiếu → AI tự gọi `cloud_topup`, in QR" được đưa lên đầu; mô tả hệ và APP_FLOW đặt sau. Kiểm thử 17/09: Claude Code (sonnet) và Gemini (Antigravity CLI) tự gọi `cloud_topup` và in QR khi người dùng nói "ví hết tiền, nạp 50k"; Codex chạy headless (`codex exec`) mặc định chặn mọi lời gọi MCP theo approval policy; thêm `--approve-for-me` thì Codex cũng tự gọi `cloud_topup` và in QR (kiểm 17/09). Codex tương tác thì duyệt lời gọi tool như bình thường.

## 0.8.0 — Nạp ví ngay trong terminal

Ví thiếu tiền thì AI gọi `cloud_topup(amount)`; MCP trả **`qr_ascii`** (QR VietQR chuẩn EMVCo/NAPAS in bằng khối đầy `██`, Claude Code/Codex/Gemini CLI hiện được ngay; terminal nền sáng dùng `qr_ascii_light`, bản gọn `qr_ascii_small`; đã giải mã được bằng ZBar và OpenCV ở cả hai nền), `qr_file` (PNG tại `~/.config/monacloud/`), `qr_url` (ảnh VietQR) cùng ngân hàng, số tài khoản, số tiền, nội dung chuyển khoản. Người dùng mở app ngân hàng quét màn hình, tiền vào tự cộng ví; AI gọi `cloud_topup_status(topup_id)` tới khi `paid` rồi làm tiếp. base64 không còn nằm trong text (tiết kiệm 15–25k token mỗi lần). Khi ví chung (`billing`) chưa nhận token hoặc merchant MONA Pay chưa cấu hình, `cloud_topup` tự chuyển sang đường compute `/api/payments/vietqr` (ví local, prefix VIBECLOUD, báo có tự cộng).

## 0.5.0 — MONA Base beta

Thêm `cloud_base_create/list/get/delete/credentials` cùng alias `vibecloud_base_*`. Base thay Supabase, chung MONA Pass/ví MONA Cloud và khớp app deploy. Sandbox chỉ ước tính, không provision; chờ Base provision-live trước khi publish package.

## 0.4.0 — Đưa thư mục hiện tại lên web

Prompt Claude Code: **“Đưa dự án này lên MONA Cloud, dùng thư mục hiện tại”**.

AI làm 99%: `cloud_app_detect(local_dir)` offline → đọc host và giá → sandbox nếu cần host mới → hỏi duyệt chi phí một lần → `cloud_app_create(local_dir)` → kiểm và trả URL. Có domain riêng thì `cloud_app_domain_add` và hướng dẫn CNAME. Human đăng ký MONA Pass qua device flow; hết credit 20k thì AI gọi `cloud_topup` và in QR, human chỉ quét.

| Tool | Đầu vào / hành vi 0.4.0 |
|---|---|
| `cloud_app_detect` | `local_dir`: stack, port, start, Dockerfile, build_type, tên env từ `.env.example`; không mạng |
| `cloud_app_create` | `local_dir`, `name?`, `build_type?`, `env?`, `port?`, `domain?`: ZIP → tạo source=upload → multipart → poll → `{url, app_id, build, seconds}` |
| `cloud_app_deploy` | `app_id`, `local_dir?`: có thư mục thì ZIP mới, upload, chờ rồi deploy; bỏ thư mục để dùng bản cũ |
| `cloud_app_domain_add` | `app_id`, `host`: gắn domain và nhận hướng dẫn CNAME |

```text
cloud_app_detect({ local_dir: "/absolute/path/to/project" })
cloud_app_create({ local_dir: "/absolute/path/to/project", name: "shop", sandbox: true })
// Sau khi đã duyệt chi phí
cloud_app_create({ local_dir: "/absolute/path/to/project", name: "shop" })
cloud_app_deploy({ app_id: "<app_id>", local_dir: "/absolute/path/to/project" })
```

ZIP tối đa 80 MiB, loại `.env*`, `*.pem`, `.git`, `node_modules` và symlink; áp dụng `.gitignore`/`.dockerignore`. `dist` được giữ mặc định. Git vẫn dùng `repo_url` như trước. [Hợp đồng upload, giới hạn và cách tiếp tục job](docs/local-deploy.md).

## Yêu cầu

- Node.js 20 trở lên.
- Một MONA Pass có quyền dùng client `monacloud-mcp`.
- MONA Pass, Billing, compute MONA Cloud và MONA Pay đã được cấu hình theo môi trường triển khai.

## Cài và đăng nhập

Đăng nhập lần đầu bằng OAuth Device Authorization Grant:

```bash
npx -y monacloud-mcp login
```

Lệnh in URL tại `pass.monacloud.vn` và mã thiết bị. Sau khi xác nhận, offline refresh token được lưu tại `~/.config/monacloud/token.json`; thư mục có mode `0700`, file có mode `0600`. Server tự refresh access token và không in token ra log.

Kiểm tra hoặc đăng xuất:

```bash
npx -y monacloud-mcp whoami
npx -y monacloud-mcp logout
```

### Claude Code

```bash
claude mcp add monacloud -- npx -y monacloud-mcp
```

### Codex (`~/.codex/config.toml`)

```toml
[mcp_servers.monacloud]
command = "npx"
args = ["-y", "monacloud-mcp"]
```

### Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "monacloud": {
      "command": "npx",
      "args": ["-y", "monacloud-mcp"]
    }
  }
}
```

MCP client không cần giữ username/password sản phẩm. Có thể truyền PAT trực tiếp bằng `MONACLOUD_TOKEN` trong CI hoặc môi trường không dùng token store; không commit giá trị này.

## Tool

Tên tool dùng `snake_case` để giữ tương thích với prompt MONA Pay cũ.

### MONA Cloud

| Tool | Công dụng |
|---|---|
| `cloud_whoami` | Hồ sơ MONA Pass hiện tại |
| `cloud_balance` | Số dư ví VND chung |
| `cloud_ledger` | Ledger nạp/trừ/hoàn tiền có cursor |
| `cloud_topup(amount)` | Tạo yêu cầu nạp, trả `qr_ascii` (in trong terminal), `qr_file`, `qr_url`, ngân hàng/số TK/số tiền/nội dung; tự fallback compute khi ví chung chưa sẵn sàng |
| `cloud_topup_status(topup_id)` | Trạng thái yêu cầu nạp (pending/paid) kèm số dư, để chờ tiền vào rồi làm tiếp |
| `cloud_usage(period)` | Usage theo tháng, có thể lọc sản phẩm |
| `cloud_services` | Gom VPS/database, VA và webhook MONA Pay |
| `cloud_budget_set` / `cloud_budget_get` | Đặt và đọc budget theo product/project/token |
| `cloud_token_limit` | Đặt spend limit cho PAT/token |
| `cloud_open_console` | Trả URL console chung |

### MONA Pay

`monacloud-mcp` import `monapay-mcp` và re-export toàn bộ tool của package, không copy implementation. Dependency range là `^0.5.5`; bộ dependency offline tại lần verify này là 0.5.5 với 47 tool MONA Pay, gồm các nhóm:

- hồ sơ và nối ACB/VA bằng hai lần OTP;
- payment profile, checkout, VietQR, sandbox transaction và đối soát;
- webhook, log, thống kê và retry;
- email notification, verification, suppression và log;
- xoay key, kiểm chữ ký HMAC và sinh code mẫu webhook.

Các tên cũ như `monapay_create_qr`, `monapay_link_bank_start`, `monapay_create_webhook` được giữ nguyên. `monapay_link` là adapter chuyển tiếp: đổi MONA Pass thành `client_id/client_secret` rồi cache kín ở `~/.config/monacloud/links.json`. Adapter này sẽ được bỏ khi MONA Pay nhận JWT MONA Pass trực tiếp.

### Compute MONA Cloud

| Tool | Công dụng |
|---|---|
| `cloud_link` | Xác nhận direct MONA Pass; chỉ đổi sang `vc_live_*` nếu upstream còn ở chế độ cũ |
| `cloud_vps_create` | Hourly theo cấu hình; monthly theo `plan_code`, `period: month/year`, kiểm ví đủ giá kỳ |
| `cloud_db_create` | Tạo MongoDB, PostgreSQL hoặc MySQL |
| `cloud_job_status` | Poll job tới trạng thái cuối, có timeout |
| `cloud_services_list` | Liệt kê VPS/database |
| `cloud_service_start` / `cloud_service_stop` / `cloud_service_rebuild` | Quản lý vòng đời service |
| `cloud_prices` / `cloud_packages` | Đơn giá và gói cấu hình |
| `cloud_agent_deploy` | Stub có cấu trúc cho runtime MONA Agent wave sau |

### MONA Base (beta)

Base thay Supabase, dùng chung MONA Pass và ví MONA Cloud, đồng thời khớp với app deploy. Sandbox chỉ trả URL thử và ước tính, không tạo hạ tầng thật.

| Tool | Công dụng |
|---|---|
| `cloud_base_create` | Tạo Base, tự poll job và trả `base_id`, `studio_url`, `api_url`, `status` |
| `cloud_base_list` / `cloud_base_get` | Liệt kê hoặc đọc trạng thái Base |
| `cloud_base_credentials` | Đọc `anon_key`, `service_key`, `db_url`; bí mật, không log |
| `cloud_base_delete` | Xoá Base đã được duyệt |

Mỗi tool có alias `vibecloud_base_*` cùng schema và handler. Cần DB/Supabase cho app thì gọi `cloud_base_create`; Base dùng cùng account và khớp app deploy.

`cloud_service_stop` không bị chặn bởi số dư để người dùng luôn có thể hạn chế chi phí. Những lệnh tạo/start/rebuild thật đọc `GET /v1/balance` trước khi gọi compute MONA Cloud.

### MONA Domain — tên miền cho app (monadomain.vn)

AI tra tên, báo giá VND đã VAT, hỏi chủ thể, mua .vn/.com bằng ví MONA Cloud rồi trỏ DNS + SSL vào app. Tra giá **không cần đăng nhập**; người dùng chưa có tài khoản vẫn mua được trong phiên bằng đường giữ chỗ → quét QR → bấm claim (đăng nhập MONA Pass 1 bước = tạo ví = mua).

| Tool | Công dụng |
|---|---|
| `cloud_domain_search` | Còn trống + giá theo TLD; **guest gọi được** |
| `cloud_domain_reserve` | Giữ chỗ 30' không trừ tiền; hỏi email + sđt (+ opt-in ưu đãi); trả QR đúng giá + `claim_url` + `claim_token`/`guest_token` |
| `cloud_domain_reserve_status` | reserved / paid / claimed / expired + `next_step` |
| `cloud_domain_claim` | Đăng nhập Pass → nhận reservation, kéo tiền về ví, mua ngay (idempotent) |
| `cloud_domain_reserve_release` | Nhả chỗ khi chưa có tiền vào |
| `cloud_domain_registrant_get` / `cloud_domain_registrant_set` | Chủ thể đăng ký (.vn cá nhân cần CCCD, tổ chức cần MST) |
| `cloud_domain_buy` | Mua thẳng bằng ví khi đã đăng nhập; 402 → `cloud_topup` in QR |
| `cloud_domain_verify_start` / `cloud_domain_verify_status` / `cloud_domain_wait` | Hồ sơ .vn + chờ active |
| `cloud_domain_renew` | Gia hạn: dry_run báo giá → duyệt → trừ ví VND |
| `cloud_domain_dns_*` / `cloud_domain_ns_set` / `cloud_domain_attach` / `cloud_domain_health` | DNS, NS, gắn app, sức khoẻ |

Giữ chỗ chỉ khoá tên trong hệ MONA Cloud (`hold_scope=monacloud`), không giữ ở registry — tên đẹp thì trả sớm. Không gọi registrar tới khi tiền vào và có tài khoản nhận. Prompt `mua-ten-mien-monacloud(keyword?, app_id?)` dẫn trọn luồng.

### MONA Mail

MONA Mail là dịch vụ gửi email giao dịch cho phần mềm và AI agent của người Việt: một API, trả VND qua ví MONA Clo