monacloud-mcp 0.2.0 → 0.2.1

package/README.md

@@ -99,7 +99,21 @@ Các tên cũ như `monapay_create_qr`, `monapay_link_bank_start`, `monapay_crea
 | `cloud_prices` / `cloud_packages` | Đơn giá và gói cấu hình |
 | `cloud_agent_deploy` | Stub có cấu trúc cho runtime MONA Agent wave sau |
 
-`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 đọc `GET /v1/balance` trước khi gọi compute MONA Cloud.
+`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.
+
+## 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.
+
+Ở chế độ này MCP bỏ qua `GET /v1/balance`, tự gửi `X-Vibecloud-Sandbox: 1` đến compute API và bảo đảm response có `sandbox: true`. Ví dụ:
+
+```text
+cloud_vps_create({ app_name: "shop-demo", package_slug: "standard-2", sandbox: true })
+cloud_job_status({ job_id: "...", sandbox: true })
+cloud_services_list({ sandbox: true })
+```
+
+`cloud_job_status` tự tìm job sandbox theo ID mà không cần header. `cloud_services_list({ sandbox: true })` dùng khả năng `include_sandbox` của API để gộp service thật và sandbox. Sandbox không tạo hạ tầng thật, không trừ tiền và có thể bị dọn theo TTL của compute API. `cloud_agent_deploy` vẫn là stub cho đến khi runtime MONA Agent được phát hành, nhưng response sandbox được đánh dấu nhất quán.
 
 ### MONA Agent
 
@@ -115,7 +129,7 @@ Các tên cũ như `monapay_create_qr`, `monapay_link_bank_start`, `monapay_crea
 
 ## Spend guard và lỗi cho AI
 
-Trước lệnh compute MONA Cloud có thể phát sinh tiền, MCP đọc ví chung. HTTP `402 insufficient_funds` và `402 budget_exceeded` được chuẩn hoá thành text JSON:
+Trước lệnh compute MONA Cloud thật có thể phát sinh tiền, MCP đọc ví chung. Sandbox bỏ qua bước này vì chi phí 0đ. HTTP `402 insufficient_funds` và `402 budget_exceeded` được chuẩn hoá thành text JSON:
 
 ```json
 {
@@ -156,6 +170,7 @@ Chi tiết dành riêng cho agent: [`docs/ai-agent.md`](docs/ai-agent.md).
 | `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 |
+| `MONACLOUD_SANDBOX` | — | Đặt `1` để mọi lệnh compute hỗ trợ sandbox chạy thử 0đ, không cần ví |
 | `MONACLOUD_CONFIG_DIR` | `~/.config/monacloud` | Token và link cache |
 | `MONACLOUD_TEMPLATES_DIR` | `~/monacloud/templates` | Catalog agent local |
 | `MONACLOUD_TEMPLATES_URL` | — | Catalog JSON từ xa, chỉ dùng khi local không có |

package/STATUS.md

@@ -1,17 +1,17 @@
-# STATUS — monacloud-mcp 0.2.0
+# STATUS — monacloud-mcp 0.2.1
 
 Updated: 2026-09-04 (Asia/Ho_Chi_Minh)
 
 ## Hoàn thành
 
-- [x] Package Node 20 + TypeScript, ESM, stdio MCP; bin `monacloud-mcp`, version `0.2.0`.
+- [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`.
 - [x] 10 tool `cloud_*`: identity, balance, ledger, topup VietQR, usage, services aggregation, budget, token limit và console URL.
 - [x] Import package `monapay-mcp` và re-export toàn bộ tool, không copy code. Dependency offline tại lần verify cuối là 0.5.5/47 tool (superset 24 tool yêu cầu); cộng `monapay_link` chuyển tiếp.
 - [x] 11 tool compute tên mới `cloud_*`: link, VPS, database, job poll, list, start/stop/rebuild, prices, packages và agent-deploy stub.
 - [x] 11 alias kỹ thuật `vibecloud_*` vẫn gọi được cho client cũ, không xuất hiện trong README/hướng dẫn agent.
 - [x] 3 tool `agent_*`: list/get catalog local/remote/built-in và deploy qua cùng stub MONA Cloud.
-- [x] Spend guard đọc billing balance trước create/start/rebuild; chuẩn hoá `402 insufficient_funds|budget_exceeded` thành `{code,message,next_step,request_id?}`. Stop luôn được phép.
+- [x] Spend guard đọc billing balance trước create/start/rebuild thật; `sandbox: true` hoặc `MONACLOUD_SANDBOX=1` bỏ qua Billing, gửi header compute và đánh dấu response. Stop luôn được phép.
 - [x] 2 resource đúng brief: `monacloud://llms`, `monacloud://status`.
 - [x] 1 prompt `dung-app-ban-hang-monacloud`: VPS → DB → VA/QR → webhook → deploy.
 - [x] Không log token; token và linked credential được lưu bằng atomic write, directory `0700`, file `0600`.
@@ -28,7 +28,7 @@ $ node_modules/.bin/tsc -p tsconfig.json
 exit 0, không có diagnostic
 
 $ node --test
-tests 9, pass 9, fail 0
+tests 13, pass 13, fail 0
 ```
 
 Không chạy `npm install`; toàn bộ build/test dùng `node_modules` có sẵn và không gọi Internet.
@@ -47,7 +47,7 @@ CODEX DONE
 
 - Tên người đọc và 11 tool chính đã chuyển sang MONA Cloud / `cloud_*`; VibeCloud chỉ còn trong alias và định danh kỹ thuật tương thích.
 - Resource `monacloud://llms`, prompt dựng app, README và `docs/ai-agent.md` chỉ hướng dẫn tên mới.
-- Package, MCP server và binary version đồng bộ `0.2.0`; build và test được ghi ở gate mới bên trên.
+- Package, MCP server và binary version đồng bộ `0.2.1`; build và test được ghi ở gate mới bên trên.
 
 ## QC Claude (03/09 tối) — ZERO-DASHBOARD TEST LOCAL: PASS
 - Build tsc sạch · `node --test` 7/7 · stdio thật: **72 tool** (cloud 10 · monapay 48 · vibecloud 11 · agent 3), 2 resource, 1 prompt.

package/dist/clients.d.ts

@@ -20,11 +20,18 @@ export declare class CloudClients {
     budgetGet(): Promise<unknown>;
     tokenLimit(spendLimitVnd: number, period: string, tokenId?: string): Promise<unknown>;
     spendGuard(): Promise<JsonObject>;
+    sandboxEnabled(requested?: boolean): boolean;
     private vibecloudToken;
     vibecloud<T = unknown>(path: string, options?: {
         method?: string;
         body?: unknown;
+        query?: Record<string, string | number | undefined>;
+        headers?: Record<string, string>;
     }): Promise<T>;
+    guardedVibecloud(path: string, options?: {
+        method?: string;
+        body?: unknown;
+    }, requestedSandbox?: boolean): Promise<unknown>;
     vibecloudLink(): Promise<JsonObject>;
     monapayLink(): Promise<JsonObject>;
     prices(): Promise<unknown>;

package/dist/clients.js

@@ -69,6 +69,9 @@ export class CloudClients {
         }
         return current;
     }
+    sandboxEnabled(requested = false) {
+        return requested || this.auth.env.MONACLOUD_SANDBOX === '1';
+    }
     async vibecloudToken() {
         if (this.auth.env.VIBECLOUD_API_TOKEN)
             return this.auth.env.VIBECLOUD_API_TOKEN;
@@ -86,6 +89,16 @@ export class CloudClients {
             fetchImpl: this.fetchImpl,
         });
     }
+    async guardedVibecloud(path, options = {}, requestedSandbox = false) {
+        const sandbox = this.sandboxEnabled(requestedSandbox);
+        if (!sandbox)
+            await this.spendGuard();
+        const result = await this.vibecloud(path, {
+            ...options,
+            ...(sandbox ? { headers: { 'X-Vibecloud-Sandbox': '1' } } : {}),
+        });
+        return sandbox ? { ...asObject(result), sandbox: true } : result;
+    }
     async vibecloudLink() {
         if (this.auth.env.VIBECLOUD_API_TOKEN) {
             return { linked: true, product: 'vibecloud', mode: 'legacy_env', next_step: 'Dùng các tool cloud_*.' };

package/dist/index.js

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

package/dist/server.js

@@ -9,7 +9,9 @@ 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(['succeeded', 'failed', 'cancelled']);
+const TERMINAL_JOBS = new Set(['done', 'succeeded', 'failed', 'cancelled']);
+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 : {});
 function collection(value) {
     const data = unwrapData(value);
@@ -29,6 +31,7 @@ const sizingSchema = {
     cpu: z.number().int().min(1).max(16).optional(),
     ram_gb: z.number().int().min(1).max(64).optional(),
     disk_gb: z.number().int().min(10).max(1000).optional(),
+    sandbox: sandboxSchema,
 };
 const provisionSchema = z.object(sizingSchema).superRefine((value, context) => {
     const dimensions = [value.cpu, value.ram_gb, value.disk_gb];
@@ -41,28 +44,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.' });
     }
 });
-function agentRuntimeStub(template) {
+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.',
+        ...(sandbox ? { sandbox: true } : {}),
     };
 }
-async function pollJob(clients, jobId, wait, intervalSeconds, timeoutSeconds) {
+async function pollJob(clients, jobId, wait, intervalSeconds, timeoutSeconds, sandbox) {
     let result = await clients.vibecloud(`/api/jobs/${encodeURIComponent(jobId)}`);
     if (!wait)
-        return result;
+        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), polling: 'timeout', next_step: `Gọi lại cloud_job_status với job_id=${jobId}.` };
+        return {
+            ...asObject(result),
+            ...(sandbox ? { sandbox: true } : {}),
+            polling: 'timeout',
+            next_step: `Gọi lại cloud_job_status với job_id=${jobId}.`,
+        };
     }
-    return result;
+    return sandbox ? { ...asObject(result), sandbox: true } : result;
 }
 async function providerHealth(name, url, fetchImpl) {
     const started = Date.now();
@@ -81,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.0' }, { 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.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.` });
     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.',
@@ -187,82 +196,91 @@ 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.',
+        description: `Kiểm tra ví chung rồi tạo LXC VPS; trả job_id để poll. ${SANDBOX_DESCRIPTION}.`,
         inputSchema: provisionSchema,
     }, (body) => runTool(async () => {
-        await clients.spendGuard();
-        return clients.vibecloud('/api/lxc', { method: 'POST', body });
+        const { sandbox, ...payload } = body;
+        return clients.guardedVibecloud('/api/lxc', { method: 'POST', body: payload }, sandbox);
     }));
     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.',
+        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 () => {
-        await clients.spendGuard();
-        return clients.vibecloud('/api/lxc', { method: 'POST', body });
+        const { sandbox, ...payload } = body;
+        return clients.guardedVibecloud('/api/lxc', { method: 'POST', body: payload }, sandbox);
     }));
     const databaseSchema = provisionSchema.extend({ engine: z.enum(['mongodb', 'postgresql', 'mysql']).default('mongodb') });
     server.registerTool('cloud_db_create', {
         title: 'Tạo database MONA Cloud',
-        description: 'Kiểm tra ví chung rồi tạo MongoDB/PostgreSQL/MySQL; trả job_id để poll.',
+        description: `Kiểm tra ví chung rồi tạo MongoDB/PostgreSQL/MySQL; trả job_id để poll. ${SANDBOX_DESCRIPTION}.`,
         inputSchema: databaseSchema,
     }, (body) => runTool(async () => {
-        await clients.spendGuard();
-        return clients.vibecloud('/api/databases', { method: 'POST', body });
+        const { sandbox, ...payload } = body;
+        return clients.guardedVibecloud('/api/databases', { method: 'POST', body: payload }, sandbox);
     }));
     server.registerTool('vibecloud_create_database', {
         title: 'Alias cũ của cloud_db_create',
-        description: 'Alias tương thích; dùng cloud_db_create cho tích hợp mới.',
+        description: `Alias tương thích; dùng cloud_db_create cho tích hợp mới. ${SANDBOX_DESCRIPTION}.`,
         inputSchema: databaseSchema,
     }, (body) => runTool(async () => {
-        await clients.spendGuard();
-        return clients.vibecloud('/api/databases', { method: 'POST', body });
+        const { sandbox, ...payload } = body;
+        return clients.guardedVibecloud('/api/databases', { method: 'POST', body: payload }, sandbox);
     }));
     const jobStatusSchema = {
         job_id: z.string().min(1),
         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(180),
+        sandbox: sandboxSchema,
     };
     server.registerTool('cloud_job_status', {
         title: 'Theo dõi job MONA Cloud',
-        description: 'Đọc một job; mặc định poll tới succeeded/failed/cancelled hoặc timeout.',
+        description: 'Đọc job thật hoặc sandbox theo ID; API tự nhận diện sandbox nên không cần header.',
         inputSchema: jobStatusSchema,
-    }, ({ job_id, wait, interval_sec, timeout_sec }) => runTool(() => pollJob(clients, job_id, wait, interval_sec, timeout_sec)));
+    }, ({ job_id, wait, interval_sec, timeout_sec, sandbox }) => runTool(() => pollJob(clients, job_id, wait, interval_sec, timeout_sec, clients.sandboxEnabled(sandbox))));
     server.registerTool('vibecloud_job_status', {
         title: 'Alias cũ của cloud_job_status',
-        description: 'Alias tương thích; dùng cloud_job_status cho tích hợp mới.',
+        description: 'Alias tương thích; dùng cloud_job_status cho tích hợp mới. Job sandbox được tự nhận diện, không cần header.',
         inputSchema: jobStatusSchema,
-    }, ({ job_id, wait, interval_sec, timeout_sec }) => runTool(() => pollJob(clients, job_id, wait, interval_sec, timeout_sec)));
+    }, ({ job_id, wait, interval_sec, timeout_sec, sandbox }) => runTool(() => pollJob(clients, job_id, wait, interval_sec, timeout_sec, clients.sandboxEnabled(sandbox))));
     server.registerTool('cloud_services_list', {
         title: 'Danh sách service MONA Cloud',
-        description: 'Liệt kê VPS và database của MONA Pass hiện tại.',
-    }, () => runTool(() => clients.vibecloud('/api/services')));
+        description: 'Liệt kê VPS/database; sandbox=true gộp cả service thử 0đ bằng API, không cần header.',
+        inputSchema: { sandbox: sandboxSchema },
+    }, ({ sandbox }) => runTool(() => clients.vibecloud('/api/services', {
+        query: clients.sandboxEnabled(sandbox) ? { include_sandbox: 1 } : undefined,
+    })));
     server.registerTool('vibecloud_list_services', {
         title: 'Alias cũ của cloud_services_list',
-        description: 'Alias tương thích; dùng cloud_services_list cho tích hợp mới.',
-    }, () => runTool(() => clients.vibecloud('/api/services')));
+        description: 'Alias tương thích; dùng cloud_services_list cho tích hợp mới. sandbox=true gộp service thử 0đ, không cần header.',
+        inputSchema: { sandbox: sandboxSchema },
+    }, ({ sandbox }) => runTool(() => clients.vibecloud('/api/services', {
+        query: clients.sandboxEnabled(sandbox) ? { include_sandbox: 1 } : undefined,
+    })));
     for (const action of ['start', 'stop', 'rebuild']) {
         const name = `cloud_service_${action}`;
         server.registerTool(name, {
             title: `${action} service MONA Cloud`,
             description: action === 'stop'
                 ? 'Dừng VPS/database MONA Cloud; luôn cho phép dừng để người dùng hạn chế chi phí.'
-                : `${action} VPS/database MONA Cloud. Lệnh có thể phát sinh chi phí và kiểm tra ví trước.`,
-            inputSchema: { service_id: z.string().min(1) },
-        }, ({ service_id }) => runTool(async () => {
+                : `${action} VPS/database MONA Cloud. Lệnh có thể phát sinh chi phí và kiểm tra ví trước. ${SANDBOX_DESCRIPTION}.`,
+            inputSchema: { service_id: z.string().min(1), sandbox: sandboxSchema },
+        }, ({ service_id, sandbox }) => runTool(async () => {
+            const path = `/api/services/${encodeURIComponent(service_id)}/${action}`;
             if (action !== 'stop')
-                await clients.spendGuard();
-            return clients.vibecloud(`/api/services/${encodeURIComponent(service_id)}/${action}`, { method: 'POST' });
+                return clients.guardedVibecloud(path, { method: 'POST' }, sandbox);
+            return clients.vibecloud(path, { method: 'POST' });
         }));
         server.registerTool(`vibecloud_${action}`, {
             title: `Alias cũ của ${name}`,
-            description: `Alias tương thích; dùng ${name} cho tích hợp mới.`,
-            inputSchema: { service_id: z.string().min(1) },
-        }, ({ service_id }) => runTool(async () => {
+            description: `Alias tương thích; dùng ${name} cho tích hợp mới.${action === 'stop' ? '' : ` ${SANDBOX_DESCRIPTION}.`}`,
+            inputSchema: { service_id: z.string().min(1), sandbox: sandboxSchema },
+        }, ({ service_id, sandbox }) => runTool(async () => {
+            const path = `/api/services/${encodeURIComponent(service_id)}/${action}`;
             if (action !== 'stop')
-                await clients.spendGuard();
-            return clients.vibecloud(`/api/services/${encodeURIComponent(service_id)}/${action}`, { method: 'POST' });
+                return clients.guardedVibecloud(path, { method: 'POST' }, sandbox);
+            return clients.vibecloud(path, { method: 'POST' });
         }));
     }
     server.registerTool('cloud_prices', {
@@ -283,14 +301,14 @@ export function createServer(dependencies = {}) {
     }, () => runTool(() => clients.packages()));
     server.registerTool('cloud_agent_deploy', {
         title: 'Deploy MONA Agent trên MONA Cloud',
-        description: 'Slot runtime agent wave kế tiếp; hiện trả trạng thái stub rõ ràng.',
-        inputSchema: { template: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/) },
-    }, ({ template }) => runTool(() => agentRuntimeStub(template)));
+        description: `Slot runtime agent wave kế tiếp; hiện trả trạng thái stub rõ ràng. ${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))));
     server.registerTool('vibecloud_agent_deploy', {
         title: 'Alias cũ của cloud_agent_deploy',
-        description: 'Alias tương thích; dùng cloud_agent_deploy cho tích hợp mới.',
-        inputSchema: { template: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/) },
-    }, ({ template }) => runTool(() => agentRuntimeStub(template)));
+        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))));
     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.',

package/docs/ai-agent.md

@@ -5,7 +5,7 @@ Tài liệu này dành cho Claude, Codex, Cursor và agent dùng Model Context P
 ## 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, đọc `cloud_balance`, `cloud_packages` và `cloud_prices`.
+2. Trước khi provision thật, đọc `cloud_balance`, `cloud_packages` và `cloud_prices`. 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.
 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`.
@@ -130,7 +130,7 @@ Deploy source lên VPS từ credential của job, đưa database connection stri
 
 ## 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. Upstream vẫn là nguồn quyết định cuối và có thể trả:
+`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ả:
 
 ```json
 {
@@ -142,6 +142,21 @@ Deploy source lên VPS từ credential của job, đưa database connection stri
 
 hoặc `budget_exceeded`. Khi gặp hai code này, không retry. Gọi `cloud_topup`, `cloud_budget_get` hoặc yêu cầu user tăng budget. `cloud_service_stop` luôn được phép vì chặn stop có thể làm tăng rủi ro chi phí.
 
+## Thử 0đ bằng sandbox
+
+Thêm `sandbox: true` khi gọi `cloud_vps_create`, `cloud_db_create`, `cloud_service_start`, `cloud_service_rebuild` hoặc `cloud_agent_deploy`. Có thể đặt `MONACLOUD_SANDBOX=1` để bật cho toàn bộ MCP process. Alias `vibecloud_*` tương ứng hoạt động giống hệt.
+
+```text
+cloud_vps_create({ app_name: "shop-demo", package_slug: "standard-2", sandbox: true })
+cloud_db_create({ app_name: "shop-demo", engine: "postgresql", package_slug: "standard-2", sandbox: true })
+cloud_job_status({ job_id: "...", sandbox: true })
+cloud_services_list({ sandbox: true })
+```
+
+Với lệnh tạo/start/rebuild sandbox, MCP không gọi Billing, tự gửi `X-Vibecloud-Sandbox: 1`, và response có `sandbox: true`. `cloud_job_status` tra job theo ID mà không cần header; trạng thái `done` là terminal hợp lệ của sandbox. `cloud_services_list({ sandbox: true })` dùng `include_sandbox=1`, cũng không cần header, để gộp service thật và sandbox.
+
+Sandbox không gọi Proxmox, không cấp IP thật, không trừ tiền và có TTL do compute API quản lý. Chỉ chuyển sang lệnh thật khi người dùng yêu cầu rõ ràng. `cloud_agent_deploy` hiện vẫn trả `agent_runtime_pending`; sandbox chỉ đánh dấu response nhất quán, không giả vờ đã deploy.
+
 ## Catalog MONA Agent
 
 `agent_templates_list` trả nguồn catalog và danh sách slug. `agent_templates_get` trả toàn bộ file text cần để agent build local. Không tự nối path từ input ngoài; chỉ dùng slug đã trả.

package/package.json

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