#AI Chat System - Complete Guide

#Overview

This guide covers the Flash Turbo CMS AI Chat system, including:

Modern AI Chat interface (uses streamText, useChat, MCP integration)
MCP Server setup for tool calling
Integration patterns and best practices
Usage examples and quick start

#Quick Start

#For Users

Access AI Chat Manager
- Go to: /manager/ai-chat
- Sign in with your tenant admin account
- Start typing in the input field
Use Quick Actions
- Pre-configured prompts available
- Click button to execute common tasks
- Results display inline in real-time
Export Chat History
- Click "Export" button
- Downloads JSON file
- Useful for documentation and reference

#For Developers

Add AI Chat Overlay to Page
- Edit any page in Payload CMS
- Go to "Page Overlays" tab
- Enable overlays
- Add "AI Chat Overlay (Modern)" block
- Configure position and auto-open settings
- Publish page
API Endpoint
- POST /api/ai/chat-mcp
- Accepts messages array
- Returns streaming text response with tool calls
- Integrates with MCP tools automatically

React Component Usage

import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "@ai-sdk/react";

export function ChatInterface() {
  const { messages, status, sendMessage } = useChat({
    transport: new DefaultChatTransport({
      api: "/api/ai/chat-mcp",
    }),
  });

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          {msg.parts.map((part) => {
            if (part.type === "text") return <p>{part.text}</p>;
            if (part.type === "tool-call") 
              return <div className="tool-call">{part.toolName}</div>;
            if (part.type === "tool-result")
              return <div className="tool-result">{JSON.stringify(part.result)}</div>;
          })}
        </div>
      ))}
      <input 
        onKeyDown={(e) => {
          if (e.key === "Enter") {
            sendMessage({ 
              parts: [{ type: "text", text: e.currentTarget.value }] 
            });
          }
        }}
      />
    </div>
  );
}

#Architecture

#Components

1. API Route: `/api/ai/chat-mcp`

File: apps/multi-store/src/app/(misc)/api/ai/chat-mcp/route.ts
Purpose: Streaming chat endpoint with MCP tool integration
Features:
- Real-time text streaming
- Automatic tool calling via MCP
- Error handling and timeout management
- Session-based authentication

2. Manager Page: `/manager/ai-chat`

File: apps/multi-store/src/app/(manager)/[slug]/manager/ai-chat/page.tsx
Purpose: Full-page AI chat interface for admins
Features:
- Real-time streaming with progress indicators
- Tool call visualization (yellow cards)
- Tool result display (green cards)
- Export chat history
- Quick action buttons
- Modern gradient UI

3. AI Chat Overlay Component

File: apps/multi-store/src/components/ai/overlay/AIChatOverlayModern.tsx
Purpose: Floating chat overlay for any page
Features:
- Minimize/Maximize/Close controls
- Position customization
- Auto-open on page load
- localStorage state persistence
- Animated transitions with Framer Motion

4. Block Configuration

File: apps/multi-store/src/blocks/AIChatOverlayModern/config.ts
Purpose: CMS block for adding AI Chat to pages
Usage: Register in Pages collection, add to any page

5. Manager Sidebar Integration

File: apps/multi-store/src/components/manager/ManagerSidebar.tsx
Feature: Navigation menu item for AI Chat
Badge: "New" indicator

#MCP Server Integration

Server Configuration

Endpoint: /api/llm/mcp
Purpose: Provides tools for AI Chat to call
Tools: Database queries, product management, search, etc.

Tool Execution Flow

1. User sends message to /api/ai/chat-mcp
2. Route creates MCP client connection
3. Fetches available tools from MCP server
4. Sends messages + tools to LLM
5. LLM decides which tools to call
6. Tools execute via MCP server
7. Results returned to LLM
8. Response streamed back to client

#Message Format

#Standard Message Structure

type Message = {
  id: string;
  role: "user" | "assistant";
  content?: string;
  parts?: MessagePart[];
};

type MessagePart = 
  | { type: "text"; text: string }
  | { type: "tool-call"; toolName: string; args: any; id?: string }
  | { type: "tool-result"; toolName: string; result: any; id?: string }
  | { type: "file"; name: string; url: string; mimeType?: string };

#Examples

User Text Message

{
  "type": "text",
  "text": "Show me all products with 'organic' in the name"
}

Tool Call (Assistant)

{
  "type": "tool-call",
  "toolName": "find_products",
  "args": { "search": "organic", "limit": 10 },
  "id": "call_123"
}

Tool Result

{
  "type": "tool-result",
  "toolName": "find_products",
  "result": {
    "docs": [...],
    "totalDocs": 5
  },
  "id": "call_123"
}

#Modern vs Legacy Implementation

#✅ Modern Approach (Current - Recommended)

Uses streamText from ai package
Standard useChat hook for UI
Built-in tool call support
Automatic MCP integration
50% less boilerplate code
Full TypeScript support
Aligned with Vercel SDK roadmap

#🔴 Legacy Approach (Deprecated)

Custom streaming implementation
Manual chunk processing
Complex state management
Separate tool handling
More boilerplate
Limited TypeScript support

Migration: Both systems can run in parallel. Legacy system marked as "Legacy" in sidebar. Gradual user migration over 1-2 weeks.

#Usage Examples

#Example 1: Simple Product Query

User: "Show me all products"

Tool Call: find_products({ limit: 20 })
Tool Result: Returns 20 products with details
Response: "Here are the products in your system..."

#Example 2: Create New Item

User: "Create an item called 'Organic Coffee' with SKU 'ORG-001'"

Tool Call: create_item({
  name: "Organic Coffee",
  sku: "ORG-001"
})
Tool Result: Returns created item with ID
Response: "Created item 'Organic Coffee' (ID: xyz)"

#Example 3: Search and Statistics

User: "How many products contain 'coffee'?"

Tool Call: find_products({ search: "coffee" })
Tool Result: Returns matching products
Response: "Found 5 products containing 'coffee'"

#Configuration & Customization

#Environment Variables

OPENAI_API_KEY=sk-...           # OpenAI API key for LLM
MCP_SERVER_URL=/api/llm/mcp     # MCP server endpoint
AI_CHAT_MODEL=gpt-4o            # LLM model to use
AI_CHAT_TIMEOUT=30000           # Tool timeout in ms

#Theme Customization

Colors

Primary Gradient: primary-500 to secondary-500
User Messages: Gradient blue
Assistant Messages: White
Tool Calls: Yellow/warning
Tool Results: Green/success

Icons

User Message: MessageSquare
Assistant: Bot
Tool Call: Zap
Tool Result: CheckCircle
Send: Sparkles

#Quick Actions

Add pre-configured prompts in config:

const quickActions = [
  { label: "All Products", prompt: "Show me all products" },
  { label: "Statistics", prompt: "Give me system statistics" },
  // Add more...
];

#Testing

#Unit Tests

bun test docs/ai-chat/  # Run AI chat tests

#Manual Testing Checklist

API Route

POST to /api/ai/chat-mcp returns streaming response
Tool calls execute correctly
Error handling works
Timeouts handled gracefully

Manager Page

Overlay Component

#Integration Testing

# 1. Start dev server
bun run dev

# 2. Navigate to /manager/ai-chat
# 3. Test basic message
# 4. Test quick action
# 5. Test export
# 6. Test overlay on test page

#Troubleshooting

#No streaming visible

Check browser Network tab for /api/ai/chat-mcp
Verify OpenAI API key is set
Check server logs for errors
Ensure MCP server is running

#Tool calls not executing

Verify MCP server running at /api/llm/mcp
Check MCP server logs for errors
Test MCP tools directly in inspector
Verify LLM has access to tools

#Overlay not appearing

Verify page has overlays enabled
Check block is added to page
Verify page is published
Check browser console for errors

#Messages not appearing

Verify page loaded successfully
Check browser console for errors
Ensure authentication is valid
Test with simple text message

#Security Considerations

#Authentication

Uses existing Payload CMS authentication
Session-based access control
No additional auth required

#Data Privacy

Messages not stored in database
Export uses client-side JSON
No third-party analytics
All processing on secure servers

#Rate Limiting

Implement per-user rate limits
Monitor for abuse
Set reasonable timeouts
Log all tool calls

#Performance Optimization

#Streaming Optimization

Chunk size: optimized for 1-2 second updates
Token limit: configured for fast responses
Tool timeout: 30 seconds per tool call

#Caching Strategy

Cache frequently accessed tool results
localStorage for UI state persistence
In-memory message history (no DB writes)

#Scaling Considerations

Multiple instances can run in parallel
Stateless design allows horizontal scaling
Database connections pooled
MCP server can be load-balanced

#Best Practices

#For Users

Be specific in prompts
Use tool results to refine queries
Export important conversations
Review tool calls before execution

#For Developers

Keep API routes stateless
Implement proper error handling
Test tool execution thoroughly
Monitor performance metrics
Log all tool calls for debugging

#For Operators

Monitor MCP server health
Keep OpenAI API quota sufficient
Set up alerts for errors
Regular backup of configuration
Monitor streaming latency

#Future Enhancements

#Planned Features

Multi-session chat history (database-backed)
User preferences and custom quick actions
Voice input (speech-to-text)
File attachments for context
Collaborative chat and sharing
Usage analytics and insights
Per-tenant custom tools
Image input support

#Timeline

Q4 2025: Multi-session support
Q1 2026: Voice input and file attachments
Q2 2026: Collaboration features

#Support & Resources

#Documentation

Modern Implementation Guide: AI_CHAT_MODERN_GUIDE.md (archive)
MCP Server Setup: AI_CHAT_MCP_SERVER_SETUP.md (archive)
Legacy Guide: AI_CHAT_WORK_PENDING.md (archive)

#External Resources

#Getting Help

Check this guide first
Review archived documentation
Check browser console logs
Enable debug logging
Contact development team

Last Updated: October 27, 2025 (Consolidated) Version: 1.1.0 (Merged from 6 files) Status: ✅ Production Ready Maintenance: Review quarterly for deprecated features