How adiom-data/lance-mcp works
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.