MCP Bubble Wrap

MCP气泡膜

一个复杂的MCP（模型上下文协议）服务器，带有基于React的交互式小部件，灵感来自 OpenAI应用SDK示例.

特性

• 🫧 交互式气泡膜小部件：弹出带有平滑CSS动画的虚拟气泡
• ⚡ 现代建筑系统：Vite驱动的开发和生产构建
• 🎨 基于React的小部件：易于创建和维护UI组件
• 🎨 Tailwind CSS：实用程序优先的CSS框架，支持主题
• 🔄 热模块更换：快速开发，即时更新
• 📦 优化构建：内联资产便于部署
• 🌐 应用SDK兼容：与ChatGPT和OpenAI Apps SDK无缝协作

项目结构

mcp-bubble-wrap/
├── src/
│   ├── widgets/                # React-based widgets
│   │   ├── styles.css          # Shared Tailwind styles
│   │   ├── components/         # Shared widget components
│   │   │   └── Layout.tsx
│   │   ├── hooks/              # Shared hooks
│   │   │   ├── types.ts
│   │   │   └── use-openai-global.ts
│   │   └── bubble-wrap/
│   │       ├── BubbleWrap.tsx  # Widget component
│   │       ├── index.tsx       # Widget entry point
│   │       └── types.ts        # Widget types
│   ├── utils/                  # Shared utilities
│   │   └── logger.ts
│   ├── mcp-server.ts           # MCP server implementation
│   └── index.ts                # Server entry point
├── build-widgets.mts           # Widget build orchestrator
├── assets/                     # Built widget assets (generated)
├── dist/                       # Compiled server code (generated)
├── vite.config.mts             # Vite configuration for dev/build
├── tailwind.config.mjs         # Tailwind CSS configuration
├── postcss.config.mjs          # PostCSS configuration
└── package.json

设置

pnpm install

发展

开始一切

使用热重新加载运行完整的开发堆栈：

pnpm dev

这将开始：

1. 小部件开发服务器 （端口4444）-带HMR的Vite开发服务器
2. MCP服务器 （端口5678）-带有vite节点的TypeScript服务器
3. MCP检查员 -交互式测试UI

单个命令

# Widget development only
pnpm dev:widgets

# Build widgets
pnpm build:widgets

# Build server
pnpm build:server

# Serve built widgets
pnpm serve:widgets

构建

为生产构建服务器和小部件：

pnpm build

这将：

1. 编译TypeScript服务器代码 dist/
2. 将React小部件捆绑到 assets/ 带有哈希文件名
3. 为每个小部件生成HTML文件

环境变量

• BASE_URL -HTML生成中小部件资产的基本URL（默认值： http://localhost:5678)

- 注意：当前未使用的资源在HTML中内联 - 对于生产环境，如果为外部资源提供服务，请将其设置为部署的资产URL

• PORT -MCP服务器端口（默认值： 5678)

例子：

BASE_URL=https://your-cdn.com pnpm run build:widgets
PORT=3000 pnpm start

生产

pnpm start

创建新小部件

1. 在下创建新目录 src/widgets/:

src/widgets/my-widget/
├── MyWidget.tsx    # React component
└── index.tsx       # Entry point (imports shared styles.css)

1. 入口点模板(index.tsx):

import { createRoot } from "react-dom/client"
import MyWidget from "./MyWidget"

const rootEl = document.getElementById("my-widget-root")
if (rootEl) {
  createRoot(rootEl).render()
}

export { MyWidget }
export default MyWidget

1. 小部件组件模板(MyWidget.tsx):

import { useOpenAiGlobal } from "../hooks/use-openai-global.js"
import { Layout } from "../components/Layout.js"

interface MyWidgetProps {
  // Your props from the MCP tool
  message?: string
}

export function MyWidget() {
  // Get the structured content passed from the MCP tool
  const toolOutput = useOpenAiGlobal("toolOutput") as MyWidgetProps

  return (
    
      

        

          {toolOutput?.message || "Hello World"}
        

      

    
  )
}

export default MyWidget

1. 构建和测试：

pnpm build:widgets
pnpm dev

小部件将自动被发现和构建！

使用Tailwind CSS进行造型

所有小部件都可以访问Tailwind CSS实用程序类。这 Layout 组件自动处理：

• 主题检测：自动检测并应用OpenAI全局数据中的主题
• 布局约束：向父窗口报告大小更改
• 响应式设计：提供全尾风响应式公用设施

样式示例：

  
Loading...

小部件库

在开发过程中，请访问 http://localhost:4444 查看所有可用的小部件。

MCP检查员

MCP检查器提供了一个交互式UI，用于测试您的MCP服务器：

# Development mode (connects to local server)
pnpm inspect:dev

# Production mode
pnpm inspect:prod

建筑

小部件构建系统

构建系统的灵感来自OpenAI Apps SDK示例：

1. 发现：自动查找所有 src/widgets/**/index.{tsx,jsx} 文件
2. 捆绑：每个小部件都与Vite捆绑成一个独立的模块
3. 哈希：资产使用内容哈希进行版本控制，以破坏缓存
4. HTML生成：创建可以直接提供的独立HTML文件

MCP服务器集成

MCP服务器加载并提供构建的小部件HTML：

1. 从以下位置读取小部件HTML assets/ 目录
2. 通过传递到Apps SDK createUIResource
3. 在ChatGPT或其他Apps SDK客户端中内联呈现

Props通信

小部件通过OpenAI全局对象接收数据：

// In your widget - access toolOutput from OpenAI globals
const toolOutput = useOpenAiGlobal("toolOutput") as MyProps

// The server passes data via structuredContent
return {
  structuredContent: {
    bubbleCount: validBubbleCount,
  },
}

// This structuredContent becomes available as toolOutput in the widget

部署

Render.com

该项目包括 render.yaml 为了便于部署到Render：

1. 将代码推送到GitHub
2. 将存储库连接到Render
3. 设置环境变量：

- BASE_URL：将为您的资产提供服务的URL

自定义部署

1. 构建项目：

pnpm run build

1. 部署：

- 上传 dist/ 目录到您的服务器 - 上传 assets/ 目录（内嵌JS/CSS的HTML文件） - 启动服务器： node dist/index.js - 默认情况下，服务器将在端口5678上运行（配置为 PORT 任何人）

依赖项

运行时

• react & react-dom：UI框架
• @mcp-ui/server：MCP UI资源创建
• @modelcontextprotocol/sdk：MCP服务器SDK
• express：MCP协议的HTTP服务器
• cors：CORS中间件
• zod：架构验证
• chalk：终端颜色和日志记录

发展

• vite：构建工具和开发服务器
• @vitejs/plugin-react：对Vite的React支持
• tsx：TypeScript执行
• vite-node：使用热重载运行TypeScript服务器
• fast-glob：构建系统的文件发现
• tailwindcss：实用程序优先的CSS框架
• postcss：CSS转换工具
• autoprefixer：自动处理供应商前缀
• concurrently：并行运行多个命令
• prettier：代码格式

灵感

该项目结构深受优秀项目的启发 OpenAI应用SDK示例，特别是他们的方法：

• 小部件构建编排
• 多入口点开发
• 资产哈希和版本控制
• 开发服务器设置

许可证

麻省理工学院