monacloud-mcp 0.10.10 → 0.10.11

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({
@@ -49,11 +51,13 @@ export function registerDomainTools(server, clients) {
         return results;
     }));
     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 +66,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 +98,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 +125,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 +134,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 +149,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 +158,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 +169,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 +179,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 +187,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 +195,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 +208,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 +220,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 +232,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 +259,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)(?:_|$)/;
+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>;

package/dist/remote-verify.js

@@ -0,0 +1,62 @@
+import { createPublicKey, verify as verifySignature } from "node:crypto";
+function decodeJson(value) {
+    return JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+}
+function includesAccount(aud) {
+    return typeof aud === "string" ? aud === "account" : Array.isArray(aud) && aud.includes("account");
+}
+export function createAccessTokenVerifier(options) {
+    const issuer = options.issuer.replace(/\/$/, "");
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const ttl = options.jwksTtlMs ?? 10 * 60_000;
+    const now = options.now ?? Date.now;
+    let cached;
+    async function getJwks() {
+        if (cached && cached.expires > now())
+            return cached.document;
+        const response = await fetchImpl(`${issuer}/protocol/openid-connect/certs`);
+        if (!response.ok)
+            throw new Error(`JWKS request failed: ${response.status}`);
+        const document = await response.json();
+        if (!Array.isArray(document.keys))
+            throw new Error("JWKS response has no keys");
+        cached = { expires: now() + ttl, document };
+        return document;
+    }
+    return async function verifyAccessToken(token) {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            throw new Error("Malformed JWT");
+        const header = decodeJson(parts[0]);
+        const claims = decodeJson(parts[1]);
+        if (header.alg !== "RS256" || !header.kid)
+            throw new Error("Unsupported JWT algorithm");
+        const jwks = await getJwks();
+        const jwk = jwks.keys?.find((key) => key.kid === header.kid && (!key.alg || key.alg === "RS256"));
+        if (!jwk)
+            throw new Error("JWT signing key not found");
+        const publicKey = createPublicKey({ key: jwk, format: "jwk" });
+        const valid = verifySignature("RSA-SHA256", Buffer.from(`${parts[0]}.${parts[1]}`), publicKey, Buffer.from(parts[2], "base64url"));
+        if (!valid)
+            throw new Error("Invalid JWT signature");
+        const currentSeconds = Math.floor(now() / 1000);
+        if (claims.iss !== issuer)
+            throw new Error("Invalid token issuer");
+        if (!claims.exp || claims.exp <= currentSeconds)
+            throw new Error("Expired access token");
+        if (!claims.sub || !claims.azp)
+            throw new Error("Missing token subject or authorized party");
+        const registered = options.isRegisteredClient
+            ? await options.isRegisteredClient(claims.azp)
+            : false;
+        if (!includesAccount(claims.aud) && !registered)
+            throw new Error("Invalid token audience");
+        return {
+            token,
+            clientId: claims.azp,
+            scopes: claims.scope?.split(/\s+/).filter(Boolean) ?? [],
+            expiresAt: claims.exp,
+            extra: { sub: claims.sub },
+        };
+    };
+}

package/dist/remote.d.ts

@@ -0,0 +1,21 @@
+import express from "express";
+import { createServer as createMcpServer } from "./server.js";
+import { type VerifiedAccessToken } from "./remote-verify.js";
+export interface RemoteServerOptions {
+    publicUrl: string;
+    issuer: string;
+    initialAccessToken: string;
+    /** Thư mục lưu client DCR (clients.json) để sống qua restart; bỏ trống = chỉ giữ trong RAM (test). */
+    dataDir?: string;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof globalThis.fetch;
+    verifyAccessToken?: (token: string) => Promise<VerifiedAccessToken>;
+    createServer?: typeof createMcpServer;
+    now?: () => number;
+}
+export interface RemoteServer {
+    app: ReturnType<typeof express>;
+    close(): Promise<void>;
+    sessionCount(): number;
+}
+export declare function createRemoteServer(options: RemoteServerOptions): Promise<RemoteServer>;