nonatofabio/local-faiss-mcp

Release Notes - v0.1.0

Release Date: 2025-12-01

🎉 Initial PyPI Release

This is the first official release of local-faiss-mcp, a Model Context Protocol (MCP) server that provides local vector
database functionality using FAISS for Retrieval-Augmented Generation (RAG) applications.

✨ Features

Core Functionality

• Local Vector Storage: Uses FAISS for efficient similarity search without external dependencies
• Document Ingestion: Automatically chunks and embeds documents for storage
• Semantic Search: Query documents using natural language with sentence embeddings
• Persistent Storage: Indexes and metadata are saved to disk and can be reloaded
• MCP Compatible: Works with any MCP-compatible AI agent or client (Claude Desktop, Claude Code, etc.)

Technical Highlights

• Embedding Model: all-MiniLM-L6-v2 from sentence-transformers (384-dimensional embeddings)
• Index Type: FAISS IndexFlatL2 for exact L2 distance search
• Chunking Strategy: Documents split into ~500 word chunks with 50-word overlap
• Configurable Storage: Custom index directory support via --index-dir argument

📦 Installation

pip install local-faiss-mcp

🚀 Usage

Running the Server

Method 1: Command-line (recommended)
local-faiss-mcp --index-dir ./.vector_store

Method 2: Python module
python -m local_faiss_mcp --index-dir ./.vector_store

Method 3: Direct execution
python local_faiss_mcp/server.py --index-dir ./.vector_store

MCP Configuration

Add to your .mcp.json:
{
"mcpServers": {
"local-faiss-mcp": {
"command": "local-faiss-mcp",
"args": ["--index-dir", "./.vector_store"]
}
}
}

🛠️ Available MCP Tools

1. ingest_document

Ingest a document into the FAISS vector store.

Parameters:

• document (required): The text content to ingest
• source (optional): Identifier for the document source

Example:
{
"document": "FAISS is a library for efficient similarity search...",
"source": "faiss_docs.txt"
}

1. query_rag_store

Query the vector store for relevant document chunks.

Parameters:

• query (required): The search query text
• top_k (optional): Number of results to return (default: 3)

Example:
{
"query": "How does FAISS perform similarity search?",
"top_k": 5
}

📋 Requirements

• Python 3.10 or higher
• FAISS (CPU version)
• Sentence Transformers
• MCP SDK (≥0.9.0)

🏗️ Architecture

Package Structure

local_faiss_mcp/
├── init.py # Package initialization
├── main.py # Entry point for module execution
└── server.py # MCP server and FAISSVectorStore implementation

Data Storage

• Index File: faiss.index - FAISS vector index
• Metadata File: metadata.json - Document metadata and text chunks

🧪 Tested Platforms

• ✅ Ubuntu (latest)
• ✅ macOS (latest)
• ✅ Windows (latest)
• ✅ Python 3.10, 3.11, 3.12

📚 Documentation

• README.md: Quick start guide and usage instructions
• PUBLISHING.md: Guide for PyPI publishing (for contributors)
• Examples: See .mcp.json.example for configuration templates

🤝 Contributing

Contributions are welcome! Please see the GitHub repository for:

• Issue tracker: https://github.com/nonatofabio/local_faiss_mcp/issues
• Source code: https://github.com/nonatofabio/local_faiss_mcp

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• FAISS: Facebook AI Similarity Search library
• Sentence Transformers: For the embedding model
• MCP SDK: Anthropic's Model Context Protocol

🔗 Links

• PyPI: https://pypi.org/project/local-faiss-mcp/
• GitHub: https://github.com/nonatofabio/local_faiss_mcp
• Documentation: See README.md

Full Changelog: https://github.com/nonatofabio/local_faiss_mcp/commits/v0.1.0