ZMP-MCP 🚀

ZMP-MCP is an official-grade Model Context Protocol (MCP) server engineered for Zalo Mini App (ZMP) development, automated validation, and cloud deployment.

It bridges AI Coding Assistants (Antigravity, Claude Desktop, Cursor, VS Code / Cline, Windsurf) directly with the Zalo Mini App Platform ecosystem.

🌟 Highlights & Solved Problems

• 🔄 Bulletproof Cloud Deployment: Natively handles chunked uploads via Zalo Developer API. Fixes the notorious The 'versionStatus' is invalid bug by enforcing standard TESTING / DEVELOPMENT statuses.

• ⚡ Zero-Config Asset Synchronization: Automatically inspects Vite / Webpack build outputs and synchronizes listCSS, listSyncJS, and listAsyncJS into app-config.json and app.json. Eliminates the common "No asset defined" deployment error.

• 🛡️ Pre-flight Validation: Automatically checks bundle size constraints (max 10MB zip, max 3MB per file) and validates file extensions against Zalo's strict whitelist (.css, .js, .json, .png, .woff2, etc.) before uploading.

• 🔐 Developer Authentication: Generate QR codes for mobile Zalo scanning directly in the terminal, check login status, and manage project .env tokens seamlessly.

• 🎨 Modern Project Scaffolding: Create production-ready Zalo Mini Apps with React 18, ZAUi, Vite, and Dark Mode zero-flicker compliance out of the box.

Related MCP server: Somewhere MCP

🛠️ Available MCP Tools

🛡️ Policy Audit CLI

The same censorship-policy engine as zmp_policy_audit runs from the command line. It exits with code 1 when there is a violation, so CI can block a non-compliant build:

npx -y github:nguyenquocanhz/zmp-mcp audit ./my-mini-app        # text report
npx -y github:nguyenquocanhz/zmp-mcp audit ./my-mini-app --json # JSON report

npm run build also emits dist/zmp-audit.cjs, a dependency-free copy you can drop into a Mini App project as zmp-audit.js to run offline (node zmp-audit.js). Edit the rules in src/policy/engine.ts, never the copy.

🚀 Quickstart & Setup (Zero Configuration via npx)

No need to clone or hardcode local paths. You can execute zmp-mcp directly via npx:

npx -y github:nguyenquocanhz/zmp-mcp

Configuration for AI Clients

1. Claude Code CLI & Claude Desktop

Via Claude Code CLI:

/mcp add zmp-mcp npx -y github:nguyenquocanhz/zmp-mcp

Via claude_desktop_config.json:

{
  "mcpServers": {
    "zmp-mcp": {
      "command": "npx",
      "args": ["-y", "github:nguyenquocanhz/zmp-mcp"]
    }
  }
}

2. OpenAI Codex CLI & Desktop

Via Codex CLI:

codex mcp add zmp-mcp -- npx -y github:nguyenquocanhz/zmp-mcp

Via ~/.codex/config.toml:

[mcp_servers."zmp-mcp"]
command = "npx"
args = [ "-y", "github:nguyenquocanhz/zmp-mcp" ]

3. Antigravity / Gemini CLI

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "zmp-mcp": {
      "command": "npx",
      "args": ["-y", "github:nguyenquocanhz/zmp-mcp"]
    }
  }
}

4. Cursor / Windsurf

In Cursor settings under Features > MCP Servers:

• Name: zmp-mcp

• Type: command

• Command: npx -y github:nguyenquocanhz/zmp-mcp

💡 Typical Agent Workflows

1. Create a New Zalo Mini App

"Agent, create a new Zalo Mini App named coffee-shop titled 'Quán Cà Phê Zalo' with template zaui-blank in D:/Projects/coffee-shop."

The agent calls zmp_create_app to generate the complete project with Dark Mode, ZAUi layout, and Vite setup.

2. Validate & Build

"Build the project and make sure all assets are registered in app-config.json."

The agent executes zmp_build, producing the bundle and automatically mapping assets/index.xxx.css and assets/index.xxx.js into app-config.json.

3. Deploy to Testing

"Deploy this mini app as a Testing version with description 'Release v1.0.0'."

The agent executes zmp_deploy, packaging www/, uploading chunks to https://zmp-api.developers.zalo.me/app/upload-chunk, and returning the test URL (https://zalo.me/s/...) with quota report.

4. Webhook Verification & Local Testing (Decree 13 Compliance)

"Start a webhook listener to test Zalo user data deletion events and verify signatures."

The agent executes zmp_manage_webhook_listener (with action: start, port: 8086), giving you a ready-to-test endpoint for tunneling (ngrok http 8086) and verifying signatures with zmp_verify_webhook.

📄 License

MIT © Nguyen Quoc Anh