cordlesssteve/conversation-search-mcp

Conversation Search MCP Server

Version: 1.1.0
Status: Production Ready
Last Updated: 2025-01-07

Overview

Advanced MCP server providing semantic and traditional search capabilities across Claude Code conversation history. Features vector embeddings, hybrid search, and comprehensive conversation management tools.

🚀 Key Features

Search Capabilities

• Traditional Search: Fast FTS-based keyword search with session indexing
• Vector Search: Semantic similarity using OpenAI embeddings
• Hybrid Search: Combined semantic + keyword matching for optimal results
• Context Retrieval: Adjacent chunk expansion for full conversation context

Conversation Management

• Recent Conversations: Optimized retrieval with project filtering
• Session Details: Full conversation history with message threading
• Auto-Naming: AI-powered conversation title generation
• Batch Operations: Bulk renaming and processing capabilities

Database Operations

• Incremental Updates: Process only new conversations since last run
• Full Migration: Complete conversation database rebuild
• Statistics: Comprehensive indexing and usage metrics
• Vector Migration: One-time embedding generation for existing conversations

📊 Current Scale

• Conversations: 664 processed sessions
• Messages: 118,453+ indexed messages
• Vector Chunks: 13,847 semantic chunks
• Database Size: ~420MB optimized storage
• Embedding Cost: ~$0.57 (one-time migration)

🛠️ Technical Stack

• Runtime: Node.js with TypeScript
• Database: SQLite with FTS and vector extensions
• Embeddings: OpenAI text-embedding-3-small
• Protocol: Model Context Protocol (MCP)
• Search: Hybrid semantic + keyword matching

🔒 Security Configuration

Environment Variables Setup

1. Copy the environment template:

   cp .env.example .env
   

2. Configure your API key:

   # Edit .env and add your OpenAI API key
   OPENAI_API_KEY=your_actual_api_key_here
   

Security Best Practices

• ✅ Environment Variables: All sensitive data is configured via environment variables
• ✅ No Hardcoded Secrets: API keys are never committed to version control
• ✅ Secure Defaults: Vector search gracefully degrades without API key
• ✅ Read-Only Access: OpenAI API is used only for text embedding generation
• ✅ Local Processing: All conversation data remains on your system
• ✅ Cost Control: Built-in token estimation and cost tracking

API Key Management

• Required For: Vector search, semantic search, AI-powered naming
• Not Required For: Traditional keyword search, conversation management
• Permissions: Read-only access to OpenAI embeddings API
• Cost: ~$0.0001 per 1,000 tokens (very low cost for typical usage)
• Rate Limits: Automatic batching and retry logic included

Data Privacy

• Local Storage: All conversation data stored locally in SQLite
• No Data Sharing: Conversations never sent to external services except for embedding generation
• User Control: Vector search entirely optional and user-controlled
• Audit Trail: All API usage logged with token counts and costs

⚡ Quick Start

Prerequisites

# 1. Copy and configure environment variables
cp .env.example .env
# Edit .env with your OpenAI API key (optional)

# 2. Install dependencies
npm install

Build and Run

# Build the server
npm run build

# Test direct communication
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | node dist/src/index.js

MCP Integration

Add to your Claude Code configuration:

{
  "conversation-search": {
    "type": "stdio", 
    "command": "node",
    "args": ["/path/to/conversation-search/dist/src/index.js"],
    "env": {}
  }
}

🔍 Available Tools

Traditional Search

• search_conversations - Keyword search with role filtering
• get_recent_conversations - Latest conversations with project filtering
• get_conversation_details - Full session message history
• get_session_for_resume - Resume-formatted conversation data

Vector Search (Requires OpenAI API Key)

• vector_search_conversations - Semantic similarity search
• hybrid_search_conversations - Combined semantic + keyword search
• get_chunk_with_context - Expand search results with adjacent chunks

Management Tools

• rename_conversation - Assign custom conversation names
• generate_conversation_summary - AI-powered title generation
• list_conversations_with_names - Named conversation listing
• batch_rename_recent - Bulk conversation naming

Database Operations

• update_database - Full conversation database rebuild
• update_database_incremental - Process only new conversations
• get_indexing_stats - Database statistics and health metrics
• migrate_to_vector_database - One-time vector embedding migration

📖 Documentation

• - Real-time project state
• - System design and decisions
• - Complete tool documentation
• - Setup and contribution guide

🎯 Performance

• Search Speed: Sub-second response for most queries
• Memory Efficient: SQLite-based storage with optimized indexes
• Scalable: Handles 100K+ messages with consistent performance
• Graceful Degradation: Traditional search works without OpenAI API key

🔧 Monitoring

Check server health:

# Get comprehensive statistics
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_indexing_stats"}, "id": 1}' | node dist/src/index.js

Expected output includes traditional and vector database metrics, processing dates, and configuration status.

📝 License

Private development tool - not for redistribution.