Add AI chat to an existing app with MCP and Gram

- Show me all tasks assigned to Sarah that are due this week. 
- How many users visited my blog last week?
- Find me the top three candidates who applied yesterday

TaskBoard/
├── taskboard/                 # Existing Next.js app
│   ├── src/
│   │   ├── app/api/           # CRUD API routes
│   │   │   ├── items/         # Task CRUD operations
│   │   │   ├── login/         # User authentication
│   │   │   └── register/      # User registration
│   │   ├── components/        # React components
│   │   └── lib/               # Database and auth helpers
│   └── prisma/                # SQLite database
└── docker-compose.yml         # Container setup

TaskBoard/
├── taskboard/                 # Existing Next.js app (unchanged)
│   ├── src/
│   │   ├── app/api/
│   │   │   ├── items/
│   │   │   ├── chat/          # New: proxy to chat service
│   │   │   ├── login/
│   │   │   └── register/
│   │   ├── components/
│   │   │   ├── KanbanBoard/
│   │   │   └── ChatComponent/ # New: floating chat popup
│   │   └── lib/
├── mcp-agent-service/         # New: small chat microservice
│   ├── main.py                # FastAPI + OpenAI Agents SDK
│   ├── requirements.txt       # 6 dependencies
│   └── Dockerfile             # Python container
└── docker-compose.yml         # Updated: runs both services

git clone https://github.com/ritza-co/TaskBoard.git
cd TaskBoard
 
# Make sure you're on the main branch (CRUD only, no chat)
git checkout main
 
# Create environment file
cp .env.example .env
 
# Start with Docker (recommended for testing)
docker-compose up --build

# In the taskboard directory
npm install
npm run generate-docs

# Install ngrok if you haven't already
brew install ngrok  # or download from ngrok.com
 
# In a new terminal, expose your local API
ngrok http 3000

// taskboard/src/components/ChatComponent.tsx
import React, { useState, useRef, useEffect } from 'react';
import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
 
interface Message {
  role: 'user' | 'assistant';
  content: string;
  timestamp: string;
  toolUsage?: any;
  isStreaming?: boolean;
}
 
interface ChatComponentProps {
  userId: string;
  onChatClose?: () => void;
}
 
const ChatComponent: React.FC<ChatComponentProps> = ({ userId, onChatClose }) => {
  const [messages, setMessages] = useState<Message[]>([]);
  const [input, setInput] = useState('');
  const [isLoading, setIsLoading] = useState(false);
  const [sessionId, setSessionId] = useState<string | null>(null);
  const [isOpen, setIsOpen] = useState(false);
  const messagesEndRef = useRef<HTMLDivElement>(null);
  const textareaRef = useRef<HTMLTextAreaElement>(null);
 
  const MAX_MESSAGES = 5;
  const userMessageCount = messages.filter(msg => msg.role === 'user').length;
 
  // Core chat functionality - sendMessage, handleKeyDown, etc.
  const sendMessage = async () => {
    if (!input.trim() || isLoading) return;
    
    // ... message handling logic
    try {
      const response = await fetch(`/api/chat?userId=${encodeURIComponent(userId)}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          message: userMessage.content,
          conversation_history: messages.map(msg => ({
            role: msg.role,
            content: msg.content,
            timestamp: msg.timestamp,
          })),
          session_id: sessionId,
        }),
      });
      // ... response processing with streaming animation
    } catch (error) {
      // ... error handling
    }
  };
 
  return (
    <>
      {/* Floating Chat Button */}
      {!isOpen && (
        <button
          onClick={() => setIsOpen(true)}
          className="fixed bottom-4 right-4 z-50 w-14 h-14 bg-black text-white rounded-2xl shadow-2xl hover:shadow-xl transition-all duration-300 flex items-center justify-center"
          aria-label="Open Task Agent"
        >
          {/* Chat icon SVG */}
          <svg className="w-8 h-8" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z" />
          </svg>
        </button>
      )}
 
      {/* Chat Sidebar with responsive design, message rendering, and input area */}
      {isOpen && (
        <div className="fixed top-0 right-0 h-full z-50 w-full md:w-96 bg-white/95 backdrop-blur-lg border-l border-gray-200 shadow-2xl flex flex-col">
          {/* Header with controls */}
          <div className="flex-shrink-0 flex items-center justify-between p-4 border-b border-gray-200">
            {/* ... header content */}
          </div>
 
          {/* Messages area with tool usage indicators */}
          <div className="flex-1 overflow-y-auto p-4 space-y-4">
            {messages.map((message, index) => (
              <div key={index} className={/* message styling */}>
                {/* Tool usage display */}
                {message.role === 'assistant' && message.toolUsage && (
                  <div className="mb-3 p-3 rounded-lg border">
                    {/* Tool indicators */}
                  </div>
                )}
                {/* Message content with ReactMarkdown */}
                <ReactMarkdown remarkPlugins={[remarkGfm]}>
                  {message.content}
                </ReactMarkdown>
              </div>
            ))}
          </div>
 
          {/* Input area */}
          <div className="flex-shrink-0 p-4 border-t border-gray-200">
            {/* Textarea and send button */}
          </div>
        </div>
      )}
    </>
  );
};
 
export default ChatComponent;

// taskboard/src/app/dashboard/page.tsx
// Add this import at the top
import ChatComponent from '@/components/ChatComponent';
 
// Inside your dashboard component, add this after the TaskModal component at the end of the final return statement:
{/* Floating Chat Component */}
{userId && <ChatComponent userId={userId} onChatClose={() => fetchItems(true)} />}

# In the /taskboard directory
npm install react-markdown remark-gfm

# From the TaskBoard root directory
mkdir mcp-agent-service
cd mcp-agent-service

# mcp-agent-service/requirements.txt
openai-agents
fastapi==0.116.1
uvicorn==0.35.0
python-dotenv==1.1.1
pydantic==2.11.7
httpx==0.28.1
requests==2.32.4

# mcp-agent-service/main.py
import os
import uuid
import asyncio
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from typing import List, Optional, Dict, Any
# OpenAI Agents SDK - handles the AI agent logic
from agents import Agent, Runner, SQLiteSession
from agents.mcp import MCPServerStdio  # Connects to Gram MCP server
 
app = FastAPI(title="OpenAI Agents Chat Microservice", version="1.0.0")
 
# Validate required environment variables
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
TASKBOARD_SERVER_URL = os.getenv("TASKBOARD_SERVER_URL")
 
if not TASKBOARD_SERVER_URL:
    raise ValueError("TASKBOARD_SERVER_URL environment variable is required")
 
if not OPENAI_API_KEY:
    raise ValueError("OPENAI_API_KEY environment variable is required")
 
# Set OpenAI API key for the library
os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY
 
# Add CORS middleware to allow requests from Next.js app
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
 
class ChatRequest(BaseModel):
    message: str
    conversation_history: List[Dict[str, Any]] = []
    session_id: Optional[str] = None
 
class ChatResponse(BaseModel):
    response: str
    session_id: str
    user_message_count: int
    tool_usage: Optional[Dict[str, Any]] = None
 
def extract_user_id_from_history(conversation_history: List[Dict[str, Any]]) -> Optional[str]:
    """Extract user ID from system message in conversation history."""
    for msg in conversation_history:
        if msg.get('role') == 'system' and msg.get('content'):
            content = msg['content']
            if 'User ID:' in content:
                return content.split('User ID:')[1].split('.')[0].strip()
    return None
 
async def create_mcp_server() -> MCPServerStdio:
    """Create MCP server connection to Gram.
 
    This connects to your Gram MCP server, which acts as a bridge
    between the OpenAI Agent and your TaskBoard API.
    """
    return MCPServerStdio(
        name="GramTaskboard",
        params={
            "command": "npx",  # Uses the mcp-remote package
            "args": [
                "mcp-remote",
                "https://app.getgram.ai/mcp/your-server-id",  # Replace with your actual Gram MCP server URL from Step 1
                "--header",
                f"MCP-TASKBOARD-SERVER-URL:{TASKBOARD_SERVER_URL}",  # Tells Gram where to find your API
                "--timeout", "120000"
            ]
        },
        cache_tools_list=True,  # Cache for performance
        client_session_timeout_seconds=120.0,
        max_retry_attempts=2,
        retry_backoff_seconds_base=2.0
    )
 
async def create_agent_with_mcp(user_id: str, mcp_server: MCPServerStdio) -> Agent:
    """Create an OpenAI Agent that knows how to use your TaskBoard API.
 
    The Agent automatically discovers your API endpoints via the MCP server
    and learns how to call them based on user requests.
    """
    return Agent(
        name="TaskBoard Assistant",
        instructions=f"""You are a helpful assistant that can manage tasks in a TaskBoard application.
        You can list, create, update, delete, and search for tasks using the available MCP tools.
 
        When interacting with tasks:
        - Always use the provided MCP tools to perform TaskBoard operations
        - Be helpful and provide clear responses about task operations
        - If a user wants to move a task, update its status (todo, doing, done)
        - When listing tasks, organize them by status if helpful
        - When creating tasks, ask for clarification if title or description is unclear
 
        {f'The user ID is: {user_id}. Always use this user ID when calling TaskBoard tools.' if user_id else 'User ID not available - tools may not work properly.'}
 
        Available task statuses: todo, doing, done
 
        Use natural language to explain what actions you're taking and their results.""",
        model="gpt-4o-mini",  # The LLM that powers the agent
        mcp_servers=[mcp_server]  # Your TaskBoard API tools
    )
 
@app.post("/chat", response_model=ChatResponse)
async def chat(request: ChatRequest):
    # Generate session ID if not provided
    session_id = request.session_id or str(uuid.uuid4())
 
    # Count user messages in conversation history
    user_message_count = 1  # Current message
    for msg in request.conversation_history:
        if msg.get('role') == 'user':
            user_message_count += 1
 
    # Check if we've reached the limit (5 messages)
    if user_message_count > 5:
        return ChatResponse(
            response="This conversation has reached the maximum limit of 5 user messages. Please start a new conversation.",
            session_id=session_id,
            user_message_count=user_message_count
        )
 
    # Extract userId from conversation history
    user_id = extract_user_id_from_history(request.conversation_history)
 
    try:
        # Create MCP server connection
        mcp_server = await create_mcp_server()
 
        # Use the MCP server with timeout
        async with asyncio.timeout(180):  # 3 minute total timeout
            async with mcp_server as server:
                # Create agent with the connected MCP server
                agent = await create_agent_with_mcp(user_id, server)
 
                # Create session for conversation persistence
                session = SQLiteSession(session_id, "conversations.db")
 
                # Run the agent
                result = await Runner.run(
                    agent,
                    request.message,
                    session=session
                )
 
                # Extract tool usage information
                tool_usage = None
                if hasattr(result, 'tool_calls') and result.tool_calls:
                    tool_usage = {
                        "has_tools": True,
                        "tool_calls": [
                            {
                                "function": {
                                    "name": tc.get('name', 'unknown'),
                                    "arguments": tc.get('arguments', {})
                                },
                                "content": tc.get('result', 'No result')
                            } for tc in result.tool_calls
                        ]
                    }
 
                return ChatResponse(
                    response=result.final_output,
                    session_id=session_id,
                    user_message_count=user_message_count,
                    tool_usage=tool_usage
                )
 
    except asyncio.TimeoutError:
        return ChatResponse(
            response="The TaskBoard service is taking too long to respond. Please try again in a few minutes.",
            session_id=session_id,
            user_message_count=user_message_count
        )
    except Exception as e:
        print(f"Error in chat endpoint: {e}")
        return ChatResponse(
            response="I'm experiencing technical difficulties. Please try again in a moment.",
            session_id=session_id,
            user_message_count=user_message_count
        )
 
@app.get("/health")
async def health_check():
    return {"status": "healthy", "service": "openai-agents-chat-microservice"}
 
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8085)

# mcp-agent-service/.env
OPENAI_API_KEY=your_openai_api_key_here
TASKBOARD_SERVER_URL=https://your-ngrok-url.ngrok.io  # Your ngrok URL from Step 1

// taskboard/src/app/api/chat/route.ts
import { NextRequest, NextResponse } from 'next/server';
 
const CHAT_SERVICE_URL = process.env.CHAT_SERVICE_URL || 'http://localhost:8085';
 
export async function POST(request: NextRequest) {
  // Get userId from URL parameter (handled by middleware)
  let userId = request.headers.get('x-user-id');
 
  if (!userId) {
    userId = new URL(request.url).searchParams.get('userId');
  }
 
  if (!userId) {
    return NextResponse.json({ message: 'Unauthorized - userId required' }, { status: 401 });
  }
 
  try {
    const body = await request.json();
 
    // Prepare conversation history with user context
    const conversationHistory = body.conversation_history || [];
 
    // Add system message with user ID for security
    conversationHistory.unshift({
      role: 'system',
      content: `User ID: ${userId}. Always use this user ID when calling TaskBoard tools to ensure you access the correct user's data.`,
      timestamp: new Date().toISOString()
    });
 
    const requestBody = {
      message: body.message,
      conversation_history: conversationHistory,
      session_id: body.session_id,
    };
 
    // Forward to chat service
    const chatResponse = await fetch(`${CHAT_SERVICE_URL}/chat`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(requestBody),
    });
 
    if (!chatResponse.ok) {
      throw new Error(`Chat service responded with status: ${chatResponse.status}`);
    }
 
    const chatData = await chatResponse.json();
    return NextResponse.json(chatData);
 
  } catch (error) {
    console.error('Chat API error:', error);
    return NextResponse.json(
      { message: 'Failed to process chat request' },
      { status: 500 }
    );
  }
}

// taskboard/src/middleware.ts
// Update the config at the bottom of the file:
export const config = {
  matcher: ['/api/items', '/api/items/:path*', '/api/chat'], // Add /api/chat
};

# mcp-agent-service/Dockerfile
FROM python:3.11-slim
 
# Install Node.js and npm for npx command
RUN apt-get update && apt-get install -y \
    curl \
    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*
 
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
 
EXPOSE 8085
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8085"]

# docker-compose.yml
version: '3.8'
 
services:
  taskboard:
    build: ./taskboard
    ports:
      - "3000:3000"
    environment:
      - CHAT_SERVICE_URL=http://chat-service:8085
      - DATABASE_URL=${DATABASE_URL:-file:./prisma/dev.db}
    depends_on:
      - chat-service
    volumes:
      - ./taskboard/prisma/dev.db:/app/prisma/dev.db
    networks:
      - taskboard-network
    env_file:
      - .env
 
  chat-service:
    build: ./mcp-agent-service
    ports:
      - "8085:8085"
    environment:
      - PYTHONUNBUFFERED=1
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - TASKBOARD_SERVER_URL=${TASKBOARD_SERVER_URL:-http://taskboard:3000}
    networks:
      - taskboard-network
    env_file:
      - .env
 
networks:
  taskboard-network:
    driver: bridge

# .env (in root TaskBoard directory)
DATABASE_URL="file:./prisma/dev.db" # Already present
OPENAI_API_KEY=your_openai_api_key_here # Add your OpenAI API key here
TASKBOARD_SERVER_URL=https://your-ngrok-url.ngrok.io  # Your ngrok URL from Step 1

# From the root TaskBoard directory
docker-compose up --build

- Show me all my tasks
- Create a task called 'Test the chat feature'
- Move the chat feature task to doing