Links
Revised 2026-08-08 after external review. Several claims in the first version of this issue were wrong and are corrected below. See the revision note at the bottom.
Context
After #40 was resolved, one of the reporters described the end-to-end workflow he actually runs mcp-pandoc inside of. Auditing the server against a real workflow, rather than against its own feature list, surfaced a set of gaps worth fixing together.
markdown in git = single source of truth
│
OUTBOUND │ md ──reference_doc=house.docx──► .docx ──► review ──► distribute
│ Word files are disposable builds, never hand-edited
│
INBOUND │ inbound .docx ──► md ──┐
│ inbound .pptx ──► md ──┴──► agent reads and reasons over them
It runs as an MCP server rather than as pandoc CLI calls because conversion is one step inside an agent loop: the agent researches, edits the markdown, builds the Word file, and publishes, without the human switching tools.
What the audit found
| Workflow step |
Status |
md → docx with reference_doc |
Works |
| docx → md |
Works, but silently drops embedded images |
| pptx → md |
Supported by pandoc >= 3.8.3. Not exposed by this server |
pdf offered as an input format |
Pandoc has no PDF reader in any release |
txt offered as an input format |
Not a pandoc reader. Fails inline, silently ignored for files |
reference_doc for odt / pptx |
Pandoc supports it; we restrict to docx |
| Minimum pandoc version |
Not declared. Makes several capability questions unanswerable |
| The #40 class of break recurring |
CI does not install the way users install |
| Server-side warnings |
Bare print() to stderr, with no level and no route to the model |
Child issues
| Priority |
Issue |
|
| P0 |
#54 |
Declare and enforce a minimum pandoc binary version |
| P1 |
#45 |
CI: add Windows and Python 3.13 to the test matrix |
| P1 |
#46 |
CI: install the way users install, with fresh resolution |
| P1 |
#47 |
Remove pdf from the input_format enum |
| P1 |
#48 |
Expose extract_media so docx to markdown keeps embedded images |
| P1 |
#57 |
input_format: "txt" fails inline and is ignored for files |
| P2 |
#49 |
Expose pptx in both directions (input requires pandoc >= 3.8.3) |
| P2 |
#50 |
Replace bare print() with stderr logging and tool-result warnings |
| P2 |
#52 |
Widen reference_doc to odt and pptx output |
| P3 |
#51 |
Add --version and a troubleshooting section |
Feature requests split out:
| Issue |
|
| #55 |
Support pptx as an input format (pandoc >= 3.8.3) |
| #56 |
Decide whether PDF input belongs in scope |
Order of work. #54 first, because it blocks any honest statement about format support. Then the P1 correctness and CI items. #49 and #55 depend on #54 landing.
Out of scope, and worth its own audit
The trust boundary. Inbound documents originate from third parties, the server accepts arbitrary filesystem paths, and it executes user-supplied filter scripts. See #36 and #33. Excluded here deliberately rather than overlooked, but it is arguably more consequential than anything listed above.
Also from the feedback
What made this bug hard to spot from the client side is that an import-time crash is completely silent, my agent just showed the server as not connecting, with no logs.
Accurate for the protocol: the crash precedes the MCP session, so nothing can be reported through it. The traceback does reach stderr, and current MCP debugging guidance says stdio hosts capture it, so the failure was invisible in one client rather than universally. #51 reduces diagnosis cost.
Revision note, 2026-08-08
The first version of this issue contained several errors, corrected here and in the child issues.
| Claim |
Correction |
| "pptx → md is not possible, pandoc has no pptx reader" |
Wrong. Pandoc 3.8.3 added a native pptx reader on 2025-12-01. The claim came from testing a local pandoc 3.7.0.2 and reporting the result as permanent |
| "python-pptx would be required" |
Withdrawn. No non-pandoc dependency is needed |
| "Every fresh install broken for eleven months" |
Wrong. mcp 2.0.0 shipped 2026-07-28, #40 was filed 07-29, fixed 07-31. Roughly three days. The quiet period in the repo was a separate fact |
| "Zero commits for eleven months" |
Wrong. 11 commits after v0.8.1, through 2025-09-15 |
| "Locked CI caused #40" |
The uncapped dependency was the cause. Locked CI was a detection gap |
| "Both reporters on Windows 11 with Python 3.13" |
Only @pbarone gave both. @Andrea-encrypted reported Windows without a Python version |
| "Migrate to MCP logging notifications" |
Reversed. That feature is deprecated as of spec 2026-07-28; new implementations SHOULD NOT adopt it |
| "Most clients ignore stderr" |
Unsupported. The spec says clients MAY ignore it |
Format matrix listed txt as readable |
Wrong. txt is not a pandoc reader in either direction |
Thanks to the reviewer who caught these. The pattern behind most of them was the same: testing against a stale local binary and stating the result as a general truth.
Links
docs/audits/2026-08-agent-workflow-audit.md, landing in docs: correct factual errors in the workflow audit #58ef3de10), against pandoc 3.7.0.2 and mcp python SDK 2.xContext
After #40 was resolved, one of the reporters described the end-to-end workflow he actually runs mcp-pandoc inside of. Auditing the server against a real workflow, rather than against its own feature list, surfaced a set of gaps worth fixing together.
It runs as an MCP server rather than as pandoc CLI calls because conversion is one step inside an agent loop: the agent researches, edits the markdown, builds the Word file, and publishes, without the human switching tools.
What the audit found
reference_docpdfoffered as an input formattxtoffered as an input formatreference_docfor odt / pptxprint()to stderr, with no level and no route to the modelChild issues
pdffrom theinput_formatenumextract_mediaso docx to markdown keeps embedded imagesinput_format: "txt"fails inline and is ignored for filespptxin both directions (input requires pandoc >= 3.8.3)print()with stderr logging and tool-result warningsreference_docto odt and pptx output--versionand a troubleshooting sectionFeature requests split out:
pptxas an input format (pandoc >= 3.8.3)Order of work. #54 first, because it blocks any honest statement about format support. Then the P1 correctness and CI items. #49 and #55 depend on #54 landing.
Out of scope, and worth its own audit
The trust boundary. Inbound documents originate from third parties, the server accepts arbitrary filesystem paths, and it executes user-supplied filter scripts. See #36 and #33. Excluded here deliberately rather than overlooked, but it is arguably more consequential than anything listed above.
Also from the feedback
Accurate for the protocol: the crash precedes the MCP session, so nothing can be reported through it. The traceback does reach stderr, and current MCP debugging guidance says stdio hosts capture it, so the failure was invisible in one client rather than universally. #51 reduces diagnosis cost.
Revision note, 2026-08-08
The first version of this issue contained several errors, corrected here and in the child issues.
txtas readabletxtis not a pandoc reader in either directionThanks to the reviewer who caught these. The pattern behind most of them was the same: testing against a stale local binary and stating the result as a general truth.