docx-mcp AGENTS.md

AGENTS.md

Instructions for AI coding agents operating in this repository.

Project

docx-mcp is a Python library that applies AI-generated legal document changes as professional tracked changes (w:ins/w:del) with comments inside .docx files. It manipulates OOXML directly via lxml -- python-docx is only used in test fixture generation.

Build / Lint / Test

# Install dependencies
uv sync

# Run all tests
uv run pytest tests/ -v

# Run a single test file
uv run pytest tests/test_redliner.py -v

# Run a single test by name
uv run pytest tests/test_redliner.py::TestSingleModify::test_modify_produces_tracked_changes -v

# Lint
uvx ruff check src/ tests/

# Auto-fix lint
uvx ruff check src/ tests/ --fix

# Type check
uvx ty check src/ tests/

# Run the MCP server (stdio transport)
uv run docx-mcp-server

Test fixtures (.docx files) are auto-generated on first run by a session-scoped pytest fixture. They live in tests/fixtures/generated/ (gitignored).

LSP errors about unresolved imports (lxml, pydantic, docx, pytest, diff_match_patch) are expected -- these packages lack type stubs but work at runtime. Do not try to fix these.

Code Style

Imports

Imports are ordered: stdlib, third-party, local -- each group separated by a blank line, alphabetical within each group. Enforced by ruff rule I (isort).

import contextlib
from pathlib import Path

from lxml import etree

from docx_mcp.document import DocxDocument
from docx_mcp.models import Change, ChangeType, RedlineConfig

Formatting

• Line length: 100 characters.
• Target: Python 3.14+ (py314).
• Ruff rules enforced: F, E, W, I, UP, B, SIM, ANN, RUF.
• ANN (type annotations) is disabled for test files.

Type Annotations

• Use modern union syntax: str | None, Path | str | bytes. Never Optional or Union.
• lxml elements are typed as etree._Element (the private type is the convention here).
• All public functions have full parameter and return type annotations.
• Keyword-only arguments after * for id_manager and config parameters.