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

| Prop | Type | Default | Description | | ------------- | --------------------------- | ------- | -------------------------------- | | mcpConfig | McpConfig | - | MCP server configuration | | trigger | TriggerProps | - | Trigger button configuration | | dialog | DialogProps | - | Dialog configuration | | chat | ChatProps | - | Chat interface configuration | | defaultOpen | boolean | false | Whether dialog starts open | | showTrigger | boolean | true | Whether to show trigger button | | isOpen | boolean | - | External control of dialog state | | onToggle | (isOpen: boolean) => void | - | External dialog state handler | | onOpen | () => void | - | Callback when dialog opens | | onClose | () => void | - | Callback when dialog closes |

TriggerProps

| Prop | Type | Default | Description | | ------------ | -------------------------------------------------------------------------- | ---------------- | ----------------------- | | label | string | "Chat" | Button label/tooltip | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'custom' | 'bottom-right' | Button position | | size | 'sm' \| 'md' \| 'lg' | 'md' | Button size | | variant | 'primary' \| 'secondary' \| 'outline' | 'primary' | Button style variant | | className | string | - | Custom CSS classes | | showBadge | boolean | false | Show notification badge | | badgeCount | number | - | Badge count number |

DialogProps

| Prop | Type | Default | Description | | --------------------- | ---------------------------------------- | ---------------------- | --------------------------- | | title | string | "MCP Chat Assistant" | Dialog title | | size | 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' | 'lg' | Dialog size | | closeOnOverlayClick | boolean | true | Close when clicking overlay | | showCloseButton | boolean | true | Show close button |

ChatProps

| Prop | Type | Default | Description | | ------------- | --------- | --------- | --------------------- | | hideSidebar | boolean | false | Hide tools sidebar | | height | string | "600px" | Chat interface height | | className | string | - | Custom CSS classes |

McpConfig

| Prop | Type | Description | | ------------ | -------- | -------------------- | | serverUrl | string | MCP server URL | | clientName | string | Client identifier | | authToken | string | Authentication token |

🎨 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