MCP 小部件
🚀 命令行工具，用于初始化支持ChatGPT小部件的MCP（模型上下文协议）服务器。
](https://www.npmjs.com/package/mcp-widget) 
在几秒钟内快速搭建一个带有小部件和完整开发环境的MCP服务器。
✨ 特点/功能
- 🎯（目标、瞄准、决心等意，具体根据上下文而定） 交互式命令行界面 (CLI) - 指导项目设置并进行验证
- ⚡ 闪电符号（在中文语境中，该符号通常直接以“⚡”表示，无需翻译，但若需解释，可称为“闪电符号”或“电光符号”） 多个框架 - 在Next.js和Vite之间选择
- 🔧（扳手或工具的象征） 预配置的MCP服务器 - 现成可用的MCP协议实现
- 🎨 表示绘画或艺术创作的符号。 小部件系统 - 基于React的小部件，支持热重载
- 📦 翻译为中文是：📦（这个符号本身没有直接的中文翻译，它通常代表“包裹”或“箱子”的意思，在网络或日常交流中用作表情符号或简化的表示）。如果需要一个更具体的描述，可以是“包裹”或“箱子”。 完整的开发环境 - 开始构建所需的一切
- 🧪 试管/实验器材（符号，常用于表示化学实验或科学实验） 准备测试 - 包含MCP Inspector集成
- 🌐（这个符号本身没有直接对应的中文翻译，它通常代表“互联网”或“全球网络”的意象，可以简单理解为“网络”或“万维网”的象征。） ChatGPT集成 - 通过ngrok连接到ChatGPT进行端到端（E2E）测试
- 📝（笔记或待办事项的符号） TypeScript 支持 - 对Next.js和Vite模板提供完整的TypeScript支持
🚀 快速入门
# Using npx (recommended)
npx mcp-widget create my-app
# Or install globally
npm install -g mcp-widget
mcp-widget create my-app
# Or use specific package manager
pnpm dlx mcp-widget create my-app
yarn dlx mcp-widget create my-app📖 使用方法
交互模式
只需运行该命令并按照提示操作：
npx mcp-widget create my-app你会被问到：
- 项目名称 - 必须为小写，仅包含字母数字和连字符
- 框架 - 在以下选项中选择：
- 快点 - TypeScript + React，具备快速热更新（HMR）功能 - Next.js - 使用TypeScript和App Router的全栈开发
非交互模式
对于脚本和自动化操作，您可以通过命令行参数指定所有选项：
# Create with specific template
npx mcp-widget create my-app --template vite
npx mcp-widget create my-app --template nextjs
# Use short flags
npx mcp-widget create my-app -t vite
# Skip all prompts with --yes flag (uses defaults)
npx mcp-widget create my-app --yes
# Combine options
npx mcp-widget create my-app -t nextjs -y可用选项：
--template，-t- 要使用的模板（vite或者nextjs)--yes，-y- 跳过交互式提示，使用默认值
示例：
# Interactive mode
npx mcp-widget create
# Mixed mode - name provided, prompt for template
npx mcp-widget create my-app
# Full non-interactive mode
npx mcp-widget create my-app -t nextjs创造了什么？
您的新项目包括：
my-chatgpt-app/
├── src/
│ ├── server/
│ │ └── server.ts # MCP server implementation
│ └── widgets/
│ └── hello-world/
│ └── index.tsx # Example widget
├── scripts/
│ └── dev.js # Development server
├── package.json
├── tsconfig.json # TypeScript configuration
├── tsconfig.node.json # TypeScript config for Node.js
├── tsconfig.server.json # TypeScript config for server
├── vite.config.js # Widget build configuration
└── README.md # Project-specific documentation🏗️ 项目模板
Vite 模板
非常适合快速原型制作和以小部件为中心的开发，全面支持TypeScript。
建筑：
- 小部件开发服务器 (端口4450) - 使用Vite和HMR进行小部件开发
- MCP 服务器 (端口 8000) - SSE（服务器发送事件）端点位于
/mcp - 预览服务器 (端口 5173) - 本地小部件预览用户界面
开始开发：
cd my-app
npm run dev终点（或：结局指标）：
- 小部件预览：
- MCP终端：
- 小部件资源：
Next.js 模板
使用TypeScript和API路由构建的全栈应用程序。
建筑：
- Next.js 应用 (端口3000) - 完整应用程序，包含API路由
- MCP SSE 路线 -
/api/mcp用于MCP协议 - MCP消息路由 -
/api/mcp/messages用于工具调用
开始开发：
cd my-app
npm run dev终点（或：试验终点）：
- 应用：
- MCP端点：
🛠️ 开发工作流程
1. 创建您的项目
npx mcp-widget create my-app
# Follow the prompts2. 开始开发
cd your-project-name
npm install # If dependencies weren't auto-installed
npm run dev3. 使用MCP Inspector进行测试
# In a new terminal
npx @modelcontextprotocol/inspector http://localhost:8000/mcp或者对于 Next.js：
npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp4. 连接至ChatGPT（可选）
使用 ngrok 通过 ChatGPT 测试您的 MCP 服务器：
# Install ngrok
brew install ngrok/ngrok/ngrok
# Start tunnel (while your app is running)
ngrok http 8000 # or 3000 for Next.js
# Use the HTTPS URL to create a Custom GPT in ChatGPT完整指南： 看 docs/CHATGPT_INTEGRATION.md
5. 为生产环境构建（或：准备生产版本）
npm run build📚 MCP 协议
生成的项目实现了 模型上下文协议 与；带着；用；凭借
支持的功能
- ✅ 工具 - 执行具有结构化输入/输出的功能
- ✅ 资源 - 以正确的MIME类型提供HTML小部件
- ✅ 资源模板 - 用于动态加载的小部件模板
- ✅ 翻译成中文是：勾选/确认/正确 结构化内容 - 配备元数据的丰富响应
示例工具
“hello-world”工具展示了完整流程：
// Call the tool
{
"name": "hello-world",
"arguments": {
"message": "Hello from ChatGPT!"
}
}
// Returns
{
"content": [
{ "type": "text", "text": "Hello World Tool called..." }
],
"structuredContent": [
{
"type": "message",
"message": "Hello from ChatGPT!",
"timestamp": "2025-10-19T..."
}
],
"_meta": {
"outputTemplate": "ui://widget/hello-world.html"
}
}🎨 小部件开发
小部件（Widgets）是React组件，它们可以：
- 访问
window.openai.toolOutput用于数据 - 检测
window.openai.displayMode（明亮/黑暗） - 在开发过程中进行热重载
- 构建为独立的HTML+JS文件
创建一个新的小部件
- 创建目录：
src/widgets/my-widget/ - 添加
index.tsx：
import React, { useState, useEffect } from "react";
import { createRoot } from "react-dom/client";
// Define types for tool output
interface ToolOutput {
message?: string;
[key: string]: any;
}
// Extend window interface
declare global {
interface Window {
openai?: {
toolOutput?: ToolOutput;
displayMode?: string;
};
}
}
function MyWidget() {
const [data, setData] = useState(null);
useEffect(() => {
const output = window.openai?.toolOutput;
if (output) {
setData(output);
}
}, []);
return
My Custom Widget: {data?.message}
;
}
const root = createRoot(document.getElementById("root")!);
root.render();- 在 MCP 服务器上注册（由 Vite 配置自动检测）
- 通过……访问
ui://widget/my-widget.html
🧪 测试
运行测试
npm test手动测试
看 TESTING.md 翻译为中文是：“测试说明文件.md” 或 “测试指南.md”（具体翻译可能根据上下文有所调整，但“md”通常表示Markdown格式的文件，所以这里没有直接翻译“md”） 作为全面测试指南。
MCP 检查器
检查器是您测试时的最佳伙伴：
npx @modelcontextprotocol/inspector http://localhost:8000/mcp验证：
- ✅ 连接成功
- ✅ 工具已列出
- ✅ 资源可访问
- ✅ 工具调用返回预期数据
📋 要求
- Node.js 18+（推荐长期支持版）
- npm 7+ / pnpm（一个包管理器，全称为Performance Packaged npm，意为高性能打包的npm） 8+ / 纱线 1.22+
🤝 贡献
欢迎贡献！请随时提交拉取请求。
- 为仓库创建分支
- 创建你的特性分支（
git checkout -b feature/amazing-feature) - 提交您的更改（
git commit -m 'Add amazing feature') - 推送至分支（
git push origin feature/amazing-feature) - 提交一个拉取请求
📝 许可证
麻省理工学院 © \[您的姓名\]
🔗 链接
💡 示例
查看一下 examples/ 目录用于：
- 自定义小部件示例
- 高级MCP服务器模式
- 与外部API的集成
- 多小部件应用程序
🎯 路线图
- \[ \] React Native 模板
- \[ \] 支持Svelte/Vue小部件
- \[ \] GraphQL 集成示例
- \[ \] Docker 部署模板
- \[ \] 单仓库模板
- \[ \] 测试实用工具包
❓ 常见问题解答 (FAQ)
为什么选择SSE而不是其他传输方式？
当前模板使用SSE（服务器发送事件）进行MCP通信。虽然MCP SDK正在向StreamableHttp方向发展，但SSE简单且在开发中运行可靠。
我可以使用JavaScript而不是TypeScript吗？
现在，两个模板都默认使用TypeScript，通过类型安全性和IntelliSense提供更好的开发者体验。不过，您也可以轻松地通过重命名来使用JavaScript .ts/.tsx 文件至 .js/.jsx 并移除类型注解。
我如何添加身份验证？
参见以下认证示例 examples/auth/ （即将推出）。
我可以将这个部署到生产环境吗？
是的！请参阅部署指南中的 docs/DEPLOYMENT.md （即将推出）。
🙏 致谢
- Anthropic的模型上下文协议
- React 18 的 React 团队
- Vite 团队，打造了令人惊叹的构建工具
- Next.js 框架团队
______________________________________________________________________
快乐的建筑！（或根据语境可译为“幸福大厦！”）！ 🚀（火箭或快速上升的箭头）
如果你觉得这个工具很有用，请给这个仓库⭐点赞！
- Node.js 18及以上版本
- pnpm（推荐）或 npm
许可证
麻省理工学院（MIT）