monacloud-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,312 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { readConfig } from './config.js';
+import { AuthManager } from './auth.js';
+import { CloudClients } from './clients.js';
+import { errorResult, runTool, textResult, toAgentError } from './errors.js';
+import { requestJson, unwrapData } from './http.js';
+import { createMonaPayClient, importedMonaPayTools, normalizeImportedResult } from './monapay.js';
+import { TemplateCatalog } from './templates.js';
+const ENTITY = 'MONA Cloud là hệ công cụ cho vibecoder Việt Nam: một MONA ID, một ví VND và một MCP để deploy VibeCloud, thu tiền MONA Pay và chạy các sản phẩm MONA.';
+const TERMINAL_JOBS = new Set(['succeeded', 'failed', 'cancelled']);
+const asObject = (value) => (value && typeof value === 'object' ? value : {});
+function collection(value) {
+    const data = unwrapData(value);
+    if (Array.isArray(data))
+        return data.filter((item) => item && typeof item === 'object');
+    const object = asObject(data);
+    for (const key of ['items', 'data', 'results', 'bank_accounts', 'virtual_accounts', 'webhooks']) {
+        const nested = object[key];
+        if (Array.isArray(nested))
+            return nested.filter((item) => item && typeof item === 'object');
+    }
+    return [];
+}
+const sizingSchema = {
+    app_name: z.string().min(2).max(80),
+    package_slug: z.string().min(1).max(64).optional(),
+    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(),
+};
+const provisionSchema = z.object(sizingSchema).superRefine((value, context) => {
+    const dimensions = [value.cpu, value.ram_gb, value.disk_gb];
+    const hasAny = dimensions.some((item) => item !== undefined);
+    const hasAll = dimensions.every((item) => item !== undefined);
+    if (value.package_slug && hasAny) {
+        context.addIssue({ code: 'custom', message: 'Dùng package_slug hoặc bộ cpu/ram_gb/disk_gb, không dùng cả hai.' });
+    }
+    if (!value.package_slug && !hasAll) {
+        context.addIssue({ code: 'custom', message: 'Cần package_slug hoặc đủ cpu, ram_gb và disk_gb.' });
+    }
+});
+function agentRuntimeStub(template) {
+    return {
+        status: 'not_available',
+        code: 'agent_runtime_pending',
+        template,
+        message: 'Runtime MONA Agent trên VibeCloud 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 VibeCloud bật runtime agent.',
+    };
+}
+async function pollJob(clients, jobId, wait, intervalSeconds, timeoutSeconds) {
+    let result = await clients.vibecloud(`/api/jobs/${encodeURIComponent(jobId)}`);
+    if (!wait)
+        return 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 vibecloud_job_status với job_id=${jobId}.` };
+    }
+    return result;
+}
+async function providerHealth(name, url, fetchImpl) {
+    const started = Date.now();
+    try {
+        const data = await requestJson(url, { fetchImpl, timeoutMs: 5_000 });
+        return { name, ok: true, latency_ms: Date.now() - started, data };
+    }
+    catch (error) {
+        return { name, ok: false, latency_ms: Date.now() - started, error: toAgentError(error) };
+    }
+}
+export function createServer(dependencies = {}) {
+    const env = dependencies.env || process.env;
+    const config = dependencies.config || readConfig(env);
+    const fetchImpl = dependencies.fetchImpl || fetch;
+    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.1.0' }, { instructions: `${ENTITY}\nDùng cloud_* cho tài khoản/ví, vibecloud_* cho hạ tầng, monapay_* cho thu tiền và 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 ID hiện tại. / Return the current MONA ID profile.',
+    }, () => runTool(async () => ({ ...(await auth.userinfo()), console_url: config.consoleUrl })));
+    server.registerTool('cloud_balance', {
+        title: 'Số dư ví MONA Cloud',
+        description: 'Đọc số dư ví VND chung trước khi tạo tài nguyên có phí.',
+    }, () => runTool(() => clients.balance()));
+    server.registerTool('cloud_ledger', {
+        title: 'Sổ cái ví MONA Cloud',
+        description: 'Đọc các dòng nạp, trừ và hoàn tiền trong ledger.',
+        inputSchema: {
+            cursor: z.string().max(2048).optional(),
+            limit: z.number().int().min(1).max(100).default(50),
+        },
+    }, ({ cursor, limit }) => runTool(() => clients.ledger(cursor, limit)));
+    server.registerTool('cloud_topup', {
+        title: 'Nạp ví bằng VietQR',
+        description: 'Tạo yêu cầu nạp ví và trả VietQR; đây là bước con người thanh toán hợp lệ.',
+        inputSchema: {
+            amount: z.number().int().min(1_000).max(1_000_000_000).describe('Số tiền nguyên VND'),
+            idempotency_key: z.string().min(1).max(255).optional(),
+        },
+    }, ({ amount, idempotency_key }) => runTool(async () => ({
+        ...asObject(await clients.topup(amount, idempotency_key)),
+        instructions: 'Mở app ngân hàng, quét qr_data_url và chuyển đúng số tiền/nội dung. Sau khi tiền vào, gọi cloud_balance.',
+    })));
+    server.registerTool('cloud_usage', {
+        title: 'Chi phí MONA Cloud theo kỳ',
+        description: 'Đọc usage và tổng tiền theo tháng, có thể lọc sản phẩm.',
+        inputSchema: {
+            period: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/, 'Dùng YYYY-MM'),
+            product: z.string().min(1).max(100).optional(),
+        },
+    }, ({ period, product }) => runTool(() => clients.usage(period, product)));
+    server.registerTool('cloud_services', {
+        title: 'Mọi dịch vụ đang chạy',
+        description: 'Gom service VibeCloud cùng tài khoản ảo và webhook MONA Pay.',
+    }, () => runTool(async () => {
+        const [vibecloud, monapay] = await Promise.all([
+            clients.vibecloud('/api/services')
+                .then((services) => ({ ok: true, services }))
+                .catch((error) => ({ ok: false, error: toAgentError(error) })),
+            (async () => {
+                try {
+                    const client = createMonaPayClient(config, env, fetchImpl);
+                    const [bankResponse, webhookResponse] = await Promise.all([
+                        client.listBankAccounts({ page: 1, limit: 100 }),
+                        client.listWebhooks(),
+                    ]);
+                    const banks = collection(bankResponse);
+                    const virtualAccounts = (await Promise.all(banks.map(async (bank) => {
+                        const id = typeof bank.id === 'string' ? bank.id : undefined;
+                        return id ? collection(await client.listVirtualAccounts(id, { page: 1, limit: 100 })) : [];
+                    }))).flat();
+                    return { ok: true, bank_accounts: banks, virtual_accounts: virtualAccounts, webhooks: collection(webhookResponse) };
+                }
+                catch (error) {
+                    return { ok: false, error: toAgentError(error) };
+                }
+            })(),
+        ]);
+        return { vibecloud, monapay };
+    }));
+    server.registerTool('cloud_budget_set', {
+        title: 'Đặt ngân sách MONA Cloud',
+        description: 'Đặt giới hạn chi tiêu theo product, project hoặc token.',
+        inputSchema: {
+            scope: z.enum(['product', 'project', 'token']),
+            scope_id: z.string().min(1).max(255),
+            limit_vnd: z.number().int().min(0),
+            period: z.enum(['day', 'month']),
+        },
+    }, (body) => runTool(() => clients.budgetSet(body)));
+    server.registerTool('cloud_budget_get', {
+        title: 'Đọc ngân sách MONA Cloud',
+        description: 'Liệt kê giới hạn và mức đã dùng theo kỳ.',
+    }, () => runTool(() => clients.budgetGet()));
+    server.registerTool('cloud_token_limit', {
+        title: 'Giới hạn chi tiêu của token',
+        description: 'Đặt spend guard riêng cho token hiện tại hoặc token_id chỉ định.',
+        inputSchema: {
+            spend_limit_vnd: z.number().int().min(0),
+            period: z.enum(['day', 'month']),
+            token_id: z.string().min(1).max(255).optional(),
+        },
+    }, ({ spend_limit_vnd, period, token_id }) => runTool(() => clients.tokenLimit(spend_limit_vnd, period, token_id)));
+    server.registerTool('cloud_open_console', {
+        title: 'Mở MONA Cloud Console',
+        description: 'Trả URL console chung để nạp ví, đổi budget hoặc quản lý tài khoản.',
+    }, () => textResult({ url: config.consoleUrl, next_step: `Mở ${config.consoleUrl} trong trình duyệt.` }));
+    server.registerTool('monapay_link', {
+        title: 'Liên kết MONA Pay chuyển tiếp',
+        description: 'Tạm đổi MONA ID thành client credential MONA Pay và cache cục bộ; bỏ khi MONA Pay nhận JWT trực tiếp.',
+    }, () => runTool(() => clients.monapayLink()));
+    server.registerTool('vibecloud_link', {
+        title: 'Liên kết VibeCloud chuyển tiếp',
+        description: 'Xác nhận VibeCloud nhận MONA ID trực tiếp; chỉ đổi thành vc_live token khi upstream còn ở chế độ cũ.',
+    }, () => runTool(() => clients.vibecloudLink()));
+    server.registerTool('vibecloud_create_vps', {
+        title: 'Tạo VPS VibeCloud',
+        description: 'Kiểm tra ví chung rồi tạo LXC VPS; trả job_id để poll.',
+        inputSchema: provisionSchema,
+    }, (body) => runTool(async () => {
+        await clients.spendGuard();
+        return clients.vibecloud('/api/lxc', { method: 'POST', body });
+    }));
+    server.registerTool('vibecloud_create_database', {
+        title: 'Tạo database VibeCloud',
+        description: 'Kiểm tra ví chung rồi tạo MongoDB/PostgreSQL/MySQL; trả job_id để poll.',
+        inputSchema: provisionSchema.extend({ engine: z.enum(['mongodb', 'postgresql', 'mysql']).default('mongodb') }),
+    }, (body) => runTool(async () => {
+        await clients.spendGuard();
+        return clients.vibecloud('/api/databases', { method: 'POST', body });
+    }));
+    server.registerTool('vibecloud_job_status', {
+        title: 'Theo dõi job VibeCloud',
+        description: 'Đọc một job; mặc định poll tới succeeded/failed/cancelled hoặc timeout.',
+        inputSchema: {
+            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),
+        },
+    }, ({ job_id, wait, interval_sec, timeout_sec }) => runTool(() => pollJob(clients, job_id, wait, interval_sec, timeout_sec)));
+    server.registerTool('vibecloud_list_services', {
+        title: 'Danh sách service VibeCloud',
+        description: 'Liệt kê VPS và database của MONA ID hiện tại.',
+    }, () => runTool(() => clients.vibecloud('/api/services')));
+    for (const action of ['start', 'stop', 'rebuild']) {
+        server.registerTool(`vibecloud_${action}`, {
+            title: `${action} service VibeCloud`,
+            description: action === 'stop'
+                ? 'Dừng VPS/database VibeCloud; luôn cho phép dừng để người dùng hạn chế chi phí.'
+                : `${action} VPS/database VibeCloud. 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 () => {
+            if (action !== 'stop')
+                await clients.spendGuard();
+            return clients.vibecloud(`/api/services/${encodeURIComponent(service_id)}/${action}`, { method: 'POST' });
+        }));
+    }
+    server.registerTool('vibecloud_prices', {
+        title: 'Bảng giá VibeCloud',
+        description: 'Đọc đơn giá giờ hiện hành.',
+    }, () => runTool(() => clients.prices()));
+    server.registerTool('vibecloud_packages', {
+        title: 'Gói cấu hình VibeCloud',
+        description: 'Liệt kê package_slug và cấu hình CPU/RAM/đĩa.',
+    }, () => runTool(() => clients.packages()));
+    server.registerTool('vibecloud_agent_deploy', {
+        title: 'Deploy MONA Agent trên VibeCloud',
+        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)));
+    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.',
+    }, () => runTool(() => catalog.list()));
+    server.registerTool('agent_templates_get', {
+        title: 'Chi tiết MONA Agent template',
+        description: 'Đọc README, AGENTS.md, tools, deploy, checklist và skills của một template.',
+        inputSchema: { template: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/) },
+    }, ({ template }) => runTool(() => catalog.get(template)));
+    server.registerTool('agent_deploy', {
+        title: 'Dùng ngay MONA Agent template',
+        description: 'Gọi cùng runtime với vibecloud_agent_deploy.',
+        inputSchema: { template: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/) },
+    }, ({ template }) => runTool(() => agentRuntimeStub(template)));
+    const imported = importedMonaPayTools(config, env, fetchImpl);
+    for (const [name, tool] of Object.entries(imported)) {
+        if (!tool.enabled)
+            continue;
+        const register = server.registerTool.bind(server);
+        register(name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            annotations: tool.annotations,
+            _meta: tool._meta,
+        }, async (...args) => {
+            try {
+                return await normalizeImportedResult(tool.handler(...args));
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        });
+    }
+    server.registerResource('monacloud-llms', 'monacloud://llms', {
+        title: 'MONA Cloud llms.txt tổng',
+        description: 'Bản máy đọc mô tả stack và luồng AI-first của MONA Cloud.',
+        mimeType: 'text/plain',
+    }, async (uri) => ({ contents: [{
+                uri: uri.href,
+                mimeType: 'text/plain',
+                text: `${ENTITY}\n\nHuman chỉ đăng ký MONA ID, nạp tiền và cung cấp OTP/KYC bắt buộc. AI dùng MCP làm phần còn lại.\n\n- cloud_*: tài khoản, ví, ledger, usage, budget, dịch vụ.\n- vibecloud_*: VPS, database, job, start/stop/rebuild, giá/gói.\n- monapay_*: nối ngân hàng, checkout/QR, giao dịch, webhook và email.\n- agent_*: catalog và deploy template.\n\nConsole: ${config.consoleUrl}\nVibeCloud: https://vibecloud.vn\nMONA Pay: https://monapay.vn\n`,
+            }] }));
+    server.registerResource('monacloud-status', 'monacloud://status', {
+        title: 'Trạng thái hệ MONA Cloud',
+        description: 'Health tổng hợp của MONA ID, billing, VibeCloud và MONA Pay.',
+        mimeType: 'application/json',
+    }, async (uri) => {
+        const members = await Promise.all([
+            providerHealth('mona-id', `${config.issuer}/.well-known/openid-configuration`, fetchImpl),
+            providerHealth('billing', `${config.billingUrl}/v1/healthz`, fetchImpl),
+            providerHealth('vibecloud', `${config.vibecloudApi}/api/prices`, fetchImpl),
+            providerHealth('monapay', `${config.monapayApi}/health`, fetchImpl),
+        ]);
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ checked_at: new Date().toISOString(), members }, null, 2) }] };
+    });
+    server.registerPrompt('dung-app-ban-hang-monacloud', {
+        title: 'Dựng app bán hàng có thu tiền trên MONA Cloud',
+        description: 'Chuỗi zero-dashboard: VPS → DB → VA/QR → webhook → deploy.',
+        argsSchema: {
+            app_name: z.string().optional(),
+            framework: z.string().optional(),
+        },
+    }, ({ app_name, framework }) => ({ messages: [{
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `Dựng app bán hàng ${app_name || 'của tôi'} bằng ${framework || 'stack phù hợp'} trên MONA Cloud theo đúng thứ tự:\n1. Gọi cloud_whoami, cloud_balance, vibecloud_packages và vibecloud_prices. Nếu thiếu tiền, gọi cloud_topup rồi dừng để người dùng quét VietQR.\n2. Gọi vibecloud_create_vps và vibecloud_create_database; poll từng job bằng vibecloud_job_status tới succeeded.\n3. Gọi monapay_link nếu MONA Pay còn ở lớp chuyển tiếp. Gọi monapay_whoami; nếu chưa có VA, nối ngân hàng bằng chuỗi monapay_link_bank_start → HỎI OTP → verify → notification_register → HỎI OTP lần 2 → verify. Không tự đoán OTP.\n4. Viết endpoint webhook có HMAC và idempotency theo transaction_code; đăng ký bằng monapay_create_webhook, bắn monapay_test_webhook và đọc monapay_webhook_logs.\n5. Tích hợp monapay_create_checkout hoặc monapay_create_qr vào app, chỉ giao hàng sau CHECKOUT_PAID.\n6. Deploy code lên VPS vừa tạo, kiểm tra health và báo URL/credential cần lưu. Không yêu cầu người dùng mở dashboard ngoài bước nạp tiền/OTP bắt buộc.`,
+                },
+            }] }));
+    return server;
+}

package/dist/templates.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from './config.js';
+type CatalogEntry = {
+    slug: string;
+    name: string;
+    description: string;
+    products: string[];
+};
+export declare class TemplateCatalog {
+    readonly config: Config;
+    readonly fetchImpl: typeof fetch;
+    constructor(config: Config, fetchImpl?: typeof fetch);
+    private assertSlug;
+    list(): Promise<{
+        source: string;
+        templates: CatalogEntry[];
+    }>;
+    get(slug: string): Promise<Record<string, unknown>>;
+}
+export {};

package/dist/templates.js

@@ -0,0 +1,117 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CloudError } from './errors.js';
+import { requestJson } from './http.js';
+const BUILTIN = [
+    { slug: 'cskh-zalo', name: 'CSKH Zalo', description: 'Trả lời khách từ tài liệu shop và chuyển ca khó cho người.', products: ['MONA AI', 'MONA Base', 'Zalo ZNS'] },
+    { slug: 'sales-chot-don', name: 'Sales chốt đơn', description: 'Tư vấn, báo giá, tạo QR MONA Pay và xác nhận tiền vào.', products: ['MONA Pay', 'MONA AI'] },
+    { slug: 'ke-toan-hddt', name: 'Kế toán HĐĐT', description: 'Đọc tiền vào, phát hành hoá đơn điện tử và nhắc công nợ.', products: ['MONA Pay', 'monahddt', 'MONA Mail'] },
+    { slug: 'content-seo', name: 'Content SEO', description: 'Viết và đăng bài theo voice thương hiệu, có gate QC.', products: ['MONA AI'] },
+    { slug: 'noi-bo-kin', name: 'Nội bộ kín', description: 'Trợ lý đọc tài liệu công ty, dữ liệu không rời server.', products: ['VibeCloud', 'MONA Base', 'Ollama'] },
+    { slug: 'tro-giang-academy', name: 'Trợ giảng Academy', description: 'Trợ giảng cho academy của giảng viên.', products: ['mona.academy', 'MONA AI'] },
+];
+const allowedSlug = /^[a-z0-9][a-z0-9-]{0,79}$/;
+const standardFiles = ['README.md', 'AGENTS.md', 'tools.json', 'deploy.md', 'CHECKLIST.md'];
+async function directoryExists(path) {
+    try {
+        return (await readdir(path, { withFileTypes: true })).length >= 0;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function summaryFromReadme(slug, readme) {
+    const lines = (readme || '').split(/\r?\n/).map((line) => line.trim());
+    const name = lines.find((line) => /^#\s+/.test(line))?.replace(/^#\s+/, '') || slug;
+    const description = lines.find((line) => line && !line.startsWith('#')) || 'MONA Agent template';
+    return { slug, name, description, products: [] };
+}
+export class TemplateCatalog {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    assertSlug(slug) {
+        if (!allowedSlug.test(slug)) {
+            throw new CloudError('invalid_template', 'Tên template không hợp lệ.', 'Gọi agent_templates_list rồi dùng đúng slug trong catalog.');
+        }
+    }
+    async list() {
+        if (await directoryExists(this.config.templatesDir)) {
+            const entries = await readdir(this.config.templatesDir, { withFileTypes: true });
+            const templates = [];
+            for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+                if (!entry.isDirectory() || !allowedSlug.test(entry.name))
+                    continue;
+                templates.push(summaryFromReadme(entry.name, await readOptional(join(this.config.templatesDir, entry.name, 'README.md'))));
+            }
+            return { source: this.config.templatesDir, templates };
+        }
+        if (this.config.templatesUrl) {
+            const remote = await requestJson(`${this.config.templatesUrl}/catalog.json`, { fetchImpl: this.fetchImpl });
+            return { source: this.config.templatesUrl, templates: Array.isArray(remote.templates) ? remote.templates : [] };
+        }
+        return { source: 'built-in-wave-1-catalog', templates: BUILTIN };
+    }
+    async get(slug) {
+        this.assertSlug(slug);
+        if (await directoryExists(this.config.templatesDir)) {
+            const directory = join(this.config.templatesDir, slug);
+            let entries;
+            try {
+                entries = await readdir(directory, { withFileTypes: true });
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    throw new CloudError('template_not_found', `Không có template ${slug}.`, 'Gọi agent_templates_list để xem slug hiện có.');
+                }
+                throw error;
+            }
+            const files = {};
+            for (const filename of standardFiles) {
+                const content = await readOptional(join(directory, filename));
+                if (content !== undefined)
+                    files[filename] = content;
+            }
+            const skillsEntry = entries.find((entry) => entry.isDirectory() && entry.name === 'skills');
+            if (skillsEntry) {
+                const skillFiles = await readdir(join(directory, 'skills'), { withFileTypes: true });
+                for (const file of skillFiles) {
+                    if (!file.isFile() || !/\.(md|json|txt)$/i.test(file.name))
+                        continue;
+                    const content = await readFile(join(directory, 'skills', file.name), 'utf8');
+                    files[`skills/${file.name}`] = content;
+                }
+            }
+            return { slug, source: directory, files };
+        }
+        if (this.config.templatesUrl) {
+            const remote = await requestJson(`${this.config.templatesUrl}/templates/${encodeURIComponent(slug)}.json`, { fetchImpl: this.fetchImpl });
+            return { slug, source: this.config.templatesUrl, ...remote };
+        }
+        const template = BUILTIN.find((entry) => entry.slug === slug);
+        if (!template) {
+            throw new CloudError('template_not_found', `Không có template ${slug}.`, 'Gọi agent_templates_list để xem slug hiện có.');
+        }
+        return {
+            ...template,
+            source: 'built-in-wave-1-catalog',
+            status: 'catalog_only',
+            next_step: 'Catalog runtime chưa được phát hành; dùng vibecloud_agent_deploy để kiểm tra trạng thái triển khai.',
+        };
+    }
+}

package/docs/ai-agent.md

@@ -0,0 +1,159 @@
+# MONA Cloud MCP — hướng dẫn cho AI agent
+
+Tài liệu này dành cho Claude, Codex, Cursor và agent dùng Model Context Protocol. Mục tiêu là hoàn thành tích hợp end-to-end mà không yêu cầu người dùng mở dashboard, trừ ba việc hợp lệ: đăng ký MONA ID, nạp tiền và OTP/KYC bắt buộc.
+
+## 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`, `vibecloud_packages` và `vibecloud_prices`.
+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`.
+6. Không giao hàng chỉ dựa vào browser redirect. Chỉ xác nhận đơn sau webhook `CHECKOUT_PAID` hoặc đối soát server-side.
+7. Nếu tool trả `isError`, parse text content thành `{code,message,next_step,request_id?}` và làm theo `next_step`. Không retry vô hạn lệnh ghi.
+
+## Xác thực
+
+MCP dùng OAuth 2.0 Device Authorization Grant với public client `monacloud-mcp`, scope:
+
+```text
+openid profile email product billing-api offline_access
+```
+
+Token store mặc định là `~/.config/monacloud/token.json`, mode `0600`. Access token tự refresh bằng offline refresh token. Trong CI, `MONACLOUD_TOKEN` có thể cung cấp PAT trực tiếp.
+
+Không in hoặc copy token vào source, issue, log, output tool hay nội dung webhook. Sản phẩm đích xác minh JWT MONA ID và audience tương ứng.
+
+### Adapter chuyển tiếp
+
+MONA Pay và VibeCloud có thể chưa nhận JWT MONA ID trực tiếp tại thời điểm wave 1:
+
+- gọi `monapay_link` một lần để nhận/cache `client_id/client_secret` MONA Pay;
+- gọi `vibecloud_link` để xác nhận direct MONA ID; tool chỉ nhận/cache `vc_live_*` khi upstream từ chối JWT và còn bật adapter cũ;
+- linked credential nằm ở `~/.config/monacloud/links.json`, mode `0600`;
+- không gọi link lại ở mỗi request;
+- khi upstream nhận JWT trực tiếp, bỏ adapter mà không đổi tên tool nghiệp vụ.
+
+Nếu tài khoản MONA Pay cũ cần OTP email để link, trả quyền điều khiển cho người dùng ở đúng bước OTP rồi tiếp tục `monapay_link`.
+
+## Luồng dựng app bán hàng
+
+### 1. Kiểm tra account, ví và cấu hình hạ tầng
+
+```text
+cloud_whoami
+cloud_balance
+vibecloud_packages
+vibecloud_prices
+```
+
+Chọn `package_slug` nếu có thể. Chỉ dùng custom sizing khi cần; không gửi đồng thời `package_slug` và `cpu/ram_gb/disk_gb`.
+
+Nếu ví thiếu:
+
+```text
+cloud_topup({ amount: 200000, idempotency_key: "topup:<project>:<stable-id>" })
+```
+
+Giữ cùng idempotency key khi retry cùng một yêu cầu nạp.
+
+### 2. Tạo compute và database
+
+```text
+vibecloud_create_vps({ app_name: "shop-demo", package_slug: "standard-2" })
+vibecloud_create_database({ app_name: "shop-demo", engine: "postgresql", package_slug: "standard-2" })
+```
+
+Mỗi response là job. Dùng:
+
+```text
+vibecloud_job_status({ job_id: "...", wait: true, interval_sec: 3, timeout_sec: 180 })
+```
+
+Chỉ dùng `result`/credential khi trạng thái `succeeded`. Với `failed`, đọc `error`; sửa nguyên nhân rồi mới retry. Không đưa database password vào commit hoặc response công khai.
+
+### 3. Chuẩn bị MONA Pay
+
+```text
+monapay_link
+monapay_whoami
+```
+
+Nếu chưa có tài khoản ngân hàng/VA:
+
+```text
+monapay_link_bank_start
+→ DỪNG, hỏi OTP ACB
+monapay_link_bank_verify_otp
+monapay_notification_register
+→ DỪNG, hỏi OTP ACB lần hai
+monapay_notification_verify_otp
+```
+
+Đây là hai điểm human-in-the-loop bắt buộc. Không yêu cầu người dùng đưa username/password ACB hoặc MONA Pay.
+
+### 4. Viết và test webhook
+
+1. Lấy code mẫu bằng `monapay_generate_webhook_snippet`.
+2. Tạo HTTPS endpoint trong app.
+3. Xác minh `X-Mona-Signature = sha256=HMAC-SHA256(secret, "<timestamp>.<raw_body>")`.
+4. Từ chối timestamp lệch quá 300 giây.
+5. Dùng `transaction_code` làm unique idempotency key.
+6. Đăng ký bằng `monapay_create_webhook` với `HMAC_SHA256` và secret ngẫu nhiên ít nhất 32 ký tự.
+7. Gọi `monapay_test_webhook`; đọc `monapay_webhook_logs` và `monapay_webhook_stats`.
+
+### 5. Thu tiền
+
+Ưu tiên hosted checkout khi app cần link thanh toán:
+
+```text
+monapay_create_checkout({
+  amount: 250000,
+  order_code: "DH_10234",
+  return_url: "https://shop.example/checkout/return",
+  idempotency_key: "checkout:DH_10234"
+})
+```
+
+Dùng `monapay_create_qr` khi đã có đủ thông tin ACB/VA và cần render QR trực tiếp. Sandbox dùng `monapay_sandbox_transaction`; không test bằng tiền thật.
+
+### 6. Deploy và xác minh
+
+Deploy source lên VPS từ credential của job, đưa database connection string qua secret environment, chạy migration, bật HTTPS và gọi health endpoint. Sau đó:
+
+- tạo checkout sandbox;
+- tạo transaction sandbox;
+- xác nhận webhook chỉ xử lý một lần khi event bị gửi lại;
+- xác nhận đơn chuyển `paid` sau webhook;
+- đọc `cloud_services` để báo lại toàn bộ service/VA/webhook;
+- không echo credential nhạy cảm trong báo cáo.
+
+## Spend guard
+
+`vibecloud_create_vps`, `vibecloud_create_database`, `vibecloud_start` và `vibecloud_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ả:
+
+```json
+{
+  "code": "insufficient_funds",
+  "message": "Ví thiếu tiền...",
+  "next_step": "Nạp ví tại https://monacloud.vn/console rồi gọi lại tool."
+}
+```
+
+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. `vibecloud_stop` luôn được phép vì chặn stop có thể làm tăng rủi ro chi phí.
+
+## 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ả.
+
+`agent_deploy` và `vibecloud_agent_deploy` hiện là stub có chủ đích, trả `agent_runtime_pending`; không giả vờ đã provision. Khi nhận code này, có thể đọc template và triển khai thủ công hoặc báo rõ runtime hosted chưa được bật.
+
+## Resource hữu ích
+
+- Đọc `monacloud://llms` khi cần bối cảnh toàn hệ sinh thái.
+- Đọc `monacloud://status` trước khi kết luận lỗi là do credential hoặc request.
+- Dùng prompt `dung-app-ban-hang-monacloud` để lấy chuỗi tác vụ chuẩn.
+
+## Tiêu chí hoàn tất
+
+Một lượt được coi là xong khi app và database chạy, webhook HMAC test pass, sandbox checkout chuyển `paid`, credential nằm trong secret store, và agent báo lại URL cùng trạng thái dịch vụ. Không coi việc “đã tạo job” là hoàn tất; phải poll tới terminal state và kiểm health thực tế.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "monacloud-mcp",
+  "version": "0.1.0",
+  "description": "Unified MCP server for MONA Cloud, MONA Pay, VibeCloud and MONA Agent.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "monacloud-mcp": "dist/index.js"
+  },
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "STATUS.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "monapay-mcp": "^0.3.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "typescript": "^7.0.2"
+  }
+}