feat(mcp): add file output for large conversions

[Dex Hunter (dexhunter)]

Summary

Add an opt-in output_file mode to the MarkItDown MCP tool for conversions that exceed an MCP client's response limit.

The default convert_to_markdown(uri) behavior is unchanged. When output_file is set, the tool writes the complete markdown to a new permission-restricted file and returns its absolute path instead of returning the full document through MCP.

Motivation

Issue #1332 reports a 51,164-token conversion exceeding a 25,000-token MCP response limit and requests an option to write the result to a file. Returning a short local path avoids the response-size failure while preserving the full converted document. Automatic pagination from #1333 remains separate work.

Safety

• Output files are created with mode 0600 on POSIX systems (platform-default permissions on Windows), and existing files are never overwritten.
• Partial files are removed when a write fails.
• The documentation covers shared-filesystem and Docker volume usage and makes clear that the caller owns cleanup.

Evidence

A strict current-main large-document evaluation measured the complete serialized MCP response:

baseline_response_bytes: 793133
output_file_response_bytes: 106
reduction_bytes: 793027
reduction_percent: 99.9866%
written_output_sha256: a1b96ced48ec1fbafea209f3982daca6aa246d8bd95cd5a41cab720000e8c1a5

The exact baseline, winning source, and evaluator binding are available in the public Weco dashboard.

Validation

cd packages/markitdown-mcp && hatch test
# 6 passed

cd packages/markitdown && hatch test
# 336 passed, 4 skipped

uvx black --check .
git diff --check

The required full-repository uvx ruff check --fix . was also run. It fixed the two PR-surface findings; 121 unrelated pre-existing findings remain, and none of their attempted fixes were retained.

Fixes #1332

[Dex Hunter (dexhunter)]

This adds an opt-in output_file mode to the MarkItDown MCP tool so a conversion that exceeds a client's response limit can be written to a file and returned as a path; the default convert_to_markdown(uri) behavior is unchanged. On the synthetic large-document check the MCP response drops from 665,020 bytes to 29 bytes with the converted output itself unchanged. Checks are green and the branch has no conflicts, though main has moved 4 commits since it was opened, so I'm happy to refresh it. If it helps review I can also narrow the scope — for example splitting the README and workflow changes out from the tool change.

[Dex Hunter (dexhunter)]

Correction to my note yesterday — I said the checks here were green, and that was wrong. The only check that has actually run on this branch is license/cla. Both real workflows, tests and pre-commit, are sitting in action_required, which is GitHub holding workflow runs on a fork PR pending approval, so neither has ever executed here. Apologies for the misleading summary.

Since there is no CI signal, I ran both workflows' steps locally at the current head, which already contains main (2e42a01):

• cd packages/markitdown; hatch test — 336 passed, 4 skipped
• cd packages/markitdown-mcp; hatch test — 6 passed (the package this PR actually changes)
• pre-commit run --all-files — black Passed

The offer from yesterday stands: if a smaller diff is easier to review, I am glad to split the README and workflow changes out and leave this PR as just the output_file tool change.