@flair/mcp-client

A complete, ready-to-use React component and backend client for MCP (Model Context Protocol) AI chat with OpenAI integration. Includes both the UI component and the OpenAI-powered backend logic.

Features

• 🎨 Complete UI Component - Ready-to-use chat interface with streaming support
• 🤖 OpenAI Integration - Built-in OpenAI client with conversation management
• 🔧 API Helpers - Simple Next.js API route helpers for instant setup
• 🎨 Customizable Styling - CSS variables for easy theming
• 📦 All-in-One Package - No need to configure MCP clients separately

Installation

npm install @flair/mcp-client

Quick Start

1. Set up environment variables

Create a .env.local file:

OPENAI_API_KEY=your_openai_api_key
MCP_SERVER_COMMAND="node /path/to/your/mcp-server/build/index.js"
OPENAI_MODEL=chatgpt-5-mini

2. Create API route

Create app/api/mcp/chat/route.ts:

import { createMCPChatHandler, createMCPClearHandler } from "@flair/mcp-client/server";

const chatHandler = createMCPChatHandler({
  openaiApiKey: process.env.OPENAI_API_KEY!,
  mcpServerCommand: process.env.MCP_SERVER_COMMAND!,
  openaiModel: process.env.OPENAI_MODEL,
});

const clearHandler = createMCPClearHandler();

export async function POST(req: Request) {
  return chatHandler(req);
}

export async function DELETE(req: Request) {
  return clearHandler(req);
}

3. Add the component to your app

import { MCPChat } from '@flair/mcp-client';
import '@flair/mcp-client/dist/styles/MCPChat.css';

export default function Page() {
  return (
    <div>
      <h1>My App</h1>
      <MCPChat companyNumber="12345678" />
    </div>
  );
}

4. Import CSS in your layout

import '@flair/mcp-client/dist/styles/MCPChat.css';

That's it! Your MCP chat is ready to use.

Component Props

interface MCPChatProps {
  companyNumber?: string;      // Optional context
  apiEndpoint?: string;         // Default: "/api/mcp/chat"
  customStyles?: React.CSSProperties;  // CSS variable overrides
  className?: string;           // Additional CSS class
}

Custom Styling

Override CSS variables:

const customStyles = {
  '--mcp-primary-color': '#7c5cff',
  '--mcp-border-radius': '24px',
} as React.CSSProperties;

<MCPChat customStyles={customStyles} />

Available CSS variables:

• --mcp-primary-color
• --mcp-bg
• --mcp-card-bg
• --mcp-text
• --mcp-text-secondary
• --mcp-border
• --mcp-border-radius
• --mcp-spacing

Advanced Usage

Direct Client Usage

If you need more control, use the client directly (server-side only):

import { MCPClientOpenAI } from '@flair/mcp-client/server';

const client = new MCPClientOpenAI({
  openaiApiKey: process.env.OPENAI_API_KEY!,
  mcpServerCommand: process.env.MCP_SERVER_COMMAND!,
  openaiModel: "chatgpt-5-mini",
});

await client.connect();
const response = await client.processQuery("Hello!", (thinking) => {
  console.log(thinking);
});
console.log(response);
await client.cleanup();

Custom API Implementation

Create your own streaming handler (server-side):

import { MCPClientOpenAI } from '@flair/mcp-client/server';

export async function POST(req: Request) {
  const { message } = await req.json();
  
  const client = new MCPClientOpenAI({
    openaiApiKey: process.env.OPENAI_API_KEY!,
    mcpServerCommand: process.env.MCP_SERVER_COMMAND!,
  });
  
  await client.connect();
  
  const response = await client.processQuery(message, (thinking) => {
    // Handle thinking steps
  });
  
  await client.cleanup();
  
  return Response.json({ response });
}

API Reference

See EXAMPLES.md for detailed examples.

Development

Building the Package

# Build with automatic patch version bump (1.0.0 → 1.0.1)
npm run build

# Build without version bump (development)
npm run build:no-version

# Bump minor version (1.0.0 → 1.1.0) for new features
npm run version:minor

# Bump major version (1.0.0 → 2.0.0) for breaking changes
npm run version:major

# Create release tarball
npm run release

Versioning: Every npm run build automatically increments the patch version.