📋 Table of Contents

• Overview
• Main Features
• Architecture
• Getting Started
  • Prerequisites
  • Installation
  • Running the Application
• MCP Integration
• Environment Variables
• API Documentation
• Contributors
• License

🎯 Overview

LangConnect Client is a modern, Next.js-based GUI interface for managing vector databases powered by PostgreSQL with pgvector extension. It provides an intuitive web interface for document management, vector search capabilities, and seamless integration with AI assistants through the Model Context Protocol (MCP).

This project was inspired by langchain-ai/langconnect.

✨ Main Features

📚 Collection Management

• CRUD operations with custom metadata support
• Real-time statistics and bulk operations

📄 Document Management

• Multi-format support (PDF, TXT, MD, DOCX, HTML)
• Automatic text extraction and chunking
• Drag-and-drop batch upload

🔍 Advanced Search

• Semantic: Vector similarity search with OpenAI embeddings
• Keyword: PostgreSQL full-text search
• Hybrid: Combined search with configurable weights

🔐 Authentication

• Supabase JWT authentication with automatic token refresh
• Role-based access control
• Secure refresh token management with NextAuth.js

🤖 MCP Integration

• 9+ tools for AI assistants (Claude, Cursor)
• stdio and SSE transport support

🎨 Modern UI

• Next.js with Tailwind CSS
• Dark/Light themes, Multi-language (EN/KO)

🏗️ Architecture

Authentication Flow

The authentication system implements a secure token refresh mechanism:

┌─────────────┐     ┌──────────────┐     ┌───────────┐
│   Browser   │────▶│   NextAuth   │────▶│ Supabase  │
│             │◀────│   (JWT)      │◀────│   Auth    │
└─────────────┘     └──────────────┘     └───────────┘
     │                      │
     │ httpOnly cookie     │ refresh token
     │ (encrypted JWT)     │ stored in JWT
     │                      │
     ▼                      ▼
 Only accessToken      Auto refresh when
 exposed to client     accessToken expires

Key Security Features:

• Refresh tokens are never exposed to the client
• Automatic token refresh when access token expires
• Token rotation on each refresh for enhanced security
• Encrypted JWT storage in httpOnly cookies

🚀 Getting Started

Quick Start

# Clone and setup
git clone https://github.com/teddynote-lab/langconnect-client.git
cd langconnect-client
cp .env.example .env

# Edit .env with your credentials, then:
make build   # Build Docker images
make up      # Start all services

Create MCP configuration

Stop services

Prerequisites

• Docker and Docker Compose
• Node.js 20+ (for MCP inspector)
• Python 3.11+ with UV package manager
• Supabase account

Installation

1. Clone the repository

   git clone https://github.com/teddynote-lab/langconnect-client.git
   cd langconnect-client

2. Set up environment variables

3. Configure Supabase

   a. Create a new project at supabase.com

   b. Get your API credentials:

   • Go to Project Settings → API
   • Copy the URL and anon public key

   c. Update .env file:

   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_KEY=your-anon-public-key

4. Build the application

Running the Application

1. Start all services

2. Access the services

   • 🎨 Frontend: http://localhost:3000
   • 📚 API Documentation: http://localhost:8080/docs
   • 🔍 Health Check: http://localhost:8080/health

3. Stop services

4. View logs

🤖 MCP Integration

Automated Setup

1. Generate MCP configuration

   This command will:

   • Prompt for your Supabase credentials
   • Automatically obtain an access token
   • Update .env with the token
   • Generate mcpserver/mcp_config.json

2. Integration with AI Assistants

   For Claude Desktop:

   • Copy the contents of mcpserver/mcp_config.json
   • Paste into Claude Desktop's MCP settings

   For Cursor:

   • Copy the MCP configuration
   • Add to Cursor's settings under MCP integrations

Available MCP Tools

• search_documents - Perform semantic/keyword/hybrid search
• list_collections - List all collections
• get_collection - Get collection details
• create_collection - Create new collection
• delete_collection - Delete collection
• list_documents - List documents in collection
• add_documents - Add text documents
• delete_document - Delete documents
• get_health_status - Check API health
• multi_query - Generate multiple search queries from a single question

Sample RAG Prompt

Here is a sample RAG prompt that can be used in Claude Desktop.

You are a question-answer assistant based on given document.
You must use MCP tool(`langconnect-rag-mcp`) to answer the question.

#Search Configuration:
- Target Collection: (user's request, default value: RAG)
- Search Type: hybrid(preferred)
- Search Limit: 5(default)

#Search Guidelines:
Follow the guidelines step-by-step to find the answer.
1. Use `list_collections` to list up collections and find right **Collection ID** for user's request.
2. Use `multi_query` to generate at least 3 sub-questions which are related to original user's request.
3. Search all queries generated from previous step(`multi_query`) and find useful documents from collection.
4. Use searched documents to answer the question.

---

## Format:
(answer to the question)

**Source**
- [1] (Source and page numbers)
- [2] (Source and page numbers)
- ...

---

[Note]
- Answer in same language as user's request
- Append sources that you've referenced at the very end of your answer.
- If you can't find your answer from <search_results>, just say you can't find any relevant source to answer the question without any narrative sentences.

Running MCP SSE Server

Quick Start with Script

# Use the convenient launcher script
./run_mcp_sse.sh

This script will:

• Check if all requirements are met (uv, .env file)
• Verify API server is running
• Start the MCP SSE server with automatic authentication

Manual Start

# Or run directly
uv run python mcpserver/mcp_sse_server.py

The server now includes automatic authentication:

• Tests existing token validity on startup
• Prompts for login if token is expired or missing
• Automatically updates .env with new token
• Starts the SSE server on port 8765

Testing MCP Integration

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

In the Inspector:

1. Select "SSE" as transport type
2. Enter http://localhost:8765/sse as URL
3. Connect and test the available tools

🔧 Environment Variables

👥 Contributors

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.