How andrea9293/mcp-documentation-server works
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).