MCP RAG Server

MCP RAG Server

A Model Context Protocol (MCP) server for Retrieval-Augmented Generation with document parsing and vector database storage using ChromaDB.

Features

• Document Processing: Supports PDF, Markdown, and text files with enhanced parsing
• Vector Search: Uses ChromaDB v2 API for semantic similarity search
• File Watching: Automatically processes new and changed files
• MCP Integration: Full MCP protocol support with resources and tools
• Large Document Support: Intelligent chunking for documents of any size
• Robust Error Handling: Comprehensive error recovery and retry mechanisms
• Silent Operation: No console output for clean MCP server behavior
• Enhanced PDF Processing: Node.js-optimized PDF.js with memory management

Recent Improvements

Version 1.x Features

• ✅ ChromaDB v2 Compatibility: Updated to use ChromaDB 2.4.6 API
• ✅ PDF.js Node.js Fix: Resolved DOMMatrix errors using legacy build
• ✅ Large Document Handling: Automatic chunking for files >4KB with reconstruction
• ✅ Enhanced Error Recovery: Retry logic with exponential backoff
• ✅ Silent MCP Operation: Removed all console logging for proper MCP server behavior
• ✅ Memory Optimization: Batch processing and garbage collection for large PDFs
• ✅ Content Sanitization: Robust handling of special characters and encoding issues

Prerequisites

• Node.js 18+
• ChromaDB server running and accessible (v0.4.0+)
• Network access to your ChromaDB instance

Installation

1. Clone and install dependencies:

2. Build the project:

Configuration

Environment Variables

Create a .env file in the project root:

Command Line Options

You can also configure via command line:

Set the Chroma server URL via the CHROMA_URL environment variable. For example, in your MCP config:

If not set, the default is http://localhost:8000.

ChromaDB Setup

This server requires ChromaDB v2 API. Install and run ChromaDB:

For Docker:

Testing ChromaDB Connection

Run the included test suite to verify your setup:

This will verify:

• Network connectivity to ChromaDB v2 API
• Document insertion and retrieval
• Large document chunking and reconstruction
• Search functionality

Running Tests

Run the comprehensive test suite:

Note: You may see a deprecation warning about the punycode module during tests. This is from a dependency and does not affect functionality.

Usage

As MCP Server

The server runs in stdio mode for MCP protocol communication:

The server operates silently without console output, suitable for MCP integration.

MCP Resources

• rag://documents - List all documents
• rag://document/{id} - Get specific document

MCP Tools

• search - Query documents with semantic similarity
• add_document - Manually add document content
• remove_document - Delete a document by ID
• status - Get server statistics

Document Support

Large Document Handling

The server automatically handles large documents:

• Files >4KB: Split into 4KB chunks with smart sentence boundaries
• Content Reconstruction: Seamlessly rebuilds full documents when requested
• Memory Efficiency: Batch processing prevents memory overflow
• Progress Tracking: Metadata tracks chunk relationships for proper reconstruction

Troubleshooting

Connection Issues

Error: ECONNREFUSED or fetch failed

1. Verify ChromaDB v2 is running:
   curl http://localhost:8000/api/v1/heartbeat
2. Check for v1/v2 API compatibility:
   # Should return 200 OK for v2 curl http://localhost:8000/api/v1/version
3. Verify ChromaDB server configuration allows external connections

Error: 410 Gone responses

This indicates a v1/v2 API mismatch. Ensure you're running ChromaDB v0.4.0+ and the client is using v2.4.6+.

Error: chromadb-default-embed not found

The chromadb-default-embed package should be automatically installed. If you see this error:

Document Processing Issues

PDF.js DOMMatrix errors:

✅ Fixed in v1.x - Now uses Node.js-compatible legacy build.

Large PDF processing:

• ✅ Enhanced in v1.x - Automatic batch processing with 100MB file size limits
• Memory management with garbage collection between batches
• 30-second timeout protection per PDF

Files not being processed:

1. Check the watch directory exists and is readable
2. Verify file extensions are supported
3. Check file permissions
4. Run tests to verify parsing functionality

Memory Issues

For large document collections:

1. The server now includes automatic memory management
2. Large documents are automatically chunked
3. If still needed, increase Node.js memory limit:
   node --max-old-space-size=4096 build/index.js

Silent Operation

The server now runs silently by design for proper MCP integration. If you need debugging:

1. Run tests with verbose output: npm run test:verbose
2. Use the debug test files in src/tests/
3. Check error responses from MCP tools

Known Issues

• Punycode Deprecation Warning: You may see deprecation warnings about the punycode module from Node.js dependencies. This does not affect functionality and will be resolved when dependencies are updated.

Development

Project Structure

Building

Adding New Document Types

1. Add parser logic to src/parsers/document-parser.ts
2. Update file extension handling
3. Add tests in src/tests/
4. Consider chunking strategy for large files

Performance Optimization

ChromaDB Settings

For optimal performance, configure your ChromaDB server with:

• ChromaDB v0.4.0+ for v2 API compatibility
• Sufficient memory allocation (4GB+ recommended)
• SSD storage for better I/O
• Network optimization for remote connections

Document Chunking

The server now uses intelligent chunking:

• Automatic chunking: Files >4KB split at sentence boundaries
• Content reconstruction: Full documents rebuilt on retrieval
• Metadata tracking: Chunk relationships preserved
• Memory efficiency: Batch processing prevents overflow

Adjust chunk settings based on your use case:

• Small chunks (500-800 chars): Better precision, more storage
• Large chunks (1200-2000 chars): Better context, less storage
• Overlap: 10-20% of chunk size for continuity

Security Considerations

• ChromaDB server should be behind a firewall
• Use authentication if ChromaDB supports it
• Validate document sources before processing
• Monitor resource usage to prevent DoS
• Content sanitization prevents injection attacks

API Reference

MCP Tools

search

Query documents using semantic similarity.

Parameters:

• query (string): Search query
• limit (number, optional): Max results (default: 5)

Returns: Array of matching document chunks with scores

Enhanced Features:

• ✅ Searches across chunked content
• ✅ Includes parent document information
• ✅ Cosine similarity scoring

add_document

Add document content manually.

Parameters:

• content (string): Document text content
• filename (string): Document filename
• metadata (object, optional): Additional metadata

Returns: Success message with chunk count

Enhanced Features:

• ✅ Automatic chunking for large content
• ✅ Content sanitization
• ✅ Retry logic with exponential backoff

remove_document

Delete a document by ID.

Parameters:

• id (string): Document ID

Returns: Success confirmation

Enhanced Features:

• ✅ Removes all associated chunks
• ✅ Graceful error handling

status

Get server statistics and configuration.

Returns: Object with document count, chunk count, total size, and configuration

Enhanced Features:

• ✅ Real-time statistics
• ✅ Memory usage information
• ✅ ChromaDB connection status

Migration Guide

Future Versions

When upgrading to future versions:

1. Update Dependencies: Run npm update to get latest compatible versions
2. Update Environment Variables: Check for any new configuration options
3. Rebuild Project: Run npm run clean && npm run build
4. Test Connection: Run npm test to verify compatibility

Breaking Changes in v1.x

• Environment variable CHROMA_HOST renamed to CHROMA_URL
• ChromaDB v1 API no longer supported
• Console logging removed (use tests for debugging)

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (npm test)
5. Verify no console output in main code
6. Submit a pull request