monacloud-mcp 0.7.0 → 0.8.1

package/README.md

@@ -2,7 +2,15 @@
 
 `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ý, duyệt chi phí, 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.
+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, không bảo mở console" đượ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 `exec` cần cho phép gọi MCP (mặc định chặn approval) rồi cũng làm được.
+
+## 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. Không còn bảo người dùng mở console để nạ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
 
@@ -12,7 +20,7 @@ Thêm `cloud_base_create/list/get/delete/credentials` cùng alias `vibecloud_bas
 
 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 và nạp ví khi hết credit 20k.
+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 |
 |---|---|
@@ -94,7 +102,8 @@ Tên tool dùng `snake_case` để giữ tương thích với prompt MONA Pay c
 | `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_data_url` và hướng dẫn VietQR |
+| `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 |
@@ -211,7 +220,7 @@ Trước lệnh compute MONA Cloud thật có thể phát sinh tiền, MCP đọ
 {
   "code": "budget_exceeded",
   "message": "Ví thiếu 20.000 đ hoặc đã chạm giới hạn chi tiêu.",
-  "next_step": "Nạp ví hoặc tăng ngân sách tại https://monacloud.vn/console rồi gọi lại tool.",
+  "next_step": "Gọi cloud_topup để lấy QR nạp ví hoặc cloud_budget_set để tăng ngân sách rồi gọi lại tool.",
   "request_id": "req_..."
 }
 ```
@@ -227,7 +236,7 @@ Người dùng nói:
 Agent thực hiện:
 
 1. `cloud_whoami` → `cloud_balance` → `cloud_packages`.
-2. Nếu ví thiếu: `cloud_topup(200000)`, đưa QR cho người dùng và chờ xác nhận.
+2. Nếu ví thiếu: `cloud_topup(200000)`, in nguyên khối `qr_ascii` cho người dùng quét bằng app ngân hàng, rồi `cloud_topup_status` tới khi `paid`.
 3. `cloud_vps_create` + `cloud_db_create`, sau đó `cloud_job_status` cho từng job.
 4. `monapay_link` nếu adapter chuyển tiếp chưa có credential; `monapay_whoami` để kiểm tra VA.
 5. Nếu chưa có VA: bắt đầu nối ACB, hỏi người dùng OTP đúng hai điểm bắt buộc, không tự đoán.

package/STATUS.md

@@ -1,5 +1,9 @@
 # STATUS — monacloud-mcp 0.5.0
 
+## 0.8.0 — nạp ví ngay trong terminal (17/09/2026)
+- [x] `cloud_topup` trả `qr_ascii` (VietQR EMVCo/NAPAS dựng local, CRC16 khớp mẫu acb-ipn) + `qr_file` PNG + `qr_url` + ngân hàng/số TK/số tiền/nội dung; bỏ base64 khỏi text. Fallback compute `/api/payments/vietqr` khi billing 401/403/404/502/503 (merchant MONA Pay placeholder). Thêm `cloud_topup_status`.
+- [x] Lời cho AI: instructions/llms/prompt/README/docs nói rõ AI tự tạo QR, người dùng chỉ quét, không mở console (luật AI-first §1, Mon chốt 17/09).
+
 Updated: 2026-09-14 (Asia/Ho_Chi_Minh)
 
 ## MONA Base beta — hoàn tất offline

package/dist/clients.d.ts

@@ -14,9 +14,18 @@ export declare class CloudClients {
         headers?: Record<string, string>;
     }): Promise<T>;
     balance(): Promise<unknown>;
+    /** Số dư ví local compute (nơi yêu cầu nạp qua /api/payments/vietqr được cộng), đọc từ /api/me. */
+    localBalance(): Promise<JsonObject>;
     ledger(cursor?: string, limit?: number): Promise<unknown>;
     usage(period: string, product?: string): Promise<unknown>;
-    topup(amount: number, idempotencyKey?: string): Promise<unknown>;
+    /**
+     * Tạo yêu cầu nạp ví. Ưu tiên ví chung (billing /v1/topups → MONA Pay); khi billing chưa nhận token
+     * hoặc merchant MONA Pay chưa cấu hình (401/403/404/502/503) thì tạo qua compute /api/payments/vietqr
+     * (ví local, prefix VIBECLOUD, báo có tự cộng). Người dùng chỉ quét QR; không cần console.
+     */
+    topup(amount: number, idempotencyKey?: string): Promise<JsonObject>;
+    /** Trạng thái một yêu cầu nạp (pending/paid) kèm số dư hiện tại, để AI chờ tiền vào rồi làm tiếp. */
+    topupStatus(topupId: string): Promise<JsonObject>;
     budgetSet(body: {
         scope: string;
         scope_id: string;

package/dist/clients.js

@@ -54,7 +54,7 @@ export class CloudClients {
                 ? '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}.`
+                ? 'Gọi cloud_topup để lấy QR nạp ví (in qr_ascii cho người dùng quét), chờ cloud_topup_status paid hoặc cloud_balance cập nhật rồi thử lại.'
                 : 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'
@@ -85,22 +85,94 @@ export class CloudClients {
                 currency: 'VND',
                 wallet: 'local',
                 source: '/api/me',
-                note: 'Số dư ví local MONA Cloud compute (billing.monacloud.vn không nhận token này). Nạp tại console → ví. / Local compute wallet balance.',
+                note: 'Số dư ví local MONA Cloud compute (billing.monacloud.vn không nhận token này). Thiếu tiền thì gọi cloud_topup: QR VietQR in ngay trong terminal, người dùng quét bằng app ngân hàng, không cần mở console. / Local compute wallet balance; top up with cloud_topup.',
             };
         }
     }
+    /** Số dư ví local compute (nơi yêu cầu nạp qua /api/payments/vietqr được cộng), đọc từ /api/me. */
+    async localBalance() {
+        const root = asObject(unwrapData(await this.vibecloud('/api/me')));
+        const me = asObject(root.user ?? root);
+        const credit = Number(me.credit_vnd ?? 0);
+        const promo = Number(me.promo_credit_vnd ?? 0);
+        const total = me.total_credit_vnd !== undefined ? Number(me.total_credit_vnd) : credit + promo;
+        return {
+            balance_vnd: Number.isFinite(total) ? total : 0,
+            credit_vnd: Number.isFinite(credit) ? credit : 0,
+            promo_credit_vnd: Number.isFinite(promo) ? promo : 0,
+            currency: 'VND',
+            wallet: 'local',
+            source: '/api/me',
+        };
+    }
     ledger(cursor, limit = 50) {
         return this.billing('/v1/ledger', { query: { cursor, limit } });
     }
     usage(period, product) {
         return this.billing('/v1/usage', { query: { period, product } });
     }
-    topup(amount, idempotencyKey) {
-        return this.billing('/v1/topups', {
-            method: 'POST',
-            headers: { 'Idempotency-Key': idempotencyKey || `mcp-topup-${randomUUID()}` },
-            body: { amount_vnd: amount },
-        });
+    /**
+     * Tạo yêu cầu nạp ví. Ưu tiên ví chung (billing /v1/topups → MONA Pay); khi billing chưa nhận token
+     * hoặc merchant MONA Pay chưa cấu hình (401/403/404/502/503) thì tạo qua compute /api/payments/vietqr
+     * (ví local, prefix VIBECLOUD, báo có tự cộng). Người dùng chỉ quét QR; không cần console.
+     */
+    async topup(amount, idempotencyKey) {
+        const key = idempotencyKey || `mcp-topup-${randomUUID()}`;
+        try {
+            const central = asObject(unwrapData(await this.billing('/v1/topups', {
+                method: 'POST',
+                headers: { 'Idempotency-Key': key },
+                body: { amount_vnd: amount },
+            })));
+            return { amount_vnd: amount, ...central, wallet: 'central', source: '/v1/topups' };
+        }
+        catch (error) {
+            const status = error instanceof CloudError ? error.status ?? 0 : 0;
+            if (!(error instanceof CloudError) || ![401, 403, 404, 502, 503].includes(status))
+                throw error;
+            const local = asObject(unwrapData(await this.vibecloud('/api/payments/vietqr', {
+                method: 'POST',
+                body: { amount },
+            })));
+            return {
+                topup_id: local.payment_id,
+                order_ref: local.description,
+                amount_vnd: typeof local.amount === 'number' ? local.amount : amount,
+                status: local.status ?? 'pending',
+                qr_url: local.qr_url,
+                qr_data_url: local.qr_data_url,
+                wallet: 'local',
+                source: '/api/payments/vietqr',
+                fallback_reason: error.code,
+            };
+        }
+    }
+    /** Trạng thái một yêu cầu nạp (pending/paid) kèm số dư hiện tại, để AI chờ tiền vào rồi làm tiếp. */
+    async topupStatus(topupId) {
+        if (/^[0-9a-f]{24}$/i.test(topupId)) {
+            const root = asObject(unwrapData(await this.vibecloud(`/api/payments/${encodeURIComponent(topupId)}`)));
+            const payment = asObject(root.payment ?? root);
+            const status = typeof payment.status === 'string' ? payment.status : 'pending';
+            return {
+                topup_id: topupId,
+                status,
+                paid: status === 'paid',
+                amount_vnd: payment.amount,
+                order_ref: payment.description,
+                updated_at: payment.updated_at ?? payment.paid_at,
+                wallet: 'local',
+                balance: await this.localBalance(),
+            };
+        }
+        const ledger = await this.ledger(undefined, 100).catch(() => undefined);
+        const paid = ledger !== undefined && JSON.stringify(ledger).includes(topupId);
+        return {
+            topup_id: topupId,
+            status: paid ? 'paid' : 'pending',
+            paid,
+            wallet: 'central',
+            balance: await this.balance(),
+        };
     }
     budgetSet(body) {
         return this.billing('/v1/budgets', { method: 'POST', body });
@@ -125,7 +197,7 @@ export class CloudClients {
             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.`);
+            throw new CloudError('insufficient_funds', `Ví thiếu tiền: có ${balance} đ${requiredVnd === undefined ? '' : `, cần ${requiredVnd} đ`}.`, 'Gọi cloud_topup để lấy QR nạp ví in ngay trong terminal; người dùng quét xong thì gọi lại tool.');
         }
         return current;
     }

package/dist/compute.d.ts

@@ -1,7 +1,7 @@
 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 = "AI l\u00E0m 99%: cloud_app_detect(local_dir) offline \u2192 cloud_app_host_list, cloud_prices/cloud_packages/cloud_plan_list v\u00E0 cloud_balance \u2192 cloud_app_create(local_dir, sandbox=true) n\u1EBFu ch\u01B0a c\u00F3 app host \u0111\u1EC3 \u01B0\u1EDBc t\u00EDnh chi ph\u00ED gi\u1EDD/g\u00F3i \u2192 h\u1ECFi human m\u1ED9t l\u1EA7n duy\u1EC7t chi ph\u00ED n\u1EBFu ch\u01B0a \u0111\u01B0\u1EE3c duy\u1EC7t \u2192 cloud_app_create(local_dir, sandbox=false) \u2192 poll t\u1EDBi done/succeeded \u2192 ki\u1EC3m v\u00E0 tr\u1EA3 URL. C\u1EA7n DB/Supabase? cloud_base_create (beta) \u2014 chung account/v\u00ED MONA Cloud, kh\u1EDBp app deploy. N\u1EBFu human c\u00F3 domain: cloud_app_domain_add v\u00E0 h\u01B0\u1EDBng d\u1EABn CNAME t\u1EEB API. Human \u0111\u0103ng k\u00FD MONA Pass b\u1EB1ng device flow, n\u1EA1p ti\u1EC1n khi h\u1EBFt credit 20k; AI l\u00E0m c\u00E1c b\u01B0\u1EDBc c\u00F2n l\u1EA1i. App git cloud_app_create(repo_url) \u0111\u00E3 live; kh\u00F4ng g\u1ECDi agent_deploy cho deploy d\u1EF1 \u00E1n. / Detect locally, estimate, obtain cost approval once, upload and deploy, create an optional Base, return URL, then attach an optional domain.";
+export declare const APP_FLOW = "AI l\u00E0m 99%: cloud_app_detect(local_dir) offline \u2192 cloud_app_host_list, cloud_prices/cloud_packages/cloud_plan_list v\u00E0 cloud_balance \u2192 cloud_app_create(local_dir, sandbox=true) n\u1EBFu ch\u01B0a c\u00F3 app host \u0111\u1EC3 \u01B0\u1EDBc t\u00EDnh chi ph\u00ED gi\u1EDD/g\u00F3i \u2192 h\u1ECFi human m\u1ED9t l\u1EA7n duy\u1EC7t chi ph\u00ED n\u1EBFu ch\u01B0a \u0111\u01B0\u1EE3c duy\u1EC7t \u2192 cloud_app_create(local_dir, sandbox=false) \u2192 poll t\u1EDBi done/succeeded \u2192 ki\u1EC3m v\u00E0 tr\u1EA3 URL. C\u1EA7n DB/Supabase? cloud_base_create (beta) \u2014 chung account/v\u00ED MONA Cloud, kh\u1EDBp app deploy. N\u1EBFu human c\u00F3 domain: cloud_app_domain_add v\u00E0 h\u01B0\u1EDBng d\u1EABn CNAME t\u1EEB API. Human \u0111\u0103ng k\u00FD MONA Pass b\u1EB1ng device flow m\u1ED9t l\u1EA7n; h\u1EBFt credit 20k th\u00EC AI g\u1ECDi cloud_topup v\u00E0 in QR (qr_ascii) ngay trong terminal, human ch\u1EC9 qu\u00E9t b\u1EB1ng app ng\u00E2n h\u00E0ng, kh\u00F4ng m\u1EDF console; AI l\u00E0m c\u00E1c b\u01B0\u1EDBc c\u00F2n l\u1EA1i. App git cloud_app_create(repo_url) \u0111\u00E3 live; kh\u00F4ng g\u1ECDi agent_deploy cho deploy d\u1EF1 \u00E1n. / Detect locally, estimate, obtain cost approval once, upload and deploy, create an optional Base, return URL, then attach an optional domain.";
 export declare function rows(value: unknown, key: string): Row[];
 export declare function planEstimate(clients: CloudClients, code: string, cycle?: string): Promise<{
     plan: Row;

package/dist/compute.js

@@ -4,7 +4,7 @@ import { unwrapData } from './http.js';
 import { finishAppJob } from './jobs.js';
 import { detectProject } from './local.js';
 import { localAppTools } from './local-app.js';
-export const APP_FLOW = 'AI làm 99%: cloud_app_detect(local_dir) offline → cloud_app_host_list, cloud_prices/cloud_packages/cloud_plan_list và cloud_balance → cloud_app_create(local_dir, sandbox=true) nếu chưa có app host để ước tính chi phí giờ/gói → hỏi human một lần duyệt chi phí nếu chưa được duyệt → cloud_app_create(local_dir, sandbox=false) → poll tới done/succeeded → kiểm và trả URL. Cần DB/Supabase? cloud_base_create (beta) — chung account/ví MONA Cloud, khớp app deploy. Nếu human có domain: cloud_app_domain_add và hướng dẫn CNAME từ API. Human đăng ký MONA Pass bằng device flow, nạp tiền khi hết credit 20k; AI làm các bước còn lại. App git cloud_app_create(repo_url) đã live; không gọi agent_deploy cho deploy dự án. / Detect locally, estimate, obtain cost approval once, upload and deploy, create an optional Base, return URL, then attach an optional domain.';
+export const APP_FLOW = 'AI làm 99%: cloud_app_detect(local_dir) offline → cloud_app_host_list, cloud_prices/cloud_packages/cloud_plan_list và cloud_balance → cloud_app_create(local_dir, sandbox=true) nếu chưa có app host để ước tính chi phí giờ/gói → hỏi human một lần duyệt chi phí nếu chưa được duyệt → cloud_app_create(local_dir, sandbox=false) → poll tới done/succeeded → kiểm và trả URL. Cần DB/Supabase? cloud_base_create (beta) — chung account/ví MONA Cloud, khớp app deploy. Nếu human có domain: cloud_app_domain_add và hướng dẫn CNAME từ API. Human đăng ký MONA Pass bằng device flow một lần; hết credit 20k thì AI gọi cloud_topup và in QR (qr_ascii) ngay trong terminal, human chỉ quét bằng app ngân hàng, không mở console; AI làm các bước còn lại. App git cloud_app_create(repo_url) đã live; không gọi agent_deploy cho deploy dự án. / Detect locally, estimate, obtain cost approval once, upload and deploy, create an optional Base, return URL, then attach an optional domain.';
 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);

package/dist/qr.d.ts

@@ -0,0 +1,46 @@
+type JsonObject = Record<string, unknown>;
+export declare const BANK_BIN: Record<string, string>;
+/** CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF) theo chuẩn EMVCo, trả 4 ký tự hex hoa. */
+export declare function crc16(input: string): string;
+/**
+ * Nội dung chuyển khoản: bỏ dấu tiếng Việt, chỉ giữ chữ/số/khoảng trắng, tối đa 50 ký tự.
+ * Giống cách img.vietqr.io chuẩn hoá (VIBECLOUD-123 → VIBECLOUD123) để khớp regex báo có /VIBECLOUD\d+/ ở app-api.
+ */
+export declare function transferContent(value: string): string;
+export type VietQrParts = {
+    bin: string;
+    account: string;
+    amount?: number;
+    addInfo?: string;
+};
+/** Chuỗi VietQR EMVCo (NAPAS, dịch vụ QRIBFTTA = chuyển tới số tài khoản), có CRC16. */
+export declare function buildVietQrPayload(parts: VietQrParts): string;
+export type VietQrImage = {
+    bankCode: string;
+    bin?: string;
+    account: string;
+    amount?: number;
+    addInfo?: string;
+    accountName?: string;
+};
+/** Đọc link ảnh img.vietqr.io/image/<BANK|BIN>-<account>-<template>.png?amount=&addInfo=&accountName= */
+export declare function parseVietQrImageUrl(value: string | undefined): VietQrImage | undefined;
+/**
+ * QR bằng ký tự khối đầy '██' (1 module = 2 cột × 1 dòng, vùng lặng 2 module), in thẳng trong terminal.
+ * Chỉ dùng U+2588 nên mọi font monospace vẽ kín ô, không hở nét như nửa khối.
+ * darkTerminal=true (mặc định: nền tối, chữ sáng) vẽ module SÁNG bằng khối → QR đúng cực (đen trên trắng).
+ * darkTerminal=false (nền sáng, chữ đen) vẽ module TỐI bằng khối.
+ */
+export declare function renderQrAscii(payload: string, darkTerminal?: boolean): string;
+/** Bản nửa khối (▀▄█) gọn hơn, 2 hàng module / 1 dòng; tuỳ font terminal có thể hở nét. */
+export declare function renderQrAsciiSmall(payload: string): Promise<string>;
+export declare function renderQrPng(payload: string): Promise<Buffer>;
+export declare function dataUrlToBuffer(value: unknown): Buffer | undefined;
+export declare function saveQrFile(dir: string, name: string, buffer: Buffer): Promise<string>;
+/**
+ * Chuẩn hoá kết quả nạp ví để AI đưa cho người dùng: bỏ base64 khỏi text (tốn 15–25k token, CLI không vẽ),
+ * thêm qr_ascii (terminal nền tối) / qr_ascii_light (nền sáng) / qr_ascii_small (nửa khối), qr_file (PNG trên máy
+ * người dùng), giữ qr_url (ảnh VietQR) và các trường tiền/nội dung.
+ */
+export declare function presentTopup(topup: JsonObject, qrDir: string): Promise<JsonObject>;
+export {};

package/dist/qr.js

@@ -0,0 +1,208 @@
+// QR nạp ví hiện được ngay trong terminal (Claude Code / Codex / Gemini CLI).
+// Các CLI không vẽ ảnh PNG từ tool result, nên MCP tự dựng chuỗi VietQR EMVCo (NAPAS)
+// rồi in QR bằng ký tự khối; kèm file PNG + link ảnh để người dùng chọn cách quét.
+import QRCode from 'qrcode';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+// Mã ngân hàng (như img.vietqr.io dùng) → BIN NAPAS. Bổ sung khi MONA nhận tiền ở ngân hàng khác.
+export const BANK_BIN = {
+    ACB: '970416',
+    VCB: '970436', VIETCOMBANK: '970436',
+    TCB: '970407', TECHCOMBANK: '970407',
+    MB: '970422', MBB: '970422', MBBANK: '970422',
+    BIDV: '970418',
+    VPB: '970432', VPBANK: '970432',
+    TPB: '970423', TPBANK: '970423',
+    VIB: '970441',
+    STB: '970403', SACOMBANK: '970403',
+    CTG: '970415', ICB: '970415', VIETINBANK: '970415',
+    VBA: '970405', AGRIBANK: '970405',
+    MSB: '970426',
+    SHB: '970443',
+    HDB: '970437', HDBANK: '970437',
+    OCB: '970448',
+    EIB: '970431', EXIMBANK: '970431',
+    LPB: '970449', LPBANK: '970449',
+    SEAB: '970440', SEABANK: '970440',
+    NAB: '970428', NAMABANK: '970428',
+    BAB: '970409', BACABANK: '970409',
+    NCB: '970419',
+    ABB: '970425', ABBANK: '970425',
+    PVCB: '970412', PVCOMBANK: '970412',
+    VAB: '970427', VIETABANK: '970427',
+    KLB: '970452', KIENLONGBANK: '970452',
+    PGB: '970430', PGBANK: '970430',
+    BVB: '970438', BAOVIETBANK: '970438',
+    VCCB: '970454', BVBANK: '970454',
+    CAKE: '546034',
+    TIMO: '963388',
+};
+const tlv = (id, value) => `${id}${String(value.length).padStart(2, '0')}${value}`;
+/** CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF) theo chuẩn EMVCo, trả 4 ký tự hex hoa. */
+export function crc16(input) {
+    let crc = 0xffff;
+    for (const byte of Buffer.from(input, 'utf8')) {
+        crc ^= byte << 8;
+        for (let bit = 0; bit < 8; bit += 1) {
+            crc = crc & 0x8000 ? ((crc << 1) ^ 0x1021) & 0xffff : (crc << 1) & 0xffff;
+        }
+    }
+    return crc.toString(16).toUpperCase().padStart(4, '0');
+}
+/**
+ * Nội dung chuyển khoản: bỏ dấu tiếng Việt, chỉ giữ chữ/số/khoảng trắng, tối đa 50 ký tự.
+ * Giống cách img.vietqr.io chuẩn hoá (VIBECLOUD-123 → VIBECLOUD123) để khớp regex báo có /VIBECLOUD\d+/ ở app-api.
+ */
+export function transferContent(value) {
+    return value
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/đ/g, 'd')
+        .replace(/Đ/g, 'D')
+        .replace(/[^A-Za-z0-9 ]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 50);
+}
+/** Chuỗi VietQR EMVCo (NAPAS, dịch vụ QRIBFTTA = chuyển tới số tài khoản), có CRC16. */
+export function buildVietQrPayload(parts) {
+    if (!/^\d{6}$/.test(parts.bin))
+        throw new Error(`BIN ngân hàng không hợp lệ: ${parts.bin}`);
+    if (!/^[A-Za-z0-9]{1,19}$/.test(parts.account))
+        throw new Error(`Số tài khoản không hợp lệ: ${parts.account}`);
+    const amount = parts.amount !== undefined ? Math.round(parts.amount) : undefined;
+    const merchant = tlv('00', 'A000000727') + tlv('01', tlv('00', parts.bin) + tlv('01', parts.account)) + tlv('02', 'QRIBFTTA');
+    let payload = tlv('00', '01') + tlv('01', amount ? '12' : '11') + tlv('38', merchant) + tlv('53', '704');
+    if (amount && amount > 0)
+        payload += tlv('54', String(amount));
+    payload += tlv('58', 'VN');
+    const content = parts.addInfo ? transferContent(parts.addInfo) : '';
+    if (content)
+        payload += tlv('62', tlv('08', content));
+    payload += '6304';
+    return payload + crc16(payload);
+}
+/** Đọc link ảnh img.vietqr.io/image/<BANK|BIN>-<account>-<template>.png?amount=&addInfo=&accountName= */
+export function parseVietQrImageUrl(value) {
+    if (!value)
+        return undefined;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+    const match = /\/image\/([A-Za-z0-9]+)-([A-Za-z0-9]+)-[A-Za-z0-9_]+\.(?:png|jpe?g)$/i.exec(url.pathname);
+    if (!match)
+        return undefined;
+    const bankCode = match[1].toUpperCase();
+    const bin = /^\d{6}$/.test(bankCode) ? bankCode : BANK_BIN[bankCode];
+    const amountRaw = url.searchParams.get('amount');
+    const amount = amountRaw && /^\d+$/.test(amountRaw) ? Number(amountRaw) : undefined;
+    return {
+        bankCode,
+        ...(bin ? { bin } : {}),
+        account: match[2],
+        ...(amount !== undefined ? { amount } : {}),
+        ...(url.searchParams.get('addInfo') ? { addInfo: url.searchParams.get('addInfo') } : {}),
+        ...(url.searchParams.get('accountName') ? { accountName: url.searchParams.get('accountName') } : {}),
+    };
+}
+/**
+ * QR bằng ký tự khối đầy '██' (1 module = 2 cột × 1 dòng, vùng lặng 2 module), in thẳng trong terminal.
+ * Chỉ dùng U+2588 nên mọi font monospace vẽ kín ô, không hở nét như nửa khối.
+ * darkTerminal=true (mặc định: nền tối, chữ sáng) vẽ module SÁNG bằng khối → QR đúng cực (đen trên trắng).
+ * darkTerminal=false (nền sáng, chữ đen) vẽ module TỐI bằng khối.
+ */
+export function renderQrAscii(payload, darkTerminal = true) {
+    const code = QRCode.create(payload, { errorCorrectionLevel: 'M' });
+    const size = code.modules.size;
+    const data = code.modules.data;
+    const quiet = 2;
+    const block = '██';
+    const blank = '  ';
+    const fill = (dark) => (dark === darkTerminal ? blank : block);
+    const width = size + quiet * 2;
+    const edge = fill(false).repeat(width);
+    const lines = [];
+    for (let i = 0; i < quiet; i += 1)
+        lines.push(edge);
+    for (let row = 0; row < size; row += 1) {
+        let line = fill(false).repeat(quiet);
+        for (let col = 0; col < size; col += 1)
+            line += fill(Boolean(data[row * size + col]));
+        lines.push(line + fill(false).repeat(quiet));
+    }
+    for (let i = 0; i < quiet; i += 1)
+        lines.push(edge);
+    return lines.join('\n');
+}
+/** Bản nửa khối (▀▄█) gọn hơn, 2 hàng module / 1 dòng; tuỳ font terminal có thể hở nét. */
+export function renderQrAsciiSmall(payload) {
+    // qrcode 1.5.x: renderer utf8 lỗi 'Invalid array length' khi truyền margin → dùng mặc định.
+    return QRCode.toString(payload, { type: 'utf8' });
+}
+export function renderQrPng(payload) {
+    return QRCode.toBuffer(payload, { type: 'png', errorCorrectionLevel: 'M', margin: 2, scale: 8 });
+}
+export function dataUrlToBuffer(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const match = /^data:image\/(?:png|jpe?g);base64,([A-Za-z0-9+/=\s]+)$/i.exec(value);
+    if (!match)
+        return undefined;
+    const buffer = Buffer.from(match[1].replace(/\s+/g, ''), 'base64');
+    return buffer.length ? buffer : undefined;
+}
+export async function saveQrFile(dir, name, buffer) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const file = join(dir, name);
+    await writeFile(file, buffer, { mode: 0o600 });
+    return file;
+}
+const safeName = (value) => value.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64) || 'topup';
+/**
+ * Chuẩn hoá kết quả nạp ví để AI đưa cho người dùng: bỏ base64 khỏi text (tốn 15–25k token, CLI không vẽ),
+ * thêm qr_ascii (terminal nền tối) / qr_ascii_light (nền sáng) / qr_ascii_small (nửa khối), qr_file (PNG trên máy
+ * người dùng), giữ qr_url (ảnh VietQR) và các trường tiền/nội dung.
+ */
+export async function presentTopup(topup, qrDir) {
+    const { qr_data_url: qrDataUrl, ...rest } = topup;
+    const orderRef = typeof rest.order_ref === 'string' ? rest.order_ref : typeof rest.topup_id === 'string' ? rest.topup_id : 'topup';
+    const image = parseVietQrImageUrl(typeof rest.qr_url === 'string' ? rest.qr_url : undefined);
+    const amount = typeof rest.amount_vnd === 'number' ? rest.amount_vnd : image?.amount;
+    const result = {
+        ...rest,
+        ...(amount !== undefined ? { amount_vnd: amount } : {}),
+    };
+    let payload;
+    if (image?.bin) {
+        try {
+            payload = buildVietQrPayload({ bin: image.bin, account: image.account, amount, addInfo: image.addInfo ?? orderRef });
+            result.bank = image.bankCode;
+            result.bank_bin = image.bin;
+            result.bank_account = image.account;
+            if (image.accountName)
+                result.bank_account_name = image.accountName;
+            result.transfer_content = transferContent(image.addInfo ?? orderRef);
+            result.qr_payload = payload;
+            result.qr_ascii = renderQrAscii(payload, true);
+            result.qr_ascii_light = renderQrAscii(payload, false);
+            result.qr_ascii_small = await renderQrAsciiSmall(payload);
+        }
+        catch (error) {
+            result.qr_ascii_error = error instanceof Error ? error.message : String(error);
+        }
+    }
+    const png = dataUrlToBuffer(qrDataUrl) ?? (payload ? await renderQrPng(payload) : undefined);
+    if (png) {
+        try {
+            result.qr_file = await saveQrFile(qrDir, `topup-${safeName(orderRef)}.png`, png);
+        }
+        catch (error) {
+            result.qr_file_error = error instanceof Error ? error.message : String(error);
+        }
+    }
+    return result;
+}

package/dist/server.js

@@ -11,6 +11,7 @@ import { registerMailTools } from './mail.js';
 import { APP_FLOW, createVps, registerComputeTools } from './compute.js';
 import { pollJob } from './jobs.js';
 import { registerBaseTools } from './base.js';
+import { presentTopup } from './qr.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. Base beta thay Supabase bằng cloud_base_*, chung account/ví MONA Cloud và khớp app deploy. 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);
@@ -91,7 +92,9 @@ 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.5.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}` });
+    const server = new McpServer({ name: 'monacloud-mcp', version: '0.8.1' }, 
+    // Codex chỉ chắc chắn đọc 512 ký tự đầu của instructions → luật quan trọng nhất đặt trước, mô tả hệ đặt sau.
+    { instructions: `Ví thiếu tiền: AI tự gọi cloud_topup, in nguyên khối qr_ascii (QR VietQR) cho người dùng quét bằng app ngân hàng ngay trong terminal, rồi cloud_topup_status tới khi paid; không bảo người dùng mở console để nạp. Dù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 chờ người dùng ở: quét QR nạp, duyệt chi phí, thêm DNS, OTP hoặc KYC.\n${ENTITY}\n${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.',
@@ -109,16 +112,23 @@ export function createServer(dependencies = {}) {
         },
     }, ({ cursor, limit }) => runTool(() => clients.ledger(cursor, limit)));
     server.registerTool('cloud_topup', {
-        title: 'Nạp ví bằng VietQR',
-        description: 'Tạo yêu cầu nạp ví và trả VietQR; đây là bước con người thanh toán hợp lệ.',
+        title: 'Nạp ví bằng VietQR ngay trong terminal',
+        description: 'AI tự tạo yêu cầu nạp ví và nhận QR VietQR: qr_ascii (khối đầy, in thẳng trong Claude Code/Codex/Gemini; nền sáng dùng qr_ascii_light), qr_file (PNG trên máy), qr_url (ảnh). Người dùng chỉ quét bằng app ngân hàng, không cần mở console. Tiền vào tự cộng ví; xác nhận bằng cloud_topup_status.',
         inputSchema: {
-            amount: z.number().int().min(1_000).max(1_000_000_000).describe('Số tiền nguyên VND'),
+            amount: z.number().int().min(10_000).max(500_000_000).describe('Số tiền nguyên VND, tối thiểu 10.000'),
             idempotency_key: z.string().min(1).max(255).optional(),
         },
     }, ({ amount, idempotency_key }) => runTool(async () => ({
-        ...asObject(await clients.topup(amount, idempotency_key)),
-        instructions: 'Mở app ngân hàng, quét qr_data_url và chuyển đúng số tiền/nội dung. Sau khi tiền vào, gọi cloud_balance.',
+        ...(await presentTopup(asObject(await clients.topup(amount, idempotency_key)), config.configDir)),
+        instructions: 'In NGUYÊN khối qr_ascii cho người dùng (terminal nền tối, mặc định; terminal nền sáng in qr_ascii_light; giữ nguyên ký tự, mỗi dòng một hàng, không bọc lại) kèm ngân hàng, số tài khoản, số tiền và nội dung chuyển khoản. Người dùng mở app ngân hàng quét QR trên màn hình; nếu terminal hiển thị mờ thì mở qr_file hoặc qr_url. Chuyển ĐÚNG số tiền và nội dung. Sau khi người dùng báo đã chuyển, gọi cloud_topup_status(topup_id) tới khi paid rồi làm tiếp; không tạo lại yêu cầu nạp khi chưa thấy tiền vào.',
     })));
+    server.registerTool('cloud_topup_status', {
+        title: 'Trạng thái yêu cầu nạp ví',
+        description: 'Đọc trạng thái một yêu cầu nạp (pending/paid) sau khi người dùng quét QR, kèm số dư hiện tại. Dùng để chờ tiền vào rồi tiếp tục việc đang làm.',
+        inputSchema: {
+            topup_id: z.string().min(1).max(128).describe('topup_id do cloud_topup trả'),
+        },
+    }, ({ topup_id }) => runTool(() => clients.topupStatus(topup_id)));
     server.registerTool('cloud_usage', {
         title: 'Chi phí MONA Cloud theo kỳ',
         description: 'Đọc usage và tổng tiền theo tháng, có thể lọc sản phẩm.',
@@ -181,7 +191,7 @@ export function createServer(dependencies = {}) {
     }, ({ spend_limit_vnd, period, token_id }) => runTool(() => clients.tokenLimit(spend_limit_vnd, period, token_id)));
     server.registerTool('cloud_open_console', {
         title: 'Mở MONA Cloud Console',
-        description: 'Trả URL console chung để nạp ví, đổi budget hoặc quản lý tài khoản.',
+        description: 'Trả URL console khi người dùng muốn tự xem hoá đơn hoặc quản lý tài khoản. Nạp ví KHÔNG cần console: dùng cloud_topup (QR in trong terminal).',
     }, () => textResult({ url: config.consoleUrl, next_step: `Mở ${config.consoleUrl} trong trình duyệt.` }));
     server.registerTool('monapay_link', {
         title: 'Liên kết MONA Pay chuyển tiếp',
@@ -349,7 +359,7 @@ export function createServer(dependencies = {}) {
     }, async (uri) => ({ contents: [{
                 uri: uri.href,
                 mimeType: 'text/plain',
-                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, Base beta thay Supabase, job, vòng đời service, plans, subscriptions, invoices/PDF, credit và apps từ git hoặc thư mục local (source=upload); cần DB/Supabase thì dùng cloud_base_create — chung account, khớp app deploy; cloud_app_detect hoàn toàn offline.\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`,
+                text: `${ENTITY}\n\n${APP_FLOW}\n\nHuman đă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 bằng cloud_topup (in ngay trong terminal, không mở console) 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, Base beta thay Supabase, job, vòng đời service, plans, subscriptions, invoices/PDF, credit và apps từ git hoặc thư mục local (source=upload); cần DB/Supabase thì dùng cloud_base_create — chung account, khớp app deploy; cloud_app_detect hoàn toàn offline.\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',
@@ -376,7 +386,7 @@ 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. ${APP_FLOW}\nTheo đú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. Cần DB/Supabase thì ưu tiên cloud_base_create (beta) — chung account, khớp app deploy. Nếu deploy dự án dùng cloud_app_detect(local_dir), cloud_app_host_list rồi cloud_app_create(local_dir), 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 dự án local, dùng cloud_app_create(local_dir) sau khi duyệt ước tính; git dùng repo_url; 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.`,
+                    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. ${APP_FLOW}\nTheo đú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, in nguyên khối qr_ascii kèm số tiền/nội dung để người dùng quét bằng app ngân hàng, rồi cloud_topup_status tới khi paid; không bảo người dùng mở console.\n2. Nếu dùng VPS gọi cloud_vps_create và cloud_db_create. Cần DB/Supabase thì ưu tiên cloud_base_create (beta) — chung account, khớp app deploy. Nếu deploy dự án dùng cloud_app_detect(local_dir), cloud_app_host_list rồi cloud_app_create(local_dir), 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 dự án local, dùng cloud_app_create(local_dir) sau khi duyệt ước tính; git dùng repo_url; 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; nạp tiền cũng qua cloud_topup, người dùng chỉ quét QR và nhập OTP bắt buộc.`,
                 },
             }] }));
     server.registerPrompt('gui-mail-otp-monamail', {
@@ -399,7 +409,7 @@ export function createServer(dependencies = {}) {
 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.`,
+Chỉ dừng hỏi người dùng ở bước thêm DNS hoặc nạp tiền (quét QR). Nếu mail_plan_set trả insufficient_funds, gọi cloud_topup, in nguyên khối qr_ascii để người dùng quét bằng app ngân hàng, rồi cloud_topup_status tới khi paid 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/dist/templates.js

@@ -5,7 +5,7 @@ import { requestJson } from './http.js';
 const BUILTIN = [
     { slug: 'cskh-zalo', name: 'CSKH Zalo', description: 'Trả lời khách từ tài liệu shop và chuyển ca khó cho người.', products: ['MONA AI', 'MONA Base', 'Zalo ZNS'] },
     { slug: 'sales-chot-don', name: 'Sales chốt đơn', description: 'Tư vấn, báo giá, tạo QR MONA Pay và xác nhận tiền vào.', products: ['MONA Pay', 'MONA AI'] },
-    { slug: 'ke-toan-hddt', name: 'Kế toán HĐĐT', description: 'Đọc tiền vào, phát hành hoá đơn điện tử và nhắc công nợ.', products: ['MONA Pay', 'monahddt', 'MONA Mail'] },
+    { slug: 'ke-toan-hddt', name: 'Kế toán HĐĐT', description: 'Đọc tiền vào, phát hành hoá đơn điện tử và nhắc công nợ.', products: ['MONA Pay', 'MONA eInvoice', 'MONA Mail'] },
     { slug: 'content-seo', name: 'Content SEO', description: 'Viết và đăng bài theo voice thương hiệu, có gate QC.', products: ['MONA AI'] },
     { slug: 'noi-bo-kin', name: 'Nội bộ kín', description: 'Trợ lý đọc tài liệu công ty, dữ liệu không rời server.', products: ['MONA Cloud', 'MONA Base', 'Ollama'] },
     { slug: 'tro-giang-academy', name: 'Trợ giảng Academy', description: 'Trợ giảng cho academy của giảng viên.', products: ['mona.academy', 'MONA AI'] },

package/docs/ai-agent.md

@@ -13,13 +13,13 @@ Prompt Claude Code: **“Đưa dự án này lên MONA Cloud, dùng thư mục h
 5. Sửa code local: `cloud_app_deploy({app_id, local_dir})`. Chỉ đổi env: `cloud_app_env_set` với map đầy đủ rồi `cloud_app_deploy({app_id})`. Timeout giữ job_id/app_id để tiếp tục, không tạo app mới.
 6. Cần DB/Supabase thì gọi `cloud_base_create` (beta): sandbox để lấy ước tính, duyệt chi phí rồi tạo thật. Base dùng chung account/ví MONA Cloud và khớp app deploy. Lưu credential vào secret store hoặc `.env` không commit; không log `anon_key`, `service_key`, `db_url`.
 
-Human chỉ cần đăng ký MONA Pass/device flow, duyệt chi phí một lần và nạp tiền khi hết credit 20k; DNS là bước thêm khi dùng domain riêng. AI làm các bước kỹ thuật còn lại. `.env*` kể cả `.env.example` không vào ZIP; truyền secret cần thiết qua `env`, không công khai. Xem [hợp đồng local deploy](local-deploy.md). VPS/database thủ công dưới đây chỉ dùng khi dự án cần hoặc người dùng chọn.
+Human chỉ cần đăng ký MONA Pass/device flow một lần, duyệt chi phí một lần và quét QR nạp ví do AI tạo (`cloud_topup`) khi hết credit 20k; DNS là bước thêm khi dùng domain riêng. AI làm các bước kỹ thuật còn lại. `.env*` kể cả `.env.example` không vào ZIP; truyền secret cần thiết qua `env`, không công khai. Xem [hợp đồng local deploy](local-deploy.md). VPS/database thủ công dưới đây chỉ dùng khi dự án cần hoặc người dùng chọn.
 
 ## Quy tắc vận hành
 
 1. Bắt đầu bằng `cloud_whoami`. Nếu nhận `login_required`, yêu cầu người dùng chạy `monacloud-mcp login`; không hỏi username hoặc password trong chat.
 2. Trước khi provision thật, đọc `cloud_balance`, `cloud_plan_list` hoặc `cloud_packages`/`cloud_prices`; báo ước tính và hỏi duyệt chi phí nếu chưa được duyệt. Với `sandbox: true`, không cần đọc hoặc nạp ví.
-3. Khi cần nạp, gọi `cloud_topup`; đưa nguyên `qr_data_url`, số tiền, nội dung và hạn thanh toán cho người dùng. Chỉ tiếp tục sau khi `cloud_balance` phản ánh tiền vào.
+3. Khi cần nạp, gọi `cloud_topup`; in NGUYÊN khối `qr_ascii` (không bọc lại) kèm ngân hàng, số tài khoản, số tiền, nội dung chuyển khoản; nhắc `qr_file`/`qr_url` nếu terminal hiển thị mờ. Không bảo người dùng mở console. Chỉ tiếp tục sau khi `cloud_topup_status` trả `paid` hoặc `cloud_balance` phản ánh tiền vào.
 4. Với OTP ngân hàng, dừng đúng sau `monapay_link_bank_start` và `monapay_notification_register`. Hỏi người dùng mã vừa nhận; không suy đoán, brute-force hoặc ghi OTP vào source/log.
 5. Mọi endpoint webhook phải xác minh HMAC, chống replay theo timestamp và idempotent theo `transaction_code`.
 6. Không giao hàng chỉ dựa vào browser redirect. Chỉ xác nhận đơn sau webhook `CHECKOUT_PAID` hoặc đối soát server-side.
@@ -175,7 +175,7 @@ const { id } = await monamail.emails.send({
 
 `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`.
+Ranh giới human của luồng Mail sau đăng nhập là **thêm DNS và quét QR nạp tiền**. Khi `mail_plan_set` trả `insufficient_funds`, gọi `cloud_topup`, in `qr_ascii` cho user quét và chờ `cloud_topup_status` paid hoặc `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
 
@@ -192,7 +192,7 @@ Ranh giới human của luồng Mail sau đăng nhập là **thêm DNS và nạp
 {
   "code": "insufficient_funds",
   "message": "Ví thiếu tiền...",
-  "next_step": "Nạp ví tại https://monacloud.vn/console rồi gọi lại tool."
+  "next_step": "Gọi cloud_topup để lấy QR nạp ví rồi gọi lại tool."
 }
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "monacloud-mcp",
-  "version": "0.7.0",
-  "description": "MCP server for MONA Cloud \u2014 deploy apps (Vercel alternative), Supabase-compatible Postgres/Auth/Storage bases (Supabase alternative), VND wallet, MONA Pay & Mail \u2014 for AI agents (Claude, Cursor, Codex) in Vietnam.",
+  "version": "0.8.1",
+  "description": "MCP server for MONA Cloud — deploy apps (Vercel alternative), Supabase-compatible Postgres/Auth/Storage bases (Supabase alternative), VND wallet, MONA Pay & Mail — for AI agents (Claude, Cursor, Codex) in Vietnam.",
   "license": "MIT",
   "homepage": "https://monacloud.vn",
   "repository": {
@@ -52,10 +52,12 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "monapay-mcp": "^0.5.5",
+    "qrcode": "^1.5.4",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",
+    "@types/qrcode": "^1.5.6",
     "typescript": "^7.0.2"
   }
 }