# Docio MCP Server

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

```bash
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:

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

### With VS Code

Add to your MCP configuration:

```json
{
  "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:**
```javascript
{
  "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

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

### Running in Development

```bash
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](https://pandoc.org/) - Universal document converter
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol for AI tool integration
- [Claude Desktop](https://claude.ai/) - AI assistant with MCP support