Adeu: Python Toolchain & MCP Server
This directory contains the core Python implementation of Adeu. It provides the core Redline Engine, the developer SDK, the command-line interface (CLI), and the FastMCP server backend.
Adeu acts as a "Virtual DOM" for Microsoft Word. It translates complex DOCX XML into token-efficient CriticMarkup for LLMs, validates structural edits, and patches the XML safely to preserve document formatting, metadata, and styles. On Windows, it also interfaces directly with live Microsoft Word instances via COM.
Local Development Setup
Adeu is managed using uv and packaged via hatchling. It requires Python 3.12 or higher.
# Clone and enter the directory
cd python
# Install dependencies and sync the virtual environment
uv sync
# Run the test suite
uv run pytest
The Command Line Interface (CLI)
The adeu CLI provides a powerful suite of tools for interacting with documents locally.
Extraction & Reading
Extract text as CriticMarkup. Use --clean-view to simulate "Accept All Changes".
# Extract full text
uvx adeu extract contract.docx -o output.md
# Extract only the structural heading outline
uvx adeu extract contract.docx --mode outline
# Extract the form fields ledger (content controls)
uvx adeu extract contract.docx --mode fields
# Strip navigation prose and headers for raw token efficiency
uvx adeu extract contract.docx --no-chrome
# Windows Only: Extract text from the actively open Word document
uvx adeu extract --live
Diffing
Generate a word-level patch diff or a one-step redlined .docx comparison between two document versions.
# Compare two DOCX files (@@ Word Patch @@ output)
uvx adeu diff original.docx modified.docx
# Write the comparison directly as a tracked-changes .docx in one step
uvx adeu diff original.docx modified.docx -o redlined.docx --author "AI Reviewer"
# Output raw JSON edits for programmatic use
uvx adeu diff original.docx modified.docx --json
Applying Edits
Apply a JSON array of DocumentChange objects (or a modified markdown file) back to the DOCX.
# Apply a JSON batch of edits to a file
uvx adeu apply original.docx edits.json --author "AI Reviewer" -o redlined.docx
# Manual / inline formatting markup (strikethrough + bold red underline instead of Track Changes)
uvx adeu apply original.docx edits.json --author "AI Reviewer" --manual -o manual.docx
# Word-level redline fragments under one spanning comment for commented edits
uvx adeu apply original.docx edits.json --author "AI Reviewer" --commented-change-granularity word -o redlined.docx
# Emit the batch result as machine-readable JSON on stdout (for agents/scripts)
uvx adeu apply original.docx edits.json --json
# Partial salvage mode: apply valid edits while reporting failing edits
uvx adeu apply original.docx edits.json --partial
# Terse error context: produce compact error messages
uvx adeu apply original.docx edits.json --terse-errors
# Windows Only: Apply edits directly to the live, open Word canvas
uvx adeu apply edits.json --live
Accepting All Changes
Accept every tracked change in one operation, producing a finalized clean document. Mirrors the accept_all_changes MCP tool — including its default.
Comment removal is ON by default (--remove-comments): the output is meant to be distributable, and comments are internal review notes that must not travel to a counterparty. Use --no-remove-comments when the review conversation is still live.
# Writes contract_clean.docx next to the input; comments are DELETED
uvx adeu accept-all contract.docx
# Accept the tracked changes but keep the comments
uvx adeu accept-all contract.docx --no-remove-comments
# Explicit output path, machine-readable result on stdout
uvx adeu accept-all contract.docx -o final.docx --json
Every deleted comment is reported by id and author (removed_comment_details under --json). A comment whose anchored text an accepted deletion consumes is removed either way — Word does the same.
The library API is the other way round:
RedlineEngine.accept_all_revisions()defaults toremove_comments=False, because an SDK caller composing their own pipeline should not lose annotations implicitly.
Sanitization
Strip sensitive metadata, hidden text, and author names before external distribution.
# Full scrub (fails if unresolved track changes exist unless --accept-all is passed)
uvx adeu sanitize contract.docx --accept-all -o clean.docx
# Keep your redlines/comments, but anonymize the author and strip metadata
uvx adeu sanitize redline.docx --keep-markup --author "My Firm"
JSON-Lines Daemon (adeu serve)
For high-throughput local agent drivers or CI harnesses, run adeu serve to maintain a warm process and document cache over stdin/stdout JSON-Lines:
uv run adeu serve
Agentic / Headless Usage (the CLI as an API)
When an agent operates in a closed sandbox (a CI pipeline, a containerized coding agent) it cannot reach an MCP server. The CLI is the fallback: a strictly local, air-gapped command-line API that accepts the same JSON change schema as the MCP tools. The mapping is 1:1:
| MCP tool | CLI equivalent |
|---|---|
read_docx |
adeu extract <doc> [--json] |
diff_docx_files |
adeu diff <orig> <mod> [--json] |
process_document_batch |
adeu apply <doc> <changes.json> [--json] |
accept_all_changes |
adeu accept-all <doc> [--json] |
The I/O contract (see docs/cli-agent-spec.md for the full specification):
- stdout carries only document data (Markdown/CriticMarkup) or, with
--json, a machine-readable JSON result.uvx adeu extract doc.docx > out.mdalways produces a clean file, even with--debug. - stderr carries all logs, progress messages, warnings, and errors.
- Exit codes:
0= success (in--partialmode, at least one edit applied; checkedits_skippedin JSON stats to detect skipped edits)1= failure (in atomic mode, if any edit fails; in--partialmode, if all edits fail)
adeu apply --json prints the engine's raw stats object — edits_applied, edits_skipped, per-edit reports with CriticMarkup previews, plus output_path — and suppresses the human-readable logs. A batch that fails validation prints {"error": "batch_validation_failed", "failed": [{"index", "reason"}, ...], "errors": [...]} and exits 1.
The Python SDK
The SDK allows you to embed Adeu's Redline Engine directly into your own Python applications without pulling in MCP server dependencies (pip install adeu or uv add adeu).
Applying Tracked Changes
The engine processes a flat list of DocumentChange objects (ModifyText, SetField, AcceptChange, RejectChange, ReplyComment, InsertTableRow, DeleteTableRow).
from io import BytesIO
from adeu import RedlineEngine, ModifyText, AcceptChange
# 1. Load the document stream
with open("contract.docx", "rb") as f:
stream = BytesIO(f.read())
# 2. Define your edits
changes = [
ModifyText(
target_text="State of New York",
new_text="State of Delaware",
comment="Standardized jurisdiction.",
match_mode="all",
),
AcceptChange(target_id="Chg:12"),
]
# 3. Initialize the engine and apply
engine = RedlineEngine(stream, author="AI Copilot")
stats = engine.process_batch(changes)
# 4. Save the result
with open("contract_redlined.docx", "wb") as f:
f.write(engine.save_to_stream().getvalue())
Extracting Text
Read a document into CriticMarkup representation.
from io import BytesIO
from adeu import extract_text_from_stream
with open("contract.docx", "rb") as f:
stream = BytesIO(f.read())
# Extract raw text with {++ ++} and {-- --} tags intact
markdown_text = extract_text_from_stream(stream)
# Extract clean text simulating "Accept All Changes"
clean_text = extract_text_from_stream(stream, clean_view=True)
Sanitizing Documents
Run the metadata scrubber programmatically.
from adeu.sanitize import sanitize_docx
result = sanitize_docx(
input_path="draft.docx",
output_path="final.docx",
keep_markup=True,
author="Legal Team",
)
print(result.report_text)
The MCP Server
The Python backend exposes Adeu's capabilities to AI agents via the Model Context Protocol (MCP), powered by FastMCP (shipped in the optional adeu[mcp] extra so SDK and CLI installs stay slim).
Running the Server
You can boot the server over stdio for agent consumption:
uvx --from "adeu[mcp]" adeu-server
Or install into an existing environment with pip install "adeu[mcp]" / uv add "adeu[mcp]".
Claude Desktop Integration
Adeu provides an initialization command to automatically inject the MCP server into your local Claude Desktop configuration.
# Installs to Claude Desktop using the global uvx path
uvx adeu init
# Local Developer Mode: Configures Claude to run the server from your current source tree
uv run adeu init --local
File access
By default, the Python MCP server can read and save documents in any folder its account can access. The following checks apply to MCP tool calls. The standalone adeu CLI and Python library use their own file handling.
- Saving a document. Choose
.docxor the input's extension, ignoring case and excluding.pdf. Fordiff_docx_files, either input's extension qualifies, and the output must be distinct from both inputs. Save.docm,.dotm,.dotxand.dotoutputs beside the input with the matching extension. - Replacing a file. The destination may be new, an empty regular file, or a Word package. Adeu checks the ZIP listing for
[Content_Types].xmlandword/document.xml. To recover from an interrupted save, it also accepts a regular file with a Word extension beside the input if its ZIP directory is missing or malformed. Adeu refuses directories, special files such as pipes, and readable non-Word ZIPs. - Opening a document.
open_local_filelaunches the native application only for a regular Word package ending in.docx,.docm,.dotxor.dotm. The same check applies toopen_word_documentwhen the Windows test tools are enabled. - Resolving paths. Adeu follows symbolic links and Windows junctions before checking and using the destination. For a new file it resolves the existing parent folders first. Default outputs and the
.unverified.docxdiagnostic copy go through the same checks before any missing output folders are created. On Windows, use ordinary file names. Reserved device names, colons after the drive prefix, and components ending in a dot or space are refused.
To limit MCP file access to specific folders, set ADEU_ALLOWED_DIRS in your MCP host configuration. This Windows example allows two folders.
{
"mcpServers": {
"adeu": {
"command": "uvx",
"args": ["--from", "adeu[mcp]", "adeu-server"],
"env": { "ADEU_ALLOWED_DIRS": "C:\\Projects\\Contracts;D:\\Reviewed" }
}
}
}
Use a semicolon-separated list on Windows and a colon-separated list on macOS or Linux (for example, /srv/contracts:/srv/reviewed). Every entry must be an absolute path to an existing folder. An empty list or invalid entry prevents startup. Restart the server to load changes, or unset the variable and restart to restore the default. At startup, the server logs the resolved folders to stderr.
All input and output paths, including baselines and diagnostic copies, must resolve inside a listed folder. A folder-access refusal names the allowed folders.
Live Word Interop (Windows COM)
On Windows, the MCP server uses pywin32 to read or edit documents already open in Microsoft Word. Omit file_path in read_docx or original_docx_path in process_document_batch to work with the active document.
With folder restrictions enabled, live tools check the open document's actual local path, including for Save As. Save an unsaved or cloud-only document from Word into an allowed folder before using these tools.
Testing & Architectural Constraints
When developing inside the python/ directory, please note the following invariants:
- Surgical Mode: The
RedlineEnginenever performs global document normalization on load or save. This strict behavior prevents the silent destruction of unrelated metadata (like<w:proofErr>) and minimizes XML diff noise. - COM Teardown: In
live_word.pyand its associated tests, we intentionally omitpythoncom.CoUninitialize()andapp.Quit()during teardown. FastMCP andpytesthold proxies unpredictably: forcing teardown causes fatal RPC Access Violations (0x800706be). We let the OS handle the apartment lifecycle. - Testing Asserts: Native
python-docxParagraph.textproperties silently ignore text inside<w:ins>tags. When writing tests to verify redlines, strictly useextract_text_from_stream(clean_view=True)to accurately evaluate the accepted text state.
Environment Variables
| Variable | Description | Default |
|---|---|---|
ADEU_ALLOWED_DIRS |
Allowed folders for MCP tool file access. See File access. | Unset (all accessible folders) |
ADEU_DOC_CACHE_ENTRIES |
Capacity for in-memory parsed document LRU cache | 3 |
ADEU_NO_CACHE |
Set to 1 or true to disable disk-level projection caching |
0 |
ADEU_CACHE_DIR |
Custom storage directory for disk projection cache | OS cache dir |
ADEU_AUTHOR |
Fallback author name for tracked changes when unspecified | OS username (fallback: Adeu AI) |
Metadata
Release files for adeu 4.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| adeu-4.2.0.tar.gz | 1.2 MB | With provenance | Details for adeu-4.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| adeu-4.2.0-py3-none-any.whl | Python 3 | none | any | Details for adeu-4.2.0-py3-none-any.whl |
Total release size: 1.6 MB
Release files / adeu-4.2.0.tar.gz
| Download URL | adeu-4.2.0.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b6b69f7760565941c64c8a7ffc5cab873f71f006c6813f508ae59cf82024dc30
|
|
BLAKE2b-256 checksum How to use checksums |
931c81fe3f9bb6f421c5896cfea5579f0203fd02eba87d07a4d72ab35baed910
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / adeu-4.2.0-py3-none-any.whl
| Download URL | adeu-4.2.0-py3-none-any.whl |
|---|---|
| Size | 479.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5119a9ade69173fc63d9d6412a8ee79eddca374ed748c07d99705c67feb385bc
|
|
BLAKE2b-256 checksum How to use checksums |
e57a8eb7b2a19b2b52dc5a4919abbaada18da37674e8baa7739353da5e38d014
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for adeu 4.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for adeu-4.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.