How jkf87/hwp-mcp works
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).