Tổng quan về framework

Framework cung cấp giải pháp phát triển AI App theo chuẩn @modelcontextprotocol/ext-apps — đặc tả mở rộng của MCP dành cho UI widget trong AI chat, không phụ thuộc vào bất kỳ vendor nào. Framework được tối ưu để chạy trên V-App, đồng thời tương thích với các host hỗ trợ ext-apps khác như ChatGPT (GPT App).

Framework được xây dựng để:

• Cung cấp đầy đủ các JSAPIs và Components cần thiết.
• Khai báo tools, skills và UI (resource, CSP, securitySchemes) theo chuẩn ext-apps.
• Xây dựng MCP server và widget theo cấu trúc được định sẵn.
• Tuân thủ các yêu cầu về policy và security.
• Chuẩn hóa cách giao tiếp giữa UI Widget và MCP Server.
• Hỗ trợ đầy đủ các types để quá trình phát triển app dễ dàng hơn.

Kiến trúc

Người dùng  →  AI Agent  →  MCP Server
                               │  ├── Tools   (xử lý logic, trả dữ liệu)
                               │  └── Skills  (hướng dẫn AI gọi đúng tool)
                               │
                               ▼  structuredContent
                            Host (V-App)
                               │  mở widget
                               ▼
                            Widget (React)
                               ├── useToolInfo()   ← nhận kết quả từ AI
                               └── useCallTool()   ← tự gọi tool khi user tương tác

• Tools — handler trên server xử lý yêu cầu, trả về content (AI đọc) và structuredContent (widget đọc)
• Skills — file SKILL.md hướng dẫn AI biết khi nào nên gọi tool nào
• useToolInfo — hook nhận kết quả khi AI vừa gọi tool và mở widget (passive)
• useCallTool — hook cho phép widget tự gọi tool khi người dùng tương tác (active)

Cấu trúc của AI App

<app-root>/
├── server/                # MCP Server (Backend logic)
│   ├── src/
│   │   ├── index.ts       # Entry point, MCP server initialization
│   │   ├── tools/         # Tool handlers (data & render tools)
│   │   ├── resources/     # Resource templates (UI definitions)
├── web/                   # Widget UI (Frontend - React/Vite)
│   ├── src/
│   │   ├── widgets/       # UI Components (e.g., todo-list.tsx)
│   │   ├── hooks/         # Custom hooks for Host communication
│   ├── vite.config.ts
├── skills/                # Agent Context & Instructions
│   └── <skill-name>/
│       └── SKILL.md       # Markdown + YAML frontmatter
├── app.config.json        # Central config: App ID, CSP, OAuth, Tool mapping
├── .env                   # Environment variables (Secrets, MCP URL)
└── package.json           # Root workspace configuration

Cài đặt

npm install @v-miniapp/ai

Sau khi cài đặt, import theo từng phía:

• Server: import { McpServer } from '@v-miniapp/ai/server' — xem MCP Server
• Widget: import { AppProvider, useCallTool, ... } from '@v-miniapp/ai/web' — xem MCP Apps

Các thành phần trong framework

• @v-miniapp/ai/server: Cung cấp các hàm để đăng ký Tools, Skills, Resources theo MCP SDK.
• @v-miniapp/ai/web: Hỗ trợ React component, Provider và Hooks để có thể render widget và tương tác với MCP Server.

Tài liệu chi tiết

Chủ đề	Mô tả
MCP Server	Khởi tạo server, đăng ký tools, resources, skills, prompts
MCP Apps (Widget UI)	AppProvider, hooks giao tiếp với server và host
Khai báo Skills	Tạo file SKILL.md, binding tools, đăng ký skill
Host Context	Đọc thông tin môi trường từ host: theme, platform, timezone, v.v.
Đa ngôn ngữ	Thiết lập i18n, đọc locale từ hostContext