A TypeScript-based Model Context Protocol (MCP) server that provides local-first document management and semantic search using embeddings. The server exposes a collection of MCP tools and is optimized for performance with on-disk persistence, an in-memory index, and caching.

NEW! Enhanced with Google Gemini AI for advanced document analysis and contextual understanding. Ask complex questions and get intelligent summaries, explanations, and insights from your documents. To get API Key go to Google AI Studio

• Intelligent Document Analysis: Gemini AI understands context, relationships, and concepts
• Natural Language Queries: Ask a question, not just keywords
• Smart Summarization: Get comprehensive overviews and explanations
• Contextual Insights: Understand how different parts of your documents relate
• File Mapping Cache: Avoid re-uploading the same files to Gemini for efficiency

• AI-Powered Search 🤖: Advanced document analysis with Gemini AI for contextual understanding and intelligent insights
• Traditional Semantic Search: Chunk-based search using embeddings plus in-memory keyword index
• Context Window Retrieval: Gather surrounding chunks for richer LLM answers

• O(1) Document lookup and keyword index through DocumentIndex for instant retrieval
• LRU EmbeddingCache to avoid recomputing embeddings and speed up repeated queries
• Parallel chunking and batch processing to accelerate ingestion of large documents
• Streaming file reader to process large files without high memory usage

• Intelligent file handling: copy-based storage with automatic backup preservation
• Complete deletion: removes both JSON files and associated original files
• Local-only storage: no external database required. All data resides in ~/.mcp-documentation-server/

Example configuration for an MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": [
        "-y",
        "@andrea9293/mcp-documentation-server"
      ],
      "env": {
            "MCP_BASE_DIR": "/path/to/workspace",  // Optional, custom data directory (default: ~/.mcp-documentation-server)
            "GEMINI_API_KEY": "your-api-key-here",  // Optional, enables AI-powered search
            "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
      }
    }
  }
}

• Add documents using the add_document tool or by placing .txt, .md, or .pdf files into the uploads folder and calling process_uploads.
• Search documents with search_documents to get ranked chunk hits.
• Use get_context_window to fetch neighboring chunks and provide LLMs with richer context.

The server exposes several tools (validated with Zod schemas) for document lifecycle and search:

• add_document — Add a document (title, content, metadata)
• list_documents — List stored documents and metadata
• get_document — Retrieve a full document by id
• delete_document — Remove a document, its chunks, and associated original files

• process_uploads — Convert files in uploads folder into documents (chunking + embeddings + backup preservation)
• get_uploads_path — Returns the absolute uploads folder path
• list_uploads_files — Lists files in uploads folder

• search_documents_with_ai — 🤖 AI-powered search using Gemini for advanced document analysis (requires GEMINI_API_KEY)
• search_documents — Semantic search within a document (returns chunk hits and LLM hint)
• get_context_window — Return a window of chunks around a target chunk index

Configure behavior via environment variables. Important options:

• MCP_BASE_DIR — base directory for data storage (default: ~/.mcp-documentation-server). Set this to use independent workspaces.
• MCP_EMBEDDING_MODEL — embedding model name (default: Xenova/all-MiniLM-L6-v2). Changing the model requires re-adding documents.
• GEMINI_API_KEY — Google Gemini API key for AI-powered search features (optional, enables search_documents_with_ai).
• MCP_INDEXING_ENABLED — enable/disable the DocumentIndex (true/false). Default: true.
• MCP_CACHE_SIZE — LRU embedding cache size (integer). Default: 1000.
• MCP_PARALLEL_ENABLED — enable parallel chunking (true/false). Default: true.
• MCP_MAX_WORKERS — number of parallel workers for chunking/indexing. Default: 4.
• MCP_STREAMING_ENABLED — enable streaming reads for large files. Default: true.
• MCP_STREAM_CHUNK_SIZE — streaming buffer size in bytes. Default: 65536 (64KB).
• MCP_STREAM_FILE_SIZE_LIMIT — threshold (bytes) to switch to streaming path. Default: 10485760 (10MB).

Example .env (defaults applied when variables are not set):

MCP_BASE_DIR=/path/to/workspace   # Base directory for data storage (default: ~/.mcp-documentation-server)
MCP_INDEXING_ENABLED=true          # Enable O(1) indexing (default: true)
GEMINI_API_KEY=your-api-key-here   # Google Gemini API key (optional)
MCP_CACHE_SIZE=1000                # LRU cache size (default: 1000)
MCP_PARALLEL_ENABLED=true          # Enable parallel processing (default: true)
MCP_MAX_WORKERS=4                  # Parallel worker count (default: 4)
MCP_STREAMING_ENABLED=true         # Enable streaming (default: true)
MCP_STREAM_CHUNK_SIZE=65536        # Stream chunk size (default: 64KB)
MCP_STREAM_FILE_SIZE_LIMIT=10485760 # Streaming threshold (default: 10MB)

Default storage layout (data directory):

~/.mcp-documentation-server/  # Or custom path via MCP_BASE_DIR
├── data/      # Document JSON files
└── uploads/   # Drop files (.txt, .md, .pdf) to import

Add a document via MCP tool:

{
  "tool": "add_document",
  "arguments": {
    "title": "Python Basics",
    "content": "Python is a high-level programming language...",
    "metadata": {
      "category": "programming",
      "tags": ["python", "tutorial"]
    }
  }
}

Search a document:

{
  "tool": "search_documents",
  "arguments": {
    "document_id": "doc-123",
    "query": "variable assignment",
    "limit": 5
  }
}

Advanced Analysis (requires GEMINI_API_KEY):

{
  "tool": "search_documents_with_ai",
  "arguments": {
    "document_id": "doc-123",
    "query": "explain the main concepts and their relationships"
  }
}

Complex Questions:

{
  "tool": "search_documents_with_ai",
  "arguments": {
    "document_id": "doc-123",
    "query": "what are the key architectural patterns and how do they work together?"
  }
}

Summarization Requests:

{
  "tool": "search_documents_with_ai",
  "arguments": {
    "document_id": "doc-123",
    "query": "summarize the core principles and provide examples"
  }
}

Fetch context window:

{
  "tool": "get_context_window",
  "arguments": {
    "document_id": "doc-123",
    "chunk_index": 5,
    "before": 2,
    "after": 2
  }
}

• Complex Questions: "How do these concepts relate to each other?"
• Summarization: "Give me an overview of the main principles"
• Analysis: "What are the key patterns and their trade-offs?"
• Explanation: "Explain this topic as if I were new to it"
• Comparison: "Compare these different approaches"

• Smart Caching: File mapping prevents re-uploading the same content

• Efficient Processing: Only relevant sections are analyzed by Gemini

• Contextual Results: More accurate and comprehensive answers

• Natural Interaction: Ask questions in plain English

• Embedding models are downloaded on first use; some models require several hundred MB of downloads.

• The DocumentIndex persists an index file and can be rebuilt if necessary.

• The EmbeddingCache can be warmed by calling process_uploads, issuing curated queries, or using a preload API when available.

Set via MCP_EMBEDDING_MODEL environment variable:

• Xenova/all-MiniLM-L6-v2 (default) - Fast, good quality (384 dimensions)
• Xenova/paraphrase-multilingual-mpnet-base-v2 (recommended) - Best quality, multilingual (768 dimensions)

The system automatically manages the correct embedding dimension for each model. Embedding providers expose their dimension via getDimensions().

⚠️ Important: Changing models requires re-adding all documents as embeddings are incompatible.

git clone https://github.com/andrea9293/mcp-documentation-server.git

cd mcp-documentation-server

npm run dev

npm run build

npm run inspect

1. Fork the repository
2. Create a feature branch: git checkout -b feature/name
3. Follow Conventional Commits for messages
4. Open a pull request

MIT - see LICENSE file

• 📖 Documentation
• 🐛 Report Issues
• 💬 MCP Community

Built with FastMCP and TypeScript 🚀