# andrea9293/mcp-documentation-server architecture

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

- Interactive diagram: https://gitdiagram.com/andrea9293/mcp-documentation-server
- Repository: https://github.com/andrea9293/mcp-documentation-server

## Overview

##### Project type and purpose
- This is an open-source, TypeScript-based MCP “documentation server” tool.
- It exposes a set of Model Context Protocol (MCP) tools over a local server/CLI, handling document ingestion, on-disk persistence, in-memory indexing, embedding-based semantic search, and optional AI-powered search via Google Gemini.

##### File structure
Top-level:
- package.json, tsconfig.json, build/test/script configs
- README, CHANGELOG, LICENSE, docs/ (policies and contribution guides)
src/ directory: core modules and entry point
- server.ts – MCP server bootstrap & tool registration
- document-manager.ts – create/read/delete document metadata & JSON persistence
- embedding-provider.ts & embeddings/embedding-cache.ts – compute & cache embeddings (LRU cache)
- gemini-file-mapping-service.ts & gemini-search-service.ts – integration with Google Gemini AI, file mapping cache
- indexing/document-index.ts – in-memory O(1) keyword index
- intelligent-chunker.ts – split documents into chunks (with parallelization in indexing/ folder)
- search-engine.ts – combine embedding similarity, index lookup, and AI calls for search
- utils.ts, types.ts – shared helpers and Zod schemas

##### Key insights from the README
- Data lives under `~/.mcp-documentation-server/` in two subfolders: data/ (JSON docs & chunks) and uploads/ (raw files).
- Tools exposed (add_document, process_uploads, search_documents, search_documents_with_ai, get_context_window, etc.)
- Configurable features via env vars: indexing toggle, cache size, parallelism, streaming, external AI key & model.
- Emphasis on performance (LRU cache, streaming readers, parallel chunking) and extensibility (MCP protocol).

- MCP Client / CLI / External Caller
- MCP Server (server.ts)
– Tool Router & Zod Validation
– DocumentManager (persistence)
– FileProcessing Pipeline (ProcessUploads)
– IndexingService (DocumentIndex)
– Chunker (IntelligentChunker + parallel workers)
– EmbeddingProvider + EmbeddingCache
– SearchEngine
– GeminiFileMappingService & GeminiSearchService (optional AI path)
- Local Storage
– Data dir (JSON docs & chunk files)
– Uploads dir (raw files)
– Embedding cache (LRU in memory)
- External Service
– Google Gemini AI

b. Relationships & data flow
1. Client issues MCP command → Server.ts dispatch
2. For add/process_uploads:
- DocumentManager writes metadata to data/
- IntelligentChunker splits full text → chunks
- EmbeddingProvider computes embeddings → stored in chunks + LRU cache
- DocumentIndex updates in-memory index
- Raw files copied to uploads/ with backup preservation
3. For search:
- Client→ search_documents → DocumentIndex retrieves candidate chunks → EmbeddingProvider similarity ranking → SearchEngine returns hits (+ hint)
- Client→ search_documents_with_ai → above + GeminiFileMappingService checks cache → GeminiSearchService calls Google Gemini → enriched results
4. For get_context_window: SearchEngine + DocumentManager fetch neighboring chunks

c. Architectural patterns & design principles
- Modular separation: each concern in its own service/module
- In-memory + on-disk hybrid (cache + persistence)
- Pipeline & parallel processing for ingestion
- LRU caching to avoid repeated embedding calls
- Clean protocol layer (MCP) decoupled from implementation

d. Key technologies & frameworks
- TypeScript + Node.js
- Zod for schema validation
- Xenova embedding models (configurable)
- Google Gemini AI (optional external service)
- FastMCP under the hood

##### Final advice
- MCP tool interface is upfront, since that’s the primary integration point.
- Clarity: the goal is to show how documents flow from raw files → chunks → embeddings → index → search results (with optional AI enrichment).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% MCP Client Layer
    Client["MCP Client / CLI / External Caller"]:::client
    Client -->|issues MCP command| Server

    %% MCP Server Layer
    subgraph "MCP Server"
        direction TB
        Server["MCP Server"]:::internal
        DocumentManager["DocumentManager"]:::internal
        IntelligentChunker["IntelligentChunker"]:::internal
        EmbeddingProvider["EmbeddingProvider"]:::internal
        EmbeddingCache["EmbeddingCache"]:::internal
        DocumentIndex["DocumentIndex"]:::internal
        SearchEngine["SearchEngine"]:::internal
        GeminiFileMappingService["GeminiFileMappingService"]:::internal
        GeminiSearchService["GeminiSearchService"]:::internal
        Utils["Utils"]:::internal
        Types["Types & Schemas"]:::internal
    end

    Server --> DocumentManager
    Server --> IntelligentChunker
    Server --> EmbeddingProvider
    Server --> DocumentIndex
    Server --> SearchEngine
    Server --> GeminiFileMappingService
    Server --> GeminiSearchService
    Server --> Utils
    Server --> Types

    %% Processing Pipeline
    DocumentManager -->|writes metadata| DataDir
    DocumentManager -->|copies raw files| Uploads
    IntelligentChunker -->|chunks docs| DocumentIndex
    IntelligentChunker --> EmbeddingProvider
    EmbeddingProvider --> EmbeddingCache
    EmbeddingCache --> DocumentIndex
    DocumentIndex --> SearchEngine

    %% Search Flows
    SearchEngine -->|returns results| Client

    %% AI-Enhanced Search
    SearchEngine -->|checks cache| GeminiFileMappingService
    GeminiFileMappingService --> GeminiSearchService
    GeminiSearchService -->|calls| GeminiAI
    GeminiAI -->|responses| GeminiSearchService
    GeminiSearchService -->|enriched results| SearchEngine

    %% Storage Layer
    DataDir["Data Dir\n(JSON docs & chunks)"]:::storage
    Uploads["Uploads Dir\n(raw files)"]:::storage

    %% External Service
    GeminiAI["Google Gemini AI"]:::external

    %% Click Events
    click Server "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/server.ts"
    click DocumentManager "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/document-manager.ts"
    click EmbeddingProvider "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/embedding-provider.ts"
    click EmbeddingCache "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/embeddings/embedding-cache.ts"
    click GeminiFileMappingService "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/gemini-file-mapping-service.ts"
    click GeminiSearchService "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/gemini-search-service.ts"
    click DocumentIndex "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/indexing/document-index.ts"
    click IntelligentChunker "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/intelligent-chunker.ts"
    click SearchEngine "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/search-engine.ts"
    click Utils "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/utils.ts"
    click Types "https://github.com/andrea9293/mcp-documentation-server/blob/main/src/types.ts"

    %% Styles
    classDef client fill:#e0d7f9,stroke:#8a2be2,color:#000
    classDef internal fill:#d0e7ff,stroke:#1f78b4,color:#000
    classDef storage fill:#d4f8d4,stroke:#2ca02c,color:#000
    classDef external fill:#ffe4b3,stroke:#ff7f0e,color:#000
```
