monacloud-mcp 0.2.1 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # 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ích hợp MONA Pay và đọc catalog MONA Agent ngay trong Claude Code, Codex hoặc Cursor.
+`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í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 chỉ cần đăng ký, nạp tiền và cung cấp OTP/KYC khi bắt buộc. Các bước 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.
+Human chỉ cần đăng ký, thêm DNS khi cần, nạp tiền và cung cấp OTP/KYC khi bắt buộc. Các bước 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.
 
 ## Yêu cầu
 
@@ -101,6 +101,41 @@ Các tên cũ như `monapay_create_qr`, `monapay_link_bank_start`, `monapay_crea
 
 `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 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, không cần thẻ, thuộc nhóm MONA Cloud của The MONA Group.
+
+20 tool `mail_*` dùng MONA Pass sẵn có; tài khoản Mail được tạo tự động ở request đầu. Site: https://monamail.vn, API: https://api.monamail.vn.
+
+| Tên | Việc |
+|---|---|
+| `mail_account` | Đọc tài khoản, email chủ, quota và bước kế tiếp |
+| `mail_plans` | Đọc giá và quota hiện hành của các gói |
+| `mail_plan_set` | Đổi gói, trừ ví VND khi chọn gói trả phí |
+| `mail_send` | Gửi OTP/thông báo hoặc thử bằng `sandbox: true` |
+| `mail_status` | Đọc trạng thái, events và nội dung sandbox |
+| `mail_list` | Lọc lịch sử theo trạng thái, người nhận và thời gian |
+| `mail_domain_add` | Thêm domain, trả records DNS và hướng dẫn |
+| `mail_domain_verify` | Kiểm DKIM và xác minh domain |
+| `mail_domain_cloudflare` | Thêm DNS bằng token Cloudflare của người dùng, dùng một lần, không lưu/log |
+| `mail_domains_list` | Liệt kê domain cùng trạng thái |
+| `mail_api_key_create` | Tạo key live/test, secret chỉ trả một lần |
+| `mail_api_keys_list` | Xem prefix và trạng thái key |
+| `mail_api_key_revoke` | Thu hồi key của app |
+| `mail_webhook_create` | Đăng ký HTTPS endpoint và các sự kiện email |
+| `mail_webhooks_list` | Liệt kê webhook |
+| `mail_webhook_test` | Gửi payload `email.delivered` mẫu |
+| `mail_suppressions_list` | Xem địa chỉ ngừng gửi và lý do |
+| `mail_suppression_remove` | Gỡ suppression của tài khoản; không gỡ lớp toàn hệ |
+| `mail_template_create` | Tạo mẫu với biến `{{ten_bien}}` |
+| `mail_stats` | Đọc thống kê giao thư và bounce theo thời gian |
+
+`mail_send` nhận 1 đến 50 người nhận, tối đa 10 tags, `subject` tối đa 998 ký tự và ít nhất một trong `html`/`text`. Khi dùng `template_id`, template thay cho `subject`/`html`/`text`. Sender `onboarding@monamail.vn` chỉ gửi tới email chủ từ `mail_account`; domain riêng cần verified trước khi gửi.
+
+Key chỉ trả một lần; ghi vào `.env` của app dưới tên `MONAMAIL_API_KEY`, không cần in ra chat. MCP tiếp tục dùng MONA Pass; app dùng SDK `monamail` với key `mm_live_` hoặc `mm_test_`. Sandbox bằng `mail_send({ ..., sandbox: true })` gửi header `X-Mona-Sandbox: 1` và trả `sandbox: true`; sandbox không gửi ra Internet, không tính quota hoặc trừ ví. Dùng `mail_status` để xem `sandbox_preview`.
+
+Mọi POST gửi `Idempotency-Key` từ `idempotency_key` hoặc tự tạo `mcp-mail-<uuid>`. Truyền key ổn định khi cần retry: trong 24 giờ, cùng key và body trả response cũ; khác body trả `idempotency_conflict`. MCP đưa key vào header, không đưa `sandbox` vào body API. Giá gói lấy bằng `mail_plans`; lỗi thiếu ví từ `mail_plan_set` hướng dẫn gọi `cloud_topup`.
+
 ## Thử 0đ bằng sandbox
 
 Truyền `sandbox: true` cho `cloud_vps_create`, `cloud_db_create`, `cloud_service_start`, `cloud_service_rebuild` hoặc `cloud_agent_deploy` để thử luồng mà không cần số dư ví. Có thể bật mặc định cho cả MCP process bằng `MONACLOUD_SANDBOX=1`; các alias `vibecloud_*` có cùng hành vi.
@@ -124,8 +159,9 @@ cloud_services_list({ sandbox: true })
 ## Resource và prompt
 
 - `monacloud://llms`: mô tả máy đọc của toàn stack MONA Cloud.
-- `monacloud://status`: health tổng hợp MONA Pass, Billing, compute MONA Cloud và MONA Pay.
+- `monacloud://status`: health tổng hợp MONA Pass, Billing, compute MONA Cloud, MONA Pay và MONA Mail (`/v1/healthz`).
 - Prompt `dung-app-ban-hang-monacloud`: chuỗi VPS → database → VA/QR → webhook → deploy, chỉ dừng để hỏi nạp tiền hoặc OTP bắt buộc.
+- Prompt `gui-mail-otp-monamail(app_name?, framework?, domain?)`: account → thử onboarding → domain/DNS → verify → API key → `.env` → SDK OTP → webhook bounced; chỉ dừng ở bước thêm DNS hoặc nạp tiền.
 
 ## Spend guard và lỗi cho AI
 
@@ -160,6 +196,17 @@ Agent thực hiện:
 
 Chi tiết dành riêng cho agent: [`docs/ai-agent.md`](docs/ai-agent.md).
 
+## Ví dụ một lượt: gửi mail OTP
+
+Người dùng nói: “Tích hợp gửi mail OTP cho app shop bằng MONA Mail, domain shop.vn.”
+
+1. `mail_account`: lấy email chủ, quota và domain đã xác minh.
+2. Nếu chưa có domain, `mail_send` từ `onboarding@monamail.vn` tới email chủ, dùng idempotency key riêng; `mail_status` kiểm kết quả.
+3. `mail_domain_add({ domain: "shop.vn" })`: đưa records để user thêm DNS, hoặc gọi `mail_domain_cloudflare` bằng token của họ; sau đó `mail_domain_verify`.
+4. `mail_api_key_create({ name: "shop-otp", mode: "live" })`: ghi key trực tiếp vào `.env` dưới tên `MONAMAIL_API_KEY`.
+5. Viết server dùng `new MonaMail(process.env.MONAMAIL_API_KEY)` và `monamail.emails.send(...)` với `tags: ["otp"]`; kiểm thư bằng `mail_status`.
+6. Viết endpoint HMAC, `mail_webhook_create` với `events: ["email.bounced"]`, lưu secret rồi `mail_webhook_test`; khi thiếu ví gọi `cloud_topup` và chờ user nạp.
+
 ## Biến môi trường
 
 | Biến | Mặc định | Ý nghĩa |
@@ -167,6 +214,7 @@ Chi tiết dành riêng cho agent: [`docs/ai-agent.md`](docs/ai-agent.md).
 | `MONACLOUD_ISSUER` | `https://pass.monacloud.vn/realms/mona` | OIDC issuer |
 | `MONACLOUD_BILLING_URL` | `https://billing.monacloud.vn` | Billing/ví API |
 | `MONAPAY_API` | `https://api.monapay.vn` | MONA Pay API |
+| `MONAMAIL_API` | `https://api.monamail.vn` | MONA Mail API, dùng Bearer MONA Pass của MCP |
 | `MONACLOUD_API` | `https://api.monacloud.vn` | Compute API của MONA Cloud |
 | `MONACLOUD_CONSOLE_URL` | `https://monacloud.vn/console` | URL trả cho bước human |
 | `MONACLOUD_TOKEN` | — | PAT/access token ưu tiên token store |

package/STATUS.md

@@ -1,8 +1,36 @@
-# STATUS — monacloud-mcp 0.2.1
+# STATUS — monacloud-mcp 0.3.0
 
-Updated: 2026-09-04 (Asia/Ho_Chi_Minh)
+Updated: 2026-09-05 (Asia/Ho_Chi_Minh)
 
-## Hoàn thành
+## 0.3.0 — MONA Mail
+
+- [x] Thêm đủ 20 tool `mail_*` theo CONTRACT-MONA-MAIL-API §5 trong `src/mail.ts`, đăng ký sau nhóm compute `cloud_*`.
+- [x] `MONAMAIL_API` mặc định `https://api.monamail.vn`; `CloudClients.mail()` dùng `requestJson` và `auth.accessToken()` MONA Pass, không có token cache Mail riêng.
+- [x] Mọi POST có `Idempotency-Key` từ `idempotency_key` hoặc `mcp-mail-<uuid>`; `mail_send` chuyển `sandbox: true` thành `X-Mona-Sandbox: 1` và đánh dấu response.
+- [x] Schema chặn email sai, trên 50 người nhận, trên 10 tags, subject trên 998 ký tự, gói/mode/event ngoài enum, webhook không dùng HTTPS và tham số lạ. Domain chuyển lowercase/IDN sang punycode.
+- [x] Tool mô tả VI/EN có tình huống sử dụng; domain trả records và hướng dẫn DNS/Cloudflare. API key chỉ trả một lần để app lưu `.env` với tên `MONAMAIL_API_KEY`; không thêm log token/key, không lưu token Cloudflare.
+- [x] Lỗi Mail qua `CloudError`: giữ thông tin API, gồm `403 domain_not_verified`; `402 mail_plan_set` trả `insufficient_funds` và bước tiếp theo nhắc `cloud_topup`. `src/http.ts`, `src/errors.ts` và hành vi lỗi tool cũ giữ nguyên.
+- [x] Instructions/entity, `monacloud://llms` và health MONA Mail `/v1/healthz` đã cập nhật. Có prompt `gui-mail-otp-monamail` với account → onboarding → DNS → verify → key → `.env` → SDK OTP → webhook bounced.
+- [x] README có bảng 20 tool, ví dụ OTP 6 bước và env Mail; `docs/ai-agent.md` có ranh giới human DNS/nạp tiền, sandbox, webhook HMAC và idempotency 24 giờ.
+- [x] Version package, MCP server và CLI đồng bộ `0.3.0`. `src/index.ts` chỉ đổi version; không sửa `src/monapay.ts`.
+
+Gate ngày 05/09/2026:
+
+```text
+$ node_modules/.bin/tsc -p tsconfig.json
+exit 0, không có diagnostic
+
+$ node --test test/*.test.mjs
+tests 23, pass 23, fail 0
+```
+
+Stdio process thật xác nhận **103 tool = 83 cũ + 20 Mail**, 2 resource, 2 prompt, server version `0.3.0`. Test bao phủ auth/header/body, sandbox, records DNS, key một lần, HTTP 402/403/409/429, GET/query/DELETE 204, schema và prompt. Test cũ về compute, MONA Pay, alias và catalog đều xanh.
+
+Lựa chọn theo contract: `subject` được bỏ khi có `template_id` vì §3 cho phép template thay nội dung; gửi trực tiếp bắt buộc subject và ít nhất html/text. Các POST ngoài `mail_send` cũng nhận `idempotency_key` tuỳ chọn để retry an toàn. Giá/quota và quyền domain vẫn do API quyết định, không hard-code giá gói.
+
+Toàn bộ thay đổi và thư mục tạm của gate nằm trong workspace MCP; thư mục tạm đã dọn sau gate. Không chạy `npm install`, không gọi Internet hoặc production; dùng dependency có sẵn và fetch mock. Chưa kiểm gửi mail thật/DNS/SMTP production vì brief yêu cầu offline.
+
+## Hoàn thành ở 0.2.1
 
 - [x] Package Node 20 + TypeScript, ESM, stdio MCP; bin `monacloud-mcp`, version `0.2.1`.
 - [x] OAuth device flow client `monacloud-mcp`, scope `offline_access`, token store private `0600`, refresh tự động; CLI `login`, `logout`, `whoami`.
@@ -55,3 +83,11 @@ CODEX DONE
 - Lưu ý test tự động: trang consent Keycloak có form action TƯƠNG ĐỐI (`/realms/mona/login-actions/consent?...`) → script phải ghép host; urllib Python rớt cookie ở hop 302 → dùng curl cookie jar.
 - Chưa: publish npm (`npm publish` — Claude làm khi deploy), `monapay_link`/`vibecloud_link` chờ endpoint link phía sản phẩm (gói E monapay, brief VIBECLOUD-MONAID đã có `/api/auth/monaid/link`).
 - 04/09: publish npm `monacloud-mcp` 0.1.0 rồi 0.1.1 (sửa dep monapay-mcp ^0.3.0 → ^0.5.5 vì 0.5.x không khớp ^0.3).
+- 04/09: sandbox bỏ spend guard (Codex) → publish 0.2.1; verify: cloud_vps_create sandbox:true với ví 0đ → job queued; không sandbox → insufficient_funds đúng.
+
+CODEX B DONE
+
+## QC Claude 05/09 (JOB B mail_*) — PASS local
+- tsc sạch · `node --test` 23/23 · 20 tool `mail_*` + prompt `gui-mail-otp-monamail` + health `monamail` trong `monacloud://status`.
+- Claude vá: `idempotencyHeaders` luôn gửi `Idempotency-Key` (mặc định `mcp-mail-<uuid>`) thay vì chỉ khi có tham số — AI retry an toàn theo contract §5.
+- Chưa publish npm 0.3.0: chờ `api.monamail.vn` live (deploy theo `handoff/DEPLOY-MONA-MAIL-RUNBOOK.md`) rồi zero-dashboard test prod bằng `handoff/tests/test_mail_zero_dashboard.py`.

package/dist/clients.d.ts

@@ -7,6 +7,12 @@ export declare class CloudClients {
     readonly fetchImpl: typeof fetch;
     constructor(config: Config, auth: AuthManager, fetchImpl?: typeof fetch);
     private billing;
+    mail<T = unknown>(path: string, options?: {
+        method?: string;
+        body?: unknown;
+        query?: Record<string, string | number | undefined>;
+        headers?: Record<string, string>;
+    }): Promise<T>;
     balance(): Promise<unknown>;
     ledger(cursor?: string, limit?: number): Promise<unknown>;
     usage(period: string, product?: string): Promise<unknown>;
@@ -19,7 +25,7 @@ export declare class CloudClients {
     }): Promise<unknown>;
     budgetGet(): Promise<unknown>;
     tokenLimit(spendLimitVnd: number, period: string, tokenId?: string): Promise<unknown>;
-    spendGuard(): Promise<JsonObject>;
+    spendGuard(requiredVnd?: number): Promise<JsonObject>;
     sandboxEnabled(requested?: boolean): boolean;
     private vibecloudToken;
     vibecloud<T = unknown>(path: string, options?: {
@@ -31,10 +37,17 @@ export declare class CloudClients {
     guardedVibecloud(path: string, options?: {
         method?: string;
         body?: unknown;
-    }, requestedSandbox?: boolean): Promise<unknown>;
+    }, requestedSandbox?: boolean, requiredVnd?: number): Promise<unknown>;
     vibecloudLink(): Promise<JsonObject>;
     monapayLink(): Promise<JsonObject>;
     prices(): Promise<unknown>;
     packages(): Promise<unknown>;
+    plans(): Promise<unknown>;
+    invoicePdf(invoiceId: string): Promise<{
+        invoice_id: string;
+        path: string;
+        mime_type: string;
+        size_bytes: number;
+    }>;
 }
 export {};

package/dist/clients.js

@@ -1,7 +1,10 @@
 import { randomUUID } from 'node:crypto';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { readLinks, writeLinks } from './auth.js';
 import { CloudError } from './errors.js';
-import { requestJson, unwrapData } from './http.js';
+import { apiError, requestJson, unwrapData } from './http.js';
 const asObject = (value) => (value && typeof value === 'object' ? value : {});
 function pickString(objects, keys) {
     for (const object of objects) {
@@ -29,6 +32,40 @@ export class CloudClients {
             fetchImpl: this.fetchImpl,
         });
     }
+    async mail(path, options = {}) {
+        try {
+            return await requestJson(`${this.config.monamailApi}${path}`, {
+                ...options,
+                headers: {
+                    ...(options.method === 'POST' ? { 'Idempotency-Key': `mcp-mail-${randomUUID()}` } : {}),
+                    ...options.headers,
+                },
+                token: await this.auth.accessToken(),
+                fetchImpl: this.fetchImpl,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof CloudError) || !error.status)
+                throw error;
+            // Mail keeps the API's error contract without changing legacy HTTP errors.
+            const root = asObject(error.details);
+            const objects = [root, asObject(root.detail)];
+            const code = path === '/v1/account/plan' && error.status === 402
+                ? 'insufficient_funds'
+                : pickString(objects, ['code']) || error.code;
+            const fallback = code === 'insufficient_funds'
+                ? `Gọi cloud_topup để nạp ví, chờ cloud_balance cập nhật rồi thử lại. Console: ${this.config.consoleUrl}.`
+                : code === 'quota_exceeded'
+                    ? 'Gọi mail_plans rồi mail_plan_set để đổi gói trước khi gửi tiếp.'
+                    : code === 'budget_exceeded'
+                        ? 'Gọi cloud_budget_get và điều chỉnh ngân sách trước khi thử lại.'
+                        : error.nextStep;
+            const nextStep = pickString(objects, ['next_step']) || fallback;
+            throw new CloudError(code, pickString(objects, ['message']) || error.message, code === 'insufficient_funds' && !nextStep.includes('cloud_topup')
+                ? `${nextStep} Gọi cloud_topup để nạp ví.`
+                : nextStep, { status: error.status, details: error.details, requestId: error.requestId });
+        }
+    }
     balance() {
         return this.billing('/v1/balance');
     }
@@ -61,11 +98,14 @@ export class CloudClients {
             fetchImpl: this.fetchImpl,
         });
     }
-    async spendGuard() {
-        const current = asObject(await this.balance());
+    async spendGuard(requiredVnd) {
+        const current = asObject(unwrapData(await this.balance()));
         const balance = current.balance_vnd;
-        if (typeof balance === 'number' && balance <= 0) {
-            throw new CloudError('insufficient_funds', 'Ví thiếu tiền: số dư hiện tại là 0 đ.', `Nạp ví tại ${this.config.consoleUrl} rồi gọi lại tool.`);
+        if (requiredVnd !== undefined && (typeof balance !== 'number' || !Number.isFinite(balance))) {
+            throw new CloudError('invalid_balance', 'Không đọc được số dư để duyệt giá gói.', 'Gọi cloud_balance rồi thử lại.');
+        }
+        if (typeof balance === 'number' && (requiredVnd === undefined ? balance <= 0 : balance < requiredVnd)) {
+            throw new CloudError('insufficient_funds', `Ví thiếu tiền: có ${balance} đ${requiredVnd === undefined ? '' : `, cần ${requiredVnd} đ`}.`, `Gọi cloud_topup để nạp ví tại ${this.config.consoleUrl} rồi gọi lại tool.`);
         }
         return current;
     }
@@ -89,10 +129,10 @@ export class CloudClients {
             fetchImpl: this.fetchImpl,
         });
     }
-    async guardedVibecloud(path, options = {}, requestedSandbox = false) {
+    async guardedVibecloud(path, options = {}, requestedSandbox = false, requiredVnd) {
         const sandbox = this.sandboxEnabled(requestedSandbox);
         if (!sandbox)
-            await this.spendGuard();
+            await this.spendGuard(requiredVnd);
         const result = await this.vibecloud(path, {
             ...options,
             ...(sandbox ? { headers: { 'X-Vibecloud-Sandbox': '1' } } : {}),
@@ -167,4 +207,46 @@ export class CloudClients {
     packages() {
         return requestJson(`${this.config.vibecloudApi}/api/packages`, { fetchImpl: this.fetchImpl });
     }
+    plans() {
+        return requestJson(`${this.config.vibecloudApi}/api/plans`, { fetchImpl: this.fetchImpl });
+    }
+    async invoicePdf(invoiceId) {
+        const token = await this.vibecloudToken();
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.config.vibecloudApi}/api/invoices/${encodeURIComponent(invoiceId)}.pdf`, {
+                headers: { Authorization: `Bearer ${token}`, Accept: 'application/pdf' },
+                signal: AbortSignal.timeout(30_000),
+                redirect: 'error',
+            });
+        }
+        catch {
+            throw new CloudError('network_error', 'Không tải được PDF hoá đơn.', 'Gọi lại cloud_invoice_pdf với cùng invoice_id.');
+        }
+        if (!response.ok) {
+            const body = await response.text();
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                parsed = { message: body.slice(0, 1000) };
+            }
+            throw apiError(response, parsed);
+        }
+        const bytes = Buffer.from(await response.arrayBuffer());
+        if (bytes.subarray(0, 5).toString('ascii') !== '%PDF-') {
+            throw new CloudError('invalid_pdf', 'API không trả nội dung PDF hợp lệ.', 'Kiểm tra invoice_id rồi thử lại.');
+        }
+        const directory = await mkdtemp(join(tmpdir(), 'monacloud-invoice-'));
+        const path = join(directory, 'invoice.pdf');
+        try {
+            await writeFile(path, bytes, { mode: 0o600, flag: 'wx' });
+        }
+        catch (error) {
+            await rm(directory, { recursive: true, force: true });
+            throw error;
+        }
+        return { invoice_id: invoiceId, path, mime_type: 'application/pdf', size_bytes: bytes.length };
+    }
 }

package/dist/compute.d.ts

@@ -0,0 +1,18 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CloudClients } from './clients.js';
+type Row = Record<string, unknown>;
+export declare const APP_FLOW = "Khi user n\u00F3i \"deploy repo\", d\u00F9ng cloud_app_create (app t\u1EEB git \u0111ang m\u1EDF). \u0110\u1ECDc cloud_app_host_list, cloud_prices/cloud_packages v\u00E0 cloud_balance; n\u1EBFu ch\u01B0a c\u00F3 app host th\u00EC cloud_app_create sandbox=true tr\u01B0\u1EDBc \u0111\u1EC3 l\u1EA5y \u01B0\u1EDBc t\u00EDnh. \u0110\u1ECDc \u2192 \u01B0\u1EDBc t\u00EDnh VND \u2192 h\u1ECFi duy\u1EC7t n\u1EBFu ch\u01B0a \u0111\u01B0\u1EE3c duy\u1EC7t \u2192 l\u00E0m th\u1EADt \u2192 poll t\u1EDBi done/succeeded \u2192 ki\u1EC3m URL. Kh\u00F4ng g\u1ECDi agent_deploy cho repo git. / Deploy a repository with cloud_app_create; inspect, estimate, obtain approval, then deploy.";
+export declare function rows(value: unknown, key: string): Row[];
+export declare function planEstimate(clients: CloudClients, code: string, cycle?: string): Promise<{
+    plan: Row;
+    estimate: {
+        billing_mode: string;
+        plan_code: string;
+        period: string;
+        amount_vnd: number;
+        currency: string;
+    };
+}>;
+export declare function createVps(clients: CloudClients, body: Row): Promise<unknown>;
+export declare function registerComputeTools(server: McpServer, clients: CloudClients): void;
+export {};

package/dist/compute.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { CloudError, runTool } from './errors.js';
+import { unwrapData } from './http.js';
+import { finishAppJob } from './jobs.js';
+export const APP_FLOW = 'Khi user nói "deploy repo", dùng cloud_app_create (app từ git đang mở). Đọc cloud_app_host_list, cloud_prices/cloud_packages và cloud_balance; nếu chưa có app host thì cloud_app_create sandbox=true trước để lấy ước tính. Đọc → ước tính VND → hỏi duyệt nếu chưa được duyệt → làm thật → poll tới done/succeeded → kiểm URL. Không gọi agent_deploy cho repo git. / Deploy a repository with cloud_app_create; inspect, estimate, obtain approval, then deploy.';
+const sandbox = z.boolean().optional().describe('Thử 0đ, không tạo hạ tầng thật / Sandbox, no charge');
+const id = z.string().trim().min(1).max(255);
+const planCode = z.string().trim().min(2).max(64);
+const period = z.enum(['month', 'year']);
+const object = (value) => value && typeof value === 'object' ? value : {};
+export function rows(value, key) {
+    const data = unwrapData(value);
+    const list = Array.isArray(data) ? data : object(data)[key];
+    return Array.isArray(list) ? list.filter((row) => row && typeof row === 'object') : [];
+}
+export async function planEstimate(clients, code, cycle = 'month') {
+    const plan = rows(await clients.plans(), 'plans').find((row) => row.code === code && row.active !== false);
+    if (!plan)
+        throw new CloudError('plan_not_found', `Không có gói đang mở: ${code}.`, 'Gọi cloud_plan_list để chọn plan_code.');
+    const amount = plan[cycle === 'year' ? 'price_year_vnd' : 'price_month_vnd'];
+    if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0) {
+        throw new CloudError('invalid_plan_price', 'Không đọc được giá gói.', 'Gọi cloud_plan_list rồi thử lại; không tự đoán giá.');
+    }
+    return { plan, estimate: { billing_mode: 'monthly', plan_code: code, period: cycle, amount_vnd: amount, currency: 'VND' } };
+}
+export async function createVps(clients, body) {
+    const { sandbox: requested, ...payload } = body;
+    if (payload.billing_mode !== 'monthly')
+        return clients.guardedVibecloud('/api/lxc', { method: 'POST', body: payload }, requested === true);
+    const { plan, estimate } = await planEstimate(clients, String(payload.plan_code), String(payload.period || 'month'));
+    // Wave A rejects mixed sizing. Strip all hourly sizing before the real request.
+    delete payload.cpu;
+    delete payload.ram_gb;
+    delete payload.disk_gb;
+    delete payload.package_slug;
+    const isSandbox = clients.sandboxEnabled(requested === true);
+    const outgoing = isSandbox
+        ? { app_name: payload.app_name, cpu: plan.cpu, ram_gb: plan.ram_gb, disk_gb: plan.disk_gb }
+        : payload;
+    const result = await clients.guardedVibecloud('/api/lxc', { method: 'POST', body: outgoing }, isSandbox, estimate.amount_vnd);
+    return { ...object(result), estimate, ...(isSandbox ? {
+            preview_billing_mode: 'hourly', requested_billing_mode: 'monthly',
+            next_step: 'Sandbox chỉ thử cấu hình gói qua hourly (0đ); chưa tạo subscription. Duyệt giá estimate rồi gọi cloud_vps_create billing_mode=monthly, sandbox=false.',
+        } : {}) };
+}
+export function registerComputeTools(server, clients) {
+    // Every new compute tool keeps a mechanical legacy alias, using the same schema and handler.
+    const register = (name, description, schema, handler) => {
+        for (const toolName of [name, name.replace(/^cloud_/, 'vibecloud_')]) {
+            server.registerTool(toolName, {
+                description: toolName === name ? description : `Alias tương thích của ${name}. / Compatibility alias. ${description}`,
+                inputSchema: schema,
+            }, (args) => runTool(() => handler(args)));
+        }
+    };
+    register('cloud_plan_list', 'Bảng gói cùng giá tháng/năm; gợi ý gói rẻ nhất đủ CPU/RAM/đĩa yêu cầu, admin_only không tự chọn. Đọc trước khi duyệt chi phí. / List plans, prices and sizing recommendation.', z.object({ cpu: z.number().int().positive().optional(), ram_gb: z.number().positive().optional(), disk_gb: z.number().positive().optional() }).strict(), async (needs) => {
+        const plans = rows(await clients.plans(), 'plans');
+        const eligible = plans.filter((plan) => plan.active !== false && !plan.admin_only
+            && ['cpu', 'ram_gb', 'disk_gb'].every((key) => typeof plan[key] === 'number' && Number(plan[key]) >= (needs[key] || 0))
+            && typeof plan.price_month_vnd === 'number').sort((a, b) => Number(a.price_month_vnd) - Number(b.price_month_vnd));
+        return { plans, recommendation: eligible[0] ? { plan_code: eligible[0].code, reason: 'Gói giá tháng thấp nhất đáp ứng cấu hình yêu cầu; kiểm tra tải thực tế, backup và included_db.' } : null,
+            next_step: 'Chọn plan_code và month/year, báo giá tương ứng rồi hỏi duyệt trước cloud_vps_create.' };
+    });
+    register('cloud_subscription_list', 'Đọc các gói đang dùng, kỳ gia hạn và auto-renew. / List subscriptions.', z.object({}).strict(), () => clients.vibecloud('/api/subscriptions'));
+    register('cloud_subscription_update', 'Đổi gói/chu kỳ/gia hạn sau khi đọc subscription và giá, ước tính rồi được duyệt. Upgrade tính prorate, downgrade kỳ sau. Huỷ: auto_renew=false, cancel_action=hourly|stop. / Update or cancel renewal.', z.object({ service_id: id, plan_code: planCode.optional(), period: period.optional(), auto_renew: z.boolean().optional(), cancel_action: z.enum(['hourly', 'stop']).optional() }).strict()
+        .refine((args) => [args.plan_code, args.period, args.auto_renew, args.cancel_action].some((value) => value !== undefined), 'Cần ít nhất một thay đổi subscription.'), async ({ service_id, ...body }) => {
+        // Cancellation must remain possible with an empty wallet. Proration is authoritative at the API.
+        return clients.vibecloud(`/api/services/${encodeURIComponent(service_id)}/subscription`, { method: 'POST', body });
+    });
+    register('cloud_invoice_list', 'Đọc hoá đơn hàng tháng của tài khoản. / List monthly invoices.', z.object({}).strict(), () => clients.vibecloud('/api/invoices'));
+    register('cloud_invoice_pdf', 'Tải PDF hoá đơn vào file tạm riêng tư, trả path; sao chép ra nơi cần giữ trước khi hệ điều hành dọn. / Download invoice PDF to a private temporary file.', z.object({ invoice_id: id }).strict(), ({ invoice_id }) => clients.invoicePdf(invoice_id));
+    register('cloud_credit_redeem', 'Dùng mã credit người dùng cung cấp sau khi họ đồng ý; không thử đoán mã. / Redeem an approved promotional credit code.', z.object({ code: z.string().trim().min(2).max(64) }).strict(), ({ code }) => clients.vibecloud('/api/credit-codes/redeem', { method: 'POST', body: { code: code.toUpperCase() } }));
+    const appNotice = 'App từ git đang mở; endpoint có thể chưa live. / Git apps rollout in progress. ';
+    const poll = { wait: z.boolean().default(true), interval_sec: z.number().int().min(1).max(30).default(3), timeout_sec: z.number().int().min(1).max(600).default(600) };
+    const env = z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.string());
+    const domain = z.string().trim().min(3).max(253).regex(/^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,63}$/, 'Chỉ hostname, không URL/path.');
+    const appId = z.object({ app_id: id, sandbox }).strict();
+    const repo = z.string().trim().min(1).max(2048).refine((value) => {
+        if (/^git@[a-zA-Z0-9.-]+:[^\s]+$/.test(value))
+            return true;
+        try {
+            const u = new URL(value);
+            return ['https:', 'ssh:'].includes(u.protocol) && !u.password && (u.protocol === 'ssh:' || !u.username) && !u.search && !u.hash && u.pathname.length > 1;
+        }
+        catch {
+            return false;
+        }
+    }, 'Dùng HTTPS hoặc SSH git URL không chứa token/mật khẩu.');
+    const compute = async (path, options, requested) => {
+        const isSandbox = clients.sandboxEnabled(requested);
+        const result = await clients.vibecloud(path, { ...options, ...(isSandbox ? { headers: { 'X-Vibecloud-Sandbox': '1' } } : {}) });
+        return isSandbox ? { ...(Array.isArray(result) ? { items: result } : object(result)), sandbox: true } : result;
+    };
+    register('cloud_app_create', appNotice + APP_FLOW, z.object({ repo_url: repo, branch: z.string().trim().min(1).max(255).default('main'), build_type: z.enum(['dockerfile', 'nixpacks', 'static']).default('dockerfile'), dockerfile: z.string().min(1).max(1024).default('Dockerfile'), env: env.default({}), domain: domain.optional(), app_host_id: id.optional(), port: z.number().int().min(1).max(65535).default(3000), sandbox, ...poll }).strict(), async ({ sandbox: requested, wait, interval_sec, timeout_sec, ...body }) => finishAppJob(clients, await clients.guardedVibecloud('/api/apps', { method: 'POST', body }, requested), clients.sandboxEnabled(requested), wait, interval_sec, timeout_sec));
+    register('cloud_app_list', appNotice + 'Liệt kê app trước khi tạo để tránh trùng. / List apps.', z.object({ sandbox }).strict(), ({ sandbox }) => compute('/api/apps', {}, sandbox));
+    register('cloud_app_host_list', appNotice + 'Đọc app host; chưa có host thì sandbox cloud_app_create trước để ước tính. / List app hosts.', z.object({ sandbox }).strict(), ({ sandbox }) => compute('/api/app-hosts', {}, sandbox));
+    register('cloud_app_get', appNotice + 'Đọc status, URL, lần deploy và app host. / Inspect app.', appId, ({ app_id, sandbox }) => compute(`/api/apps/${encodeURIComponent(app_id)}`, {}, sandbox));
+    register('cloud_app_deploy', appNotice + 'Deploy lại sau khi đọc app/log và được duyệt; poll job tới kết quả. / Redeploy and poll.', appId.extend(poll), async ({ app_id, sandbox, wait, interval_sec, timeout_sec }) => finishAppJob(clients, await clients.guardedVibecloud(`/api/apps/${encodeURIComponent(app_id)}/deploy`, { method: 'POST' }, sandbox), clients.sandboxEnabled(sandbox), wait, interval_sec, timeout_sec));
+    register('cloud_app_env_set', appNotice + 'Đặt env sau khi được duyệt, gửi đầy đủ map cần giữ; không log secret. / Set app environment.', appId.extend({ env }), ({ app_id, env, sandbox }) => compute(`/api/apps/${encodeURIComponent(app_id)}/env`, { method: 'PUT', body: { env } }, sandbox));
+    register('cloud_app_domain_add', appNotice + 'Thêm domain đã được duyệt, trả hướng dẫn CNAME từ API; chờ DNS trước kiểm HTTPS. / Attach custom domain.', appId.extend({ host: domain }), ({ app_id, host, sandbox }) => compute(`/api/apps/${encodeURIComponent(app_id)}/domains`, { method: 'POST', body: { host } }, sandbox));
+    register('cloud_app_logs', appNotice + 'Đọc tối đa 500 dòng log; có thể chứa secret, không đưa nguyên log ra công khai. / Read deployment logs.', appId.extend({ deployment: id.optional() }), ({ app_id, deployment, sandbox }) => compute(`/api/apps/${encodeURIComponent(app_id)}/logs`, { query: { deployment } }, sandbox));
+    register('cloud_app_delete', appNotice + 'Sau khi user duyệt xoá: xoá app/domain/A record; app host vẫn có thể tính phí. / Delete an approved app.', appId, ({ app_id, sandbox }) => compute(`/api/apps/${encodeURIComponent(app_id)}`, { method: 'DELETE' }, sandbox));
+}

package/dist/config.d.ts

@@ -2,6 +2,7 @@ export type Config = {
     issuer: string;
     billingUrl: string;
     monapayApi: string;
+    monamailApi: string;
     vibecloudApi: string;
     consoleUrl: string;
     clientId: string;

package/dist/config.js

@@ -8,6 +8,7 @@ export function readConfig(env = process.env) {
         issuer: cleanBaseUrl(env.MONACLOUD_ISSUER || 'https://pass.monacloud.vn/realms/mona'),
         billingUrl: cleanBaseUrl(env.MONACLOUD_BILLING_URL || 'https://billing.monacloud.vn'),
         monapayApi: cleanBaseUrl(env.MONAPAY_API || env.MONAPAY_BASE_URL || 'https://api.monapay.vn'),
+        monamailApi: cleanBaseUrl(env.MONAMAIL_API || 'https://api.monamail.vn'),
         vibecloudApi: cleanBaseUrl(env.MONACLOUD_API || env.VIBECLOUD_API || env.VIBECLOUD_API_URL || 'https://api.monacloud.vn'),
         consoleUrl: cleanBaseUrl(env.MONACLOUD_CONSOLE_URL || 'https://monacloud.vn/console'),
         clientId: env.MONACLOUD_CLIENT_ID || 'monacloud-mcp',

package/dist/http.d.ts

@@ -1,3 +1,4 @@
+import { CloudError } from './errors.js';
 export type HttpOptions = {
     method?: string;
     token?: string;
@@ -7,5 +8,6 @@ export type HttpOptions = {
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
 };
+export declare function apiError(response: Response, body: unknown): CloudError;
 export declare function requestJson<T = unknown>(url: string, options?: HttpOptions): Promise<T>;
 export declare function unwrapData<T = unknown>(value: unknown): T;

package/dist/http.js

@@ -8,7 +8,7 @@ const nestedString = (body, key) => {
     const nested = detail[key];
     return typeof nested === 'string' && nested ? nested : undefined;
 };
-function apiError(response, body) {
+export function apiError(response, body) {
     const parsed = asRecord(body);
     const requestId = response.headers.get('x-request-id')
         || nestedString(parsed, 'request_id');

package/dist/index.js

@@ -22,7 +22,7 @@ async function main() {
         return;
     }
     if (command === '--version' || command === '-v') {
-        console.log('0.2.1');
+        console.log('0.3.0');
         return;
     }
     if (command === '--help' || command === '-h' || command === 'help') {

package/dist/jobs.d.ts

@@ -0,0 +1,9 @@
+import type { CloudClients } from './clients.js';
+export declare const TERMINAL_JOBS: Set<string>;
+export declare function pollJob(clients: CloudClients, jobId: string, wait: boolean, intervalSeconds: number, timeoutSeconds: number, sandbox: boolean): Promise<Record<string, unknown>>;
+export declare function finishAppJob(clients: CloudClients, created: unknown, sandbox: boolean, wait: boolean, interval: number, timeout: number): Promise<{
+    job_id?: string | undefined;
+    url?: string | undefined;
+    application_id?: string | undefined;
+    sandbox?: boolean | undefined;
+}>;

package/dist/jobs.js

@@ -0,0 +1,38 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { CloudError } from './errors.js';
+import { unwrapData } from './http.js';
+export const TERMINAL_JOBS = new Set(['done', 'succeeded', 'failed', 'cancelled', 'error']);
+const object = (value) => (value && typeof value === 'object' ? value : {});
+export async function pollJob(clients, jobId, wait, intervalSeconds, timeoutSeconds, sandbox) {
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    const read = async () => object(unwrapData(await clients.vibecloud(`/api/jobs/${encodeURIComponent(jobId)}`)));
+    let result = await read();
+    while (wait && !TERMINAL_JOBS.has(String(result.status)) && Date.now() < deadline) {
+        await delay(Math.min(intervalSeconds * 1000, Math.max(0, deadline - Date.now())));
+        if (Date.now() >= deadline)
+            break;
+        result = await read();
+    }
+    return {
+        ...result,
+        ...(sandbox ? { sandbox: true } : {}),
+        ...(wait && !TERMINAL_JOBS.has(String(result.status)) ? {
+            polling: 'timeout', job_id: jobId,
+            next_step: `Gọi lại cloud_job_status với job_id=${jobId}; không tạo lại app.`,
+        } : {}),
+    };
+}
+export async function finishAppJob(clients, created, sandbox, wait, interval, timeout) {
+    const start = object(unwrapData(created));
+    const jobId = typeof start.job_id === 'string' ? start.job_id
+        : !start.url && typeof start.id === 'string' ? start.id : undefined;
+    const job = jobId && wait ? await pollJob(clients, jobId, true, interval, timeout, sandbox) : start;
+    const result = object(job.result);
+    if (['failed', 'error', 'cancelled'].includes(String(job.status)) || result.status === 'error') {
+        throw new CloudError('app_deploy_failed', `Deploy thất bại${jobId ? ` (job ${jobId})` : ''}: ${job.error || result.errorMessage || result.error || 'kiểm tra log build'}`, 'Gọi cloud_app_logs và cloud_app_get để sửa lỗi; chỉ cloud_app_deploy lại sau khi sửa.');
+    }
+    return { ...start, ...job, ...(jobId ? { job_id: jobId } : {}),
+        ...(typeof result.url === 'string' ? { url: result.url } : {}),
+        ...(typeof result.application_id === 'string' ? { application_id: result.application_id } : {}),
+        ...(sandbox ? { sandbox: true } : {}) };
+}

package/dist/mail.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CloudClients } from './clients.js';
+import type { Config } from './config.js';
+export declare function registerMailTools(server: McpServer, clients: CloudClients, config: Config): void;

package/dist/mail.js

@@ -0,0 +1,183 @@
+import { randomUUID } from 'node:crypto';
+import { domainToASCII } from 'node:url';
+import { z } from 'zod';
+import { runTool } from './errors.js';
+const id = z.string().trim().min(1).max(255);
+const email = z.string().max(320).regex(/^[^\s@<>,;]+@[^\s@<>,;]+\.[^\s@<>,;]+$/, 'Cần địa chỉ email hợp lệ.');
+const mailbox = z.union([
+    email,
+    z.string().max(998).regex(/^[^<>\r\n]+<[^\s@<>,;]+@[^\s@<>,;]+\.[^\s@<>,;]+>$/, 'Dùng email hoặc Tên <email>.'),
+]);
+const recipients = z.union([mailbox, z.array(mailbox).min(1).max(50)]);
+const subject = z.string().min(1).max(998).regex(/^[^\r\n]+$/, 'Subject không chứa xuống dòng.');
+const domain = z.string().trim().toLowerCase().transform(domainToASCII).pipe(z.string().max(253).regex(/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/, 'Cần domain hợp lệ, không kèm URL.'));
+const httpsUrl = z.string().url().refine((value) => new URL(value).protocol === 'https:', 'Cần URL HTTPS.');
+const timestamp = z.iso.datetime({ offset: true });
+const dateOrTimestamp = z.union([z.iso.date(), timestamp]);
+const idempotency = {
+    idempotency_key: z.string().min(1).max(255).regex(/^[\x21-\x7e]+$/, 'Idempotency key dùng ký tự ASCII, không khoảng trắng.').optional()
+        .describe('Giữ cùng key khi thử lại cùng yêu cầu trong 24 giờ. / Reuse for retries.'),
+};
+const empty = z.object({}).strict();
+const events = z.enum([
+    'email.sent', 'email.delivered', 'email.deferred', 'email.bounced',
+    'email.complained', 'email.suppressed', 'email.failed', 'domain.verified',
+]);
+const status = z.enum(['queued', 'sent', 'delivered', 'deferred', 'bounced', 'complained', 'suppressed', 'failed', 'sandbox']);
+function idempotencyHeaders(key) {
+    return { 'Idempotency-Key': key || `mcp-mail-${randomUUID()}` };
+}
+export function registerMailTools(server, clients, config) {
+    server.registerTool('mail_account', {
+        title: 'Tài khoản MONA Mail',
+        description: `Khi bắt đầu tích hợp email, đọc tài khoản, quota và bước kế tiếp. / Use first to read account and quota at ${config.monamailApi}.`,
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/account')));
+    server.registerTool('mail_plans', {
+        title: 'Gói MONA Mail',
+        description: 'Khi chọn gói gửi mail, đọc giá và quota hiện hành. / Use to compare current email plans.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/plans')));
+    server.registerTool('mail_plan_set', {
+        title: 'Đổi gói MONA Mail',
+        description: 'Khi cần đổi quota, chọn gói; gói trả phí trừ ví VND, thiếu tiền gọi cloud_topup. / Use to change the email plan.',
+        inputSchema: z.object({ plan: z.enum(['free', 'khoi-nghiep', 'kinh-doanh', 'doanh-nghiep']) }).strict(),
+    }, ({ plan }) => runTool(() => clients.mail('/v1/account/plan', { method: 'PUT', body: { plan } })));
+    server.registerTool('mail_send', {
+        title: 'Gửi email giao dịch',
+        description: 'Khi gửi OTP hoặc thông báo, dùng domain đã verify; onboarding@monamail.vn chỉ gửi tới email chủ. sandbox=true thử 0đ, không gửi ra Internet. / Use to send transactional email or test in sandbox.',
+        inputSchema: z.object({
+            from: mailbox,
+            to: recipients,
+            subject: subject.optional().describe('Bắt buộc nếu không dùng template_id. / Required without a template.'),
+            html: z.string().min(1).optional(),
+            text: z.string().min(1).optional(),
+            reply_to: recipients.optional(),
+            tags: z.array(z.string().regex(/^[a-z0-9_-]+$/)).max(10).optional(),
+            template_id: id.optional(),
+            variables: z.record(z.string(), z.unknown()).optional(),
+            unsubscribe_url: httpsUrl.optional(),
+            ...idempotency,
+            sandbox: z.boolean().optional().describe('Gửi X-Mona-Sandbox: 1, không tính quota hoặc trừ ví. / Test without delivery or charges.'),
+        }).strict().superRefine((value, context) => {
+            if (!value.template_id) {
+                if (!value.subject)
+                    context.addIssue({ code: 'custom', path: ['subject'], message: 'Cần subject khi không dùng template_id.' });
+                if (!value.html && !value.text)
+                    context.addIssue({ code: 'custom', path: ['html'], message: 'Cần ít nhất html hoặc text khi không dùng template_id.' });
+            }
+        }),
+    }, ({ sandbox, idempotency_key, ...body }) => runTool(async () => {
+        const result = await clients.mail('/v1/emails', {
+            method: 'POST',
+            headers: { ...idempotencyHeaders(idempotency_key), ...(sandbox ? { 'X-Mona-Sandbox': '1' } : {}) },
+            body,
+        });
+        return sandbox ? { ...result, sandbox: true } : result;
+    }));
+    server.registerTool('mail_status', {
+        title: 'Trạng thái email',
+        description: 'Khi cần xác nhận thư đã giao, đọc trạng thái, events và sandbox_preview. / Use to inspect an email after sending.',
+        inputSchema: z.object({ email_id: id }).strict(),
+    }, ({ email_id }) => runTool(() => clients.mail(`/v1/emails/${encodeURIComponent(email_id)}`)));
+    server.registerTool('mail_list', {
+        title: 'Danh sách email',
+        description: 'Khi tra lịch sử gửi, lọc theo trạng thái, người nhận hoặc thời gian. / Use to search sent email history.',
+        inputSchema: z.object({
+            limit: z.number().int().min(1).max(100).default(20),
+            status: status.optional(),
+            to: email.optional(),
+            since: timestamp.optional(),
+        }).strict(),
+    }, (query) => runTool(() => clients.mail('/v1/emails', { query })));
+    server.registerTool('mail_domain_add', {
+        title: 'Thêm domain gửi email',
+        description: 'Khi gửi bằng domain của app, thêm domain. Trả record DNS; nếu người dùng dùng Cloudflare có thể gọi mail_domain_cloudflare với token của họ (không lưu). / Use to register a sender domain and get DNS records.',
+        inputSchema: z.object({
+            domain: domain.refine((value) => value !== 'monamail.vn' && !value.endsWith('.monamail.vn'), 'Dùng domain của anh chị, không dùng domain MONA Mail.'),
+            ...idempotency,
+        }).strict(),
+    }, ({ domain, idempotency_key }) => runTool(async () => ({
+        ...await clients.mail('/v1/domains', {
+            method: 'POST', headers: idempotencyHeaders(idempotency_key), body: { domain },
+        }),
+        instructions: 'Thêm các records vào DNS rồi gọi mail_domain_verify. Nếu dùng Cloudflare, gọi mail_domain_cloudflare với token người dùng cung cấp; token chỉ dùng một lần, không lưu. DKIM đúng là đủ để verify; SPF/DMARC là cảnh báo. Nếu đã có SPF, thêm include:_spf.monamail.vn vào record hiện có.',
+    })));
+    server.registerTool('mail_domain_verify', {
+        title: 'Xác minh DNS domain',
+        description: 'Khi đã thêm DNS, kiểm DKIM và trạng thái domain. / Use after adding DNS records to verify the sender domain.',
+        inputSchema: z.object({ domain_id: id, ...idempotency }).strict(),
+    }, ({ domain_id, idempotency_key }) => runTool(() => clients.mail(`/v1/domains/${encodeURIComponent(domain_id)}/verify`, {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key),
+    })));
+    server.registerTool('mail_domain_cloudflare', {
+        title: 'Thêm DNS qua Cloudflare',
+        description: 'Khi người dùng cung cấp token Cloudflare, thêm DNS rồi verify domain. Token dùng một lần, không lưu, không log. / Use a user-provided Cloudflare token to configure DNS and verify.',
+        inputSchema: z.object({ domain_id: id, api_token: z.string().trim().min(1).max(4096), ...idempotency }).strict(),
+    }, ({ domain_id, api_token, idempotency_key }) => runTool(() => clients.mail(`/v1/domains/${encodeURIComponent(domain_id)}/cloudflare`, {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key), body: { api_token },
+    })));
+    server.registerTool('mail_domains_list', {
+        title: 'Domain MONA Mail',
+        description: 'Khi chọn địa chỉ gửi, xem domain và trạng thái xác minh. / Use to find verified sender domains.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/domains')));
+    server.registerTool('mail_api_key_create', {
+        title: 'Tạo API key MONA Mail',
+        description: 'Khi tích hợp SDK vào app, tạo key live hoặc test. Key chỉ trả một lần; ghi vào .env của app dưới tên MONAMAIL_API_KEY, không cần in ra chat. / Use to create an app key; store the one-time secret in .env.',
+        inputSchema: z.object({ name: id, mode: z.enum(['live', 'test']), ...idempotency }).strict(),
+    }, ({ idempotency_key, ...body }) => runTool(() => clients.mail('/v1/api-keys', {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key), body,
+    })));
+    server.registerTool('mail_api_keys_list', {
+        title: 'Danh sách API key',
+        description: 'Khi kiểm tra key của app, đọc prefix và trạng thái; không trả secret. / Use to inspect existing API key metadata.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/api-keys')));
+    server.registerTool('mail_api_key_revoke', {
+        title: 'Thu hồi API key',
+        description: 'Khi key không còn dùng hoặc bị lộ, thu hồi bằng key_id. / Use to revoke an unused or compromised API key.',
+        inputSchema: z.object({ key_id: id }).strict(),
+    }, ({ key_id }) => runTool(() => clients.mail(`/v1/api-keys/${encodeURIComponent(key_id)}`, { method: 'DELETE' })));
+    server.registerTool('mail_webhook_create', {
+        title: 'Tạo webhook email',
+        description: 'Khi app cần nhận sự kiện gửi hoặc bounce, đăng ký HTTPS webhook; lưu secret một lần vào .env, không log. / Use to subscribe an app to email events.',
+        inputSchema: z.object({ url: httpsUrl, events: z.array(events).min(1).max(8), ...idempotency }).strict(),
+    }, ({ idempotency_key, ...body }) => runTool(() => clients.mail('/v1/webhooks', {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key), body,
+    })));
+    server.registerTool('mail_webhooks_list', {
+        title: 'Danh sách webhook email',
+        description: 'Khi kiểm tra cấu hình sự kiện của app, liệt kê webhook. / Use to inspect registered email webhooks.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/webhooks')));
+    server.registerTool('mail_webhook_test', {
+        title: 'Thử webhook email',
+        description: 'Khi đã có endpoint, gửi mẫu email.delivered để kiểm tra HTTP response. / Use to test webhook delivery to an app.',
+        inputSchema: z.object({ webhook_id: id, ...idempotency }).strict(),
+    }, ({ webhook_id, idempotency_key }) => runTool(() => clients.mail(`/v1/webhooks/${encodeURIComponent(webhook_id)}/test`, {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key),
+    })));
+    server.registerTool('mail_suppressions_list', {
+        title: 'Địa chỉ ngừng gửi',
+        description: 'Khi thư bị suppressed, xem địa chỉ và lý do ngừng gửi. / Use to diagnose suppressed recipients.',
+        inputSchema: empty,
+    }, () => runTool(() => clients.mail('/v1/suppressions')));
+    server.registerTool('mail_suppression_remove', {
+        title: 'Gỡ suppression tài khoản',
+        description: 'Khi đã xử lý nguyên nhân chặn, gỡ suppression của tài khoản; lớp toàn hệ không gỡ được. / Use to remove an account-level suppression.',
+        inputSchema: z.object({ email }).strict(),
+    }, ({ email }) => runTool(() => clients.mail(`/v1/suppressions/${encodeURIComponent(email)}`, { method: 'DELETE' })));
+    server.registerTool('mail_template_create', {
+        title: 'Tạo mẫu email',
+        description: 'Khi app dùng lại nội dung mail, tạo template với biến {{ten_bien}}. / Use to create a reusable email template.',
+        inputSchema: z.object({ name: id, subject, html: z.string().min(1), text: z.string().min(1).optional(), ...idempotency }).strict(),
+    }, ({ idempotency_key, ...body }) => runTool(() => clients.mail('/v1/templates', {
+        method: 'POST', headers: idempotencyHeaders(idempotency_key), body,
+    })));
+    server.registerTool('mail_stats', {
+        title: 'Thống kê gửi email',
+        description: 'Khi đánh giá khả năng giao thư, đọc tỷ lệ delivered và bounce theo thời gian. / Use to review email delivery statistics.',
+        inputSchema: z.object({ from: dateOrTimestamp.optional(), to: dateOrTimestamp.optional() }).strict().refine((value) => !value.from || !value.to || Date.parse(value.from) <= Date.parse(value.to), 'Thời điểm from phải trước hoặc bằng to.'),
+    }, (query) => runTool(() => clients.mail('/v1/stats', { query })));
+}

package/dist/server.js

@@ -1,4 +1,3 @@
-import { setTimeout as delay } from 'node:timers/promises';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { readConfig } from './config.js';
@@ -8,8 +7,10 @@ import { errorResult, runTool, textResult, toAgentError } from './errors.js';
 import { requestJson, unwrapData } from './http.js';
 import { createMonaPayClient, importedMonaPayTools, normalizeImportedResult } from './monapay.js';
 import { TemplateCatalog } from './templates.js';
-const ENTITY = 'MONA Cloud là hệ công cụ cho vibecoder Việt Nam: một MONA Pass, một ví VND và một MCP để chạy app/VPS, thu tiền MONA Pay và dùng các sản phẩm MONA.';
-const TERMINAL_JOBS = new Set(['done', 'succeeded', 'failed', 'cancelled']);
+import { registerMailTools } from './mail.js';
+import { APP_FLOW, createVps, registerComputeTools } from './compute.js';
+import { pollJob } from './jobs.js';
+const ENTITY = 'MONA Cloud là hệ công cụ cho vibecoder Việt Nam: một MONA Pass, một ví VND và một MCP để chạy app/VPS, thu tiền MONA Pay và dùng các sản phẩm MONA. Dùng mail_* để gửi email giao dịch (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, không cần thẻ, thuộc nhóm MONA Cloud của The MONA Group.';
 const SANDBOX_DESCRIPTION = 'sandbox=true: thử 0đ, không cần ví';
 const sandboxSchema = z.boolean().optional().describe(SANDBOX_DESCRIPTION);
 const asObject = (value) => (value && typeof value === 'object' ? value : {});
@@ -44,35 +45,34 @@ const provisionSchema = z.object(sizingSchema).superRefine((value, context) => {
         context.addIssue({ code: 'custom', message: 'Cần package_slug hoặc đủ cpu, ram_gb và disk_gb.' });
     }
 });
+const vpsSchema = z.object({
+    ...sizingSchema,
+    billing_mode: z.enum(['hourly', 'monthly']).optional(),
+    plan_code: z.string().trim().min(2).max(64).optional(),
+    period: z.enum(['month', 'year']).optional(),
+}).strict().superRefine((value, context) => {
+    if (value.billing_mode === 'monthly') {
+        if (!value.plan_code)
+            context.addIssue({ code: 'custom', message: 'Monthly cần plan_code.' });
+        return;
+    }
+    if (value.plan_code || value.period)
+        context.addIssue({ code: 'custom', message: 'plan_code/period chỉ dùng với billing_mode=monthly.' });
+    const checked = provisionSchema.safeParse(value);
+    if (!checked.success)
+        for (const issue of checked.error.issues)
+            context.addIssue({ code: 'custom', message: issue.message, path: issue.path });
+});
 function agentRuntimeStub(template, sandbox = false) {
     return {
         status: 'not_available',
         code: 'agent_runtime_pending',
         template,
         message: 'Runtime MONA Agent trên MONA Cloud chưa được phát hành; tool này là slot wave kế tiếp theo brief.',
-        next_step: 'Dùng agent_templates_get để lấy nội dung template và triển khai thủ công, hoặc thử lại khi MONA Cloud bật runtime agent.',
+        next_step: `Dùng agent_templates_get để đọc template. ${APP_FLOW}`,
         ...(sandbox ? { sandbox: true } : {}),
     };
 }
-async function pollJob(clients, jobId, wait, intervalSeconds, timeoutSeconds, sandbox) {
-    let result = await clients.vibecloud(`/api/jobs/${encodeURIComponent(jobId)}`);
-    if (!wait)
-        return sandbox ? { ...asObject(result), sandbox: true } : result;
-    const deadline = Date.now() + timeoutSeconds * 1000;
-    while (!TERMINAL_JOBS.has(String(asObject(result).status || '')) && Date.now() < deadline) {
-        await delay(intervalSeconds * 1000);
-        result = await clients.vibecloud(`/api/jobs/${encodeURIComponent(jobId)}`);
-    }
-    if (!TERMINAL_JOBS.has(String(asObject(result).status || ''))) {
-        return {
-            ...asObject(result),
-            ...(sandbox ? { sandbox: true } : {}),
-            polling: 'timeout',
-            next_step: `Gọi lại cloud_job_status với job_id=${jobId}.`,
-        };
-    }
-    return sandbox ? { ...asObject(result), sandbox: true } : result;
-}
 async function providerHealth(name, url, fetchImpl) {
     const started = Date.now();
     try {
@@ -90,7 +90,7 @@ export function createServer(dependencies = {}) {
     const auth = new AuthManager(config, env, fetchImpl);
     const clients = new CloudClients(config, auth, fetchImpl);
     const catalog = new TemplateCatalog(config, fetchImpl);
-    const server = new McpServer({ name: 'monacloud-mcp', version: '0.2.1' }, { instructions: `${ENTITY}\nDùng cloud_* cho tài khoản, ví và hạ tầng; monapay_* cho thu tiền; agent_* cho catalog. Không bao giờ yêu cầu mật khẩu sản phẩm. Chỉ dừng hỏi người dùng khi cần nạp tiền, OTP ngân hàng hoặc KYC bắt buộc.` });
+    const server = new McpServer({ name: 'monacloud-mcp', version: '0.3.0' }, { instructions: `${ENTITY}\nDùng cloud_* cho tài khoản, ví và hạ tầng; monapay_* cho thu tiền; mail_* để gửi email giao dịch (MONA Mail); agent_* cho catalog. Không bao giờ yêu cầu mật khẩu sản phẩm. Đọc → ước tính → hỏi duyệt nếu chưa được duyệt → làm. Dừng khi cần DNS, nạp tiền, duyệt chi phí, OTP hoặc KYC. ${APP_FLOW}` });
     server.registerTool('cloud_whoami', {
         title: 'Tài khoản MONA Cloud',
         description: 'Xác minh MONA Pass hiện tại. / Return the current MONA Pass profile.',
@@ -196,20 +196,14 @@ export function createServer(dependencies = {}) {
     }, () => runTool(() => clients.vibecloudLink()));
     server.registerTool('cloud_vps_create', {
         title: 'Tạo VPS MONA Cloud',
-        description: `Kiểm tra ví chung rồi tạo LXC VPS; trả job_id để poll. ${SANDBOX_DESCRIPTION}.`,
-        inputSchema: provisionSchema,
-    }, (body) => runTool(async () => {
-        const { sandbox, ...payload } = body;
-        return clients.guardedVibecloud('/api/lxc', { method: 'POST', body: payload }, sandbox);
-    }));
+        description: `Đọc cloud_plan_list (monthly) hoặc cloud_prices/cloud_packages (hourly), ước tính rồi hỏi duyệt trước tạo. Monthly bỏ CPU/RAM/đĩa, lấy từ plan_code; period=month|year. Kiểm ví đủ giá gói, trả estimate và job_id. / Estimate, approve, create VPS. ${SANDBOX_DESCRIPTION}.`,
+        inputSchema: vpsSchema,
+    }, (body) => runTool(() => createVps(clients, body)));
     server.registerTool('vibecloud_create_vps', {
         title: 'Alias cũ của cloud_vps_create',
         description: `Alias tương thích; dùng cloud_vps_create cho tích hợp mới. ${SANDBOX_DESCRIPTION}.`,
-        inputSchema: provisionSchema,
-    }, (body) => runTool(async () => {
-        const { sandbox, ...payload } = body;
-        return clients.guardedVibecloud('/api/lxc', { method: 'POST', body: payload }, sandbox);
-    }));
+        inputSchema: vpsSchema,
+    }, (body) => runTool(() => createVps(clients, body)));
     const databaseSchema = provisionSchema.extend({ engine: z.enum(['mongodb', 'postgresql', 'mysql']).default('mongodb') });
     server.registerTool('cloud_db_create', {
         title: 'Tạo database MONA Cloud',
@@ -309,9 +303,11 @@ export function createServer(dependencies = {}) {
         description: `Alias tương thích; dùng cloud_agent_deploy cho tích hợp mới. ${SANDBOX_DESCRIPTION}.`,
         inputSchema: { template: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/), sandbox: sandboxSchema },
     }, ({ template, sandbox }) => runTool(() => agentRuntimeStub(template, clients.sandboxEnabled(sandbox))));
+    registerComputeTools(server, clients);
+    registerMailTools(server, clients, config);
     server.registerTool('agent_templates_list', {
         title: 'Catalog MONA Agent',
-        description: 'Đọc template từ thư mục local, URL catalog hoặc catalog wave 1 tích hợp.',
+        description: 'Đọc template từ thư mục local, URL catalog hoặc catalog wave 1 tích hợp. Deploy repo git: dùng cloud_app_create, sandbox trước nếu chưa có host.',
     }, () => runTool(() => catalog.list()));
     server.registerTool('agent_templates_get', {
         title: 'Chi tiết MONA Agent template',
@@ -320,7 +316,7 @@ export function createServer(dependencies = {}) {
     }, ({ template }) => runTool(() => catalog.get(template)));
     server.registerTool('agent_deploy', {
         title: 'Dùng ngay MONA Agent template',
-        description: 'Gọi cùng runtime với cloud_agent_deploy.',
+        description: 'Gọi cùng runtime với cloud_agent_deploy. Với deploy repo git, dùng cloud_app_create (đang mở), sandbox trước nếu chưa có host.',
         inputSchema: { template: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/) },
     }, ({ template }) => runTool(() => agentRuntimeStub(template)));
     const imported = importedMonaPayTools(config, env, fetchImpl);
@@ -351,11 +347,11 @@ export function createServer(dependencies = {}) {
     }, async (uri) => ({ contents: [{
                 uri: uri.href,
                 mimeType: 'text/plain',
-                text: `${ENTITY}\n\nHuman chỉ đăng ký MONA Pass, nạp tiền và cung cấp OTP/KYC bắt buộc. AI dùng MCP làm phần còn lại.\n\n- cloud_*: tài khoản, ví, ledger, usage, budget, VPS, database, job, vòng đời service và giá/gói.\n- monapay_*: nối ngân hàng, checkout/QR, giao dịch, webhook và email.\n- agent_*: catalog và deploy template.\n\nMONA Cloud: https://monacloud.vn\nCompute API: https://api.monacloud.vn\nMONA Pay: https://monapay.vn\n`,
+                text: `${ENTITY}\n\n${APP_FLOW}\n\nHuman đăng ký MONA Pass, duyệt chi phí, thêm DNS khi cần, nạp tiền và cung cấp OTP/KYC bắt buộc. AI dùng MCP làm phần còn lại.\n\n- cloud_*: tài khoản, ví, ledger, usage, budget, VPS, database, job, vòng đời service, plans, subscriptions, invoices/PDF, credit và apps từ git (đang mở).\n- monapay_*: nối ngân hàng, checkout/QR, giao dịch, webhook và email.\n- mail_*: tài khoản, domain, API key, gửi mail, trạng thái, webhook, suppression (MONA Mail https://monamail.vn, API https://api.monamail.vn)\n- agent_*: catalog và deploy template.\n\nMONA Cloud: https://monacloud.vn\nCompute API: https://api.monacloud.vn\nMONA Pay: https://monapay.vn\n`,
             }] }));
     server.registerResource('monacloud-status', 'monacloud://status', {
         title: 'Trạng thái hệ MONA Cloud',
-        description: 'Health tổng hợp của MONA Pass, billing, compute MONA Cloud và MONA Pay.',
+        description: 'Health tổng hợp của MONA Pass, billing, compute MONA Cloud, MONA Pay và MONA Mail.',
         mimeType: 'application/json',
     }, async (uri) => {
         const members = await Promise.all([
@@ -363,6 +359,7 @@ export function createServer(dependencies = {}) {
             providerHealth('billing', `${config.billingUrl}/v1/healthz`, fetchImpl),
             providerHealth('monacloud-compute', `${config.vibecloudApi}/api/prices`, fetchImpl),
             providerHealth('monapay', `${config.monapayApi}/health`, fetchImpl),
+            providerHealth('monamail', `${config.monamailApi}/v1/healthz`, fetchImpl),
         ]);
         return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ checked_at: new Date().toISOString(), members }, null, 2) }] };
     });
@@ -377,7 +374,30 @@ export function createServer(dependencies = {}) {
                 role: 'user',
                 content: {
                     type: 'text',
-                    text: `Dựng app bán hàng ${app_name || 'của tôi'} bằng ${framework || 'stack phù hợp'} trên MONA Cloud theo đúng thứ tự:\n1. Gọi cloud_whoami, cloud_balance, cloud_packages và cloud_prices. Nếu thiếu tiền, gọi cloud_topup rồi dừng để người dùng quét VietQR.\n2. Gọi cloud_vps_create và cloud_db_create; poll từng job bằng cloud_job_status tới succeeded.\n3. Gọi monapay_link nếu MONA Pay còn ở lớp chuyển tiếp. Gọi monapay_whoami; nếu chưa có VA, nối ngân hàng bằng chuỗi monapay_link_bank_start → HỎI OTP → verify → notification_register → HỎI OTP lần 2 → verify. Không tự đoán OTP.\n4. Viết endpoint webhook có HMAC và idempotency theo transaction_code; đăng ký bằng monapay_create_webhook, bắn monapay_test_webhook và đọc monapay_webhook_logs.\n5. Tích hợp monapay_create_checkout hoặc monapay_create_qr vào app, chỉ giao hàng sau CHECKOUT_PAID.\n6. Deploy code lên VPS vừa tạo, kiểm tra health và báo URL/credential cần lưu. Không yêu cầu người dùng mở dashboard ngoài bước nạp tiền/OTP bắt buộc.`,
+                    text: `Dựng app bán hàng ${app_name || 'của tôi'} bằng ${framework || 'stack phù hợp'} trên MONA Cloud theo đúng thứ tự:\n1. Gọi cloud_whoami, cloud_balance, cloud_plan_list, cloud_packages và cloud_prices. Báo ước tính và hỏi duyệt chi phí nếu chưa được duyệt. Nếu thiếu tiền, gọi cloud_topup rồi dừng để người dùng quét VietQR.\n2. Nếu dùng VPS gọi cloud_vps_create và cloud_db_create; nếu deploy repo dùng cloud_app_host_list rồi cloud_app_create (đang mở), sandbox trước nếu chưa có host. Poll từng job bằng cloud_job_status tới done/succeeded.\n3. Gọi monapay_link nếu MONA Pay còn ở lớp chuyển tiếp. Gọi monapay_whoami; nếu chưa có VA, nối ngân hàng bằng chuỗi monapay_link_bank_start → HỎI OTP → verify → notification_register → HỎI OTP lần 2 → verify. Không tự đoán OTP.\n4. Viết endpoint webhook có HMAC và idempotency theo transaction_code; đăng ký bằng monapay_create_webhook, bắn monapay_test_webhook và đọc monapay_webhook_logs.\n5. Tích hợp monapay_create_checkout hoặc monapay_create_qr vào app, chỉ giao hàng sau CHECKOUT_PAID.\n6. Với repo git, dùng cloud_app_create sau khi duyệt ước tính; kiểm cloud_app_get/cloud_app_logs và health rồi báo URL. Chỉ dùng VPS thủ công khi người dùng chọn. Không yêu cầu người dùng mở dashboard ngoài bước nạp tiền/OTP bắt buộc.`,
+                },
+            }] }));
+    server.registerPrompt('gui-mail-otp-monamail', {
+        title: 'Gửi mail OTP bằng MONA Mail',
+        description: 'Tích hợp OTP zero-dashboard: account → onboarding → DNS → verify → API key → SDK → webhook bounced.',
+        argsSchema: {
+            app_name: z.string().optional(),
+            framework: z.string().optional(),
+            domain: z.string().optional(),
+        },
+    }, ({ app_name, framework, domain }) => ({ messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Tích hợp gửi mail OTP cho ${app_name || 'app của tôi'} bằng ${framework || 'stack hiện có của app'}, domain ${domain || 'lấy từ cấu hình app'}, dùng MONA Mail theo thứ tự:
+1. Gọi mail_account để lấy email chủ, quota, domain và next_step. MCP dùng MONA Pass sẵn có, tài khoản Mail được tạo tự động ở request đầu.
+2. Nếu chưa có domain verified, gửi thử mail_send từ onboarding@monamail.vn tới đúng email chủ vừa lấy, subject "Thử OTP MONA Mail", text là nội dung thử và idempotency_key riêng cho lượt thử. Gọi mail_status theo id; chỉ báo đã giao khi status=delivered. Nếu yêu cầu sandbox, dùng sandbox: true rồi kiểm sandbox_preview, không báo đã gửi thư thật.
+3. Gọi mail_domain_add cho domain của app. Trả nguyên records để người dùng thêm DNS; đây là điểm được dừng hỏi. Nếu đã có token Cloudflare của người dùng, gọi mail_domain_cloudflare để thêm DNS và verify; token chỉ dùng một lần, không lưu hoặc log. Nếu cần token, xin ngay tại bước DNS.
+4. Gọi mail_domain_verify, đọc checks và chờ status=verified; DKIM đúng là đủ, SPF/DMARC là cảnh báo. Khi đã có SPF, gộp include:_spf.monamail.vn vào record hiện có.
+5. Gọi mail_api_key_create với name theo app và mode live; khi thử sandbox chọn mode test (mm_test_). Key chỉ trả một lần: ghi trực tiếp vào .env của app dưới tên MONAMAIL_API_KEY, bỏ .env khỏi git, không in key ra chat hoặc log. Chỉ báo prefix nếu cần nhận diện.
+6. Viết code gửi OTP ở server bằng SDK npm monamail: import { MonaMail } from 'monamail'; const monamail = new MonaMail(process.env.MONAMAIL_API_KEY); const { id } = await monamail.emails.send({ from: 'Tên app <noreply@DOMAIN_DA_VERIFY>', to: emailNguoiNhan, subject: 'Mã OTP', text: 'Mã OTP: ' + otp, tags: ['otp'], idempotency_key: requestId }); Thay placeholder bằng domain đã verify, sinh OTP ngẫu nhiên có hạn dùng và giới hạn số lần thử. Giữ cùng idempotency_key khi retry cùng yêu cầu trong 24 giờ. Gọi mail_status để kiểm kết quả.
+7. Viết HTTPS endpoint nhận email.bounced; xác minh HMAC trên timestamp và raw body bằng MonaMail.verifyWebhook, chống replay và xử lý idempotent theo event id. Gọi mail_webhook_create với events: ['email.bounced'], lưu secret riêng trong .env, rồi mail_webhook_test (payload thử là email.delivered). Kiểm suppression bằng mail_suppressions_list khi có bounce.
+Chỉ dừng hỏi người dùng ở bước thêm DNS hoặc nạp tiền. Nếu mail_plan_set trả insufficient_funds, gọi cloud_topup rồi chờ người dùng nạp và cloud_balance cập nhật. Dùng mail_plans để đọc giá hiện hành, không hard-code giá. Không yêu cầu mở dashboard để lấy API key.`,
                 },
             }] }));
     return server;

package/docs/ai-agent.md

@@ -1,6 +1,6 @@
 # MONA Cloud MCP — hướng dẫn cho AI agent
 
-Tài liệu này dành cho Claude, Codex, Cursor và agent dùng Model Context Protocol. Mục tiêu là hoàn thành tích hợp end-to-end mà không yêu cầu người dùng mở dashboard, trừ ba việc hợp lệ: đăng ký MONA Pass, nạp tiền và OTP/KYC bắt buộc.
+Tài liệu này dành cho Claude, Codex, Cursor và agent dùng Model Context Protocol. Mục tiêu là hoàn thành tích hợp end-to-end mà không yêu cầu người dùng mở dashboard; các bước human gồm đăng ký MONA Pass, thêm DNS khi cần, nạp tiền và OTP/KYC bắt buộc.
 
 ## Quy tắc vận hành
 
@@ -128,6 +128,49 @@ Deploy source lên VPS từ credential của job, đưa database connection stri
 - đọc `cloud_services` để báo lại toàn bộ service/VA/webhook;
 - không echo credential nhạy cảm trong báo cáo.
 
+## 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, không cần thẻ, thuộc nhóm MONA Cloud của The MONA Group.
+
+20 tool `mail_*` gọi `MONAMAIL_API` (mặc định `https://api.monamail.vn`) bằng access token MONA Pass hiện tại. JWT cần audience `monamail` hoặc `mona-products`; scope `product` đã có trong MCP. Tài khoản Mail được tạo tự động từ `sub` và `email` ở request đầu, không cần link hoặc đăng ký sản phẩm riêng.
+
+Dùng prompt `gui-mail-otp-monamail` với `app_name?`, `framework?`, `domain?` và thực hiện:
+
+1. `mail_account` lấy email chủ, quota, domain và `next_step`. `mail_plans` đọc gói và giá hiện hành khi cần đổi quota.
+2. Nếu chưa có domain verified, `mail_send` từ `onboarding@monamail.vn` tới đúng email chủ. Gọi `mail_status` theo `id`; `queued` hoặc `sent` chưa có nghĩa thư đã tới hộp nhận.
+3. `mail_domain_add` trả records DKIM/SPF/DMARC. Dừng ở bước DNS để user thêm records hoặc cung cấp token Cloudflare. Nếu đã có token, gọi `mail_domain_cloudflare` ngay; token dùng một lần, không ghi file, cache, log hoặc chat. Nếu có SPF sẵn, gộp `include:_spf.monamail.vn` vào record hiện có.
+4. `mail_domain_verify` đọc `checks`; chỉ gửi bằng domain riêng khi `status=verified`. DKIM đúng là đủ để verify, SPF/DMARC là cảnh báo.
+5. `mail_api_key_create` với `name` của app và `mode: "live"` hoặc `"test"`. Key chỉ trả một lần; ghi thẳng vào `.env` dưới tên `MONAMAIL_API_KEY`, bảo đảm `.env` không vào git. Chỉ dùng prefix để nhận diện key trong báo cáo. MCP vẫn dùng MONA Pass, app dùng key của SDK.
+6. Tích hợp SDK `monamail` tại server; sinh OTP ngẫu nhiên, có hạn dùng và giới hạn số lần thử. Gửi bằng `monamail.emails.send`, sau đó kiểm trạng thái qua `mail_status`.
+7. Viết HTTPS endpoint cho `email.bounced`, đăng ký `mail_webhook_create`, lưu secret riêng trong `.env`, gọi `mail_webhook_test`. Payload test là `email.delivered`, endpoint cần tiếp nhận mẫu này để kiểm đường truyền. Xem `mail_suppressions_list` khi địa chỉ bị ngừng gửi; `mail_suppression_remove` chỉ gỡ lớp account, API có thể trả `global_suppression` cho lớp toàn hệ.
+
+Ví dụ code Node.js trong app sau khi có key và domain verified:
+
+```ts
+import { MonaMail } from 'monamail';
+
+const monamail = new MonaMail(process.env.MONAMAIL_API_KEY);
+const { id } = await monamail.emails.send({
+  from: 'Shop <noreply@shop.vn>',
+  to: emailNguoiNhan,
+  subject: 'Mã OTP',
+  text: `Mã OTP: ${otp}`,
+  tags: ['otp'],
+  idempotency_key: requestId,
+});
+```
+
+`emailNguoiNhan`, `otp` và `requestId` lấy từ luồng xác thực của app. Dùng `MonaMail.verifyWebhook({ secret, timestamp, body, signature })` kiểm `X-Mona-Signature` trên `"<X-Mona-Timestamp>.<raw_body>"`. Chống replay theo timestamp, xử lý event một lần theo payload `id`/`X-Mona-Event-Id`.
+
+Ranh giới human của luồng Mail sau đăng nhập là **thêm DNS và nạp tiền**. Khi `mail_plan_set` trả `insufficient_funds`, gọi `cloud_topup`, đưa VietQR cho user và chờ `cloud_balance` cập nhật trước khi thử lại. Không yêu cầu user mở dashboard lấy API key. Lỗi Mail giữ `code`, `message`, `next_step`, `request_id` từ API, gồm `domain_not_verified`, `quota_exceeded`, `budget_exceeded` và `idempotency_conflict`.
+
+### Sandbox và idempotency Mail
+
+- MCP: `mail_send({ ..., sandbox: true })` gửi `X-Mona-Sandbox: 1`, kết quả có `sandbox: true`.
+- App: key `mm_test_` bật sandbox qua SDK; key `mm_live_` dùng để gửi thật. `MONACLOUD_SANDBOX` dành cho compute, không tự bật sandbox Mail.
+- Sandbox đi qua pipeline nhưng không gửi ra Internet, không tính quota hoặc trừ ví. Dùng `mail_status` để đọc trạng thái `sandbox` và `sandbox_preview`; không báo thư sandbox đã được giao thật.
+- Mọi POST Mail có header `Idempotency-Key`: dùng tham số `idempotency_key` hoặc MCP tự tạo `mcp-mail-<uuid>`. Khi retry phải truyền cùng key và giữ nguyên body trong TTL 24 giờ. Cùng key/body trả response cũ, khác body trả 409 `idempotency_conflict`. Nếu bỏ key, mỗi lần gọi MCP là yêu cầu mới.
+
 ## Spend guard
 
 `cloud_vps_create`, `cloud_db_create`, `cloud_service_start` và `cloud_service_rebuild` đọc `GET /v1/balance` trước khi gọi sản phẩm thật. Upstream vẫn là nguồn quyết định cuối và có thể trả:
@@ -168,6 +211,7 @@ Sandbox không gọi Proxmox, không cấp IP thật, không trừ tiền và c
 - Đọc `monacloud://llms` khi cần bối cảnh toàn hệ sinh thái.
 - Đọc `monacloud://status` trước khi kết luận lỗi là do credential hoặc request.
 - Dùng prompt `dung-app-ban-hang-monacloud` để lấy chuỗi tác vụ chuẩn.
+- Dùng prompt `gui-mail-otp-monamail` để tích hợp OTP, DNS, API key và webhook Mail.
 
 ## Tiêu chí hoàn tất
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monacloud-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Unified MCP server for MONA Cloud, MONA Pay and MONA Agent.",
   "license": "MIT",
   "type": "module",