mcp-pandoc

Converts content between different formats. Transforms input content from any supported format into the specified output format.

🚨 CRITICAL REQUIREMENTS - PLEASE READ:

1. PDF Conversion:

   • You MUST install TeX Live BEFORE attempting PDF conversion:

   • Ubuntu/Debian: sudo apt-get install texlive-xetex

   • macOS: brew install texlive

   • Windows: Install MiKTeX or TeX Live from https://miktex.org/ or https://tug.org/texlive/

   • PDF conversion will FAIL without this installation

2. File Paths - EXPLICIT REQUIREMENTS:

   • When asked to save or convert to a file, you MUST provide:

     • Complete directory path

     • Filename

     • File extension

   • Example request: 'Write a story and save as PDF'

   • You MUST specify: '/path/to/story.pdf' or 'C:\Documents\story.pdf'

   • The tool will NOT automatically generate filenames or extensions

3. File Location After Conversion:

   • After successful conversion, the tool will display the exact path where the file is saved

   • Look for message: 'Content successfully converted and saved to: [file_path]'

   • You can find your converted file at the specified location

   • If no path is specified, files may be saved in system temp directory (/tmp/ on Unix systems)

   • For better control, always provide explicit output file paths

Supported formats:- Basic: txt, html, markdown, ipynb, odt- Advanced (REQUIRE complete file paths): pdf, docx, rst, latex, epub✅ CORRECT Usage Examples:

1. 'Convert this text to HTML' (basic conversion)

   • Tool will show converted content

2. 'Save this text as PDF at /documents/story.pdf'

   • Correct: specifies path + filename + extension

   • Tool will show: 'Content successfully converted and saved to: /documents/story.pdf'

❌ INCORRECT Usage Examples:

1. 'Save this as PDF in /documents/'

   • Missing filename and extension

2. 'Convert to PDF'

   • Missing complete file path

When requesting conversion, ALWAYS specify:

1. The content or input file

2. The desired output format

3. For advanced formats: complete output path + filename + extension Example: 'Convert this markdown to PDF and save as /path/to/output.pdf'

🎨 DOCX STYLING (NEW FEATURE): 4. Custom DOCX Styling with Reference Documents:

• Use reference_doc parameter to apply professional styling to DOCX output

• Create custom templates with your branding, fonts, and formatting

• Perfect for corporate reports, academic papers, and professional documents

• Example: 'Convert this report to DOCX using /templates/corporate-style.docx as reference and save as /reports/Q4-report.docx'

🎯 PANDOC FILTERS (NEW FEATURE): 5. Pandoc Filter Support:

• Use filters parameter to apply custom Pandoc filters during conversion

• Filters are Python scripts that modify document content during processing

• Perfect for Mermaid diagram conversion, custom styling, and content transformation

• Example: 'Convert this markdown with mermaid diagrams to DOCX using filters=["./filters/mermaid-to-png-vibrant.py"] and save as /reports/diagram-report.docx'

📋 Creating Reference Documents:

• Generate template: pandoc -o template.docx --print-default-data-file reference.docx

• Customize in Word/LibreOffice: fonts, colors, headers, margins

• Use for consistent branding across all documents

📋 Filter Requirements:

• Filters must be executable Python scripts

• Use absolute paths or paths relative to current working directory

• Filters are applied in the order specified

• Common filters: mermaid conversion, color processing, table formatting

📄 Defaults File Support (NEW FEATURE): 7. Pandoc Defaults File Support:

• Use defaults_file parameter to specify a YAML configuration file

• Similar to using pandoc -d option in the command line

• Allows setting multiple options in a single file

• Options in the defaults file can include filters, reference-doc, and other Pandoc options

• Example: 'Convert this markdown to DOCX using defaults_file="/path/to/defaults.yaml" and save as /reports/report.docx'

Note: After conversion, always check the success message for the exact file location.