local_faiss_mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server implementation that uses FAISS (Facebook AI Similarity Search) as a local vector database for Retrieval-Augmented Generation (RAG) applications.

The goal is to create a self-contained, local RAG system where:

• FAISS handles vector storage and similarity search operations
• The MCP server exposes FAISS functionality as tools for AI agent interaction
• Documents can be ingested, chunked, embedded, and stored locally
• AI agents can query the vector store using natural language

Architecture

The system has three main components:

1. FAISS Vector Store: Local vector database that stores and indexes document embeddings

   • Supports in-memory or disk-persisted indexes
   • Uses similarity metrics (L2 distance, dot product, cosine similarity)

2. MCP Server: Provides tool interface for agent interaction

   • Tool: ingest_document - handles document chunking, embedding generation, and storage in FAISS
   • Tool: query_rag_store - performs similarity searches to retrieve relevant document chunks

3. Agent Integration: Enables natural language interaction with the vector store

   • AI agents use MCP tools to interact with FAISS-backed storage
   • Retrieved chunks augment agent responses for RAG

Key Design Principles

• Local-first: All storage and operations happen locally, no external vector DB services required
• MCP Protocol: Follows Model Context Protocol specifications for tool definitions and agent interaction
• Embedding-based Search: Uses vector embeddings for semantic similarity search rather than keyword matching

Development Commands

Setup

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

Running the Server

# Using the installed command (easiest)
local-faiss-mcp --index-dir /path/to/index/directory

# With custom embedding model
local-faiss-mcp --index-dir /path/to/index/directory --embed all-mpnet-base-v2

# As a Python module
python -m local_faiss_mcp --index-dir /path/to/index/directory

# Direct execution (for development)
python local_faiss_mcp/server.py --index-dir /path/to/index/directory