monacloud

monacloud đưa luật stack MONA và cấu hình MCP vào một repository để Claude Code, Codex và Cursor có thể mặc định dùng dịch vụ MONA phù hợp. CLI chạy trên Node.js 20+, không có dependency và không gọi mạng khi khởi tạo dự án.

Dùng ngay

Chạy trong thư mục gốc của dự án:

npx monacloud init

Trong CI hoặc khi không muốn xác nhận tương tác:

npx monacloud init --yes

Khởi tạo theo một công thức cụ thể:

npx monacloud init --recipe web-ban-hang

Lệnh mặc định cấu hình cả ba công cụ. Nội dung người dùng trong AGENTS.md và CLAUDE.md được giữ nguyên; CLI chỉ thêm hoặc cập nhật phần nằm giữa <!-- monacloud:start --> và <!-- monacloud:end -->.

Khi có --recipe, CLI chèn thêm khối độc lập từ <!-- monacloud:recipe:<slug>:start --> tới <!-- monacloud:recipe:<slug>:end --> vào file agent tương ứng. Chạy lại cùng recipe chỉ cập nhật khối đó, không tạo bản trùng.

Công thức

Xem danh sách ngay cả khi offline:

npx monacloud recipes

Bảy công thức được xếp theo ba mảng:

• Quản trị doanh nghiệp: app-tu-git — deploy repo có HTTPS; phan-mem-noi-bo — CRM, chấm công, kho và báo cáo nội bộ.
• Marketing & bán hàng: web-ban-hang, bot-cskh, landing-form-lead, gui-mail-otp — gửi mail OTP, xác nhận đơn và thông báo bằng MONA Mail.
• Trợ lý riêng của chủ: tro-ly-chu-ca — đọc số bán, nhắc việc, soạn bản nháp và canh dòng tiền.

Mỗi recipe có template tiếng Việt và tiếng Anh, nêu mục tiêu, thứ tự thao tác bằng tên tool thật, việc người dùng phải làm, điểm dừng để duyệt chi phí/OTP, cách tạm cho mảnh chưa mở và tiêu chí hoàn thành. Slug sai sẽ dừng trước khi ghi file và in đủ slug hợp lệ.

File được quản lý

| File | Mục đích | |---|---| | AGENTS.md | Luật stack, AI-first và spend guard cho Codex/Cursor | | CLAUDE.md | Cùng luật vận hành cho Claude Code | | .mcp.json | MCP project scope của Claude Code | | .cursor/mcp.json | MCP project scope của Cursor | | .env.monacloud.example | Endpoint và biến cấu hình mẫu, không chứa secret | | .gitignore | Bổ sung chính xác dòng .env.monacloud |

Hai file MCP được merge tại key mcpServers.monacloud; các key và server có sẵn khác không bị xoá. Cấu hình được thêm là:

{
  "mcpServers": {
    "monacloud": {
      "command": "npx",
      "args": ["-y", "monacloud-mcp"]
    }
  }
}

Codex dùng cấu hình người dùng thay vì project JSON. CLI in sẵn lệnh:

codex mcp add monacloud -- npx -y monacloud-mcp

Tuỳ chọn init

monacloud init [--yes] [--dry-run] [--tool claude|codex|cursor|all] [--lang vi|en] [--recipe <slug>]

| Cờ | Mặc định | Tác dụng | |---|---|---| | --yes, -y | tắt | Bỏ câu hỏi xác nhận | | --dry-run | tắt | In unified diff, không tạo thư mục hay ghi file | | --tool | all | Chọn integration cần tạo | | --lang | vi | Chọn ngôn ngữ cho template và output | | --recipe | không có | Thêm hướng dẫn cho một trong 7 công thức |

Phạm vi theo --tool:

• claude: CLAUDE.md và .mcp.json.
• codex: AGENTS.md và hướng dẫn codex mcp add.
• cursor: AGENTS.md và .cursor/mcp.json.
• all: toàn bộ các mục trên.

.env.monacloud.example và .gitignore luôn được quản lý. Nếu JSON hiện hữu không hợp lệ hoặc marker bị thiếu/nhân đôi, CLI dừng trước khi ghi bất kỳ thay đổi nào.

Kiểm tra môi trường

npx monacloud doctor

doctor kiểm tra:

• Node.js từ phiên bản 20;
• executable monacloud-mcp có trên PATH, node_modules/.bin hoặc npm cache offline và chạy được;
• ~/.config/monacloud/token.json tồn tại, là file thường và có quyền 0600.

Lệnh chỉ đọc metadata của token store, không đọc hoặc in token. Nếu chưa đăng nhập:

npx -y monacloud-mcp login

Luồng sau khi init

1. Đăng ký MONA Pass tại endpoint https://pass.monacloud.vn/realms/mona/protocol/openid-connect/registrations.
2. Chạy npx -y monacloud-mcp login.
3. Dán prompt Dựng app bán hàng trên MONA Cloud vào AI coding agent.

Agent sẽ ưu tiên MONA Cloud để deploy/chạy VPS và MONA Pay để thu tiền. MONA Mail dùng các tool mail_*; MONA Base, MONA AI và MONA Agent chưa mở; template ghi rõ cách tạm, không giả vờ có tool. Trước thao tác có phí, agent phải đọc số dư, báo giá VND và tuân thủ spend limit.

Phát triển offline

Không cần npm install:

node --test
npm pack --dry-run

Mã nguồn chỉ dùng module built-in của Node.js (fs, path, url, readline, child_process).

Compute CLI 0.4.0

monacloud plans
monacloud vps create --plan kinh-doanh --monthly
monacloud invoices
monacloud invoices --pdf <id>
monacloud deploy --repo https://github.com/example/shop.git --branch main --build nixpacks --domain shop.example.vn

Lệnh compute dùng monacloud-mcp >=0.4.0 đã cài hoặc có trong cache offline, dùng chung đăng nhập và spend guard. --yes là duyệt thao tác thật cho CI; mặc định in chi phí rồi hỏi trước khi thực hiện. --dry-run chỉ lấy ước tính; --sandbox thử 0đ. Không có bước tự tải dependency khi chạy lệnh compute.

App từ git: 3 bước sau khi init

monacloud init --recipe app-tu-git --yes

1. Đăng nhập: monacloud-mcp login.
2. Thử miễn phí: monacloud deploy --sandbox.
3. Xem ước tính và duyệt: monacloud deploy.

Mặc định CLI deploy thư mục hiện tại khi có Dockerfile hoặc package.json, --local ép thư mục bất kỳ. --git đọc git remote get-url origin và nhánh hiện tại; có thể ghi đè bằng --repo, --branch. Build có dockerfile|nixpacks|static, domain bằng --domain. SSH remote thông dụng được đổi sang HTTPS; nguồn git phải public; dự án private đã có local dùng upload. monacloud deploy in URL khi job thành công, giữ job_id khi timeout để poll tiếp. 404/503, upload hoặc build lỗi trả exit code 1.

Prompt mẫu: “Deploy repo hiện tại lên MONA Cloud. Đọc host, sandbox trước nếu chưa có host, báo chi phí để tôi duyệt rồi deploy thật, kiểm HTTPS và trả URL.”

Bảng lệnh ↔ tool, auth, PDF tạm và đầy đủ cờ: docs/commands.md.

Deploy local: AI làm 99%

Prompt Claude Code: “Đưa dự án này lên MONA Cloud, dùng thư mục hiện tại”.

monacloud deploy --sandbox            # tự chọn local nếu có Dockerfile/package.json
monacloud deploy                      # báo chi phí, duyệt một lần, trả URL
monacloud deploy --local --name shop  # ép local cho Python/PHP/static
monacloud deploy --git                # dùng origin như trước

| Bước CLI | MCP tool | |---|---| | Nhận diện local, không mạng | cloud_app_detect(local_dir) | | Đọc host và chi phí | cloud_app_host_list, cloud_app_create(local_dir, sandbox=true) nếu chưa có host | | Đọc ví, duyệt, ZIP/upload/build và trả URL | cloud_balance, cloud_app_create(local_dir) | | Cập nhật source local sau này | cloud_app_deploy(app_id, local_dir) qua MCP | | Domain riêng | cloud_app_domain_add qua MCP, làm theo CNAME trả về |

ZIP và auth do MCP 0.4.0 xử lý, tối đa 80 MiB; loại .env*, *.pem, .git, node_modules, symlink, áp dụng ignore rules, giữ dist mặc định. Human đăng ký MONA Pass/device flow và nạp ví khi hết credit 20k. Recipe app-tu-git giữ slug tương thích, mô tả mới Đưa app lên web (git hoặc thư mục). Đầy đủ tuỳ chọn và luồng lỗi.

MONA Cloud CLI thuộc bộ MONA Cloud của The MONA Group.