mcp-compliant document format conversion via pandoc bridge
Implements a Model Context Protocol server that wraps the Pandoc document conversion library, enabling AI assistants and MCP clients to invoke format transformations through standardized tool-call semantics. The server registers a single convert-contents tool that accepts source content or file paths, validates input/output format compatibility, and delegates conversion to pypandoc, which internally shells out to the native Pandoc binary. This architecture decouples the MCP communication layer from the underlying conversion engine, allowing Claude Desktop and other MCP-compatible clients to transparently access Pandoc's 30+ format support without direct binary invocation.
Unique: Exposes Pandoc's full format library through MCP's standardized tool-call protocol, allowing AI assistants to invoke conversions as first-class operations without requiring users to manage CLI invocations or external scripts. Distinguishes between basic formats (returned as strings in responses) and advanced formats (requiring filesystem operations), enabling efficient in-conversation conversions while supporting complex file-based workflows.
vs alternatives: Unlike standalone Pandoc CLI or Python pypandoc bindings, mcp-pandoc integrates directly into Claude's tool ecosystem, enabling conversational format decisions and multi-step document workflows without context switching or manual file management.
dual-mode input handling with content-string and file-path conversion
The convert-contents tool accepts two mutually-exclusive input modes: direct content strings (for in-memory conversions) or complete file paths (for filesystem-based operations). The tool validates that exactly one input source is provided, then routes to the appropriate pypandoc method — either `convert_text()` for string inputs or `convert_file()` for file paths. This dual-mode design enables both lightweight conversational conversions (e.g., 'convert this markdown snippet to HTML') and heavyweight batch operations (e.g., 'convert all DOCX files in /documents to PDF'), without requiring separate tools or complex parameter negotiation.
Unique: Implements a single tool with two distinct execution paths (content-string vs file-path) rather than separate tools, reducing cognitive load for users while maintaining clean separation of concerns internally. The validation logic ensures mutual exclusivity, preventing ambiguous or conflicting input specifications.
vs alternatives: More flexible than tools that support only file inputs (requiring users to save snippets to disk) or only string inputs (limiting batch operations), while simpler than multi-tool approaches that duplicate conversion logic across separate endpoints.
format-aware output routing with basic-vs-advanced format distinction
The server implements a two-tier output strategy based on format classification: basic formats (markdown, HTML, plain text) are converted via pypandoc and returned directly as strings in the MCP response, enabling zero-latency in-conversation results; advanced formats (PDF, DOCX, RST, LaTeX, EPUB) require an explicit output_file parameter and are written to the filesystem, since these binary or complex formats cannot be serialized into MCP text responses. This routing logic is enforced at the tool parameter level — advanced formats will reject requests without an output_file path, preventing silent failures or incomplete conversions.
Unique: Explicitly separates basic and advanced formats with different output mechanisms (in-response strings vs filesystem writes), optimizing for the common case of lightweight text conversions while supporting complex binary formats. This two-tier design is enforced at the tool schema level, preventing invalid parameter combinations before execution.
vs alternatives: More efficient than tools that always write to disk (adding latency for simple conversions) or always return strings (failing on binary formats), while clearer than tools that silently choose output modes based on format, which can surprise users.
pandoc binary abstraction via pypandoc python wrapper
The server delegates all format conversion logic to the pypandoc Python library, which wraps the native Pandoc binary and provides a Pythonic API (`convert_text()`, `convert_file()` methods). This abstraction layer shields the MCP server from direct binary invocation, error handling, and version compatibility concerns. pypandoc internally manages Pandoc subprocess spawning, argument marshaling, and stdout/stderr capture, allowing the server to focus on MCP protocol compliance and tool parameter validation rather than low-level process management.
Unique: Relies on pypandoc as a thin abstraction layer over Pandoc, avoiding custom subprocess orchestration and format-specific parsing logic. This design prioritizes simplicity and maintainability over performance, accepting the overhead of Python subprocess spawning in exchange for leveraging Pandoc's comprehensive format support.
vs alternatives: Simpler than custom Pandoc wrappers that reimplement subprocess management and error handling, while more flexible than hardcoded format converters that support only a subset of Pandoc's formats. Trades some performance for code simplicity and format breadth.
mcp tool registration and parameter schema validation
The server implements MCP's tool-listing and tool-execution handlers by registering a convert-contents tool with a detailed JSON schema that defines required parameters (contents or input_file, input_format, output_format, and conditionally output_file for advanced formats), parameter types, and descriptions. When an MCP client invokes the tool, the server validates incoming parameters against this schema before delegating to pypandoc, ensuring type safety and preventing invalid format combinations (e.g., requesting PDF output without an output_file path). This schema-driven approach enables MCP clients like Claude to provide autocomplete, parameter hints, and client-side validation before tool invocation.
Unique: Implements MCP's tool-registration pattern with a detailed JSON schema that enforces parameter constraints at the protocol level, enabling client-side hints and validation. The schema explicitly distinguishes between basic and advanced formats, with conditional output_file requirements, making invalid parameter combinations detectable before execution.
vs alternatives: More discoverable and user-friendly than tools without schema documentation, while more flexible than tools with hardcoded parameter validation that cannot adapt to new formats. Leverages MCP's standard tool-listing mechanism, making the tool accessible to any MCP-compatible client without custom integration code.
stateless, single-tool conversion interface
The server exposes a single convert-contents tool that handles all format conversion workflows, rather than separate tools for each format pair or conversion mode. This stateless design means each tool invocation is independent — no session state, no conversion history, no format caching — and the server maintains no internal state between requests. The tool accepts all necessary parameters (input, format, output path) in a single call, enabling straightforward MCP client integration and horizontal scaling (multiple server instances can handle requests without coordination).
Unique: Consolidates all format conversions into a single, stateless tool rather than format-specific or mode-specific endpoints, prioritizing simplicity and horizontal scalability over advanced features like caching or multi-step pipelines. This design aligns with MCP's philosophy of simple, composable tools.
vs alternatives: Simpler to integrate and scale than stateful tools that maintain conversion history or session context, while less feature-rich than tools with built-in caching or pipeline support. Trades advanced capabilities for straightforward, predictable behavior.