Evidence

Evidence

A test suite built on generated documents, a real subprocess round trip, and one independent comparison check quality here. The tests below ran on 2026-11-06, in the repository's own .venv and again in a fresh virtual environment built from a clean copy, on Windows with Python 3.12.10. Both runs gave the same count.

Tests

$ .venv/Scripts/python -m pytest -q
...................................................................      [100%]
67 passed in 12.05s

File	Tests	Covers
tests/test_docx_tools.py	53	Accepted text, search, variants, statistics, notes, failures, and hostile input
tests/test_server.py	14	The six tools over MCP, readable errors, stdio, and the console script

The test names describe the behavior they protect, and they group into four concerns.

Concern	Examples
Tracked changes	test_a_deletion_nested_inside_an_insertion_is_excluded, test_moved_away_text_is_excluded_and_moved_in_text_is_kept, test_a_match_inside_a_deletion_is_not_found
Document structure	test_a_term_spanning_runs_is_found, test_a_text_box_is_its_own_paragraph_and_is_not_counted_twice, test_table_cell_paragraphs_are_included
Safety	test_the_file_is_not_changed, test_an_external_entity_is_not_resolved, test_entity_expansion_does_not_blow_up, test_an_oversized_part_is_refused_before_it_is_read
Failure	test_a_missing_file_raises_rather_than_returning_empty, test_a_damaged_file_is_an_error_the_agent_can_read, test_a_bad_pattern_is_an_error_the_agent_can_read

test_the_server_works_over_real_stdio starts the server as a real subprocess, which covers the protocol path end to end. test_the_docx_logic_does_not_import_the_sdk holds the boundary between the library and the server in place.

What was measured

The server has no statistical claim to measure, so the evidence takes the form of correct outputs on known inputs.

Independent comparison. The test fixtures and the code share one author's reading of the format, which is a weakness a second reader can check. On 2026-11-06, examples/make_sample_docx.py built the sample document, and pandoc 3.6.3 read it with tracked changes accepted:

$ pandoc --track-changes=accept -t plain --wrap=none sample.docx
TODO: check the figures before this goes out.

The pilot covered twelve sites and met its target in the first year.

Cyber security spending rose.

Cybersecurity spending fell in one region.

read_accepted_text returned the same four paragraphs. That result is one document and a small one, so it counts as a consistency check and not as proof of general agreement.

Failure behavior. A missing path raises instead of returning an empty list:

FileNotFoundError [Errno 2] No such file or directory: 'nope.docx'

Round trip. The example output in How It Works came through the real MCP client over stdio, with the server as a subprocess, and tests/test_server.py exercises the same route.

Known failures and gaps

• No test has used a file saved by Word itself. Code builds every fixture, and each one is an invented document. This is the largest gap in the evidence, because the fixtures can only contain structures the author thought to write.
• The pandoc comparison ran on one sample. It is not part of the test suite.
• A pathological regular expression can stall the server. find_docx_term applies no time limit, and no test covers this.
• Headers, footers, footnotes, and endnotes are not read, so tracked changes there are invisible to every tool.
• No test run covers Linux or macOS.

Check it yourself in 5 minutes

Everything here runs offline after installation. On Windows, use .venv\Scripts\ in place of .venv/bin/.

git clone https://github.com/dboles99/docx-mcp.git
cd docx-mcp
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q                       # 67 passed
.venv/bin/python examples/call_over_stdio.py        # the six lines in How It Works

To repeat the independent comparison, with pandoc on your PATH:

.venv/bin/python examples/make_sample_docx.py sample.docx
pandoc --track-changes=accept -t plain --wrap=none sample.docx
.venv/bin/python -c "from docx_mcp import read_accepted_text as r; [print(x['text']) for x in r('sample.docx')]"

Both commands should print the same four paragraphs, and "and failed" should appear in neither.