# HWP MCP Server

MCP (Model Context Protocol) server that enables LLMs to read and modify binary HWP (한글) documents via the HWP COM API.

## Architecture

```
LLM ↔ MCP Server (Python/FastMCP) ↔ PowerShell Bridge (JSON stdin/stdout) ↔ HWP COM API ↔ 한글
```

Python MCP server manages a long-running PowerShell subprocess that hosts HWP COM objects.

## Requirements

- **Windows** (HWP COM API is Windows-only)
- **한컴오피스 한글** installed (provides HWP COM server)
- **PowerShell 5.1+** (included with Windows)
- **Python >= 3.11**

## Installation

```bash
uv pip install -e .
```

## Usage

### Run MCP Server

```bash
python -m hwp_mcp.server
```

### Claude Desktop Config

```json
{
  "mcpServers": {
    "hwp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hwp-mcp", "hwp-mcp"]
    }
  }
}
```

## MCP Tools (140)

> HWP COM API 199 HParameterSet 100% coverage

### Document Management (5)
| Tool | Description |
|------|-------------|
| `open_document` | Open HWP document |
| `close_document` | Close document |
| `list_open_documents` | List open documents |
| `save_document` | Save document |
| `save_document_as` | Save as different name/format |

### Read (5)
| Tool | Description |
|------|-------------|
| `get_document_text` | Extract full text |
| `get_paragraphs` | Get paragraph list |
| `get_tables` | Get table list |
| `get_table_data` | Get table data (2D array) |
| `search_text` | Search text |

### Write (5)
| Tool | Description |
|------|-------------|
| `replace_text` | Replace text |
| `insert_text` | Insert text |
| `set_table_cell_text` | Set table cell text |
| `append_paragraph` | Append paragraph |
| `set_text_file` | Set document content from text data |

### Formatting (3)
| Tool | Description |
|------|-------------|
| `set_text_style` | Character formatting (font, size, bold, color, etc.) |
| `set_paragraph_style` | Paragraph formatting (alignment, line spacing) |
| `set_page_style` | Page formatting (margins, orientation) |

### Table (3)
| Tool | Description |
|------|-------------|
| `create_table` | Create table |
| `add_table_row` | Add table row |
| `delete_table_row` | Delete table row |

### Advanced (5)
| Tool | Description |
|------|-------------|
| `run_hwp_action` | Execute arbitrary HWP action (power user) |
| `convert_to_hwpx` | Convert HWP → HWPX |
| `convert_to_pdf` | Convert HWP → PDF |
| `batch_convert_files` | Batch convert files (HWP, PDF, DOCX, etc.) |
| `set_file_security` | File security settings (copy/print restriction) |

### Cursor & Navigation (11)
| Tool | Description |
|------|-------------|
| `move_cursor` | Move cursor to specified position |
| `get_cursor_position` | Get current cursor position |
| `set_cursor_position` | Set cursor position (list, para, pos) |
| `get_pos_by_set` | Get cursor position as set |
| `set_pos_by_set` | Set cursor position from set |
| `get_selected_pos_by_set` | Get selection start/end positions |
| `select_text` | Select text range by coordinates |
| `get_selection_info` | Get current selection info |
| `clear_selection` | Clear selection |
| `delete_selection` | Delete selected content |
| `init_scan` | Initialize document scan |

### Field (12)
| Tool | Description |
|------|-------------|
| `create_field` | Create named field (template placeholder) |
| `field_exists` | Check if field exists |
| `get_field_list` | Get all field names |
| `get_field_text` | Read field text |
| `put_field_text` | Set field text |
| `get_current_field` | Get field name at cursor |
| `set_current_field_name` | Set current field name |
| `move_to_field` | Move cursor to field |
| `rename_field` | Rename field |
| `modify_field_properties` | Modify field properties |
| `set_field_ctrl_properties` | Set field control properties |
| `batch_fill_fields` | Batch fill multiple fields |

### Advanced Table (11)
| Tool | Description |
|------|-------------|
| `add_table_column` | Add table column |
| `delete_table_column` | Delete table column |
| `merge_table_cells` | Merge cells |
| `split_table_cell` | Split cell |
| `set_table_cell_style_adv` | Cell style (background, vertical alignment) |
| `set_table_border_adv` | Table border style |
| `table_to_text` | Table → text conversion |
| `text_to_table` | Text → table conversion |
| `swap_table_row_col` | Swap table rows/columns |
| `apply_table_template` | Apply table template |

### Enhanced Formatting (5)
| Tool | Description |
|------|-------------|
| `set_char_shape` | Extended character properties (kerning, spacing, shadow, etc.) |
| `set_bullet_style` | Bullet style |
| `set_numbering_style` | Numbering style |
| `set_tab_definition` | Tab stops |
| `manage_style` | Create/delete/apply styles |

### Page & Section (10)
| Tool | Description |
|------|-------------|
| `set_section_definition` | Section definition (binding margin, text flow) |
| `set_page_border` | Page border and background |
| `set_columns` | Multi-column layout |
| `set_page_number` | Page number |
| `set_header_footer` | Header/footer |
| `set_footnote_style` | Footnote style |
| `set_master_page` | Master page |
| `set_page_hiding` | Hide page elements (header/footer, etc.) |
| `set_page_num_ctrl` | Page number control (restart numbering) |
| `set_text_direction` | Text direction (horizontal/vertical) |

### Image & Equation (3)
| Tool | Description |
|------|-------------|
| `insert_picture` | Insert picture |
| `insert_background_picture` | Insert background picture |
| `create_equation` | Insert equation |

### Form Control (3)
| Tool | Description |
|------|-------------|
| `insert_form_control` | Insert form control (button, checkbox, etc.) |
| `set_form_properties` | Set form control properties |
| `get_form_data` | Read form data |

### Document Info (5)
| Tool | Description |
|------|-------------|
| `get_document_info` | Document metadata (page count, modified state) |
| `get_document_summary` | Document summary (title, author) |
| `get_page_text` | Extract specific page text |
| `get_page_count` | Total page count |
| `export_page_as_image` | Export page as image |

### Print & Export (3)
| Tool | Description |
|------|-------------|
| `print_document` | Print document |
| `set_watermark` | Set watermark (text/image) |
| `save_as_image` | Save document as image |

### Utility (4)
| Tool | Description |
|------|-------------|
| `convert_units` | Unit conversion (mm, pt, hwpunit) |
| `rgb_color` | RGB/Hex → HWP color value |
| `run_macro` | Run HWP macro |
| `get_file_info` | File metadata (without opening) |

### Bookmark & Hyperlink (6)
| Tool | Description |
|------|-------------|
| `insert_bookmark` | Insert bookmark |
| `insert_hyperlink` | Insert hyperlink |
| `hyperlink_jump` | Jump to hyperlink target |
| `insert_index_mark` | Insert index mark |
| `insert_auto_number` | Insert auto number field |
| `insert_cross_reference` | Insert cross reference |

### Header/Footer & Caption (2)
| Tool | Description |
|------|-------------|
| `set_drop_cap` | Drop cap (decorative first letter) |
| `set_caption` | Table/image caption |

### Document Operations (8)
| Tool | Description |
|------|-------------|
| `sort_text` | Sort text |
| `spell_check` | Spell check |
| `set_track_changes` | Track changes |
| `mail_merge` | Mail merge |
| `make_table_of_contents` | Generate table of contents |
| `insert_file` | Insert another file |
| `set_password` | Document password |
| `save_block` | Save selection to file |

### Compatibility & Settings (3)
| Tool | Description |
|------|-------------|
| `set_compatible_document` | Document compatibility mode |
| `set_view_properties` | HWP view properties (zoom, view mode, etc.) |
| `set_engine_properties` | HWP engine properties (spell check, auto-save, etc.) |

### Control & Object (4)
| Tool | Description |
|------|-------------|
| `delete_ctrl` | Delete selected control |
| `find_ctrl` | Find control |
| `check_x_object` | Check X object existence |
| `release_scan` | Release scan resources |

### Style & Script (4)
| Tool | Description |
|------|-------------|
| `import_style` | Import style |
| `export_style` | Export style |
| `run_script` | Run HWP script |
| `get_script_source` | Get script source |

### System & Security (11)
| Tool | Description |
|------|-------------|
| `register_module` | Register COM module |
| `set_drm_authority` | DRM authority |
| `lock_command` | Lock/unlock command |
| `is_command_lock` | Check command lock status |
| `set_message_box_mode` | Message box mode |
| `get_message_box_mode` | Get message box mode |
| `is_action_enable` | Check action enabled |
| `replace_action` | Replace action handler |
| `get_hwp_property` | Get HWP COM property |
| `set_hwp_property` | Set HWP COM property |
| `hwp_enum` | String → HWP enum value |

### HParameterSet Actions (10)
| Tool | Description | HParameterSet Count |
|------|-------------|---------------------|
| `hwp_table_param_action` | Table actions | 14 |
| `hwp_file_param_action` | File actions | 11 |
| `hwp_draw_param_action` | Draw object actions | 22 |
| `hwp_shape_param_action` | Shape actions | 6 |
| `hwp_style_param_action` | Style/border actions | 6 |
| `hwp_form_param_action` | Form actions | 13 |
| `hwp_doc_info_param_action` | Document info actions | 9 |
| `hwp_hanja_param_action` | Hanja/conversion actions | 11 |
| `hwp_selection_param_action` | Selection/position actions | 6 |
| `hwp_misc_param_action` | Miscellaneous actions | 69 |

## Project Structure

```
hwp-mcp/
├── src/hwp_mcp/
│   ├── __init__.py
│   ├── _core.py         # FastMCP instance & shared helpers
│   ├── server.py        # Entry point, imports all tool modules
│   ├── bridge.py        # PowerShell subprocess manager
│   ├── commands.py      # JSON command builders
│   └── tools/           # MCP tool definitions (140 tools)
│       ├── cursor.py
│       ├── doc_info.py
│       ├── document.py
│       ├── drawing.py
│       ├── field.py
│       ├── form.py
│       ├── formatting.py
│       ├── hparam.py
│       ├── hwpobject.py
│       ├── page_section.py
│       ├── print_export.py
│       ├── system.py
│       ├── table.py
│       ├── text.py
│       └── utility.py
├── scripts/
│   ├── hwp_bridge.ps1   # PowerShell COM bridge dispatcher
│   └── handlers/        # 12 handler modules
│       ├── document.ps1
│       ├── text.ps1
│       ├── table.ps1
│       ├── style_format.ps1
│       ├── action.ps1
│       ├── cursor_selection.ps1
│       ├── field.ps1
│       ├── draw_object.ps1
│       ├── form_control.ps1
│       ├── document_info.ps1
│       ├── print_export.ps1
│       ├── utility.ps1
│       └── hwpobject_methods.ps1
├── tests/
│   ├── test_bridge.py   # Bridge unit tests
│   ├── test_commands.py # Command builder unit tests
│   └── test_server.py   # Server tool unit tests
└── pyproject.toml
```

## Development

```bash
uv pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/
```

## Limitations

- **Windows only**: HWP COM API requires Windows
- **한글 required**: 한컴오피스 한글 must be installed
- **Binary HWP only**: HWPX (XML-based) needs a separate server

## License

MIT