Docio

A Model Context Protocol (MCP) server that provides comprehensive document conversion capabilities using Pandoc with additional support for Excel files and modern PDF processing.

Features

• Universal Document Conversion: Convert between 50+ document formats
• Excel Support: Full Excel (.xlsx) file creation and conversion using pure JavaScript
• Modern PDF Processing: PDF text extraction and generation using Puppeteer and pdf-parse
• No External Dependencies: All format conversions work out-of-the-box
• Batch Processing: Convert multiple documents simultaneously
• Metadata Extraction: Extract document metadata and statistics
• Document Validation: Validate document format and structure
  • Plain text extraction
  • Document metadata extraction
  • Bulk document conversion
• Smart Format Detection: Automatically detects file formats from extensions and content
• Intelligent Response System: Returns file content for text formats, file paths for binary formats
• Caching System: Efficient caching to avoid repeated conversions
• Comprehensive Format Support:
  • Documents: DOCX, DOC, ODT, RTF, PDF
  • Markup: HTML, XML, LaTeX, reStructuredText
  • E-books: EPUB
  • Presentations: PPTX

Installation

npm install -g docio-mcp

The installation will automatically download the appropriate Pandoc binary for your platform.

Usage

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "pandoc": {
      "command": "npx",
  "args": ["docio-mcp"]
    }
  }
}

With VS Code

Add to your MCP configuration:

{
  "pandoc": {
    "command": "npx",
  "args": ["docio-mcp"]
  }
}

Available Tools

convert_to_markdown

Converts documents to Markdown format optimized for AI tools.

Parameters:

• input (required): File content (base64 encoded) or file path
• inputFormat (optional): Input format (auto-detected if not specified)
• filePath (optional): Original file path for format detection
• outputOptions (optional): Conversion options
  • preserveFormatting (boolean): Preserve original formatting
  • extractImages (boolean): Extract and include images
  • tableStyle ('pipe' | 'grid' | 'simple'): Table formatting style
  • mathFormat ('unicode' | 'tex' | 'mathml'): Math formula format

Example:

{
  "input": "base64encodedcontent...",
  "inputFormat": "docx",
  "outputOptions": {
    "preserveFormatting": true,
    "tableStyle": "pipe"
  }
}

convert_document

Universal document conversion between formats.

Parameters:

• input (required): File content (base64 encoded) or file path
• outputFormat (required): Target format
• inputFormat (optional): Input format (auto-detected if not specified)
• filePath (optional): Original file path for format detection
• options (optional): Additional Pandoc options

extract_text

Extracts plain text from documents.

Parameters:

• input (required): File content (base64 encoded) or file path
• inputFormat (optional): Input format (auto-detected if not specified)
• filePath (optional): Original file path for format detection

get_document_metadata

Extracts metadata from documents.

Parameters:

• input (required): File content (base64 encoded) or file path
• inputFormat (optional): Input format (auto-detected if not specified)
• filePath (optional): Original file path for format detection

list_supported_formats

Lists all supported input and output formats.

Supported Formats

Input Formats

• Documents: docx, doc, odt, rtf, pdf
• Markup: html, xml, markdown, rst, latex
• E-books: epub, epub3
• Presentations: pptx
• Web: html5, html4

Output Formats

• Documents: docx, pdf, odt, rtf
• Markup: markdown, html, xml, latex, rst
• E-books: epub, epub3
• Plain text: plain

Development

Building from Source

git clone <repository-url>
cd docio-mcp
npm install
npm run build

Running in Development

npm run dev

Project Structure

docio-mcp/
├── src/
│   ├── index.ts          # MCP server main entry
│   ├── pandoc.ts         # Pandoc wrapper and manager
│   └── utils/
│       ├── cache.ts      # Conversion caching system
│       └── file.ts       # File utilities and format detection
├── bin/                  # Pandoc binaries (auto-downloaded)
├── scripts/
│   └── download-pandoc.js # Pandoc download script
└── dist/                 # Compiled JavaScript

Configuration

Environment variables:

• PANDOC_CACHE_SIZE: Maximum cache entries (default: 100)
• PANDOC_CACHE_TTL: Cache time-to-live in ms (default: 3600000)
• PANDOC_MAX_FILE_SIZE: Maximum file size in bytes (default: 50MB)

Platform Support

• macOS: x86_64 and ARM64 (via Rosetta)
• Windows: x86_64
• Linux: Manual Pandoc installation required

Pandoc Version

This MCP server includes Pandoc version 3.7.0.2, which provides:

• Enhanced format support
• Improved conversion quality
• Better error handling
• Security improvements

Troubleshooting

Pandoc Binary Issues

If Pandoc fails to download or execute:

1. Check internet connectivity during installation
2. Verify file permissions (macOS/Linux)
3. Try manual installation: npm run postinstall

Format Detection Issues

If format detection fails:

• Specify inputFormat explicitly
• Ensure file has correct extension
• Check file content is valid

Performance Issues

For large files or frequent conversions:

• Monitor cache usage
• Adjust cache settings via environment variables
• Consider file size limits

License

MIT License

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Related Projects

• Pandoc - Universal document converter
• Model Context Protocol - Protocol for AI tool integration
• Claude Desktop - AI assistant with MCP support