FORGE

Format-Oriented Rendering & Generation Engine

Preserve the content. Reforge the format.

FORGE is a schema-driven DOCX formatting and transformation engine for AI agents. It generates, inspects, reformats, assembles, and safely edits Word documents — without rewriting the user's content.

FORGE is not a text-generation system. The server never summarizes, rewrites, or "improves" document text. It only changes formatting and document structure, under explicit instructions, with hard preservation guarantees.

Quick Start

git clone https://github.com/IIIIQAQIIII/forge-word-docx-mcp.git
cd forge-word-docx-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt        # runtime deps
.venv/bin/pip install -r requirements-dev.txt    # tests (optional)

.venv/bin/python server.py                       # start MCP server (stdio)
.venv/bin/python test_server.py                  # self-test (25 checks)
.venv/bin/python -m pytest -q                    # full test suite

Python support: >=3.10, <3.13 — verified by CI on Python 3.10 / 3.11 / 3.12. Installer-based setup is documented in INSTALL.md.

Configure the MCP client with:

{
  "mcpServers": {
    "forge": {
      "command": "/absolute/path/to/forge-word-docx-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/forge-word-docx-mcp/server.py"]
    }
  }
}

Related MCP server: docx-mcp-server

Core Capabilities

Legacy compatibility:

• reformat_docx is the legacy template-based reformat path and remains unchanged.

• Built-in legacy generation types and templates remain unchanged.

Content Preservation (high level)

FORGE treats the user's content as immutable payload:

1. Inspector reads the DOCX into an ordered Document IR with deterministic source_locator paths (never text matching).

2. Source-Preserving Renderer only patches formatting XML (w:pPr / w:rPr / w:tblPr / w:tcPr / drawing extents).

3. Preservation Validation compares content fingerprints before/after: visible text, structure, media bytes, content sequence, table structure, and media relationships.

4. If any fingerprint fails, no output is produced.

Edit intentionally allows text changes, so it validates against an Edit Contract: Source IR + EditPlan → Expected Payload vs Actual Payload. Unauthorized changes are rejected with EDIT_CONTRACT_VIOLATION.

Format Model

ContentIntent != SemanticRole != FormatProfile != Template

• ContentIntent says what the content is (plan, summary, notice…).

• SemanticRole says what a block does (title, heading, body, caption…).

• FormatProfile says how to format each role.

• Template is only a DOCX skeleton for generation.

Profiles can be:

• Preset — built-in profiles (generic, official, academic, weekly, …).

• Reference — learned from a sample DOCX (analyze_reference_format).

• Custom — explicit overrides on a base profile.

• Guided — step-by-step sessions that only ask the key differences.

User profiles persist under FORGE_HOME/profiles/ (default ~/.forge-docx-mcp/). Dynamic templates persist under FORGE_HOME/templates/.

See docs/FORMAT_PROFILES.md and docs/ARCHITECTURE.md for details.

Examples

Synthetic examples live in examples/:

• example_reformat.py

• example_assemble.py

• example_reference_profile.py

• example_edit.py

All examples use generic synthetic data only.

Documentation

• INSTALL.md — installer and generic stdio setup.

• docs/MCP_TOOLS.md — every MCP tool, parameters, results, common errors.

• docs/FORMAT_PROFILES.md — format model, profiles, FORGE_HOME.

• docs/ARCHITECTURE.md — pipeline diagrams and subsystem responsibilities.

• CHANGELOG.md — release notes, including v1.2.1.

Release

• Current release: v1.2.1

• Status: stable

Known limitations are documented in CHANGELOG.md. No performance guarantees are implied by the development-machine benchmarks.