Pandoc

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.

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.

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.

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.

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.

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).