# gongrzhe/office-word-mcp-server architecture

> Architecture diagram of the GitHub repository gongrzhe/office-word-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gongrzhe/office-word-mcp-server
- Repository: https://github.com/gongrzhe/office-word-mcp-server

## Overview

##### Project type and purpose
- This is an open-source MCP (Model Context Protocol) server implemented in Python.
- Purpose: expose Microsoft Word (.docx) document operations (create, read, format, protect, convert, etc.) via a standardized protocol so that AI assistants (e.g., Claude for Desktop) can drive document manipulation.

##### File structure
- Top‐level:
- word_mcp_server.py – the server entrypoint
- word_document_server/ – the application package
- mcp-config.json – MCP protocol configuration
- setup_mcp.py, pyproject.toml, requirements.txt – install and dependency definitions
- word_document_server/ is split into:
- core/ – low‐level document-operation modules (footnotes.py, tables.py, styles.py, protection.py, unprotect.py)
- tools/ – higher-level APIs that combine core functions into “tools” (content_tools.py, document_tools.py, format_tools.py, protection_tools.py, etc.)
- utils/ – helper functions for file I/O, document plumbing, extended behaviors

##### Extract key architecture notes from the README
- Uses FastMCP (Python MCP implementation) to expose Python functions to any MCP client over stdio/HTTP.
- Leverages python-docx library for actual Word file manipulation.
- Designed to be modular and extensible: adding a new tool is simply a new module under tools/.

##### Main components and interactions
A. External Clients
- AI assistants (Claude for Desktop or any MCP-compatible client)
B. MCP Transport Layer
- FastMCP runtime
- mcp-config.json defines which commands/functions to expose
C. Server Application
- Entry point (word_mcp_server.py)
- Module loader that discovers and registers all functions under word_document_server/tools and core
- Implements the MCP JSON/RPC over stdin/stdout or HTTP
D. Document Engine
- python-docx library (third-party)
- Core modules: footnotes, tables, styles, protection, unprotect
- Utilities: file handling, extended docx manipulations
E. Storage
- Local file system (reads/writes .docx and .pdf)

Client → MCP Transport → Server App → Document Engine → File System
And on the return path: File System → Document Engine → Server App → MCP Transport → Client

##### Architectural patterns and design principles
- Modular layering:
- Transport Layer (MCP)
- Application Layer (tools as high-level use cases)
- Core Layer (primitive operations)
- Utility Layer (shared helpers)
- Plugin-style registration: any module under tools/ or core/ automatically becomes an MCP callable tool.
- Separation of concerns: transport, business logic, file I/O, third-party library.

##### Technology callouts
- Python 3.8+
- FastMCP (MCP protocol server)
- python-docx for Word manipulation
- Optional uvx/uvicorn for packaging or HTTP hosting
- Local filesystem for document storage

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["AI Assistant (MCP Client)"]:::external

    subgraph "MCP Transport Layer"
        Transport["FastMCP Runtime"]:::thirdparty
        Config["mcp-config.json"]:::transport
    end

    subgraph "Server Application"
        Entrypoint["word_mcp_server.py"]:::server
        Loader["Module Loader (word_document_server/main.py)"]:::server
    end

    subgraph "Dependency / Packaging"
        PyProj["pyproject.toml"]:::infra
        Setup["setup_mcp.py"]:::infra
        Req["requirements.txt"]:::infra
    end

    subgraph "Document Engine"
        DocxLib["python-docx"]:::thirdparty
        subgraph "Tools (Application Layer)"
            T1["content_tools.py"]:::tools
            T2["document_tools.py"]:::tools
            T3["extended_document_tools.py"]:::tools
            T4["footnote_tools.py"]:::tools
            T5["format_tools.py"]:::tools
            T6["protection_tools.py"]:::tools
        end
        subgraph "Core (Core Layer)"
            C1["footnotes.py"]:::core
            C2["tables.py"]:::core
            C3["styles.py"]:::core
            C4["protection.py"]:::core
            C5["unprotect.py"]:::core
        end
        subgraph "Utils (Utility Layer)"
            U1["file_utils.py"]:::utils
            U2["document_utils.py"]:::utils
            U3["extended_document_utils.py"]:::utils
        end
    end

    FS["Local File System"]:::infra

    Client -->|"MCP Request"| Transport
    Transport -->|"load config"| Config
    Transport -->|"start server"| Entrypoint
    Entrypoint -->|"initialize"| Loader
    Loader -->|"register tools"| T1
    Loader -->|"register tools"| T2
    Loader -->|"register tools"| T3
    Loader -->|"register tools"| T4
    Loader -->|"register tools"| T5
    Loader -->|"register tools"| T6
    T1 -->|"use core ops"| C1
    T2 -->|"use core ops"| C2
    T3 -->|"use core ops"| C3
    T4 -->|"use core ops"| C4
    T5 -->|"use core ops"| C3
    T6 -->|"use core ops"| C4
    C1 -->|"use utils"| U1
    C2 -->|"use utils"| U2
    C3 -->|"use utils"| U3
    C4 -->|"use utils"| U1
    C5 -->|"use utils"| U2
    U1 -->|"invoke"| DocxLib
    U2 -->|"invoke"| DocxLib
    U3 -->|"invoke"| DocxLib
    DocxLib -->|"read/write"| FS

    FS -->|"file content"| DocxLib
    DocxLib -->|"processed data"| U1
    U1 -->|"helper output"| C1
    C1 -->|"core result"| T1
    T1 -->|"response"| Loader
    Loader -->|"collect results"| Entrypoint
    Entrypoint -->|"MCP Response"| Transport
    Transport -->|"send response"| Client

    Entrypoint -->|"depends on"| PyProj
    Entrypoint -->|"setup via"| Setup
    Entrypoint -->|"requires"| Req

    click Entrypoint "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_mcp_server.py"
    click Config "https://github.com/gongrzhe/office-word-mcp-server/blob/main/mcp-config.json"
    click Loader "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/main.py"
    click T1 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/tools/content_tools.py"
    click T2 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/tools/document_tools.py"
    click T3 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/tools/extended_document_tools.py"
    click T4 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/tools/footnote_tools.py"
    click T5 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/tools/format_tools.py"
    click T6 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/tools/protection_tools.py"
    click C1 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/core/footnotes.py"
    click C2 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/core/tables.py"
    click C3 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/core/styles.py"
    click C4 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/core/protection.py"
    click C5 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/core/unprotect.py"
    click U1 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/utils/file_utils.py"
    click U2 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/utils/document_utils.py"
    click U3 "https://github.com/gongrzhe/office-word-mcp-server/blob/main/word_document_server/utils/extended_document_utils.py"
    click Req "https://github.com/gongrzhe/office-word-mcp-server/blob/main/requirements.txt"
    click PyProj "https://github.com/gongrzhe/office-word-mcp-server/blob/main/pyproject.toml"
    click Setup "https://github.com/gongrzhe/office-word-mcp-server/blob/main/setup_mcp.py"

    classDef external fill:#aaffaa,stroke:#333,stroke-width:1px
    classDef transport fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef server fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef tools fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef utils fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef thirdparty fill:#ffd699,stroke:#333,stroke-width:1px
    classDef infra fill:#dddddd,stroke:#333,stroke-width:1px
```
