Human-in-the-Loop Tool Approval

• Interactive tool call approval before execution
• Granular control with approve/deny/modify options
• Optional auto-approval mode for trusted environments
• Real-time streaming with tool execution pauses

Persistent Conversation Memory

• LangGraph checkpointer with PostgreSQL backend
• Full conversation history preservation
• Thread-based organization
• Seamless resume across sessions

Multimodal File Uploads

• Upload images, PDFs, and text files with messages
• S3-compatible storage (MinIO for development)
• Automatic file processing for AI consumption
• Production-ready with AWS S3, Cloudflare R2 support

Real-time Streaming Interface

• Server-Sent Events (SSE) for live responses
• Optimistic UI updates with React Query
• Type-safe message handling
• Error recovery and graceful degradation

Persistent Model Settings

• Provider and model selection saved to localStorage automatically
• Settings survive page reloads and thread navigation
• No backend required — zero latency reads on startup

LLM Observability with Langfuse

• End-to-end tracing of agent runs, LLM calls, tool invocations, and token usage
• Works with Langfuse Cloud or a self-hosted instance
• Toggle via LANGFUSE_ENABLED env var — zero overhead when disabled
• See docs/OBSERVABILITY.md for setup instructions

Modern Tech Stack

• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• Backend: Node.js, Prisma ORM, PostgreSQL, MinIO/S3
• AI: LangGraph.js, OpenAI/Google/Anthropic models
• UI: shadcn/ui components, Lucide icons

Quick Start

Prerequisites

• Node.js 18+ and pnpm
• Docker (for PostgreSQL and MinIO)
• OpenAI API key, Google AI API key, or Anthropic API key

1. Clone and Install

git clone https://github.com/IBJunior/fullstack-langgraph-nextjs-agent.git
cd fullstack-langgraph-nextjs-agent
pnpm install

2. Environment Setup

cp .env.example .env.local

Edit .env.local with your configuration:

# Database
DATABASE_URL="postgresql://user:password@localhost:5434/agent_db"

# AI Models (choose one or more)
OPENAI_API_KEY="sk-..."
GOOGLE_API_KEY="..."
ANTHROPIC_API_KEY="sk-ant-..."

# Optional: Default model
DEFAULT_MODEL="gpt-4o-mini"  # or "gemini-1.5-flash" or "claude-sonnet-4-5"

3. Start Services

docker compose up -d  # Starts PostgreSQL and MinIO

4. Database Setup

pnpm prisma:generate
pnpm prisma:migrate

5. Run Development Server

pnpm dev
# Or use custom port
pnpm dev --port=3005

Visit http://localhost:3000 to start chatting with your AI agent!

Screenshots

Usage Guide

Adding MCP Servers

1. Navigate to Settings - Click the gear icon in the sidebar
2. Add MCP Server - Click "Add MCP Server" button
3. Configure Server:
   • Name: Unique identifier (e.g., "filesystem")
   • Type: Choose stdio or http
   • Command: For stdio servers (e.g., npx @modelcontextprotocol/server-filesystem)
   • Args: Command arguments (e.g., ["/path/to/allow"])
   • URL: For HTTP servers

MCP server configuration form with example filesystem server setup

Want to build your own MCP server? Check out create-mcp-server - scaffold production-ready MCP servers in seconds with TypeScript, multiple frameworks (MCP SDK or FastMCP), and built-in debugging tools.

Example MCP Server Configurations

Filesystem Server (stdio)

{
  "name": "filesystem",
  "type": "stdio",
  "command": "npx",
  "args": ["@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
}

HTTP API Server

{
  "name": "web-api",
  "type": "http",
  "url": "http://localhost:8080/mcp",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

Note: Some HTTP MCP servers require OAuth 2.0 authentication. See OAuth Documentation for details.

Tool Approval Workflow

1. Agent Requests Tool - AI suggests using a tool
2. Approval Prompt - Interface shows tool details and asks for approval
3. User Decision:
   • ✅ Allow: Execute tool as requested
   • ❌ Deny: Skip tool execution
   • ✏️ Modify: Edit tool parameters before execution
4. Continue Conversation - Agent responds with tool results

Architecture

High-Level Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Next.js UI   │◄──►│  Agent Service   │◄──►│  LangGraph.js   │
│   (React 19)   │    │  (SSE Streaming) │    │    Agent        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   React Query   │    │     Prisma       │    │  MCP Clients    │
│   (State Mgmt)  │    │   (Database)     │    │   (Tools)       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                  ┌──────────────────────────────┐
                  │   PostgreSQL  │  MinIO/S3    │
                  │  (Persistence)│ (File Store) │
                  └──────────────────────────────┘

Core Components

Agent Builder (src/lib/agent/builder.ts)

• Creates StateGraph with agent→tool_approval→tools flow
• Handles tool approval interrupts
• Manages model binding and system prompts

MCP Integration (src/lib/agent/mcp.ts)

• Dynamic tool loading from database-stored MCP servers
• Support for stdio and HTTP transports
• Tool name prefixing for conflict prevention

Streaming Service (src/services/agentService.ts)

• Server-Sent Events for real-time responses
• Message processing and chunk aggregation
• Tool approval workflow handling

Chat Hook (src/hooks/useChatThread.ts)

• React Query integration for optimistic UI
• Stream management and error handling
• Tool approval user interface

File Storage (src/lib/storage/)

• S3-compatible storage with MinIO (development) or AWS S3 (production)
• File validation, upload, and content processing for AI
• Multimodal message building with base64 conversion

For detailed architecture documentation, see docs/ARCHITECTURE.md.

Development

Available Scripts

pnpm dev                 # Start development server with Turbopack
pnpm build              # Production build
pnpm start              # Start production server
pnpm lint               # Run ESLint
pnpm format             # Format with Prettier
pnpm format:check       # Check formatting

# Database
pnpm prisma:generate    # Generate Prisma client (after schema changes)
pnpm prisma:migrate     # Create and apply migrations
pnpm prisma:studio      # Open Prisma Studio (database UI)

Project Structure

src/
├── app/                 # Next.js Ap