monacloud-mcp 0.10.10 → 0.10.12

package/dist/base.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { CloudError, runTool } from './errors.js';
 import { pollJob, TERMINAL_JOBS } from './jobs.js';
 import { unwrapData } from './http.js';
+import { completeToolMetadata } from './monapay.js';
 const object = (value) => value && typeof value === 'object' ? value : {};
 const id = z.string().trim().min(1).max(255);
 const sandbox = z.boolean().optional().describe('Thử 0đ, chỉ ước tính và không tạo hạ tầng thật / Sandbox estimate only');
@@ -45,7 +46,10 @@ async function createBase(clients, body) {
 export function registerBaseTools(server, clients) {
     const register = (name, description, schema, handler) => {
         for (const toolName of [name, name.replace(/^cloud_/, 'vibecloud_')]) {
+            const metadata = completeToolMetadata(toolName, undefined, undefined);
             server.registerTool(toolName, {
+                title: metadata.title,
+                annotations: metadata.annotations,
                 description: toolName === name ? `${description} ${baseDescription}` : `Alias tương thích của ${name}. / Compatibility alias. ${description} ${baseDescription}`,
                 inputSchema: schema,
             }, (args) => runTool(() => handler(args)));

package/dist/compute.js

@@ -4,6 +4,7 @@ import { unwrapData } from './http.js';
 import { finishAppJob } from './jobs.js';
 import { detectProject } from './local.js';
 import { localAppTools } from './local-app.js';
+import { completeToolMetadata } from './monapay.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. Sau khi app có URL, CHỦ ĐỘNG hỏi tên miền riêng: human đã có domain → cloud_app_domain_add (CNAME); chưa có → cloud_domain_search gợi 3–5 đuôi (.vn trước nếu khách Việt) kèm giá VND, hỏi xác nhận chính tả + duyệt tiền → cloud_domain_buy (đã login) hoặc cloud_domain_reserve (chưa login: QR + claim_url) → cloud_domain_attach trỏ DNS + SSL. 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; 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);
@@ -49,7 +50,10 @@ 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_')]) {
+            const metadata = completeToolMetadata(toolName, undefined, undefined);
             server.registerTool(toolName, {
+                title: metadata.title,
+                annotations: metadata.annotations,
                 description: toolName === name ? description : `Alias tương thích của ${name}. / Compatibility alias. ${description}`,
                 inputSchema: schema,
             }, (args) => runTool(() => handler(args)));

package/dist/domains.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { runTool } from './errors.js';
+import { toolAnnotationsForName } from './monapay.js';
 const domainName = z.string().trim().toLowerCase()
     .min(3).max(253)
     .describe('Tên miền đầy đủ (vd: example.vn) hoặc chỉ tên chưa có đuôi (vd: example).');
@@ -24,6 +25,7 @@ const registrantSchema = z.object({
 }).strict();
 export function registerDomainTools(server, clients) {
     server.registerTool('cloud_domain_search', {
+        annotations: toolAnnotationsForName('cloud_domain_search'),
         title: 'Tìm kiếm + báo giá tên miền',
         description: 'Kiểm tra tên miền còn trống và xem giá mua (VND, đã VAT). KHÔNG cần đăng nhập MONA Pass — gọi được ngay cả khi người dùng chưa có tài khoản; dùng trước khi mua/giữ chỗ để biết available/price.',
         inputSchema: z.object({
@@ -48,12 +50,79 @@ export function registerDomainTools(server, clients) {
         }
         return results;
     }));
+    server.registerTool('cloud_domain_tld_groups', {
+        annotations: toolAnnotationsForName('cloud_domain_tld_groups'),
+        title: 'Danh mục đuôi tên miền theo ngành',
+        description: 'Liệt kê các nhóm ngành của đuôi tên miền (Ăn uống, Công nghệ & AI, Quốc gia, Việt Nam...) kèm số lượng đuôi và khoảng giá VND mỗi nhóm. Gọi tool này TRƯỚC cloud_domain_tlds để biết slug ngành cần lọc. Không cần đăng nhập.',
+        inputSchema: z.object({}).strict(),
+    }, () => runTool(() => clients.vibecloudGuestOk('/api/domains/tlds/groups')));
+    server.registerTool('cloud_domain_tlds', {
+        annotations: toolAnnotationsForName('cloud_domain_tlds'),
+        title: 'Bảng giá đuôi tên miền',
+        description: 'Bảng giá đầy đủ các đuôi tên miền MONA Domain bán được, giá VND đã gồm VAT — giá năm đầu (price_vnd, đã tính khuyến mãi nếu registry đang chạy) và giá gia hạn mỗi năm (renew_vnd). Lọc theo ngành (group, lấy slug từ cloud_domain_tld_groups), theo từ khoá (q), hoặc theo ngân sách (max_price_vnd). Dùng khi người dùng hỏi "có những đuôi nào", "đuôi nào rẻ", "đuôi nào hợp ngành X". Đuôi .vn có needs_verification=true nghĩa là cần hồ sơ xác thực chủ thể. Không cần đăng nhập.',
+        inputSchema: z.object({
+            scope: z.enum(['popular', 'all']).optional()
+                .describe('popular = nhóm đuôi thông dụng (mặc định), all = toàn bộ danh sách.'),
+            group: z.string().max(40).optional()
+                .describe('Slug ngành từ cloud_domain_tld_groups (vd: "an-uong", "cong-nghe", "viet-nam").'),
+            q: z.string().max(40).optional().describe('Tìm trong tên đuôi và nhãn tiếng Việt (vd: "shop").'),
+            max_price_vnd: z.number().int().min(0).optional().describe('Chỉ lấy đuôi có giá năm đầu không quá số này.'),
+            sort: z.enum(['popular', 'price', 'tld']).optional().describe('Thứ tự sắp xếp. Mặc định popular.'),
+            limit: z.number().int().min(1).max(1000).optional().describe('Số dòng tối đa. Mặc định 200.'),
+            offset: z.number().int().min(0).optional().describe('Bỏ qua bao nhiêu dòng đầu, để lật trang.'),
+        }).strict(),
+    }, ({ scope, group, q, max_price_vnd, sort, limit, offset }) => runTool(() => {
+        const params = new URLSearchParams();
+        if (scope)
+            params.set('scope', scope);
+        if (group)
+            params.set('group', group);
+        if (q)
+            params.set('q', q);
+        if (max_price_vnd !== undefined)
+            params.set('max_price_vnd', String(max_price_vnd));
+        if (sort)
+            params.set('sort', sort);
+        if (limit !== undefined)
+            params.set('limit', String(limit));
+        if (offset !== undefined)
+            params.set('offset', String(offset));
+        const query = params.toString();
+        return clients.vibecloudGuestOk(`/api/domains/tlds${query ? `?${query}` : ''}`);
+    }));
+    server.registerTool('cloud_domain_suggest', {
+        annotations: toolAnnotationsForName('cloud_domain_suggest'),
+        title: 'Gợi ý tên miền còn trống',
+        description: 'Gợi ý những tên miền còn trống quanh một từ khoá, kèm giá VND đã gồm VAT. Từ khoá nhận tiếng Việt có dấu, tool tự bỏ dấu thành nhãn hợp lệ. Truyền industry (slug từ cloud_domain_tld_groups) để ưu tiên đuôi hợp ngành — vd quán cà phê sẽ ra .cafe và .coffee trước. Mọi kết quả đều đã tra trạng thái thật tại nhà đăng ký. Dùng khi tên người dùng muốn đã có người lấy, hoặc khi họ chưa nghĩ ra tên. Sau khi người dùng chọn thì gọi cloud_domain_buy (hoặc cloud_domain_reserve nếu chưa đăng nhập). Không cần đăng nhập.',
+        inputSchema: z.object({
+            keyword: z.string().min(1).max(63)
+                .describe('Tên muốn đặt hoặc từ khoá mô tả sản phẩm (vd: "Cà Phê Sạch", "myapp").'),
+            industry: z.string().max(40).optional()
+                .describe('Slug ngành từ cloud_domain_tld_groups để ưu tiên đuôi hợp ngành.'),
+            limit: z.number().int().min(1).max(30).optional().describe('Số gợi ý trả về. Mặc định 12.'),
+            max_price_vnd: z.number().int().min(0).optional().describe('Chặn trần giá năm đầu.'),
+            include_taken: z.boolean().optional().describe('true = giữ lại cả tên đã có người đăng ký.'),
+        }).strict(),
+    }, ({ keyword, industry, limit, max_price_vnd, include_taken }) => runTool(() => {
+        const params = new URLSearchParams({ keyword });
+        if (industry)
+            params.set('industry', industry);
+        if (limit !== undefined)
+            params.set('limit', String(limit));
+        if (max_price_vnd !== undefined)
+            params.set('max_price_vnd', String(max_price_vnd));
+        if (include_taken)
+            params.set('include_taken', 'true');
+        return clients.vibecloudGuestOk(`/api/domains/tlds/suggest?${params}`);
+    }));
     server.registerTool('cloud_domain_registrant_get', {
+        annotations: toolAnnotationsForName('cloud_domain_registrant_get'),
         title: 'Xem thông tin chủ thể đăng ký tên miền',
         description: 'Lấy thông tin chủ thể (registrant) đã lưu. Cần dữ liệu này để mua tên miền.',
         inputSchema: z.object({}).strict(),
     }, () => runTool(() => clients.vibecloud('/api/domains/registrant')));
     server.registerTool('cloud_domain_registrant_set', {
+        annotations: toolAnnotationsForName('cloud_domain_registrant_set'),
         title: 'Cập nhật thông tin chủ thể đăng ký tên miền',
         description: 'Lưu thông tin chủ thể để đăng ký tên miền. HỎI NGƯỜI DÙNG cung cấp NGAY TRONG PHIÊN: họ tên, email, điện thoại, địa chỉ. Tên miền .vn cá nhân cần thêm CCCD 12 số + ngày sinh (DD/MM/YYYY) + giới tính; .vn tổ chức cần org_name + tax_code (MST) + representative. Lưu 1 lần, tái dùng cho các domain sau. Không tự bịa dữ liệu — thiếu trường nào thì hỏi đúng trường đó.',
         inputSchema: registrantSchema,
@@ -62,6 +131,7 @@ export function registerDomainTools(server, clients) {
         body: args,
     })));
     server.registerTool('cloud_domain_buy', {
+        annotations: toolAnnotationsForName('cloud_domain_buy'),
         title: 'Mua tên miền',
         description: [
             'Mua tên miền và trừ ví VND — làm trọn trong phiên; người dùng chỉ quét QR và xác nhận, không phải đăng ký trước hay tự làm trên web. Trước khi gọi:',
@@ -93,6 +163,7 @@ export function registerDomainTools(server, clients) {
     }));
     // --- Guest → reserve → claim (spec monadomain §12): mua TRƯỚC khi có tài khoản ---------------
     server.registerTool('cloud_domain_reserve', {
+        annotations: toolAnnotationsForName('cloud_domain_reserve'),
         title: 'Giữ chỗ tên miền + QR trả tiền (không cần tài khoản)',
         description: [
             'Giữ chỗ tên miền 30 phút cho người dùng CHƯA có MONA Pass (hoặc chưa login trên máy này) — không trừ tiền, không đăng ký thật, chỉ khoá tên trong hệ MONA Cloud.',
@@ -119,6 +190,7 @@ export function registerDomainTools(server, clients) {
         ...(clients.sandboxEnabled(sandbox === true) ? { headers: { 'X-Vibecloud-Sandbox': '1' } } : {}),
     })));
     server.registerTool('cloud_domain_reserve_status', {
+        annotations: toolAnnotationsForName('cloud_domain_reserve_status'),
         title: 'Trạng thái giữ chỗ tên miền',
         description: 'Xem reservation đã nhận tiền chưa / đã claim chưa / còn hạn không. Guest truyền claim_token (hoặc guest_token) nhận từ cloud_domain_reserve; chủ reservation đã login thì không cần. Đọc next_step trong kết quả để biết bước kế.',
         inputSchema: z.object({
@@ -127,6 +199,7 @@ export function registerDomainTools(server, clients) {
         }).strict(),
     }, ({ reservation_id, claim_token }) => runTool(() => clients.vibecloudGuestOk(`/api/domains/reserve/${encodeURIComponent(reservation_id)}`, { query: claim_token ? { t: claim_token } : undefined, guestToken: claim_token })));
     server.registerTool('cloud_domain_claim', {
+        annotations: toolAnnotationsForName('cloud_domain_claim'),
         title: 'Nhận reservation về tài khoản + mua (claim = đăng ký = trả tiền)',
         description: [
             'Gắn reservation vào MONA Pass đang đăng nhập, kéo tiền đã chuyển (nếu có) về ví rồi MUA ngay. Cần đăng nhập (monacloud-mcp login) — lần đầu đăng nhập MONA Cloud tự tạo hồ sơ + ví, không có form đăng ký riêng.',
@@ -141,6 +214,7 @@ export function registerDomainTools(server, clients) {
         }).strict(),
     }, ({ reservation_id, ...body }) => runTool(() => clients.vibecloud(`/api/domains/reserve/${encodeURIComponent(reservation_id)}/claim`, { method: 'POST', body })));
     server.registerTool('cloud_domain_reserve_release', {
+        annotations: toolAnnotationsForName('cloud_domain_reserve_release'),
         title: 'Nhả chỗ tên miền đã giữ',
         description: 'Huỷ reservation chưa nhận tiền (người dùng đổi ý / chọn tên khác). Đã có tiền vào thì không huỷ được — dùng cloud_domain_claim.',
         inputSchema: z.object({
@@ -149,6 +223,7 @@ export function registerDomainTools(server, clients) {
         }).strict(),
     }, ({ reservation_id, claim_token }) => runTool(() => clients.vibecloudGuestOk(`/api/domains/reserve/${encodeURIComponent(reservation_id)}`, { method: 'DELETE', query: claim_token ? { t: claim_token } : undefined, guestToken: claim_token })));
     server.registerTool('cloud_domain_list', {
+        annotations: toolAnnotationsForName('cloud_domain_list'),
         title: 'Danh sách tên miền đã import/mua',
         description: 'Liệt kê tên miền đã đưa vào MONA Cloud (import + mua). sandbox=true → xem domain sandbox.',
         inputSchema: z.object({
@@ -159,6 +234,7 @@ export function registerDomainTools(server, clients) {
         return clients.vibecloud('/api/domains', { headers });
     }));
     server.registerTool('cloud_domain_verify_start', {
+        annotations: toolAnnotationsForName('cloud_domain_verify_start'),
         title: 'Bắt đầu nộp hồ sơ .vn',
         description: 'Sinh bản khai đã điền sẵn và link upload hồ sơ .vn. Dùng sau khi mua tên miền .vn (status=pending_verification).',
         inputSchema: z.object({
@@ -168,6 +244,7 @@ export function registerDomainTools(server, clients) {
         method: 'POST',
     })));
     server.registerTool('cloud_domain_verify_status', {
+        annotations: toolAnnotationsForName('cloud_domain_verify_status'),
         title: 'Trạng thái hồ sơ .vn',
         description: 'Kiểm tra trạng thái duyệt hồ sơ đăng ký .vn (profile_status từ MONA Host).',
         inputSchema: z.object({
@@ -175,6 +252,7 @@ export function registerDomainTools(server, clients) {
         }).strict(),
     }, ({ id }) => runTool(() => clients.vibecloud(`/api/domains/${encodeURIComponent(id)}/verify`)));
     server.registerTool('cloud_domain_health', {
+        annotations: toolAnnotationsForName('cloud_domain_health'),
         title: 'Kiểm tra sức khoẻ tên miền',
         description: 'Kiểm tra hạn đăng ký, trạng thái hồ sơ, NS, SSL và cảnh báo tên miền đã mua.',
         inputSchema: z.object({
@@ -182,6 +260,7 @@ export function registerDomainTools(server, clients) {
         }).strict(),
     }, ({ id }) => runTool(() => clients.vibecloud(`/api/domains/${encodeURIComponent(id)}/health`)));
     server.registerTool('cloud_domain_renew', {
+        annotations: toolAnnotationsForName('cloud_domain_renew'),
         title: 'Gia hạn tên miền (trừ ví VND)',
         description: [
             'Gia hạn tên miền đã mua qua MONA Cloud. LUÔN gọi dry_run=true trước để lấy price_vnd (đã VAT), HỎI người dùng duyệt số tiền, rồi gọi lại dry_run=false — lúc đó trừ ví VND và gia hạn thật ở registrar.',
@@ -194,6 +273,7 @@ export function registerDomainTools(server, clients) {
         }).strict(),
     }, ({ id, billing_cycle, dry_run }) => runTool(() => clients.guardedVibecloud(`/api/domains/${encodeURIComponent(id)}/renew`, { method: 'POST', body: { billing_cycle, dry_run: dry_run !== false } }, false)));
     server.registerTool('cloud_domain_wait', {
+        annotations: toolAnnotationsForName('cloud_domain_wait'),
         title: 'Chờ tên miền active',
         description: 'Long-poll cho đến khi tên miền chuyển sang active/failed (mặc định timeout=60s). Dùng sau cloud_domain_buy để chờ MONA Host xử lý.',
         inputSchema: z.object({
@@ -205,6 +285,7 @@ export function registerDomainTools(server, clients) {
         return clients.vibecloud(`/api/domains/${encodeURIComponent(id)}/wait${params}`);
     }));
     server.registerTool('cloud_domain_webhook_set', {
+        annotations: toolAnnotationsForName('cloud_domain_webhook_set'),
         title: 'Đăng ký webhook tên miền',
         description: 'Đăng ký URL nhận sự kiện domain.status_changed (ký HMAC). Mỗi user 1 webhook; gọi lại để cập nhật.',
         inputSchema: z.object({
@@ -216,6 +297,7 @@ export function registerDomainTools(server, clients) {
         body: { url, secret },
     })));
     server.registerTool('cloud_domain_attach', {
+        annotations: toolAnnotationsForName('cloud_domain_attach'),
         title: 'Gắn tên miền vào ứng dụng',
         description: [
             'Gắn tên miền vào app đã deploy. Tên miền .vn chưa active vẫn gọi được — attach đặt trước, server tự hoàn tất sau khi hồ sơ được duyệt và gửi webhook domain.status_changed.',
@@ -242,26 +324,31 @@ export function registerDomainTools(server, clients) {
         priority: z.number().int().min(0).max(65535).optional().describe('Ưu tiên (MX/SRV).'),
     };
     server.registerTool('cloud_domain_dns_list', {
+        annotations: toolAnnotationsForName('cloud_domain_dns_list'),
         title: 'Xem bản ghi DNS của tên miền',
         description: 'Liệt kê bản ghi DNS (A/CNAME/MX/TXT...) của tên miền đăng ký tại MONA Cloud. domain_id lấy từ cloud_domain_list.',
         inputSchema: z.object({ domain_id: objectId }).strict(),
     }, ({ domain_id }) => runTool(() => clients.vibecloud(`/api/domains/${encodeURIComponent(domain_id)}/records`)));
     server.registerTool('cloud_domain_dns_add', {
+        annotations: toolAnnotationsForName('cloud_domain_dns_add'),
         title: 'Thêm bản ghi DNS',
         description: 'Thêm 1 bản ghi DNS. Vd trỏ web: type=A, name=@, data=<IP>. Trỏ www: type=CNAME, name=www, data=<domain>. AI làm trọn.',
         inputSchema: z.object({ domain_id: objectId, ...recordSchema }).strict(),
     }, ({ domain_id, ...record }) => runTool(() => clients.vibecloud(`/api/domains/${encodeURIComponent(domain_id)}/records`, { method: 'POST', body: record })));
     server.registerTool('cloud_domain_dns_update', {
+        annotations: toolAnnotationsForName('cloud_domain_dns_update'),
         title: 'Sửa bản ghi DNS',
         description: 'Sửa 1 bản ghi DNS theo record_id (lấy từ cloud_domain_dns_list).',
         inputSchema: z.object({ domain_id: objectId, record_id: z.string().min(1).max(128), ...recordSchema }).strict(),
     }, ({ domain_id, record_id, ...record }) => runTool(() => clients.vibecloud(`/api/domains/${encodeURIComponent(domain_id)}/records/${encodeURIComponent(record_id)}`, { method: 'PUT', body: record })));
     server.registerTool('cloud_domain_dns_delete', {
+        annotations: toolAnnotationsForName('cloud_domain_dns_delete'),
         title: 'Xoá bản ghi DNS',
         description: 'Xoá 1 bản ghi DNS theo record_id.',
         inputSchema: z.object({ domain_id: objectId, record_id: z.string().min(1).max(128) }).strict(),
     }, ({ domain_id, record_id }) => runTool(() => clients.vibecloud(`/api/domains/${encodeURIComponent(domain_id)}/records/${encodeURIComponent(record_id)}`, { method: 'DELETE' })));
     server.registerTool('cloud_domain_ns_set', {
+        annotations: toolAnnotationsForName('cloud_domain_ns_set'),
         title: 'Đổi nameserver (NS) của tên miền',
         description: 'Đổi NS cho tên miền (≥2). Vd giữ DNS ở MONA: ns1.mona.host, ns2.mona.host. Hoặc chuyển sang Cloudflare/nhà khác. AI làm hoàn toàn.',
         inputSchema: z.object({

package/dist/mail.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { domainToASCII } from 'node:url';
 import { z } from 'zod';
 import { runTool } from './errors.js';
+import { toolAnnotationsForName } from './monapay.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([
@@ -32,21 +33,25 @@ function idempotencyHeaders(key) {
 }
 export function registerMailTools(server, clients, config) {
     server.registerTool('mail_account', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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({
@@ -79,11 +84,13 @@ export function registerMailTools(server, clients, config) {
         return sandbox ? { ...result, sandbox: true } : result;
     }));
     server.registerTool('mail_status', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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({
@@ -94,6 +101,7 @@ export function registerMailTools(server, clients, config) {
         }).strict(),
     }, (query) => runTool(() => clients.mail('/v1/emails', { query })));
     server.registerTool('mail_domain_add', {
+        annotations: toolAnnotationsForName('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({
@@ -107,6 +115,7 @@ export function registerMailTools(server, clients, config) {
         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', {
+        annotations: toolAnnotationsForName('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(),
@@ -114,6 +123,7 @@ export function registerMailTools(server, clients, config) {
         method: 'POST', headers: idempotencyHeaders(idempotency_key),
     })));
     server.registerTool('mail_domain_cloudflare', {
+        annotations: toolAnnotationsForName('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(),
@@ -121,11 +131,13 @@ export function registerMailTools(server, clients, config) {
         method: 'POST', headers: idempotencyHeaders(idempotency_key), body: { api_token },
     })));
     server.registerTool('mail_domains_list', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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(),
@@ -133,16 +145,19 @@ export function registerMailTools(server, clients, config) {
         method: 'POST', headers: idempotencyHeaders(idempotency_key), body,
     })));
     server.registerTool('mail_api_keys_list', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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(),
@@ -150,11 +165,13 @@ export function registerMailTools(server, clients, config) {
         method: 'POST', headers: idempotencyHeaders(idempotency_key), body,
     })));
     server.registerTool('mail_webhooks_list', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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(),
@@ -162,16 +179,19 @@ export function registerMailTools(server, clients, config) {
         method: 'POST', headers: idempotencyHeaders(idempotency_key),
     })));
     server.registerTool('mail_suppressions_list', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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', {
+        annotations: toolAnnotationsForName('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(),
@@ -179,12 +199,14 @@ export function registerMailTools(server, clients, config) {
         method: 'POST', headers: idempotencyHeaders(idempotency_key), body,
     })));
     server.registerTool('mail_stats', {
+        annotations: toolAnnotationsForName('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 })));
     // ── Hộp thư AI agent (nhận + đọc + trả lời) ─────────────────────────────
     server.registerTool('mail_inbox_create', {
+        annotations: toolAnnotationsForName('mail_inbox_create'),
         title: 'Tạo hộp thư agent',
         description: 'Khi cần một địa chỉ email cho agent trực (đọc thư, trả lời), tạo hộp. Bỏ domain để dùng miền agent.monamail.vn (nhận ngay); truyền domain đã verify để có địa chỉ brand. / Use to create an inbox an AI agent can read and reply from.',
         inputSchema: z.object({ agent_id: agentId, domain: domain.optional() }).strict(),
@@ -192,21 +214,25 @@ export function registerMailTools(server, clients, config) {
         method: 'POST', body: domain ? { agent_id, domain } : { agent_id },
     })));
     server.registerTool('mail_inbox_list', {
+        annotations: toolAnnotationsForName('mail_inbox_list'),
         title: 'Danh sách hộp agent',
         description: 'Khi cần biết agent đang trực những hộp nào, liệt kê hộp còn hoạt động. / Use to list active agent inboxes.',
         inputSchema: empty,
     }, () => runTool(() => clients.mail('/v1/inboxes')));
     server.registerTool('mail_inbox_get', {
+        annotations: toolAnnotationsForName('mail_inbox_get'),
         title: 'Xem hộp agent',
         description: 'Khi cần địa chỉ và trạng thái của một hộp, đọc chi tiết. / Use to read one inbox.',
         inputSchema: z.object({ inbox_id: id }).strict(),
     }, ({ inbox_id }) => runTool(() => clients.mail(`/v1/inboxes/${encodeURIComponent(inbox_id)}`)));
     server.registerTool('mail_inbox_delete', {
+        annotations: toolAnnotationsForName('mail_inbox_delete'),
         title: 'Xóa hộp agent',
         description: 'Khi hộp không còn dùng, xóa mềm; thư cũ còn đọc tới hết retention. / Use to soft-delete an inbox.',
         inputSchema: z.object({ inbox_id: id }).strict(),
     }, ({ inbox_id }) => runTool(() => clients.mail(`/v1/inboxes/${encodeURIComponent(inbox_id)}`, { method: 'DELETE' })));
     server.registerTool('mail_inbox_messages', {
+        annotations: toolAnnotationsForName('mail_inbox_messages'),
         title: 'Thư trong hộp agent',
         description: 'Khi trực hộp, liệt kê thư nhận; lọc seen=false để lấy thư chưa xử lý, phân trang bằng cursor. / Use to list messages an agent needs to handle.',
         inputSchema: z.object({
@@ -220,17 +246,20 @@ export function registerMailTools(server, clients, config) {
         query: { limit, cursor, since, ...(seen === undefined ? {} : { seen: String(seen) }) },
     })));
     server.registerTool('mail_inbox_message', {
+        annotations: toolAnnotationsForName('mail_inbox_message'),
         title: 'Đọc thư trong hộp',
         description: 'Khi cần nội dung đầy đủ, header và đính kèm của một thư, đọc chi tiết; lần đọc đầu đánh dấu đã xem. / Use to read a full inbox message before replying.',
         inputSchema: z.object({ inbox_id: id, message_id: id }).strict(),
     }, ({ inbox_id, message_id }) => runTool(() => clients.mail(`/v1/inboxes/${encodeURIComponent(inbox_id)}/messages/${encodeURIComponent(message_id)}`)));
     server.registerTool('mail_inbox_reply', {
+        annotations: toolAnnotationsForName('mail_inbox_reply'),
         title: 'Trả lời thư trong hộp',
         description: 'Khi agent trả lời khách, gửi đúng thread (In-Reply-To, References) từ địa chỉ hộp; cần text hoặc html. Việc khó rút lại (hứa giá, chuyển tiền) thì báo người, đừng tự gửi. / Use to reply to an inbox message in-thread.',
         inputSchema: z.object({ inbox_id: id, message_id: id, text: z.string().min(1).optional(), html: z.string().min(1).optional() })
             .strict().refine((value) => value.text || value.html, 'Cần text hoặc html để trả lời.'),
     }, ({ inbox_id, message_id, ...body }) => runTool(() => clients.mail(`/v1/inboxes/${encodeURIComponent(inbox_id)}/messages/${encodeURIComponent(message_id)}/reply`, { method: 'POST', body })));
     server.registerTool('mail_inbox_wait', {
+        annotations: toolAnnotationsForName('mail_inbox_wait'),
         title: 'Chờ thư trong hộp',
         description: 'Khi cần chờ thư tới (ví dụ mã OTP hoặc thư khớp mẫu), chờ tối đa timeout giây; có thư khớp trả full nội dung + extracted_code, hết giờ trả 204. Gọi lại nếu cần chờ lâu hơn. / Use to wait for an OTP or a matching message.',
         inputSchema: z.object({ inbox_id: id, match: inboxMatch, timeout: z.number().int().min(0).max(300).default(120) }).strict(),
@@ -238,6 +267,7 @@ export function registerMailTools(server, clients, config) {
         query: { match, timeout },
     })));
     server.registerTool('mail_inbox_update', {
+        annotations: toolAnnotationsForName('mail_inbox_update'),
         title: 'Cấu hình hộp agent',
         description: 'Khi cần đặt cách hộp xử lý thư: mode redirect (tự forward thư về email chủ) | store (chỉ lưu) | ai (để AI trực), địa chỉ forward_to, chat Telegram nhận báo, hoặc bật/tắt hộp. / Use to configure an inbox: redirect-forward email, Telegram chat, mode, active.',
         inputSchema: z.object({
@@ -249,6 +279,7 @@ export function registerMailTools(server, clients, config) {
         }).strict().refine((v) => Object.keys(v).length > 1, 'Cần ít nhất một trường để cập nhật.'),
     }, ({ inbox_id, ...body }) => runTool(() => clients.mail(`/v1/inboxes/${encodeURIComponent(inbox_id)}`, { method: 'PATCH', body })));
     server.registerTool('mail_inbox_batch', {
+        annotations: toolAnnotationsForName('mail_inbox_batch'),
         title: 'Tạo nhiều hộp agent',
         description: 'Khi cần tạo nhiều địa chỉ một lần (ví dụ mỗi nhân viên một hộp), tạo hàng loạt trong quota gói; lỗi từng hộp không hủy cả batch. / Use to create many inboxes at once.',
         inputSchema: z.object({

package/dist/monapay.d.ts

@@ -10,6 +10,18 @@ type ImportedTool = {
     handler: (...args: unknown[]) => unknown;
     enabled: boolean;
 };
+export type ToolAnnotations = {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+/** Mechanical metadata shared by native tools and tools imported from monapay-mcp. */
+export declare function toolAnnotationsForName(name: string): ToolAnnotations;
+export declare function completeToolMetadata(name: string, title: unknown, annotations: unknown): {
+    title: string;
+    annotations: ToolAnnotations;
+};
 export declare function createMonaPayClient(config: Config, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): MonaPayClient;
 export declare function importedMonaPayTools(config: Config, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch): Record<string, ImportedTool>;
 export declare function normalizeImportedResult(result: unknown): Promise<unknown>;

package/dist/monapay.js

@@ -2,6 +2,47 @@ import { readFileSync } from 'node:fs';
 import { createServer as createMonaPayServer } from 'monapay-mcp';
 import { MonaPayClient } from 'monapay-mcp/dist/client.js';
 import { CloudError, errorResult } from './errors.js';
+// cloud_subscription_update có thể huỷ gia hạn / dừng máy (cancel_action=stop) → xếp destructive để agent hỏi lại trước khi gọi.
+const DESTRUCTIVE = /(?:^|_)(?:delete|remove|cancel|release|rotate|stop|destroy|reset|revoke|suspend)(?:_|$)|^cloud_subscription_update$/;
+const READ_ONLY = /(?:^|_)(?:list|get|status|search|balance|ledger|health|whoami|usage|services|quote|detect|wait|logs|stats|templates|tlds|prices|packages|suggest|groups)(?:_|$)/;
+const IDEMPOTENT_WRITE = /(?:^|_)(?:set|update|attach)(?:_|$)/;
+/** Mechanical metadata shared by native tools and tools imported from monapay-mcp. */
+export function toolAnnotationsForName(name) {
+    const canonical = name.replace(/^vibecloud_/, 'cloud_');
+    const destructiveHint = DESTRUCTIVE.test(canonical);
+    const readOnlyHint = !destructiveHint && (READ_ONLY.test(canonical)
+        || canonical === 'cloud_open_console'
+        || canonical === 'mail_account'
+        || canonical === 'mail_plans'
+        || canonical === 'cloud_invoice_pdf'
+        || canonical === 'cloud_base_credentials'
+        || canonical === 'mail_inbox_message'
+        || canonical === 'mail_inbox_messages'
+        || canonical === 'monapay_me'
+        || canonical === 'monapay_verify_signature'
+        || canonical === 'monapay_generate_webhook_snippet'
+        || canonical === 'monapay_quickstart');
+    const idempotentHint = readOnlyHint
+        || (destructiveHint && !/(?:^|_)(?:rotate|reset)(?:_|$)/.test(canonical))
+        || (!destructiveHint && IDEMPOTENT_WRITE.test(canonical));
+    return {
+        readOnlyHint,
+        destructiveHint,
+        idempotentHint,
+        openWorldHint: canonical !== 'cloud_app_detect',
+    };
+}
+export function completeToolMetadata(name, title, annotations) {
+    const existing = annotations && typeof annotations === 'object'
+        ? annotations
+        : {};
+    return {
+        title: typeof title === 'string' && title.trim()
+            ? title
+            : `Công cụ MONA ${name.replace(/^(?:cloud|vibecloud|monapay|mail|agent)_/, '').replaceAll('_', ' ')}`,
+        annotations: { ...toolAnnotationsForName(name), ...existing },
+    };
+}
 function linkedCredentials(config) {
     try {
         const parsed = JSON.parse(readFileSync(config.linksFile, 'utf8'));

package/dist/remote-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/remote-cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { createServer as createHttpServer } from "node:http";
+import { createRemoteServer } from "./remote.js";
+const bind = process.env.MCP_REMOTE_BIND ?? "127.0.0.1";
+const port = Number.parseInt(process.env.MCP_REMOTE_PORT ?? "8765", 10);
+const publicUrl = process.env.MCP_REMOTE_PUBLIC_URL ?? "https://mcp.monacloud.vn";
+const issuer = process.env.MONACLOUD_ISSUER ?? "https://pass.monacloud.vn/realms/mona";
+const initialAccessToken = process.env.MONA_PASS_INITIAL_ACCESS_TOKEN;
+if (!initialAccessToken)
+    throw new Error("MONA_PASS_INITIAL_ACCESS_TOKEN is required");
+if (!Number.isInteger(port) || port < 1 || port > 65_535)
+    throw new Error("MCP_REMOTE_PORT is invalid");
+const dataDir = process.env.MCP_REMOTE_DATA_DIR ?? "./data";
+const remote = await createRemoteServer({ publicUrl, issuer, initialAccessToken, dataDir });
+const httpServer = createHttpServer(remote.app);
+httpServer.listen(port, bind, () => {
+    console.log(JSON.stringify({ event: "listening", bind, port }));
+});
+let stopping = false;
+async function shutdown() {
+    if (stopping)
+        return;
+    stopping = true;
+    await remote.close();
+    await new Promise((resolve, reject) => {
+        httpServer.close((error) => error ? reject(error) : resolve());
+    });
+}
+process.on("SIGTERM", () => void shutdown());
+process.on("SIGINT", () => void shutdown());

package/dist/remote-verify.d.ts

@@ -0,0 +1,17 @@
+export interface VerifiedAccessToken {
+    token: string;
+    clientId: string;
+    scopes: string[];
+    expiresAt: number;
+    extra: {
+        sub: string;
+    };
+}
+export interface JwtVerifierOptions {
+    issuer: string;
+    fetch?: typeof globalThis.fetch;
+    jwksTtlMs?: number;
+    isRegisteredClient?: (clientId: string) => boolean | Promise<boolean>;
+    now?: () => number;
+}
+export declare function createAccessTokenVerifier(options: JwtVerifierOptions): (token: string) => Promise<VerifiedAccessToken>;