Skip to content
This repository was archived by the owner on Jul 4, 2025. It is now read-only.

Latest commit

 

History

History
294 lines (228 loc) · 9.71 KB

README.md

File metadata and controls

294 lines (228 loc) · 9.71 KB

LangConnect Client

Next.js React TypeScript Python FastAPI PostgreSQL

A Modern GUI Interface for Vector Database Management

📋 Table of Contents

🎯 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).

✨ Main Features

📚 Collection Management

  • Create, read, update, and delete document collections
  • Organize documents with custom metadata
  • Real-time statistics for documents and chunks
  • Bulk operations support

📄 Document Management

  • Multi-format support (PDF, TXT, MD, DOCX, HTML)
  • Batch upload capabilities with drag-and-drop interface
  • Automatic text extraction and chunking
  • Document-level and chunk-level management
  • Metadata customization for enhanced searchability

🔍 Advanced Search Capabilities

  • Semantic Search: Vector similarity search using OpenAI embeddings
  • Keyword Search: Traditional full-text search
  • Hybrid Search: Combines semantic and keyword search for best results
  • Metadata filtering with JSON support
  • Real-time search results with relevance scores

🔐 Authentication & Security

  • Supabase integration for secure user authentication
  • JWT-based API access
  • Session persistence
  • Role-based access control

🤖 MCP (Model Context Protocol) Integration

  • Direct integration with AI assistants (Claude Desktop, Cursor)
  • 9 comprehensive tools for document management
  • Both stdio and SSE transport support
  • Automated configuration generation

🎨 Modern UI/UX

  • Responsive design with Tailwind CSS
  • Dark/Light theme support
  • Multi-language support (English, Korean)
  • Real-time updates and notifications
  • Interactive API testing interface

🏗️ Architecture

┌─────────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Next.js Frontend  │────▶│  FastAPI Backend │────▶│   PostgreSQL    │
│   (Port 3000)       │     │  (Port 8080)     │     │   + pgvector    │
└─────────────────────┘     └──────────────────┘     └─────────────────┘
         │                           │
         └───────────┬───────────────┘
                     │
              ┌──────▼──────────┐
              │ Supabase Auth   │
              └─────────────────┘

🚀 Getting Started

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/your-username/langconnect.git
cd langconnect

  2. Set up environment variables

    cp .env.example .env

  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

# Also update these for Next.js
NEXTAUTH_SECRET=your-secret-key-here
NEXTAUTH_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:8080

  4. Build the application

    ./install.sh

    This script will:

    • Install frontend dependencies using pnpm
    • Build the Next.js application
    • Build all Docker images

Running the Application

  1. Start all services

    docker compose up -d

  2. Access the services

  3. Stop services

    docker compose down

🤖 MCP Integration

Automated Setup

  1. Generate MCP configuration

    uv run python mcp/create_mcp_json.py

    This command will:

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

  2. Integration with AI Assistants

    For Claude Desktop:

    • Copy the contents of mcp/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

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 mcp/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 as URL
  3. Connect and test the available tools

🔧 Environment Variables

Variable Description Required
OPENAI_API_KEY OpenAI API key for embeddings Yes
SUPABASE_URL Supabase project URL Yes
SUPABASE_KEY Supabase anon public key Yes
NEXTAUTH_SECRET NextAuth.js secret key Yes
NEXTAUTH_URL NextAuth URL (default: http://localhost:3000) Yes
NEXT_PUBLIC_API_URL Public API URL for frontend Yes
POSTGRES_HOST PostgreSQL host (default: postgres) No
POSTGRES_PORT PostgreSQL port (default: 5432) No
POSTGRES_USER PostgreSQL user (default: teddynote) No
POSTGRES_PASSWORD PostgreSQL password No
POSTGRES_DB PostgreSQL database name No
SSE_PORT MCP SSE server port (default: 8765) No

📚 API Documentation

The API provides comprehensive endpoints for document and collection management:

Authentication

  • POST /auth/signup - Create new account
  • POST /auth/signin - Sign in
  • POST /auth/refresh - Refresh token
  • GET /auth/me - Get current user

Collections

  • GET /collections - List collections
  • POST /collections - Create collection
  • GET /collections/{id} - Get collection
  • PUT /collections/{id} - Update collection
  • DELETE /collections/{id} - Delete collection

Documents

  • GET /collections/{id}/documents - List documents
  • POST /collections/{id}/documents - Upload documents
  • DELETE /collections/{id}/documents - Bulk delete
  • POST /collections/{id}/documents/search - Search documents

👥 Contributors


Teddy Lee
🏠
fbwndrud
🏠
jikime
🏠

📄 License

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

Made with ❤️ by TeddyNote LAB