MCP Widget

🚀 CLI tool to bootstrap MCP (Model Context Protocol) servers with ChatGPT widget support.

Quickly set up an MCP server with widgets and a complete development environment in seconds.

✨ Features

• 🎯 Interactive CLI - Guided project setup with validation
• ⚡ Multiple Frameworks - Choose between Next.js or Vite
• 🔧 Pre-configured MCP Server - Ready-to-use MCP protocol implementation
• 🎨 Widget System - React-based widgets with hot reload
• 📦 Complete Dev Environment - Everything you need to start building
• 🧪 Testing Ready - Includes MCP Inspector integration
• 🌐 ChatGPT Integration - Connect to ChatGPT via ngrok for E2E testing
• 📝 TypeScript Support - Full TypeScript support for both Next.js and Vite templates

🚀 Quick Start

# 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

📖 Usage

Interactive Mode

Simply run the command and follow the prompts:

npx mcp-widget create my-app

You'll be asked:

1. Project name - Must be lowercase, alphanumeric with hyphens only
2. Framework - Choose between:
   • Vite - TypeScript + React with fast HMR
   • Next.js - Full-stack with TypeScript and App Router

Non-Interactive Mode

For scripts and automation, you can specify all options via command line arguments:

# 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

Available Options:

• --template, -t - Template to use (vite or nextjs)
• --yes, -y - Skip interactive prompts and use defaults

Examples:

# 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

What Gets Created?

Your new project includes:

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

🏗️ Project Templates

Vite Template

Perfect for quick prototyping and widget-focused development with full TypeScript support.

Architecture:

• Widget Dev Server (Port 4450) - Vite with HMR for widget development
• MCP Server (Port 8000) - SSE endpoint at /mcp
• Preview Server (Port 5173) - Local widget preview UI

Start Development:

cd my-app
npm run dev

Endpoints:

• Widget preview: http://localhost:5173
• MCP endpoint: http://localhost:8000/mcp
• Widget assets: http://localhost:4450

Next.js Template

Full-stack application with TypeScript and API routes.

Architecture:

• Next.js App (Port 3000) - Full application with API routes
• MCP SSE Route - /api/mcp for MCP protocol
• MCP Messages Route - /api/mcp/messages for tool calls

Start Development:

cd my-app
npm run dev

Endpoints:

• Application: http://localhost:3000
• MCP endpoint: http://localhost:3000/api/mcp

🛠️ Development Workflow

1. Create Your Project

npx mcp-widget create my-app
# Follow the prompts

2. Start Development

cd your-project-name
npm install  # If dependencies weren't auto-installed
npm run dev

3. Test with MCP Inspector

# In a new terminal
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

Or for Next.js:

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

4. Connect to ChatGPT (Optional)

Test your MCP server with ChatGPT using ngrok:

# 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

Full guide: See docs/CHATGPT_INTEGRATION.md

5. Build for Production

npm run build

📚 MCP Protocol

The generated projects implement the Model Context Protocol with:

Supported Capabilities

• ✅ Tools - Execute functions with structured input/output
• ✅ Resources - Serve widget HTML with proper MIME types
• ✅ Resource Templates - Widget templates for dynamic loading
• ✅ Structured Content - Rich responses with metadata

Example Tool

The hello-world tool demonstrates the complete flow:

// 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"
  }
}

🎨 Widget Development

Widgets are React components that can:

• Access window.openai.toolOutput for data
• Detect window.openai.displayMode (light/dark)
• Hot reload during development
• Build to standalone HTML+JS

Creating a New Widget

1. Create directory: src/widgets/my-widget/
2. Add 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<ToolOutput | null>(null);

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

  return <div>My Custom Widget: {data?.message}</div>;
}

const root = createRoot(document.getElementById("root")!);
root.render(<MyWidget />);

1. Register in MCP server (auto-detected by Vite config)
2. Access via ui://widget/my-widget.html

🧪 Testing

Run Tests

npm test

Manual Testing

See TESTING.md for comprehensive testing guide.

MCP Inspector

The Inspector is your best friend for testing:

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

Verify:

• ✅ Connection successful
• ✅ Tools are listed
• ✅ Resources are accessible
• ✅ Tool calls return expected data

📋 Requirements

• Node.js 18+ (LTS recommended)
• npm 7+ / pnpm 8+ / yarn 1.22+

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

MIT © [Your Name]

🔗 Links

• Model Context Protocol Docs
• ChatGPT App SDK
• npm Package

💡 Examples

Check out the examples/ directory for:

• Custom widget examples
• Advanced MCP server patterns
• Integration with external APIs
• Multi-widget applications

🎯 Roadmap

• React Native template
• Svelte/Vue widget support
• GraphQL integration example
• Docker deployment templates
• Monorepo template
• Testing utilities package

❓ FAQ

Why SSE instead of other transports?

The templates currently use SSE (Server-Sent Events) for MCP communication. While the MCP SDK is moving towards StreamableHttp, SSE is simple and works reliably for development.

Can I use JavaScript instead of TypeScript?

Both templates now use TypeScript by default, providing better developer experience with type safety and IntelliSense. However, you can easily use JavaScript by simply renaming .ts/.tsx files to .js/.jsx and removing type annotations.

How do I add authentication?

See the authentication example in examples/auth/ (coming soon).

Can I deploy this to production?

Yes! See deployment guides in docs/DEPLOYMENT.md (coming soon).

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• React team for React 18
• Vite team for the amazing build tool
• Next.js team for the framework

---

Happy Building! 🚀

If you find this tool helpful, please ⭐ star the repo!

• Node.js 18+
• pnpm (recommended) or npm

License

MIT