# adiom-data/lance-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/adiom-data/lance-mcp
- Repository: https://github.com/adiom-data/lance-mcp

## Overview

##### Main Components
- MCP Server Core – The entry point of the application is in src/index.ts. This is where the server is initialized using configurations from src/config.ts.
- Configuration Module – The config.ts file holds critical parameters like model choices for summarization and embeddings.
- LanceDB Integration – The src/lancedb directory (with client.ts) encapsulates interactions with LanceDB. This connects to the vector database that stores both the document “catalog” (summaries) and “chunks” (vectorized segments).
- Search and Tool Modules – Under src/tools, you have two subsets:
- Base tool framework (src/tools/base/tool.ts) that likely provides common functionalities.
- Operation-specific tools in src/tools/operations (like broad_chunks_search.ts, catalog_search.ts, chunks_search.ts) which implement various search modes.
- Additionally, a registry defined in src/tools/registry.ts helps manage or expose these tools.
- Data-Seeding Script – The seed script (src/seed.ts) is run separately as a one-time (or repeated) operation to populate LanceDB with tables and initial data. It creates separate logical spaces for the catalog and the document chunks.

##### Interactions and Data Flow
- External LLM Clients (such as Claude Desktop or other MCP Client applications) initiate requests. Their configuration references are provided in the README (using npx or node commands).
- The MCP Server (launched from index.ts) listens for incoming requests. It uses the settings from config.ts (which includes model endpoints and potentially other parameters).
- When a query arrives, the server routes the request to the appropriate tool module via the tools registry. For example, if it’s a "catalog_search" request, the process is handled by src/tools/operations/catalog_search.ts.
- These tools leverage functionalities defined in the base tool module for consistent behavior.
- The tools then interact with the LanceDB client (src/lancedb/client.ts) to perform either a search against the catalog table or vectorized chunks.
- The responses from LanceDB are then formatted and returned back to the LLM client.
- In addition, the seed script (seed.ts) is an independent process that initializes or updates the LanceDB index, clearly delineated from the runtime server operations.

##### Architectural Patterns
- Modular Separation: There’s a clear separation between configuration, main server logic, database interactions, and tool/operations modules.
- Extensibility: The tools registry and separate tool modules (strategically placed under operations) suggest an architecture that encourages extending search and query capabilities.
- Reusability: The common functionalities placed in base/tool.ts permit reuse across multiple operations.

##### Putting It All Together
b. Core Server Layer:
- “Tools Registry” (src/tools/registry.ts) as a mediator of tool calls.
c. Persistence/Database Layer:
d. Auxiliary Component:
- “Seed Data Script” (src/seed.ts) which is responsible for initializing/updating the LanceDB tables.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        A["MCP Clients (e.g., Claude Desktop)"]:::client
    end

    %% Core Server Layer
    subgraph "Core Server Layer"
        B["MCP Server (index.ts)"]:::server
        C["Configuration Module (config.ts)"]:::server
        B -->|"reads"| C
    end

    %% Tools Module
    subgraph "Tools Module"
        D["Tools Registry (registry.ts)"]:::tool
        E["Base Tool Framework (tool.ts)"]:::tool
        F["Catalog Search Tool (catalog_search.ts)"]:::tool
        G["Chunks Search Tool (chunks_search.ts)"]:::tool
        H["Broad Chunks Search Tool (broad_chunks_search.ts)"]:::tool
    end

    %% Persistence / LanceDB Layer
    subgraph "LanceDB"
        I["LanceDB Client (client.ts)"]:::database
        J["Catalog (Document Summary & Metadata)"]:::database
        K["Chunks (Vectorized chunks & Metadata)"]:::database
        I -->|"accesses"| J
        I -->|"accesses"| K
    end

    %% Data-Seeding Component
    L["Seed Data Script (seed.ts)"]:::seed

    %% Connections between layers
    A -->|"request"| B
    B -->|"delegates"| D
    D -->|"executes"| F
    D -->|"executes"| G
    D -->|"executes"| H
    F -->|"uses"| E
    G -->|"uses"| E
    H -->|"uses"| E
    F -->|"queries"| I
    G -->|"queries"| I
    H -->|"queries"| I
    L -->|"populates"| I

    %% Click Events
    click B "https://github.com/adiom-data/lance-mcp/blob/main/src/index.ts"
    click C "https://github.com/adiom-data/lance-mcp/blob/main/src/config.ts"
    click I "https://github.com/adiom-data/lance-mcp/blob/main/src/lancedb/client.ts"
    click E "https://github.com/adiom-data/lance-mcp/blob/main/src/tools/base/tool.ts"
    click F "https://github.com/adiom-data/lance-mcp/blob/main/src/tools/operations/catalog_search.ts"
    click G "https://github.com/adiom-data/lance-mcp/blob/main/src/tools/operations/chunks_search.ts"
    click H "https://github.com/adiom-data/lance-mcp/blob/main/src/tools/operations/broad_chunks_search.ts"
    click D "https://github.com/adiom-data/lance-mcp/blob/main/src/tools/registry.ts"
    click L "https://github.com/adiom-data/lance-mcp/blob/main/src/seed.ts"

    %% Styles
    classDef client fill:#ffcccc,stroke:#d62728,stroke-width:2px;
    classDef server fill:#ccffcc,stroke:#2ca02c,stroke-width:2px;
    classDef tool fill:#ffffcc,stroke:#ff7f0e,stroke-width:2px;
    classDef database fill:#cce5ff,stroke:#1f77b4,stroke-width:2px;
    classDef seed fill:#ffebcc,stroke:#9467bd,stroke-width:2px;
```
