docs-mcp

MCP server for reading and writing .docx files. Exposes four paginated tools so agents can batch-read document content and styles, write content, and union style definitions — without a monolithic reformat tool.

Requirements: Python 3.11+

Features

Primary use case: reformat a draft document using a template's styles — the agent orchestrates four tool calls with pagination.

Architecture

Layered design: MCP tools delegate to services, services use adapters, adapters translate to/from domain models.

flowchart TB
  subgraph mcpLayer [MCP Layer]
    Server[FastMCP Server]
    Tools["4 Tools: get/write contents & styles"]
  end

  subgraph serviceLayer [Service Layer]
    ReadSvc[ReadService]
    WriteSvc[WriteService]
  end

  subgraph adapterLayer [Adapter Layer]
    DocxAdapter[DocxAdapter]
    ContentWriter[ContentWriter]
    StyleMigrator[StyleMigrator]
    ContentExtractor[ContentExtractor]
    StyleExtractor[StyleExtractor]
  end

  subgraph domainLayer [Domain Layer]
    DocModel[DocumentModel]
    StyleProfile[StyleProfile]
    BlockModel[ParagraphBlock / TableBlock]
  end

  Agent[Cursor Agent] -->|batch tool calls| Server
  Server --> Tools
  Tools --> ReadSvc
  Tools --> WriteSvc
  ReadSvc --> DocxAdapter
  WriteSvc --> DocxAdapter
  DocxAdapter --> ContentExtractor
  DocxAdapter --> StyleExtractor
  DocxAdapter --> ContentWriter
  DocxAdapter --> StyleMigrator
  ReadSvc --> domainLayer
  WriteSvc --> domainLayer

Layer rules

Dependency direction is always downward: MCP → Service → Adapter → Domain.

See AGENTS.md for contributor guidelines.

Tech stack

• python-docx — .docx I/O
• MCP Python SDK (mcp>=1.12.0) — FastMCP server
• uv — package manager and runner

Tools reference

All tools return JSON-serializable dicts. On failure, the response contains structured error fields instead of raising an unhandled exception:

{
  "code": "FILE_NOT_FOUND",
  "message": "File not found: /path/missing.docx",
  "details": { "path": "/path/missing.docx" }
}

Error codes: FILE_NOT_FOUND, FILE_NOT_READABLE, FILE_NOT_WRITABLE, INVALID_PATH, PARSE_ERROR, STYLE_NOT_FOUND, REFORMAT_ERROR, INTERNAL_ERROR.

get_contents_from_docx

Return a paginated batch of document content blocks.

Example response:

{
  "items": [
    {
      "block_type": "paragraph",
      "runs": [
        {
          "text": "ЛАБОРАТОРНАЯ РАБОТА №3 (Java)",
          "bold": null,
          "italic": null,
          "font_name": null,
          "font_size_pt": null
        }
      ],
      "style": {
        "name": "Heading 1",
        "style_type": "paragraph"
      }
    }
  ],
  "total": 48,
  "offset": 0,
  "limit": 10,
  "has_more": true,
  "source_path": "/path/plain.docx"
}

Blocks carry a style name reference (StyleHint), not full style definitions. See .agents/skills/docx-mcp/references/blocks for the full schema.

get_styles_from_docx

Return a paginated batch of paragraph styles from a .docx file.

Example response (first batch, offset=0):

{
  "paragraph_styles": [
    {
      "name": "Heading 1",
      "base_style": "Normal",
      "font_name": null,
      "font_size_pt": null,
      "font_color": "000000",
      "bold": null,
      "italic": null,
      "alignment": null,
      "line_spacing": 1.0,
      "space_before_pt": 18.0,
      "space_after_pt": 12.0,
      "left_indent_cm": null,
      "right_indent_cm": null,
      "first_line_indent_cm": null
    }
  ],
  "section": {
    "page_width_cm": 21.0,
    "page_height_cm": 29.7,
    "left_margin_cm": 2.5,
    "right_margin_cm": 1.0,
    "top_margin_cm": 1.5,
    "bottom_margin_cm": 1.5
  },
  "total": 33,
  "offset": 0,
  "limit": 25,
  "has_more": true,
  "source_path": "/path/format.docx"
}

section is included only when offset == 0; later batches omit it. Merge paragraph_styles client-side across batches.

write_contents_to_docx

Write content blocks to a .docx file. Creates a new file if the path does not exist; replaces the document body if it exists.

Example response:

{
  "file_path": "/path/output.docx",
  "blocks_written": 48,
  "created": true
}

write_styles_to_docx

Union style definitions onto an existing .docx file. Incoming styles win on name conflict.

Example response:

{
  "file_path": "/path/output.docx",
  "styles_added": 5,
  "styles_updated": 12,
  "styles_unchanged": 8
}

Returns FILE_NOT_FOUND if the target file does not exist — call write_contents_to_docx first.

User story: Reformat by template

Prompt example:

Reformat report_draft.docx to match company_template.docx. Save as report_final.docx.

Agent workflow:

report_draft.docx                    company_template.docx
        │                                      │
        ├─ get_contents_from_docx (batches)    ├─ get_styles_from_docx (batches)
        │                                      │
        └──────────────────┬───────────────────┘
                           ▼
              write_contents_to_docx(report_final.docx)   ← creates file
                           ▼
              write_styles_to_docx(report_final.docx)     ← union; template wins
                           ▼
                    formatted output

Step-by-step

1. Read content — paginate get_contents_from_docx(draft, offset, limit) until has_more is false. Collect all items.

2. Read styles — paginate get_styles_from_docx(template, offset, limit) until has_more is false. Merge all paragraph_styles; keep section from the first batch (offset=0).

3. Write content — write_contents_to_docx(output, contents) with the collected blocks.

4. Union styles — write_styles_to_docx(output, styles) with the merged style profile.

Pagination pattern

# Contents
items = []
offset = 0
while True:
    batch = get_contents_from_docx(path, offset=offset, limit=50)
    items.extend(batch["items"])
    if not batch["has_more"]:
        break
    offset += batch["limit"]

# Styles
paragraph_styles = []
section = None
offset = 0
while True:
    batch = get_styles_from_docx(path, offset=offset, limit=50)
    if offset == 0:
        section = batch.get("section")
    paragraph_styles.extend(batch["paragraph_styles"])
    if not batch["has_more"]:
        break
    offset += batch["limit"]
styles = {"paragraph_styles": paragraph_styles, "section": section}

Tool order

Style union rules

Applied by write_styles_to_docx via StyleProfile.union_with(incoming, master="other"):

Styles with null field values inherit from base_style at write time (StyleProfile.resolve_inherited()). For the run-level overrides bold, italic, and font_color, a resolved null is an explicit reset: the corresponding override is cleared in the target style so draft theme artifacts (e.g. blue, bold headings) do not survive a reformat.

StyleMapper (adapter helper)

When mapping source style names to a template catalog (used internally during reformat):

1. Exact name match in template styles
2. Entry in optional custom_map
3. Nearest heading fallback (Heading N → Heading min(N, available))
4. Fallback to Normal, or first available template style

Unmapped styles are tracked in unmapped_styles.

Known limitations (v1)

Not supported in the current release:

• Headers and footers (content)
• Floating images
• Text boxes
• Footnotes and endnotes
• Numbering restart / list numbering preservation
• Run-level formatting when a named paragraph style exists (deferred — styles applied in step 4 override inline hints)
• Paragraph-level direct formatting (e.g. a centered title set on the paragraph, not in the style) — not carried by content blocks; ParagraphAligner covers only the title/conclusions heuristic used in the reformat tests
• Document parse caching — each batch call re-reads the file from disk

Development

uv sync --extra dev
uv run pytest
uv run docx-mcp

Project layout

docs-mcp/
├── README.md
├── AGENTS.md
├── Dockerfile
├── pyproject.toml
├── src/docx_mcp/
│   ├── server.py          # MCP tools (thin handlers)
│   ├── errors.py
│   ├── domain/            # DocumentModel, StyleProfile, blocks
│   ├── adapters/          # python-docx isolation
│   └── services/          # ReadService, WriteService
├── tests/
│   └── assets/            # plain.docx, format.docx fixtures
└── .agents/skills/docx-mcp/  # Agent skill for MCP workflow

Test fixtures for manual exploration:

• tests/assets/plain.docx — sample content (draft)
• tests/assets/format.docx — sample styles (template)

End-to-end pipeline test: tests/test_reformat_pipeline.py.

Roadmap

Quick start

1. Clone and install

git clone <repo-url> docs-mcp
cd docs-mcp
uv sync --extra dev

2. Run tests

uv run pytest

3. Smoke test the MCP server

uv run docx-mcp

The process listens on stdio (JSON-RPC). Press Ctrl+C to stop.

4. Add to Cursor

Replace /absolute/path/to/docs-mcp with your clone path. Cursor MCP config requires absolute paths.

Native (uv):

{
  "mcpServers": {
    "docs-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/docs-mcp",
        "docx-mcp"
      ]
    }
  }
}

Docker (ephemeral session):

Build once from the repo root (no file paths in the image or build command):

cd docs-mcp
docker build -t docs-mcp .

MCP config — only how to start the server process. Which files to read/write is not configured here; every tool receives file_path from the MCP client (agent/user) at call time:

{
  "mcpServers": {
    "docs-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "docs-mcp"]
    }
  }
}

File paths in tool calls

With Docker, the default config above has no bind mounts — tool paths must exist inside the container unless you extend args. To read/write host files, add a volume mount that matches the paths you pass in tools, for example:

"args": ["run", "--rm", "-i", "-v", "/home/user/docs:/home/user/docs", "docs-mcp"]

Then the agent calls get_contents_from_docx(file_path="/home/user/docs/report.docx") — same path string on host and in the container.

One container runs for the entire MCP session (not per tool call). The host spawns the process on connect and tears it down on disconnect; --rm removes the container automatically.

License

See repository license file.