星战科技xingzhan.cloud
返回市场
MCP小部件命令行界面

MCP小部件命令行界面

作者：perixtar2 星标更新：2025-10-20
安装使用来源：spider==github.com

项目介绍

MCP Widget

🚀 命令行工具，用于快速搭建支持ChatGPT小部件的MCP（模型上下文协议）服务器。

npm 版本 许可证: MIT

几秒钟内快速设置带有小部件和完整开发环境的MCP服务器。

✨ 功能

  • 🎯 交互式CLI - 带有验证的引导项目设置
  • ⚡ 多种框架 - 可选择Next.js或Vite
  • 🔧 预配置的MCP服务器 - 即用型MCP协议实现
  • 🎨 小部件系统 - 基于React的小部件，支持热重载
  • 📦 完整的开发环境 - 开始构建所需的一切
  • 🧪 测试就绪 - 包括MCP Inspector集成
  • 🌐 ChatGPT集成 - 通过ngrok连接到ChatGPT进行端到端测试
  • 📝 TypeScript支持 - 对Next.js和Vite模板提供全面的TypeScript支持

🚀 快速开始

# 使用npx（推荐）
npx mcp-widget create my-app

# 或全局安装
npm install -g mcp-widget
mcp-widget create my-app

# 或使用特定包管理器
pnpm dlx mcp-widget create my-app
yarn dlx mcp-widget create my-app

📖 使用方法

交互模式

只需运行命令并跟随提示：

npx mcp-widget create my-app

您将被询问：

  1. 项目名称 - 必须是小写，字母数字，仅含连字符
  2. 框架 - 选择以下之一：
    • Vite - TypeScript + React，具有快速HMR
    • Next.js - 全栈，带TypeScript和App Router

非交互模式

对于脚本和自动化，您可以通过命令行参数指定所有选项：

# 使用特定模板创建
npx mcp-widget create my-app --template vite
npx mcp-widget create my-app --template nextjs

# 使用短标志
npx mcp-widget create my-app -t vite

# 使用--yes标志跳过所有提示（使用默认值）
n
px mcp-widget create my-app --yes

# 组合选项
npx mcp-widget create my-app -t nextjs -y

可用选项：

  • --template, -t - 要使用的模板（vite或nextjs）
  • --yes, -y - 跳过交互式提示并使用默认值

示例：

# 交互模式
npx mcp-widget create

# 混合模式 - 提供名称，提示模板
npx mcp-widget create my-app

# 完全非交互模式
npx mcp-widget create my-app -t nextjs

创建了什么？

您的新项目包括：

my-chatgpt-app/
├── src/
│   ├── server/
│   │   └── server.ts          # MCP服务器实现
│   └── widgets/
│       └── hello-world/
│           └── index.tsx       # 示例小部件
├── scripts/
│   └── dev.js                  # 开发服务器
├── package.json
├── tsconfig.json              # TypeScript配置
├── tsconfig.node.json         # Node.js的TypeScript配置
├── tsconfig.server.json       # 服务器的TypeScript配置
├── vite.config.js             # 小部件构建配置
└── README.md                   # 项目特定文档

🏗️ 项目模板

Vite模板

适用于快速原型设计和专注于小部件开发，具有全面的TypeScript支持。

架构：

  • 小部件开发服务器（端口4450） - Vite与HMR用于小部件开发
  • MCP服务器（端口8000） - 在/mcp处的SSE端点
  • 预览服务器（端口5173） - 本地小部件预览UI

启动开发：

cd my-app
npm run dev

端点：

Next.js模板

全栈应用，带TypeScript和API路由。

架构：

  • Next.js应用（端口3000） - 带API路由的全应用
  • MCP SSE路由 - /api/mcp用于MCP协议
  • MCP消息路由 - /api/mcp/messages用于工具调用

启动开发：

cd my-app
npm run dev

端点：

🛠️ 开发工作流程

1. 创建您的项目

npx mcp-widget create my-app
# 跟随提示

2. 启动开发

cd your-project-name
npm install  # 如果依赖项未自动安装
npm run dev

3. 使用MCP Inspector测试

# 在新的终端中
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

或者对于Next.js：

npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp

4. 连接到ChatGPT（可选）

使用ngrok测试您的MCP服务器与ChatGPT：

# 安装ngrok
brew install ngrok/ngrok/ngrok

# 启动隧道（当您的应用正在运行时）
ngrok http 8000  # 或3000用于Next.js

# 使用HTTPS URL在ChatGPT中创建自定义GPT

完整指南： 查看docs/CHATGPT_INTEGRATION.md

5. 构建生产版本

npm run build

📚 MCP协议

生成的项目实现了模型上下文协议，包含：

支持的功能

  • ✅ 工具 - 执行具有结构化输入/输出的函数
  • ✅ 资源 - 以正确的MIME类型提供小部件HTML
  • ✅ 资源模板 - 用于动态加载的小部件模板
  • ✅ 结构化内容 - 带有元数据的丰富响应

示例工具

hello-world工具演示了完整的流程：

// 调用工具
{
  "name": "hello-world",
  "arguments": {
    "message": "Hello from ChatGPT!"
  }
}

// 返回
{
  "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"
  }
}

🎨 小部件开发

小部件是React组件，可以：

  • 访问window.openai.toolOutput获取数据
  • 检测window.openai.displayMode（浅色/深色）
  • 开发期间热重载
  • 构建为独立的HTML+JS

创建一个新的小部件

  1. 创建目录：src/widgets/my-widget/
  2. 添加index.tsx：
import React, { useState, useEffect } from "react";
import { createRoot } from "react-dom/client";

// 定义工具输出类型
interface ToolOutput {
  message?: string;
  [key: string]: any;
}

// 扩展window接口
declare global {
  interface Window {
    openai?: {
      toolOutput?: ToolOutput;
      displayMode?: string;
    };
  }
}

function MyWidget() {
  const [data, setData] = useState<ToolOutput | null>(null);

  useEffect(() => {
    const output = window.openai?.toolOutput;
    if (output) {
      setData(output);
    }
  }, []);

  return <div>我的自定义小部件: {data?.message}</div>;
}

const root = createRoot(document.getElementById("root")!);
root.render(<MyWidget />);
  1. 注册在MCP服务器（由Vite配置自动检测）
  2. 通过ui://widget/my-widget.html访问

🧪 测试

运行测试

npm test

手动测试

查看TESTING.md以获得全面的测试指南。

MCP Inspector

Inspector是您最好的测试伙伴：

npx @modelcontextprotocol/inspector http://localhost:8000/mcp

验证：

  • ✅ 连接成功
  • ✅ 工具列出
  • ✅ 资源可访问
  • ✅ 工具调用返回预期数据

📋 要求

  • Node.js 18+（推荐长期支持版本）
  • npm 7+ / pnpm 8+ / yarn 1.22+

🤝 贡献

欢迎贡献！请随意提交拉取请求。

  1. 分叉仓库
  2. 创建功能分支（git checkout -b feature/amazing-feature）
  3. 提交更改（git commit -m '添加精彩功能'）
  4. 推送到分支（git push origin feature/amazing-feature）
  5. 打开拉取请求

📝 许可证

MIT © [您的名字]

🔗 链接

💡 示例

查看examples/目录：

  • 自定义小部件示例
  • 高级MCP服务器模式
  • 与外部API的集成
  • 多小部件应用程序

🎯 路线图

  • React Native模板
  • Svelte/Vue小部件支持
  • GraphQL集成示例
  • Docker部署模板
  • 单一存储库模板
  • 测试工具包

❓ 常见问题

为什么使用SSE而不是其他传输方式？

当前模板使用SSE（服务器发送事件）进行MCP通信。虽然MCP SDK正向StreamableHttp迁移，但SSE简单且可靠地适用于开发。

我能使用JavaScript而不是TypeScript吗？

两个模板现在默认使用TypeScript，提供了更好的开发者体验，包括类型安全和IntelliSense。然而，您可以通过简单地将.ts/.tsx文件重命名为.js/.jsx并移除类型注解来轻松使用JavaScript。

如何添加身份验证？

查看examples/auth/中的身份验证示例（即将推出）。

我能将其部署到生产环境中吗？

可以！查看docs/DEPLOYMENT.md中的部署指南（即将推出）。

🙏 致谢

  • Anthropic的模型上下文协议
  • React团队的React 18
  • Vite团队的出色构建工具
  • Next.js团队的框架

愉快地构建吧！ 🚀

如果您发现此工具有用，请⭐星标该仓库！

  • Node.js 1 8+
  • pnpm（推荐）或npm

许可证

MIT