AI导哈

多语言交互式UI应用

一款基于MCP Apps SDK开发的多语言交互式UI应用，支持15种语言的平滑淡入淡出动画，可在多种AI客户端中运行。

  • by lukechi1219
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 lukechi1219/hello-mcp-app

使用说明

你好MCP应用程序

多语言“Hello World”MCP应用程序，带有iPhone风格的淡入淡出动画。与 MCP应用软件开发工具包，它直接在Claude、ChatGPT、VS Code和Goose等AI客户端中呈现交互式UI。

特性

  • 15种语言，具有流畅的渐变循环动画
  • 通过MCP Apps协议在沙盒iframe中呈现的交互式UI
  • 主机主题集成（暗/亮模式、CSS变量、字体）
  • 全屏切换和刷新按钮，可双向调用工具
  • 无状态的按请求架构，实现无服务器兼容性

快速开始

pnpm install
pnpm build

部署方法

此应用程序在2个入口点支持3种部署方法：

方法 入口点 运输 模式 最适合
克劳德桌面（stdio） stdio.ts stdio 状态 本地开发和测试
Node.js HTTP node-http.ts 流式HTTP 无状态 VPS、云VM、本地HTTP
码头工人 node-http.ts 流式HTTP 无状态 云运行、AWS ECS、任何容器平台

提示： 使用 吸烟 通过HTTPS公开您的本地HTTP服务器，以便使用ChatGPT进行测试： ngrok http 3000

1.克劳德桌面（本地stdio）

作为Claude Desktop管理的本地子进程运行。不需要网络。

步骤：

# 1. Build the project
pnpm build

# 2. Verify the output exists
ls dist/entry/stdio.js

编辑Claude桌面配置：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "hello-world": {
      "command": "node",
      "args": ["/absolute/path/to/hello-mcp-app/dist/entry/stdio.js"]
    }
  }
}

# 3. Restart Claude Desktop
# 4. In conversation, type: "Use the hello-world tool"

2.Node.js HTTP服务器

使用可流式HTTP传输运行Express v5服务器。适用于VPS、云VM或本地测试。

步骤：

# Development (auto-builds UI)
pnpm dev:http

# Production
pnpm build
pnpm start

终点：

  • MCP： http://localhost:3000/mcp
  • 健康： http://localhost:3000/health

环境变量：

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

验证：

# Health check
curl http://localhost:3000/health

# MCP initialize test
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

3.Docker

使用Node.js 22 Alpine进行多阶段构建。生产就绪容器。

步骤：

# 1. Build Docker image
docker build -t hello-mcp .

# 2. Run container
docker run -p 3000:3000 hello-mcp

# 3. Verify
curl http://localhost:3000/health

自定义端口：

docker run -p 8080:3000 -e PORT=3000 hello-mcp

部署到云容器平台：

# Google Cloud Run
gcloud run deploy hello-mcp \
  --source . \
  --port 3000 \
  --allow-unauthenticated

# AWS App Runner (via ECR)
docker tag hello-mcp:latest <account-id>.dkr.ecr.<region>.amazonaws.com/hello-mcp:latest
docker push <account-id>.dkr.ecr.<region>.amazonaws.com/hello-mcp:latest

# Railway
railway up

# Fly.io
fly launch
fly deploy

部署后的MCP端点： https://your-service-url.com/mcp

连接到AI客户端

部署到HTTPS端点后，连接到任何兼容MCP的客户端：

克劳德桌面（远程）

  1. 部署到任何HTTPS端点
  2. 设置>开发人员>编辑配置
  3. 添加URL: https://your-server.com/mcp

Claude Web（远程MCP连接）

  1. 部署到任何HTTPS端点
  2. 设置>连接器>添加URL
  3. 输入： https://your-server.com/mcp

ChatGPT

需要HTTPS端点。支持MCP Apps UI渲染（与Claude相同的交互式UI）。

  1. 部署到HTTPS（云运行、ngrok等）
  2. 设置>连接器>高级>启用开发人员模式
  3. 使用您的URL添加MCP连接器
  4. 在对话中，要求使用该工具

支持： SSE，流式HTTP| 认证： OAuth，无授权 限制： 没有本地MCP服务器（必须是HTTPS）

VS代码（内部人员）

  1. 部署到任何HTTPS端点，或使用本地stdio
  2. 在VS Code MCP设置中配置

鹅

  1. 部署到任何HTTPS端点
  2. 在Goose设置中添加MCP服务器URL

建筑

hello-mcp-app/
├── src/
│   ├── core/                # Cloud-agnostic MCP server core
│   │   ├── greetings.ts     # Multilingual greeting data (15 languages)
│   │   └── create-server.ts # MCP server factory (tools + resources)
│   ├── entry/               # Platform-specific entry points
│   │   ├── stdio.ts         # Local testing (stateful)
│   │   └── node-http.ts     # Express v5 + Streamable HTTP (stateless)
│   └── ui/                  # iPhone-style welcome screen
│       ├── mcp-app.html     # Main UI structure
│       ├── mcp-app.ts       # MCP App SDK client (full lifecycle)
│       └── styles.css       # Animations + host theme fallbacks
├── Dockerfile               # Multi-stage Node.js build
└── package.json             # pnpm scripts & dependencies

所有HTTP入口点都使用 每次请求无状态 建筑：一种新鲜 McpServer +传输是根据请求创建的，与无服务器环境兼容。

MCP应用程序生命周期

UI客户端实现了完整的MCP Apps事件生命周期：

经办人 目的
ontoolinput 接收工具输入参数
ontoolresult 接收工具执行结果，更新问候语
onhostcontextchanged 应用主机主题、字体、安全区域插图
onteardown 清理动画计时器
行动 目的
callServerTool() 从服务器刷新问候语
requestDisplayMode() 切换全屏
sendLog() 调试主机日志记录

开发命令

pnpm install          # Install dependencies
pnpm dev              # Test locally via stdio
pnpm dev:http         # Test HTTP server (port 3000)
pnpm build            # Full build (UI + TypeScript)
pnpm build:ui         # Build UI bundle only
pnpm start            # Start production HTTP server

技术栈

  • 运行时：Node.js 18+
  • 语言：TypeScript（ES2022，严格模式）
  • MCP-SDK: @modelcontextprotocol/sdk + @modelcontextprotocol/ext-apps
  • 运输：流式HTTP
  • 服务器：Express v5 createMcpExpressApp
  • 构建：快+ vite-plugin-singlefile （单文件HTML捆绑包）
  • 包管理器：pnpm

许可证

麻省理工学院

相关 MCP