mcp-chat-widget

A reusable React chat widget for Model Context Protocol (MCP) interactions. This package provides a complete chat interface that can be embedded in any React application as a floating dialog that opens when clicked.

✨ Features

• 🎯 Easy Integration - Drop-in component with minimal setup
• 💬 Dialog Interface - Clean floating chat dialog that doesn't interfere with your app
• 🎨 Customizable - Configurable styling, positioning, and behavior
• 📱 Responsive - Works great on desktop and mobile devices
• 🔧 MCP Integration - Built-in support for Model Context Protocol
• 📝 TypeScript - Full TypeScript support with comprehensive type definitions
• 🎭 Flexible API - Multiple ways to integrate and customize

📦 Installation

npm install mcp-chat-widget

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom

🚀 Quick Start

Basic Usage

import React from "react";
import { ChatWidget } from "mcp-chat-widget";

function App() {
  return (
    <div>
      <h1>My App</h1>
      {/* Chat widget will appear as a floating button in bottom-right corner */}
      <ChatWidget />
    </div>
  );
}

export default App;

Custom Configuration

import { ChatWidget } from "mcp-chat-widget";

function App() {
  return (
    <ChatWidget
      trigger={{
        label: "Help & Support",
        size: "lg",
        variant: "primary",
        position: "bottom-left",
      }}
      dialog={{
        title: "AI Assistant",
        size: "xl",
        closeOnOverlayClick: false,
      }}
      chat={{
        hideSidebar: true,
        height: "500px",
      }}
      mcpConfig={{
        serverUrl: "your-mcp-server-url",
        clientName: "MyApp",
        authToken: "your-auth-token",
      }}
    />
  );
}

📚 API Reference

ChatWidget Props

TriggerProps

DialogProps

ChatProps

McpConfig

🎨 Styling

The widget uses Tailwind CSS classes internally. If you're using Tailwind in your project, the styles will be inherited. For custom styling:

Using CSS Variables

:root {
  --chat-widget-primary: #3b82f6;
  --chat-widget-secondary: #6b7280;
  --chat-widget-background: #ffffff;
  --chat-widget-border: #e5e7eb;
}

Custom Classes

<ChatWidget
  trigger={{
    className: "my-custom-trigger-styles",
  }}
  chat={{
    className: "my-custom-chat-styles",
  }}
/>

🔧 Advanced Usage

External State Control

import { useState } from "react";
import { ChatWidget } from "mcp-chat-widget";

function App() {
  const [isChatOpen, setIsChatOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsChatOpen(true)}>Open Chat</button>

      <ChatWidget
        showTrigger={false}
        isOpen={isChatOpen}
        onToggle={setIsChatOpen}
      />
    </div>
  );
}

Using Individual Components

import {
  Dialog,
  DialogChatInterface,
  ChatTriggerButton,
} from "mcp-chat-widget";

function CustomChatWidget() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <ChatTriggerButton
        onClick={() => setIsOpen(true)}
        position="custom"
        className="my-4"
      />

      <Dialog
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        title="Support Chat"
      >
        <DialogChatInterface hideSidebar />
      </Dialog>
    </>
  );
}

🔄 Events and Callbacks

<ChatWidget
  onOpen={() => {
    console.log("Chat opened");
    // Track analytics, load data, etc.
  }}
  onClose={() => {
    console.log("Chat closed");
    // Save state, cleanup, etc.
  }}
/>

🛠 Development

Local Development

1. Clone the repository
2. Install dependencies: npm install
3. Start development server: npm run dev
4. Build library: npm run build:lib

Project Structure

src/lib/
├── components/          # React components
│   ├── ChatWidget.tsx   # Main widget component
│   ├── Dialog.tsx       # Dialog/modal component
│   └── ...
├── hooks/              # React hooks
├── types/              # TypeScript types
├── utils/              # Utility functions
├── config/             # Configuration
└── index.ts            # Main exports

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a 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

📞 Support

• Create an issue for bug reports
• Start a discussion for questions
• Check our documentation for guides

🗺 Roadmap

• Theming system
• Custom message types
• File upload support
• Voice input/output
• Multiple chat instances
• Emoji support
• Message persistence

Made with ❤️ by Jetpack