How githamza0206/better-finder-mcp works
Project type and purpose
• Better Finder MCP is an open-source command-line tool with an optional local server component (MCP) for integration with Claude Desktop.
• Its purpose is to provide Git-style staging and semantic/hybrid search over local files, backed by a FAISS vector store and SQLite metadata, with an MCP endpoint for Claude.
File structure
• Top-level CLI entry points:
• main.py, enhanced_finder/main.py – launchers
• enhanced_finder/cli.py – command definitions (add, status, search, server, etc.)
• Core modules under enhanced_finder/:
• staging.py – “git-like” JSON staging system
• file_processors.py – extract and chunk file content
• indexer.py – orchestrates chunking and populating FAISS & SQLite
• config.py – default paths, ignore patterns, thresholds
• mcp_server.py – HTTP or socket MCP endpoint for Claude
• agents.py & simple_agents.py – search orchestration and optional LLM calls
• Config/build: pyproject.toml, .betterfinderignore, .gitignore
• Tests not present but extensibility implied by file_processors and agents.
README for additional insights
• Architecture summary: File Processors, FAISS Vector Store, SQLite Metadata, Staging System, MCP Server.
• Key workflows: CLI staging → index → search, or run better-finder server for MCP.
• User Interfaces:
• CLI interface (commands: add, index, search, server)
• External Client: Claude Desktop connecting via MCP
• Core subsystems:
• Staging System (JSON store)
• File Processors (extractors & chunker)
• Indexer Engine
• Search/Agent Layer
• Data stores:
• FAISS Vector Store (Semantic index)
• SQLite DB (metadata & chunk store)
• Configuration Layer (config.py, .betterfinderignore)
• External Services:
• Sentence-transformers models
• Claude Desktop via Model Context Protocol (MCP)
b. Relationships & interactions:
• CLI → Staging: “add/rm/status” read/write JSON
• CLI → Indexer: triggers file_processors → feeds FAISS + SQLite
• CLI → Search: query flows to agent/search module → vector store lookup → metadata lookup → CLI output
• CLI “server” → MCP Server → listens on localhost → on request executes same search flow → responds to Claude
• Config is read by all modules at startup
c. Architectural patterns & principles:
• Modular layering: separate CLI, staging, processing, indexing, search, server
• Data-flow pipeline: staging → processing → indexing → search
• Adapter pattern: file_processors handle multiple file types
• Strategy/plugin: simple_agents vs agents for different search behaviors
d. Key technologies & libraries:
• Python 3 with uv (CLI tool installer)
• FAISS for vector similarity search
• SQLite for metadata store
• sentence-transformers for embeddings
• JSON for staging persistence
• Native TCP/HTTP or socket for MCP
Be detailed but not over-complex
• Break the pipeline into each module as above.
• Essential elements: staging, processing, indexing, search, persistence, MCP integration.