Harijoe Piano MCP

钢琴小工具-天桥演示

该项目演示了使用Skybridge构建的交互式钢琴小部件，允许用户在ChatGPT对话中直接播放、录制和保存音乐作品。

Demo

这个项目提供了什么

交互式钢琴小部件

钢琴小部件是一种在ChatGPT内运行的功能齐全的乐器。用户可以：

• 播放笔记：使用屏幕键盘或电脑键盘弹奏钢琴音符（A3至D5范围）
• 记录表演：开始录制，以精确的时间捕捉一系列音符
• 保存歌曲：为录制的表演命名并保存以供以后播放
• 播放已保存的歌曲：以准确的时间重播以前录制的歌曲
• 管理库：查看所有已保存的歌曲及其持续时间和创建日期，并删除不再需要的歌曲

钢琴小部件具有以下功能：

• 使用Soundfont乐器实时播放音频
• 精确的定时捕捉，实现准确的歌曲回放
• 跨会话持久存储保存的歌曲
• 双语支持（英语/法语），具有自动区域设置检测功能
• 响应式设计，适应不同的屏幕尺寸

天桥特色展示

该项目展示了Skybridge框架的几个关键功能：

1. 小部件注册 (server.widget())

钢琴小部件使用注册为MCP工具 server.widget()，使其成为ChatGPT可以在对话期间调用的交互式工具。

2. 小部件安装 (mountWidget)

React组件是通过以下方式挂载的 mountWidget() 从 skybridge/web，它处理React应用程序和ChatGPT的iframe环境之间的集成。

3. 国际化 (useLocale)

小部件使用 useLocale() 钩子自动检测并适应用户的语言偏好，根据ChatGPT的区域设置以英语或法语显示UI文本。

4. 持续状态管理 (createStore)

小部件使用 createStore() 为保存的歌曲实现持久存储。这演示了如何在小部件实例和对话之间维护状态，允许用户建立一个随时间持续的录制歌曲库。

5. 开发经验

• 快速集成：在开发过程中使用Skybridge的Vite插件进行热模块更换
• TypeScript支持：整个应用程序的全类型安全
• 热模块替换：React组件的更改会立即反映在ChatGPT中，而无需重新连接

入门指南

先决条件

• Node.js 22+（见 .nvmrc 确切版本）
• pnpm（与一起安装 npm install -g pnpm)
• 哔哔

热模块更换（HMR）的本地开发

1.克隆和安装

git clone 
cd apps-sdk-template
pnpm install

2.启动开发服务器

从根目录运行开发服务器：

pnpm dev

此命令在端口3000上启动express服务器。此服务器打包：

• MCP端点位于 /mcp -又名ChatGPT应用后端
• Vite HMR开发服务器上的React应用程序，也称为ChatGPT应用程序前端

3.暴露您的本地服务器

在单独的终端中，使用ngrok暴露您的本地服务器：

ngrok http 3000

从ngrok输出中复制转发URL：

Forwarding     https://3785c5ddc4b6.ngrok-free.app -> http://localhost:3000

4.连接到ChatGPT

• 切换 设置→ 连接器→ 高级→ 开发者模式 在ChatGPT客户端中
• 导航至 设置→ 连接器→ 创建
• 输入您的ngrok URL /mcp 路径（例如。， https://3785c5ddc4b6.ngrok-free.app/mcp)
• 点击 创建

5.测试您的集成

• 在ChatGPT中启动新对话
• 使用以下命令选择新创建的连接器 + → Plus → 您的连接器
• 尝试提示模型（例如，“向我展示钢琴小部件”）

6.使用HMR进行开发

现在，您可以在以下位置编辑React组件 web 并立即看到变化：

• 对任何组件进行更改
• 保存文件
• 小部件将在ChatGPT中自动更新，无需刷新或重新连接
• Express服务器和MCP服务器继续运行，没有中断

注： 当您修改小部件组件时，更改将立即反映出来。如果修改MCP服务器代码（在 src/)，您可能需要重新加载连接器 设置→ 连接器→ \[您的连接器\]→ 重新加载.

小部件命名约定

重要提示： 为了使小部件正常工作，MCP服务器中端点的名称必须与中相应React组件的文件名匹配 web/src/widgets/.

例如：

• 如果您创建了一个名为的小部件端点 piano，您必须在以下位置创建相应的React组件文件 web/src/widgets/piano.tsx
• 端点名称和小部件文件名（不包括 .tsx 扩展名）必须相同

这种命名约定允许系统自动将小部件请求映射到相应的React组件。

部署到生产

使用Alpic将您的OpenAI应用程序部署到生产环境中。


• 在ChatGPT中，导航到 设置→ 连接器→ 创建 并添加您的MCP服务器URL（例如。， https://your-app-name.alpic.live)

项目结构

.
├── server/
│   ├── src/
│   │   ├── server.ts       # MCP server with widget registration
│   │   └── index.ts        # Express server definition
└── web/
    └── src/
        └── widgets/
            └── piano.tsx   # Piano widget React component

资源

• 应用SDK文档
• 模型上下文协议文档
• Alpic文档