MCP Documentation Server

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.

🚀 AI-Powered Document Intelligence

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

Key AI Features:

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

Core capabilities

🔍 Search & Intelligence

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

⚡ Performance & Optimization

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

📁 File Management

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/

Quick Start

Configure an MCP client

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

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": [
        "-y",
        "@andrea9293/mcp-documentation-server"
      ],
      "env": {
            "GEMINI_API_KEY": "your-api-key-here",  // Optional, enables AI-powered search
            "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
      }
    }
  }
}

Basic workflow

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.

Exposed MCP tools

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

📄 Document Management

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

📁 File Processing

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 & Intelligence

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

Configuration & environment variables

Configure behavior via environment variables. Important options:

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_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/
├── data/      # Document JSON files
└── uploads/   # Drop files (.txt, .md, .pdf) to import

Usage examples

Basic Document Operations

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
  }
}

🤖 AI-Powered Search Examples

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"
  }
}

Context Enhancement

Fetch context window:

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

When to Use AI-Powered Search:

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"

Performance Benefits:

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.

Embedding Models

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.

Development

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

cd mcp-documentation-server

npm run dev

npm run build

npm run inspect

Contributing

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

License

MIT - see LICENSE file

Support

Star History

Built with FastMCP and TypeScript 🚀