Bắt đầu

Hướng dẫn này giúp bạn tạo và chạy một AI App trong vài phút.

Yêu cầu

• Node.js >= 22
• v-miniapp-cli đã cài đặt: npm install -g @v-miniapp/cli
• Tài khoản Developer trên Console (để tạo App ID)

Bước 1: Tạo dự án

v-miniapp-cli create

CLI sẽ hỏi bạn chọn template và tạo cấu trúc thư mục chuẩn:

my-ai-app/
├── server/src/          # MCP Server (Backend)
│   ├── index.ts         # Khởi tạo McpServer, đăng ký tools/resources/skills
│   ├── tools/           # Tool handlers
│   └── db/              # Data layer
├── web/src/             # Widget (Frontend)
│   ├── widgets/         # Mỗi widget một thư mục
│   ├── locales/         # i18n
│   └── global.d.ts      # Type declarations
├── skills/              # Hướng dẫn cho AI
├── app-config.json      # Tên, version, appId
└── package.json

Xem chi tiết cấu trúc tại CLI và Cấu trúc Widget.

Bước 2: Chạy dev server

npm run dev

• MCP Server khởi động tại http://localhost:4000/mcp
• Inspector tự động mở tại http://127.0.0.1:6274/ — cho phép list tools, gọi thử tool, và xem widget render

Xem thêm Inspector.

Bước 3: Khám phá code mẫu

Template ai-app-todo đi kèm một Todo App hoàn chỉnh với 4 tools (list-todos, add-todo, toggle-todo, delete-todo), widget React, và skill.

Server — đăng ký tools và resources bằng cú pháp chuỗi:

server/src/index.ts

import { McpServer } from '@v-miniapp/ai/server'
import { addTodoTool } from './tools/add-tool'
import { listTodoTool } from './tools/list-tool'
// ...

const server = new McpServer()
  .registerResources(['manage-todos'])
  .registerSkills(['list-todos'])
  .registerTool(addTodoTool)
  .registerTool(listTodoTool)
// ...

server.run()

Widget — nhận data từ AI qua useToolInfo, tương tác qua useCallTool:

web/src/widgets/manage-todos/index.tsx

import {
  getStructuredResult,
  renderWidget,
  useCallTool,
  useToolInfo,
} from '@v-miniapp/ai/web'

function TodoApp() {
  const toolInfo = useToolInfo<'list-todos'>()
  const data = getStructuredResult(toolInfo)
  const [todos, setTodos] = useState(data?.todos || [])

  const addTodoTool = useCallTool('add-todo')

  const handleAdd = async () => {
    const result = await addTodoTool.callTool({ text: 'Mua sữa' })
    setTodos(getStructuredResult(result)?.todos ?? [])
  }
  // ...
}

renderWidget(<TodoApp />)

Xem code đầy đủ và giải thích chi tiết tại Todo AI App Showcase.

Bước 4: Build & test production

npm run build
npm run start

Server production chạy tại http://localhost:3000/mcp.

Xem thêm Build cho Production.

Bước tiếp theo

Chủ đề	Link
Kiến trúc tổng thể	Framework Overview
MCP Server chi tiết	MCP Server
Cấu trúc Widget	MCP Apps
Ví dụ hoàn chỉnh	Todo AI App
CLI & build	CLI
JS APIs	JS APIs Overview
Chuẩn thiết kế	UX Guidelines · UI Guidelines