MCP to interface with pandoc to convert files to different formats with enhanced features like Mermaid diagram conversion and defaults file support.
Single-tool server with a comprehensive but overly verbose description. The convert-contents tool has a complete input schema with proper types and enums, but the description is 4000+ characters, far exceeding the 1024-character guidance and wasting tokens with repetitive examples and formatting. Parameter descriptions are adequate but some are generic. No output schema is documented, leaving the LLM unable to plan downstream operations. Error handling is not visible in the tool definition. The tool performs a single responsibility (format conversion) correctly, but presentation quality is weakened by description bloat.
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 (returned inline): txt, html, markdown, ipynb - Advanced (REQUIRE complete file paths): pdf, docx, rst, latex, epub, odt, pptx - pptx is WRITE-ONLY: it can be produced, but not used as an input format ✅ 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, ODT & PPTX STYLING: 4. Custom Styling with Reference Documents: * Use reference_doc parameter to apply professional styling to DOCX, ODT and PPTX output * The reference document MUST match the output format: .docx for docx, .odt for odt, .pptx for pptx * 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.
Description exceeds 1024 characters by 4x (4000+ chars). Violates token efficiency guidance. Contains 20+ example code blocks, warning boxes, and formatting that wastes context. Rule: keep descriptions 10-1024 chars.
No output schema documented. LLM cannot plan downstream tool calls or know what fields are returned. Example: does success return file path, file size, execution time, or all three? Blocks tool composition.
Output format depends on input_format (pdf/docx/etc require output_file; markdown/html/txt return inline). This dependency is documented in the description but NOT in parameter definitions where the LLM reads it. Undocumented parameter relationships cause silent misuse.
Parameter 'contents' description is generic: 'The content to be converted (required if input_file not provided)'. Does not explain format expectations, encoding, size limits, or what happens on empty input.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | C | 60 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
Mutually exclusive parameters 'contents' and 'input_file' are documented in descriptions but not enforced in schema. LLM may pass both or neither without validation guidance.
No error guidance in tool definition. What happens if TeX Live is not installed? If output_file directory doesn't exist? If filters crash? LLM receives no recovery hints per pattern:recovery-guide.
Parameter 'filters' accepts arbitrary file paths without path traversal or injection prevention guidance. No validation shown for existence, executability, or safety. Tool risks command injection if LLM constructs malicious filter paths.
Naming 'convert-contents' uses hyphen (Python anti-pattern) but is acceptable for MCP. However, hyphen makes parsing ambiguous: is it 'convert' + 'contents' or a single action 'convert-contents'? Verb_noun convention ('convert_document' or 'convert_text') would be clearer.