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.