{
  "markdown": "# Local FAISS MCP Server\n\n<!-- mcp-name: io.github.nonatofabio/local-faiss-mcp -->\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Tests](https://github.com/nonatofabio/local_faiss_mcp/workflows/Tests/badge.svg)](https://github.com/nonatofabio/local_faiss_mcp/actions)\n[![PyPI version](https://badge.fury.io/py/local-faiss-mcp.svg)](https://badge.fury.io/py/local-faiss-mcp)\n\nA Model Context Protocol (MCP) server that provides local vector database functionality using FAISS for Retrieval-Augmented Generation (RAG) applications.\n\n![demo](./static/demo.gif)\n\n## Features\n\n### Core Capabilities\n- **Local Vector Storage**: Uses FAISS for efficient similarity search without external dependencies\n- **Document Ingestion**: Automatically chunks and embeds documents for storage\n- **Semantic Search**: Query documents using natural language with sentence embeddings\n- **Persistent Storage**: Indexes and metadata are saved to disk\n- **MCP Compatible**: Works with any MCP-compatible AI agent or client\n\n### v0.2.0 Highlights\n- **CLI Tool**: `local-faiss` command for standalone indexing and search\n- **Document Formats**: Native PDF/TXT/MD support, DOCX/HTML/EPUB with pandoc\n- **Re-ranking**: Two-stage retrieve and rerank for better results\n- **Custom Embeddings**: Choose any Hugging Face embedding model\n- **MCP Prompts**: Built-in prompts for answer extraction and summarization\n\n## Quickstart\n\n```bash\n# Install\npip install local-faiss-mcp\n\n# Index documents\nlocal-faiss index document.pdf\n\n# Search\nlocal-faiss search \"What is this document about?\"\n```\n\nOr use with Claude Code - configure MCP client (see [Configuration](#configuration-with-mcp-clients)) and try:\n\n```\nUse the ingest_document tool with: ./path/to/document.pdf\nThen use query_rag_store to search for: \"How does FAISS perform similarity search?\"\n```\n\nClaude will retrieve relevant document chunks from your vector store and use them to answer your question.\n\n## Installation\n\n⚡️ **Upgrading?** Run `pip install --upgrade local-faiss-mcp`\n\n### From PyPI (Recommended)\n\n```bash\npip install local-faiss-mcp\n```\n\n### Optional: Extended Format Support\n\nFor DOCX, HTML, EPUB, and 40+ additional formats, install pandoc:\n\n```bash\n# macOS\nbrew install pandoc\n\n# Linux\nsudo apt install pandoc\n\n# Or download from: https://pandoc.org/installing.html\n```\n\n**Note**: PDF, TXT, and MD work without pandoc.\n\n### From Source\n\n```bash\ngit clone https://github.com/nonatofabio/local_faiss_mcp.git\ncd local_faiss_mcp\npip install -e .\n```\n\n## Usage\n\n### Running the Server\n\nAfter installation, you can run the server in three ways:\n\n**1. Using the installed command (easiest):**\n```bash\nlocal-faiss-mcp --index-dir /path/to/index/directory\n```\n\n**2. As a Python module:**\n```bash\npython -m local_faiss_mcp --index-dir /path/to/index/directory\n```\n\n**3. For development/testing:**\n```bash\npython local_faiss_mcp/server.py --index-dir /path/to/index/directory\n```\n\n**Command-line Arguments:**\n- `--index-dir`: Directory to store FAISS index and metadata files (default: current directory)\n- `--embed`: Hugging Face embedding model name (default: `all-MiniLM-L6-v2`)\n- `--rerank`: Enable re-ranking with specified cross-encoder model (default: `BAAI/bge-reranker-base`)\n\n**Using a Custom Embedding Model:**\n```bash\n# Use a larger, more accurate model\nlocal-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2\n\n# Use a multilingual model\nlocal-faiss-mcp --index-dir ./.vector_store --embed paraphrase-multilingual-MiniLM-L12-v2\n\n# Use any Hugging Face sentence-transformers model\nlocal-faiss-mcp --index-dir ./.vector_store --embed sentence-transformers/model-name\n```\n\n**Using Re-ranking for Better Results:**\n\nRe-ranking uses a cross-encoder model to reorder FAISS results for improved relevance. This two-stage \"retrieve and rerank\" approach is common in production search systems.\n\n```bash\n# Enable re-ranking with default model (BAAI/bge-reranker-base)\nlocal-faiss-mcp --index-dir ./.vector_store --rerank\n\n# Use a specific re-ranking model\nlocal-faiss-mcp --index-dir ./.vector_store --rerank cross-encoder/ms-marco-MiniLM-L-6-v2\n\n# Combine custom embedding and re-ranking\nlocal-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2 --rerank BAAI/bge-reranker-base\n```\n\n**How Re-ranking Works:**\n1. FAISS retrieves top candidates (10x more than requested)\n2. Cross-encoder scores each candidate against the query\n3. Results are re-sorted by relevance score\n4. Top-k most relevant results are returned\n\nPopular re-ranking models:\n- `BAAI/bge-reranker-base` - Good balance (default)\n- `cross-encoder/ms-marco-MiniLM-L-6-v2` - Fast and efficient\n- `cross-encoder/ms-marco-TinyBERT-L-2-v2` - Very fast, smaller model\n\nThe server will:\n- Create the index directory if it doesn't exist\n- Load existing FAISS index from `{index-dir}/faiss.index` (or create a new one)\n- Load document metadata from `{index-dir}/metadata.json` (or create new)\n- Listen for MCP tool calls via stdin/stdout\n\n### Available Tools\n\nThe server provides two tools for document management:\n\n#### 1. ingest_document\n\nIngest a document into the vector store.\n\n**Parameters:**\n- `document` (required): Text content OR file path to ingest\n- `source` (optional): Identifier for the document source (default: \"unknown\")\n\n**Auto-detection**: If `document` looks like a file path, it will be automatically parsed.\n\n**Supported formats:**\n- Native: TXT, MD, PDF\n- With pandoc: DOCX, ODT, HTML, RTF, EPUB, and 40+ formats\n\n**Examples:**\n```json\n{\n  \"document\": \"FAISS is a library for efficient similarity search...\",\n  \"source\": \"faiss_docs.txt\"\n}\n```\n\n```json\n{\n  \"document\": \"./documents/research_paper.pdf\"\n}\n```\n\n#### 2. query_rag_store\n\nQuery the vector store for relevant document chunks.\n\n**Parameters:**\n- `query` (required): The search query text\n- `top_k` (optional): Number of results to return (default: 3)\n\n**Example:**\n```json\n{\n  \"query\": \"How does FAISS perform similarity search?\",\n  \"top_k\": 5\n}\n```\n\n### Available Prompts\n\nThe server provides MCP prompts to help extract answers and summarize information from retrieved documents:\n\n#### 1. extract-answer\n\nExtract the most relevant answer from retrieved document chunks with proper citations.\n\n**Arguments:**\n- `query` (required): The original user query or question\n- `chunks` (required): Retrieved document chunks as JSON array with fields: `text`, `source`, `distance`\n\n**Use Case:** After querying the RAG store, use this prompt to get a well-formatted answer that cites sources and explains relevance.\n\n**Example workflow in Claude:**\n1. Use `query_rag_store` tool to retrieve relevant chunks\n2. Use `extract-answer` prompt with the query and results\n3. Get a comprehensive answer with citations\n\n#### 2. summarize-documents\n\nCreate a focused summary from multiple document chunks.\n\n**Arguments:**\n- `topic` (required): The topic or theme to summarize\n- `chunks` (required): Document chunks to summarize as JSON array\n- `max_length` (optional): Maximum summary length in words (default: 200)\n\n**Use Case:** Synthesize information from multiple retrieved documents into a concise summary.\n\n**Example Usage:**\n\nIn Claude Code, after retrieving documents with `query_rag_store`, you can use the prompts like:\n\n```\nUse the extract-answer prompt with:\n- query: \"What is FAISS?\"\n- chunks: [the JSON results from query_rag_store]\n```\n\nThe prompts will guide the LLM to provide structured, citation-backed answers based on your vector store data.\n\n## Command-Line Interface\n\nThe `local-faiss` CLI provides standalone document indexing and search capabilities.\n\n### Index Command\n\nIndex documents from the command line:\n\n```bash\n# Index single file\nlocal-faiss index document.pdf\n\n# Index multiple files\nlocal-faiss index doc1.pdf doc2.txt doc3.md\n\n# Index all files in folder\nlocal-faiss index documents/\n\n# Index recursively\nlocal-faiss index -r documents/\n\n# Index with glob pattern\nlocal-faiss index \"docs/**/*.pdf\"\n```\n\n**Configuration**: The CLI automatically uses MCP configuration from:\n1. `./.mcp.json` (local/project-specific)\n2. `~/.claude/.mcp.json` (Claude Code config)\n3. `~/.mcp.json` (fallback)\n\nIf no config exists, creates `./.mcp.json` with default settings (`./.vector_store`).\n\n**Supported formats:**\n- **Native**: TXT, MD, PDF (always available)\n- **With pandoc**: DOCX, ODT, HTML, RTF, EPUB, etc.\n  - Install: `brew install pandoc` (macOS) or `apt install pandoc` (Linux)\n\n### Search Command\n\nSearch the indexed documents:\n\n```bash\n# Basic search\nlocal-faiss search \"What is FAISS?\"\n\n# Get more results\nlocal-faiss search -k 5 \"similarity search algorithms\"\n```\n\nResults show:\n- Source file path\n- FAISS distance score\n- Re-rank score (if enabled in MCP config)\n- Text preview (first 300 characters)\n\n### CLI Features\n\n- ✅ **Incremental indexing**: Adds to existing index, doesn't overwrite\n- ✅ **Progress output**: Shows indexing progress for each file\n- ✅ **Shared config**: Uses same settings as MCP server\n- ✅ **Auto-detection**: Supports glob patterns and recursive folders\n- ✅ **Format support**: Handles PDF, TXT, MD natively; DOCX+ with pandoc\n\n## Configuration with MCP Clients\n\n### Claude Code\n\nAdd this server to your Claude Code MCP configuration (`.mcp.json`):\n\n**User-wide configuration** (`~/.claude/.mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"local-faiss-mcp\": {\n      \"command\": \"local-faiss-mcp\"\n    }\n  }\n}\n```\n\n**With custom index directory**:\n```json\n{\n  \"mcpServers\": {\n    \"local-faiss-mcp\": {\n      \"command\": \"local-faiss-mcp\",\n      \"args\": [\n        \"--index-dir\",\n        \"/home/user/vector_indexes/my_project\"\n      ]\n    }\n  }\n}\n```\n\n**With custom embedding model**:\n```json\n{\n  \"mcpServers\": {\n    \"local-faiss-mcp\": {\n      \"command\": \"local-faiss-mcp\",\n      \"args\": [\n        \"--index-dir\",\n        \"./.vector_store\",\n        \"--embed\",\n        \"all-mpnet-base-v2\"\n      ]\n    }\n  }\n}\n```\n\n**With re-ranking enabled**:\n```json\n{\n  \"mcpServers\": {\n    \"local-faiss-mcp\": {\n      \"command\": \"local-faiss-mcp\",\n      \"args\": [\n        \"--index-dir\",\n        \"./.vector_store\",\n        \"--rerank\"\n      ]\n    }\n  }\n}\n```\n\n**Full configuration with embedding and re-ranking**:\n```json\n{\n  \"mcpServers\": {\n    \"local-faiss-mcp\": {\n      \"command\": \"local-faiss-mcp\",\n      \"args\": [\n        \"--index-dir\",\n        \"./.vector_store\",\n        \"--embed\",\n        \"all-mpnet-base-v2\",\n        \"--rerank\",\n        \"BAAI/bge-reranker-base\"\n      ]\n    }\n  }\n}\n```\n\n**Project-specific configuration** (`./.mcp.json` in your project):\n```json\n{\n  \"mcpServers\": {\n    \"local-faiss-mcp\": {\n      \"command\": \"local-faiss-mcp\",\n      \"args\": [\n        \"--index-dir\",\n        \"./.vector_store\"\n      ]\n    }\n  }\n}\n```\n\n**Alternative: Using Python module** (if the command isn't in PATH):\n```json\n{\n  \"mcpServers\": {\n    \"local-faiss-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"local_faiss_mcp\", \"--index-dir\", \"./.vector_store\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd this server to your Claude Desktop configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"local-faiss-mcp\": {\n      \"command\": \"local-faiss-mcp\",\n      \"args\": [\"--index-dir\", \"/path/to/index/directory\"]\n    }\n  }\n}\n```\n\n## Architecture\n\n- **Embedding Model**: Configurable via `--embed` flag (default: `all-MiniLM-L6-v2` with 384 dimensions)\n  - Supports any Hugging Face sentence-transformers model\n  - Automatically detects embedding dimensions\n  - Model choice persisted with the index\n- **Index Type**: FAISS IndexFlatL2 for exact L2 distance search\n- **Chunking**: Documents are split into ~500 word chunks with 50 word overlap\n- **Storage**: Index saved as `faiss.index`, metadata saved as `metadata.json`\n\n### Choosing an Embedding Model\n\nDifferent models offer different trade-offs:\n\n| Model | Dimensions | Speed | Quality | Use Case |\n|-------|-----------|-------|---------|----------|\n| `all-MiniLM-L6-v2` | 384 | Fast | Good | Default, balanced performance |\n| `all-mpnet-base-v2` | 768 | Medium | Better | Higher quality embeddings |\n| `paraphrase-multilingual-MiniLM-L12-v2` | 384 | Fast | Good | Multilingual support |\n| `all-MiniLM-L12-v2` | 384 | Medium | Better | Better quality at same size |\n\n**Important:** Once you create an index with a specific model, you must use the same model for subsequent runs. The server will detect dimension mismatches and warn you.\n\n## Development\n\n### Standalone Test\n\nTest the FAISS vector store functionality without MCP infrastructure:\n\n```bash\nsource venv/bin/activate\npython test_standalone.py\n```\n\nThis test:\n- Initializes the vector store\n- Ingests sample documents\n- Performs semantic search queries\n- Tests persistence and reload\n- Cleans up test files\n\n### Unit Tests\n\nRun the complete test suite:\n```bash\npytest tests/ -v\n```\n\nRun specific test files:\n```bash\n# Test embedding model functionality\npytest tests/test_embedding_models.py -v\n\n# Run standalone integration test\npython tests/test_standalone.py\n```\n\nThe test suite includes:\n- **test_embedding_models.py**: Comprehensive tests for custom embedding models, dimension detection, and compatibility\n- **test_standalone.py**: End-to-end integration test without MCP infrastructure\n\n## License\n\nMIT\n",
  "bytes": 13300,
  "sha": "22e1afc4795e66c78f3b7c307962761de5d932b58ccd1059ab039c78b52a1087",
  "repo_slug": "nonatofabio/local_faiss_mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nonatofabio_local_faiss_mcp_f4f37cb4/readme"
}