# jkf87/hwp-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/jkf87/hwp-mcp
- Repository: https://github.com/jkf87/hwp-mcp

## Overview

##### Project Type and Purpose
- This is a protocol server (MCP server) written in Python that exposes control over the Hancom HWP word processor to an external AI (e.g., Claude) via standard‐in/standard‐out.
- Its purpose is to receive high-level document commands from the AI (create document, insert text, manipulate tables, save files, batch operations), translate those into HWP COM API calls (with optional security module support), and return results to the AI.

##### High-Level File/Module Structure
- Top-Level
- hwp_mcp_stdio_server.py – entry point that implements the MCP server loop over stdio, receives JSON commands, writes JSON responses.
- requirements.txt – Python dependencies.
- security_module/FilePathCheckerModuleExample.dll – a Windows DLL that is loaded into the HWP process to bypass file-open security dialogs.
- src/utils/command_parser.py – parses incoming JSON into operation objects.
- src/tools/hwp_controller.py – wraps core document functions (create, open, save, text insertion, font settings).
- src/tools/hwp_table_tools.py – specialized table operations (insert table, populate cells, fill column numbers).
- src/__tests__/… – unit tests for command parser and controller logic.

##### Key Architectural Patterns
- Command‐Pattern / Dispatcher: JSON command → CommandParser → dispatch to a handler method in either HwpController or HwpTableTools.
- Layered Separation:
- Protocol layer (stdio server)
- Parsing layer (command_parser)
- Business logic layer (tools)
- External integration layer (HWP COM API + security_module)
- Optional Plugin (security_module) loaded at runtime when interfacing with HWP.

##### Main Components to Illustrate
a. External AI Client (Claude)
– Sends/receives JSON via stdio following MCP spec.
b. MCP Server (hwp_mcp_stdio_server.py)
– Listens on stdio, forwards raw messages to CommandParser.
c. Command Parser (src/utils/command_parser.py)
– Validates JSON schema, maps “operation” and “params” to internal command objects.
d. Dispatcher/Controller Layer
– HwpController (document creation, text/font operations)
– HwpTableTools (table insertion/filling)
e. Security Module Loader
– Loads FilePathCheckerModuleExample.dll into HWP process to suppress security dialogs.
f. HWP Application (COM API)
– The actual word processor manipulated via Windows COM.
g. Tests (src/__tests__)
– Unit tests verifying parser and controller logic.

##### Interactions and Data Flow
1. AI → (JSON over stdio) → MCP Server
2. MCP Server → CommandParser.parse() → Command Object
3. Command Object → Dispatcher → appropriate Tool Method
4. Tool Method → optionally invoke Security Module → COM API calls into HWP
5. HWP executes action, returns status
6. MCP Server → serializes JSON response → AI

##### Technologies/Frameworks
- Python 3.7+
- mcp (optional pip package for protocol scaffolding)
- win32com.client or pywin32 (COM integration)
- security_module DLL (native code)
- pytest or unittest (tests)

##### Detail Checklist
- Component names match file names (e.g., HwpController, hwp_table_tools).
- Layers and boundaries (Client vs. Server, Protocol vs. Business Logic vs. Integration).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client"
        AI["AI Client (Claude)"]:::external
    end

    %% Server Layer
    subgraph "Server"
        subgraph "Protocol Layer"
            MCP["MCP Server\n(hwp_mcp_stdio_server.py)"]:::server
        end
        subgraph "Logic Layer"
            Parser["Command Parser\n(src/utils/command_parser.py)"]:::parser
            Ctrl["HwpController\n(src/tools/hwp_controller.py)"]:::tool
            Table["HwpTableTools\n(src/tools/hwp_table_tools.py)"]:::tool
        end
        subgraph "Integration Layer"
            SecMod["Security Module\n(FilePathCheckerModuleExample.dll)"]:::dll
            HWP["HWP Application\n(COM API)"]:::com
        end
    end

    %% Test Suite
    subgraph "Tests"
        TestParser["test_command_parser.py"]:::test
        TestCtrl["test_hwp_controller.py"]:::test
    end

    %% Dependencies
    Deps["requirements.txt"]:::deps

    %% Flows
    AI -->|"JSON (stdio)"| MCP
    MCP -->|"raw JSON"| Parser
    Parser -->|"dispatch"| Ctrl
    Parser -->|"dispatch"| Table
    Ctrl -->|"load DLL"| SecMod
    Table -->|"load DLL"| SecMod
    Ctrl -->|"COM calls"| HWP
    Table -->|"COM calls"| HWP
    HWP -->|"status/result"| MCP
    MCP -->|"JSON response"| AI

    TestParser --> Parser
    TestCtrl --> Ctrl
    Deps -.-> MCP

    %% Click Events
    click MCP "https://github.com/jkf87/hwp-mcp/blob/main/hwp_mcp_stdio_server.py"
    click Parser "https://github.com/jkf87/hwp-mcp/blob/main/src/utils/command_parser.py"
    click Ctrl "https://github.com/jkf87/hwp-mcp/blob/main/src/tools/hwp_controller.py"
    click Table "https://github.com/jkf87/hwp-mcp/blob/main/src/tools/hwp_table_tools.py"
    click SecMod "https://github.com/jkf87/hwp-mcp/blob/main/security_module/FilePathCheckerModuleExample.dll"
    click TestParser "https://github.com/jkf87/hwp-mcp/blob/main/src/__tests__/test_command_parser.py"
    click TestCtrl "https://github.com/jkf87/hwp-mcp/blob/main/src/__tests__/test_hwp_controller.py"
    click Deps "https://github.com/jkf87/hwp-mcp/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef parser fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef tool fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef dll fill:#FFA500,stroke:#333,stroke-width:1px
    classDef com fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef test fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef deps fill:#FFB6C1,stroke:#333,stroke-width:1px
```
