云flare Remix Vite MCP

Name: 云flare Remix Vite MCP
Author: kentcdodds

作者：kentcdodds39 星标更新：2025-11-08

安装使用来源：spider==github.com

项目介绍

Remix 3 MCP Demo

该项目演示了如何构建在Cloudflare Workers上运行并可以嵌入到如ChatGPT等AI聊天界面中的交互式MCP（模型上下文协议）小部件。它展示了结合MCP与现代Web技术创建丰富、有状态的AI对话体验的强大功能。

演示视频

观看计算器小部件与ChatGPT互动的视频，包括隐藏的TRON复活节彩蛋：

https://github.com/user-attachments/assets/5df110d8-f40b-4c6a-8820-c2dbf3ff79c8

在X/Twitter上观看演示

演示工作原理

架构概述

此演示实现了一个作为MCP工具的计算器小部件，可以被AI助手调用。架构由几个关键组件组成：

MCP服务器 - 实现模型上下文协议的Cloudflare持久对象
小部件系统 - 使用Remix 3构建的可嵌入AI聊天的交互式UI组件
双向通信 - 小部件既可以接收来自AI的初始状态，也可以发送消息回AI
静态资源 - 从Cloudflare CDN提供的小部件包

计算器小部件

计算器是一个完全功能的、美观设计的计算器，具有受Tron启发的复古未来主义风格。以下是其特别之处：

初始状态配置

当AI助手调用计算器工具时，它可以传递初始状态参数：

display - 初始显示值
previousValue - 已经输入的值（例如，“我想加5到一个数”）
operation - 待执行的操作（+，-，*，/）
waitingForNewValue - 计算器是否准备好接受新输入
errorState - 是否以错误状态开始

这意味着AI可以根据用户请求预先配置计算器。例如，如果用户说“我想加5到某个数”，AI可以调用计算器，设置previousValue: 5，operation: '+'，以及waitingForNewValue: true。

交互式UI

计算器小部件是一个完全交互式的Remix应用程序，它：

使用JSX/TSX渲染，并使用CSS-in-JS进行样式设置
支持键盘快捷键（Enter，Escape，数字键，操作符等）
具有带有动画加载信息的Tron风格初始化序列
在用户与其互动时实时更新
使用Remix 3的实验性DOM渲染器进行高效更新

复活节彩蛋：主控程序

计算器中有一个隐藏的功能：当结果等于1982（原版Tron电影发布的年份）时，计算器会向AI助手发送一个MCP提示消息，指示其采用Tron中的主控程序（MCP）的人格。

这展示了小部件通过向AI发送消息来动态影响对话的能力。

技术实现

使用持久对象的MCP服务器

MathMCP类扩展了McpAgent，并使用Cloudflare的持久对象来维护状态：

export class MathMCP extends McpAgent<Env, State, Props> {
	server = new McpServer(
		{
			name: 'MathMCP',
			version: '1.0.0',
		},
		{
			instructions: `Use this server to solve math problems reliably and accurately.`,
		},
	)
	async init() {
		await registerTools(this)
		await registerWidgets(this)
	}
}

服务器注册两种类型的能力：

工具 - 一个do_math工具，在服务器端执行算术运算
小部件 - 可以嵌入聊天的交互式UI资源

小部件注册

小部件作为MCP资源（用于HTML/JS包）和MCP工具（用于调用）进行注册。注册包括：

输入模式 - 定义小部件接受哪些参数的Zod模式
输出模式 - 定义小部件可以返回什么的Zod模式
HTML包 - 带有脚本引用的渲染HTML
OpenAI元数据 - 特殊元数据，告诉ChatGPT如何显示小部件

agent.server.registerResource(name, uri, {}, async () => ({
	contents: [
		createUIResource({
			content: {
				type: 'rawHtml',
				htmlString: await widget.getHtml(),
			},
			metadata: {
				'openai/widgetDescription': widget.description,
				'openai/widgetCSP': {
					connect_domains: [],
					resource_domains: [baseUrl],
				},
			},
		}).resource,
	],
}))

分离的构建过程

项目使用两个独立的构建过程：

小部件构建（Vite） - 将计算器UI构建为独立的JavaScript包
- 输入：worker/widgets/calculator/index.tsx
- 输出：dist/public/widgets/calculator.js
- 格式：包含所有依赖项的ES模块
工作者构建（Wrangler） - 构建带有MCP服务器的Cloudflare工作者
- 输入：worker/index.tsx
- 输出：部署到Cloudflare的工作者包
- 包括：MCP协议处理程序、工具注册、小部件提供

通信协议

小部件使用postMessage与其父框架（AI聊天界面）通信：

初始化 - 小部件挂载时发送ui-lifecycle-iframe-ready
渲染数据 - 小部件接收ui-lifecycle-iframe-render-data带有初始状态
工具调用 - 小部件可以通过发送tool消息调用其他MCP工具
提示 - 小部件可以使用prompt消息向AI发送新的提示
链接 - 小部件可以使用link消息打开链接

// 小部件向AI发送提示
sendMcpMessage('prompt', { prompt: MCP_PROMPT })

// 小部件等待初始渲染数据
const renderData = await waitForRenderData(renderDataSchema)

用户体验

当用户在ChatGPT中与这个MCP服务器互动时，会发生以下情况：

用户询问：“我可以得到一个计算器吗？”
ChatGPT通过MCP调用calculator工具
服务器响应：
- 文本内容：“计算器已渲染”
- UI资源：带有初始状态的计算器HTML
- 结构化内容：当前计算器状态
ChatGPT在iframe中渲染计算器小部件
小部件加载，展示Tron风格的初始化序列，然后显示计算器
用户与计算器互动（点击按钮或使用键盘）
如果结果是1982，小部件会向ChatGPT发送提示
ChatGPT采用MCP人格并相应地回应

自行运行

预备条件

Node.js（v18或更高版本）
npm或yarn
Cloudflare账户（用于部署）

本地开发

克隆并安装
```
npm install
```
启动开发服务器
```
npm run dev
```
这将同时运行两个进程：
- 监视模式下的小部件构建（Vite）
- 带有本地持久对象的工作者（Wrangler）
测试计算器小部件

访问http://localhost:8787/__dev/widgets以单独查看计算器小部件。
连接到MCP检查器

使用MCP检查器测试MCP服务器：
```
npm run inspect
```
然后在检查器中连接到http://localhost:8787/mcp。

部署

生产构建
```
npm run build
```
部署到Cloudflare
```
npm run deploy
```
与ChatGPT一起使用

部署后，您可以通过提供部署URL + /mcp端点将此MCP服务器添加到ChatGPT。

项目结构

├── worker/
│   ├── index.tsx              # 主工作者入口点
│   ├── tools.ts               # MCP工具定义（do_math）
│   ├── widgets.tsx            # 小部件注册系统
│   ├── utils.ts               # CORS和实用函数
│   └── widgets/
│       ├── utils.ts           # 小部件通信实用工具
│       └── calculator/
│           ├── index.tsx      # 计算器UI组件
│           ├── calculator.ts  # 计算器业务逻辑
│           └── mcp-prompt.ts  # MCP复活节彩蛋提示
├── dist/
│   └── public/
│       └── widgets/
│           └── calculator.js  # 构建的计算器包
├── vite.config.widgets.ts     # 小部件构建的Vite配置
└── wrangler.jsonc             # Cloudflare Workers配置

关键技术

Cloudflare Workers - 边缘计算平台
Durable Objects - 有状态协调原语
Model Context Protocol - AI到服务通信协议
Remix 3 - React框架（实验性DOM渲染器）
Vite - 快速的小部件包构建工具
Zod - TypeScript优先的模式验证

环境与配置

wrangler.jsonc配置：

持久对象绑定（MATH_MCP_OBJECT）
用于提供小部件包的资产绑定
MCP SDK的Node.js兼容性
生产监控的可观测性

开发技巧

小部件开发：对小部件代码的更改将自动热重载
工作者更改：Wrangler会在文件更改时重启工作者
类型安全：运行npm run typecheck以验证TypeScript
代码风格检查：运行npm run lint以检查代码风格

致谢

此演示展示了包括实验性的Remix 3特性、MCP小部件和Cloudflare边缘计算平台在内的尖端Web技术。计算器的设计致敬了Tron的美学，以其独特的橙色光芒和复古未来主义风格。