Content
# doc-ingestor-mcp
An MCP (Model Context Protocol) server that provides intelligent document ingestion capabilities using the Docling toolkit. Convert any document (PDF, DOCX, images, HTML, etc.) into clean Markdown for AI processing and RAG pipelines.
## Features
- **Universal File Support**: PDFs, DOCX/XLSX/PPTX, images (PNG/JPEG/TIFF/BMP/WEBP), HTML, Markdown, CSV, audio files, and more
- **Flexible Input**: Process local files or remote URLs
- **Multiple Processing Pipelines**: Standard (fast, high-quality), VLM (vision-language models), ASR (audio transcription)
- **Intelligent Auto-Detection**: Automatically selects optimal settings based on file type and content
- **Queue Management**: Handles concurrent requests with proper job queuing
- **Mac M2 Optimized**: Efficient memory usage and MLX acceleration support
- **Clean Markdown Output**: High-quality structured text ready for AI consumption
## Installation
### Prerequisites
- Python 3.9+ (recommended: 3.11+)
- macOS (optimized for Apple Silicon M2)
- 8GB+ RAM recommended
### Setup
1. **Clone and install dependencies:**
```bash
git clone <repository-url>
cd doc-ingestor-mcp
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
2. **Install Docling with Mac optimizations:**
```bash
# Core Docling with MLX acceleration for Apple Silicon
pip install docling
# For MLX support (Apple Silicon only):
pip install docling[mlx]
# Optional: additional OCR engines
pip install easyocr
# Install tesseract via homebrew: brew install tesseract
```
3. **Start the MCP server:**
```bash
python -m doc_ingestor_mcp
```
The server will start and listen for MCP connections using stdio transport.
## MCP Tools
The server provides the following MCP tools:
### `convert_document`
Converts any supported document to Markdown.
**Parameters:**
- `source` (required): File path or URL to the document
- `pipeline` (optional): Processing pipeline - `"standard"`, `"vlm"`, or `"asr"`
- `options` (optional): Additional processing options
**Example:**
```json
{
"name": "convert_document",
"arguments": {
"source": "https://arxiv.org/pdf/2408.09869",
"pipeline": "standard"
}
}
```
**Response:**
```json
{
"content": [
{
"type": "text",
"text": "# Document Title\n\nConverted markdown content here..."
}
]
}
```
### `convert_document_advanced`
Advanced conversion with detailed configuration options.
**Parameters:**
- `source` (required): File path or URL
- `pipeline` (optional): `"standard"`, `"vlm"`, `"asr"`
- `ocr_enabled` (optional): Enable/disable OCR (default: auto-detect)
- `ocr_language` (optional): OCR language codes (e.g., "eng,spa")
- `table_mode` (optional): `"fast"` or `"accurate"`
- `pdf_backend` (optional): `"dlparse_v4"` or `"pypdfium2"`
- `enable_enrichments` (optional): Enable code/formula/picture enrichments
**Example:**
```json
{
"name": "convert_document_advanced",
"arguments": {
"source": "./scanned-document.pdf",
"pipeline": "standard",
"ocr_enabled": true,
"ocr_language": "eng",
"table_mode": "accurate"
}
}
```
### `get_processing_status`
Check the status of ongoing conversions (useful for large files).
**Parameters:**
- `job_id` (required): Job identifier returned from conversion requests
### `list_supported_formats`
Returns all supported input and output formats.
**Response:**
```json
{
"input_formats": ["pdf", "docx", "xlsx", "pptx", "png", "jpeg", "html", "md", "csv", "mp3", "wav"],
"output_formats": ["markdown", "html", "json", "text", "doctags"],
"pipelines": ["standard", "vlm", "asr"]
}
```
## Usage Examples
### Basic PDF Conversion
```json
{
"name": "convert_document",
"arguments": {
"source": "./research-paper.pdf"
}
}
```
### URL-based Conversion with VLM Pipeline
```json
{
"name": "convert_document",
"arguments": {
"source": "https://example.com/complex-document.pdf",
"pipeline": "vlm"
}
}
```
### Audio Transcription
```json
{
"name": "convert_document",
"arguments": {
"source": "./meeting-recording.mp3",
"pipeline": "asr"
}
}
```
### Scanned Document with OCR
```json
{
"name": "convert_document_advanced",
"arguments": {
"source": "./scanned-invoice.pdf",
"ocr_enabled": true,
"ocr_language": "eng",
"table_mode": "accurate"
}
}
```
## Pipeline Selection Guide
### Standard Pipeline (Default)
- **Best for**: Born-digital PDFs, Office documents, clean layouts
- **Features**: Advanced layout analysis, table structure recovery, optional OCR
- **Performance**: Fast, memory-efficient
- **Use when**: Document has programmatic text and standard layouts
### VLM Pipeline
- **Best for**: Complex layouts, handwritten notes, screenshots, scanned documents
- **Features**: Vision-language model processing, end-to-end page understanding
- **Performance**: Slower, higher memory usage, MLX-accelerated on M2
- **Use when**: Standard pipeline fails or document has unusual layouts
### ASR Pipeline
- **Best for**: Audio files (meetings, lectures, interviews)
- **Features**: Whisper-based transcription, multiple model sizes
- **Performance**: CPU/GPU intensive depending on model size
- **Use when**: Processing audio content
## Auto-Detection Logic
The server automatically selects optimal settings:
1. **File Type Detection**: Based on extension and content analysis
2. **OCR Decision**: Enabled for scanned PDFs and images, disabled for text-based documents
3. **Pipeline Selection**: Standard for most documents, VLM suggested for images and complex layouts
4. **Backend Selection**: Native parser (dlparse_v4) for quality, pypdfium2 for speed/compatibility
## Performance Optimization (Mac M2)
### Memory Management
- **Large Files**: Automatic chunking and streaming processing
- **Queue System**: Prevents memory overflow from concurrent requests
- **Cleanup**: Automatic temporary file cleanup after processing
### MLX Acceleration
- VLM models run with MLX optimization on Apple Silicon
- Reduced memory footprint compared to standard PyTorch
- Automatic fallback to CPU if MLX unavailable
### Configuration
```bash
# Environment variables for optimization
export DOCLING_MAX_MEMORY_GB=6 # Limit memory usage
export DOCLING_QUEUE_SIZE=3 # Max concurrent jobs
export DOCLING_ENABLE_MLX=true # Enable MLX acceleration
```
## Error Handling
### Automatic Retry Logic
- Network timeouts for URL-based files
- Fallback pipelines if primary fails
- Alternative OCR engines if primary fails
### Error Response Format
```json
{
"error": {
"type": "ConversionError",
"message": "Failed to process document",
"details": "Specific error information",
"suggestions": ["Try VLM pipeline", "Enable OCR"]
}
}
```
### Common Issues & Solutions
| Issue | Cause | Solution |
|-------|-------|----------|
| Memory error with large PDF | Insufficient RAM | Split document or reduce queue size |
| Poor OCR quality | Wrong language/engine | Specify language with `ocr_language` |
| Scrambled text order | PDF parsing issues | Try `"pdf_backend": "pypdfium2"` |
| Tables not detected | Layout complexity | Use `"table_mode": "accurate"` |
| Slow processing | Large/complex document | Try `"pipeline": "standard"` first |
## Integration Examples
### Claude Desktop MCP Configuration
Add this to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"doc-ingestor": {
"command": "python",
"args": ["-m", "doc_ingestor_mcp"],
"cwd": "/path/to/doc-ingestor-mcp"
}
}
}
```
### Testing the Installation
1. **Test basic functionality:**
```bash
# Start the server in debug mode
python -m doc_ingestor_mcp --debug
# In another terminal, test with a sample file
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "convert_document", "arguments": {"source": "test.pdf"}}}' | python -m doc_ingestor_mcp
```
2. **Test with Claude Desktop:**
- Restart Claude Desktop after adding the MCP configuration
- In a new conversation, try: "Can you convert this PDF to markdown?" and attach a PDF file
- The server should appear in Claude's available tools
3. **Test different file types:**
```bash
# Test with different pipelines
python test_server.py
```
Create `test_server.py`:
```python
import asyncio
import json
from doc_ingestor_mcp.server import DocIngestorMCPServer
from doc_ingestor_mcp.config import load_config
async def test_conversion():
config = load_config("config.yaml")
server = DocIngestorMCPServer(config)
# Test basic conversion
result = await server._handle_convert_document({
"source": "https://arxiv.org/pdf/2408.09869",
"pipeline": "standard"
})
print("Conversion successful!")
print(f"Output length: {len(result[0].text)} characters")
if __name__ == "__main__":
asyncio.run(test_conversion())
```
## File Size Limits
- **PDFs**: Up to 500MB (auto-chunked)
- **Images**: Up to 50MB per image
- **Audio**: Up to 2GB (processed in segments)
- **Office Docs**: Up to 200MB
- **URLs**: 10-minute timeout for downloads
## Security Considerations
- **Local Processing**: All processing happens locally by default
- **Remote Services**: Optional (disabled by default) for VLM APIs
- **File Cleanup**: Temporary files automatically deleted
- **URL Validation**: Safe URL patterns enforced
## Troubleshooting
### Debug Mode
```bash
python -m doc_ingestor_mcp --debug
```
### Log Analysis
```bash
tail -f ./logs/server.log
```
### Run Test Suite
```bash
python test_server.py
```
### Common Issues
**"ModuleNotFoundError: No module named 'docling'"**
```bash
pip install docling
```
**"MLX not available" warnings**
- This is normal on non-Apple Silicon Macs
- MLX acceleration is optional and will fallback to CPU
**"Queue is full" errors**
- Wait for current jobs to complete
- Increase `max_queue_size` in config.yaml
**"Download failed" for URLs**
- Check internet connection
- Verify URL is accessible
- Some sites may block automated downloads
**Memory errors with large files**
- Reduce `max_memory_gb` in config.yaml
- Try smaller files first
- Use `pipeline: "standard"` instead of `vlm`
**OCR not working**
- Install tesseract: `brew install tesseract`
- Install easyocr: `pip install easyocr`
- Check language settings in config.yaml
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Support
- **Issues**: GitHub Issues
- **Discussions**: GitHub Discussions
- **Documentation**: [Docling Project Docs](https://docling-project.github.io/docling/)
Connection Info
You Might Also Like
No recommendations available