# githamza0206/better-finder-mcp architecture

> Architecture diagram of the GitHub repository githamza0206/better-finder-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/githamza0206/better-finder-mcp
- Repository: https://github.com/githamza0206/better-finder-mcp

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        CLI_main["main.py"]:::UI
        CLI_ef_main["enhanced_finder/main.py"]:::UI
        CLI_cli["enhanced_finder/cli.py"]:::UI
        CloudClient["Claude Desktop"]:::external
    end

    %% Core Logic
    subgraph "Core Logic"
        Stage["Staging System"]:::core
        FileProc["File Processor Module"]:::core
        Indexer["Indexer Engine"]:::core
        subgraph "Search/Agent Layer"
            A1["enhanced_finder/agents.py"]:::core
            A2["enhanced_finder/simple_agents.py"]:::core
        end
        MCP["MCP Server"]:::core
    end

    %% Data Storage
    subgraph "Data Storage"
        Faiss((FAISS Vector Store)):::storage
        SQLite((SQLite DB)):::storage
    end

    %% Configuration
    subgraph "Configuration"
        Config_py["enhanced_finder/config.py"]:::config
        BFIgnore[".betterfinderignore"]:::config
    end

    %% Build & Metadata
    subgraph "Build & Metadata"
        PyProject["pyproject.toml"]:::config
        Readme["README.md"]:::config
    end

    %% External Services
    subgraph "External Services"
        Embed["sentence-transformers Models"]:::external
    end

    %% Relationships
    CLI_cli -->|"add/rm/status"| Stage
    CLI_cli -->|"index"| Indexer
    CLI_cli -->|"search"| A1
    CLI_cli -->|"server"| MCP

    Indexer -->|"extract & chunk"| FileProc
    FileProc -->|"store vectors"| Faiss
    FileProc -->|"store metadata"| SQLite

    A1 -->|"semantic query"| Faiss
    A1 -->|"metadata lookup"| SQLite
    A2 -.->|"alternative plugin"| Faiss
    A2 -.->|"alternative plugin"| SQLite

    MCP -->|"search flow"| A1
    CloudClient ---|"MCP protocol"| MCP

    %% Config dependencies
    Config_py -.-> Stage
    Config_py -.-> FileProc
    Config_py -.-> Indexer
    Config_py -.-> A1
    Config_py -.-> MCP
    BFIgnore -.-> FileProc

    %% External service usage
    FileProc -->|"embed chunks"| Embed
    A1 -->|"LLM calls"| Embed

    %% Click Events
    click CLI_main "https://github.com/githamza0206/better-finder-mcp/blob/main/main.py"
    click CLI_ef_main "https://github.com/githamza0206/better-finder-mcp/blob/main/enhanced_finder/main.py"
    click CLI_cli "https://github.com/githamza0206/better-finder-mcp/blob/main/enhanced_finder/cli.py"
    click Stage "https://github.com/githamza0206/better-finder-mcp/blob/main/enhanced_finder/staging.py"
    click FileProc "https://github.com/githamza0206/better-finder-mcp/blob/main/enhanced_finder/file_processors.py"
    click Indexer "https://github.com/githamza0206/better-finder-mcp/blob/main/enhanced_finder/indexer.py"
    click A1 "https://github.com/githamza0206/better-finder-mcp/blob/main/enhanced_finder/agents.py"
    click A2 "https://github.com/githamza0206/better-finder-mcp/blob/main/enhanced_finder/simple_agents.py"
    click MCP "https://github.com/githamza0206/better-finder-mcp/blob/main/enhanced_finder/mcp_server.py"
    click Config_py "https://github.com/githamza0206/better-finder-mcp/blob/main/enhanced_finder/config.py"
    click BFIgnore "https://github.com/githamza0206/better-finder-mcp/blob/main/.betterfinderignore"
    click PyProject "https://github.com/githamza0206/better-finder-mcp/blob/main/pyproject.toml"
    click Readme "https://github.com/githamza0206/better-finder-mcp/blob/main/README.md"

    %% Styles
    classDef UI fill:#CCE5FF,stroke:#000,stroke-width:1px
    classDef core fill:#CCFFCC,stroke:#000,stroke-width:1px
    classDef storage fill:#FFDD88,stroke:#000,stroke-width:1px
    classDef external fill:#E6CCFF,stroke:#000,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px
```
