better-chatbot

Keinsaas Navigator - A better open-source AI chatbot for individuals and teams.

Originally created by Choi Sung Keun.

<img width="1184" height="576" alt="thumbnail" loading="lazy" src="https://github.com/user-attachments/assets/d6ba80ff-a62a-4920-b266-85c4a89d6076" />

🚀 Live Demo | See the experience in action in the preview below!

Demo Chats

• MCP Tools Demo: Chat with Tools
• Image Generation Demo: Chat with Image Generation

Quick Start 🚀

Get your app running in minutes! No installation or payment required.

You only need one AI Provider API Key (OpenAI, Claude, Gemini, etc.). Everything else runs on free tiers - database, file storage, and hosting.

👉 Click this guide to deploy your site with just a few clicks

---

Keinsaas Navigator - A better open-source AI chatbot for individuals and teams, inspired by ChatGPT, Claude, Grok, and Gemini.

• Multi-AI Support - Integrates all major LLMs: OpenAI, Anthropic, Google, xAI, Ollama, and more
• Powerful Tools - MCP protocol, web search, JS/Python code execution, data visualization
• Image Generation - Create and edit images with AI models (OpenAI, Google Gemini, xAI)
• Automation - Custom agents, visual workflows, artifact generation
• Collaboration - Share agents, workflows, and MCP configurations with your team
• Voice Assistant - Realtime voice chat with full MCP tool integration
• Intuitive UX - Instantly invoke any feature with @mention
• Quick Start - Deploy free with Vercel Deploy button

Built with Vercel AI SDK and Next.js, combining the best features of leading AI services into one platform.

Table of Contents

• Table of Contents
• Preview
  • 🧩 Browser Automation with Playwright MCP
  • 🔗 Visual Workflows as Custom Tools
  • 🤖 Custom Agents
  • 🎙️ Realtime Voice Assistant + MCP Tools
  • ⚡️ Quick Tool Mentions (@) & Presets
  • 🧭 Tool Choice Mode
  • 🛠️ Default Tools
    • 🌐 Web Search
    • ⚡️ JS,PYTHON Executor
    • 📊 Data Visualization Tools
• Getting Started
  • Quick Start (Docker Compose Version) 🐳
  • Quick Start (Local Version) 🚀
  • Environment Variables
• 📘 Guides
  • 🔌 MCP Server Setup & Tool Testing
  • 🐳 Docker Hosting Guide
  • ▲ Vercel Hosting Guide
  • 🗂️ File Storage Drivers
  • 🎯 System Prompts & Chat Customization
  • 🔐 OAuth Sign-In Setup
  • 🕵🏿 Adding openAI like providers
  • 🧪 E2E Testing Guide
• 💡 Tips
  • 💬 Temporary Chat Windows
• 🗺️ Roadmap
• 🙌 Contributing
• 💬 Join Our Discord

This project is evolving at lightning speed! ⚡️ We're constantly shipping new features and smashing bugs. Star this repo to join the ride and stay in the loop with the latest updates!

Preview

Get a feel for the UX — here's a quick look at what's possible.

🧩 Browser Automation with Playwright MCP

Example: Control a web browser using Microsoft's playwright-mcp tool.

• The LLM autonomously decides how to use tools from the MCP server, calling them multiple times to complete a multi-step task and return a final message.

Sample prompt:

1. Use the @tool('web-search') to look up information about “modelcontetprotocol.”

2. Then, using : @mcp("playwright")
   - navigate Google (https://www.google.com)
   - Click the “Login” button
   - Enter my email address (neo.cgoing@gmail.com)
   - Clock the "Next"  button
   - Close the browser

<br/>

🔗 Visual Workflows as Custom Tools

<img width="1912" height="953" alt="workflow" loading="lazy" src="https://github.com/user-attachments/assets/e69e72e8-595c-480e-b519-4531f4c6331f" /> <img width="1567" alt="workflow-mention" loading="lazy" src="https://github.com/user-attachments/assets/cf3e1339-ee44-4615-a71d-f6b46833e41f" />

Example: Create custom workflows that become callable tools in your chat conversations.

• Build visual workflows by connecting LLM nodes (for AI reasoning) and Tool nodes (for MCP tool execution)
• Publish workflows to make them available as @workflow_name tools in chat
• Chain complex multi-step processes into reusable, automated sequences

<br/>

🤖 Custom Agents

<img width="1567" alt="agent-example" loading="lazy" src="https://github.com/user-attachments/assets/d0a325c0-ff1e-4038-b6bf-fcf57659a5c1" />

Example: Create specialized AI agents with custom instructions and tool access.

• Define custom agents with specific system prompts and available tools
• Easily invoke agents in chat using @agent_name
• Build task-specific assistants like a GitHub Manager agent with issue/PR tools and project context

For instance, create a GitHub Manager agent by:

• Providing GitHub tools (issue/PR creation, comments, queries)
• Adding project details to the system prompt
• Calling it with @github_manager to manage your repository

<br/>

🎙️ Realtime Voice Assistant + MCP Tools

<p align="center"> <video src="https://github.com/user-attachments/assets/e2657b8c-ce0b-40dd-80b6-755324024973" width="100%" /> </p>

This demo showcases a realtime voice-based chatbot assistant built with OpenAI's new Realtime API — now extended with full MCP tool integration. Talk to the assistant naturally, and watch it execute tools in real time.

⚡️ Quick Tool Mentions (@) & Presets

<img width="1225" alt="image" src="https://github.com/user-attachments/assets/dfe76b3b-c3d8-436e-8a7c-7b23292e234c" loading="lazy"/>

Quickly call tool during chat by typing @toolname. No need to memorize — just type @ and pick from the list!

Tool Selection vs. Mentions (@) — When to Use What:

• Tool Selection: Make frequently used tools always available to the LLM across all chats. Great for convenience and maintaining consistent context over time.
• Mentions (@): Temporarily bind only the mentioned tools for that specific response. Since only the mentioned tools are sent to the LLM, this saves tokens and can improve speed and accuracy.

Each method has its own strengths — use them together to balance efficiency and performance.

You can also create tool presets by selecting only the MCP servers or tools you need. Switch between presets instantly with a click — perfect for organizing tools by task or workflow.

🧭 Tool Choice Mode

<img width="1225" alt="image" src="https://github.com/user-attachments/assets/8fc64c6a-30c9-41a4-a5e5-4e8804f73473" loading="lazy"/>

Control how tools are used in each chat with Tool Choice Mode — switch anytime with ⌘P.

• Auto: The model automatically calls tools when needed.
• Manual: The model will ask for your permission before calling a tool.
• None: Tool usage is disabled completely.

This lets you flexibly choose between autonomous, guided, or tool-free interaction depending on the situation.

🛠️ Default Tools

🌐 Web Search

<img width="1034" height="940" alt="web-search" src="https://github.com/user-attachments/assets/261037d9-e1a7-44ad-b45e-43780390a94e" />

Built-in web search powered by Exa AI. Search the web with semantic AI and extract content from URLs directly in your chats.

• Optional: Add EXA_API_KEY to .env to enable web search
• Free Tier: 1,000 requests/month at no cost, no credit card required
• Easy Setup: Get your API key instantly at dashboard.exa.ai

🎨 Image Generation

<img width="1034" height="940" loading="lazy" alt="image-generation" src="https://github.com/user-attachments/assets/b081c837-8948-4f4d-a2f4-c8630cf0eaa2" />

Built-in image generation and editing capabilities powered by AI models. Create, edit, and modify images directly in your chats.

• Supported Operations: Image generation, editing, and composition
• Current Models: Gemini Nano Banana, OpenAI

⚡️ JS,PYTHON Executor

<img width="1225" alt="js-executor-preview" src="https://github.com/user-attachments/assets/7deed824-e70b-46d4-a294-de20ed4dc869" loading="lazy"/>

It is a simple JS execution tool.

📊 Data Visualization Tools

Interactive Tables: Create feature-rich data tables with advanced functionality:

• Sorting & Filtering: Sort by any column, filter data in real-time
• Search & Highlighting: Global search with automatic text highlighting
• Export Options: Export to CSV or Excel format with lazy-loaded libraries
• Column Management: Show/hide columns with visibility controls
• Pagination: Handle large datasets with built-in pagination
• Data Type Support: Proper formatting for strings, numbers, dates, and booleans

Chart Generation: Visualize data with various chart types (bar, line, pie charts)

Additionally, many other tools are provided, such as an HTTP client for API requests and more.

<br/>

…and there's even more waiting for you. Try it out and see what else it can do!

<br/>

Getting Started

This project uses pnpm as the recommended package manager.

# If you don't have pnpm:
npm install -g pnpm

Quick Start (Docker Compose Version) 🐳

# 1. Install dependencies
pnpm i

# 2. Enter only the LLM PROVIDER API key(s) you want to use in the .env file at the project root.
# Example: The app works with just OPENAI_API_KEY filled in.
# (The .env file is automatically created when you run pnpm i.)

# 3. Build and start all services (including PostgreSQL) with Docker Compose
pnpm docker-compose:up

Quick Start (Local Version) 🚀

pnpm i

#(Optional) Start a local PostgreSQL instance
# If you already have your own PostgreSQL running, you can skip this step.
# In that