# HWP.works - Korean Document Processing API & MCP Server

Cross-platform HWP/HWPX document processing API with MCP support. Extract text, tables, metadata from Korean HWP documents. Fill templates, edit paragraphs, compare documents. Works on any platform — no Windows required.

## Pricing

| Event           | Price   | Description                                              |
|-----------------|---------|----------------------------------------------------------|
| Actor start     | $0.01   | Charged once per Actor run start                         |
| API call        | $0.001  | Charged per document processing request                   |

## REST API Endpoints

All endpoints accept `multipart/form-data` with a `file` field.

| Endpoint                                 | Description                        | Output                                   |
|------------------------------------------|------------------------------------|------------------------------------------|
| `POST /api/v1/extract/text`             | Extract full text                  | `{ text, sections[] }`                 |
| `POST /api/v1/extract/tables`           | Extract tables                      | `{ tables[{ rows[][] }] }`             |
| `POST /api/v1/extract/metadata`         | Extract document metadata           | `{ title, author, date, ... }`         |
| `POST /api/v1/extract/images`           | Extract embedded images            | `{ images[{ base64, format }] }`       |
| `POST /api/v1/extract/formdata`        | Extract form fields                | `{ fields[{ name, value }] }`          |
| `POST /api/v1/analyze`                  | Analyze structure                  | `{ sections[], placeholders[], documentType }` |
| `POST /api/v1/fill`                     | Fill template placeholders          | Modified HWP file                       |
| `POST /api/v1/edit`                     | Edit paragraph by index            | Modified HWP file                       |
| `POST /api/v1/compare`                  | Diff two documents                 | `{ diffs[{ type, content }] }`         |
| `POST /api/v1/render`                   | Render SVG preview                 | `{ pages[{ svg }] }`                    |
| `POST /api/v1/create/hwp`               | Create new HWP                     | New HWP file                            |
| `POST /api/v1/search`                   | Search text/regex                  | `{ results[{ index, text }] }`        |
| `POST /api/v1/convert/hwpx`            | Convert to HWPX                   | HWPX file                               |
| `POST /api/v1/replace`                  | Find & replace text                | Modified HWP file                       |
| `POST /api/v1/mailmerge`                | Mail merge                        | ZIP of HWP files                        |

## MCP Server

Connect AI assistants (ChatGPT, Claude, Cursor) to the `/mcp` endpoint using Streamable HTTP transport.

### Available Tools (14 total)

**File-path tools** (for local MCP clients):  
`extract_text`, `extract_tables`, `get_metadata`, `analyze_structure`, `search_in_document`, `compare_documents`, `create_hwp`, `fill_sections`, `edit_paragraph`, `convert_to_hwpx`, `render_preview`

**Base64 tools** (for ChatGPT Apps / remote clients):  
`extract_text_apps`, `extract_tables_apps`, `analyze_structure_apps`, `search_in_document_apps`, `compare_documents_apps`, `fill_sections_apps`, `edit_paragraph_apps`

## Usage Examples

### REST API

```
# Extract text
curl -X POST "https://lurid-alley--hwp-works.apify.actor/api/v1/extract/text?token=YOUR_TOKEN" \
  -F "file=@document.hwp"

# Analyze document structure
curl -X POST "https://lurid-alley--hwp-works.apify.actor/api/v1/analyze?token=YOUR_TOKEN" \
  -F "file=@document.hwp"

# Fill template placeholders
curl -X POST "https://lurid-alley--hwp-works.apify.actor/api/v1/fill?token=YOUR_TOKEN" \
  -F "file=@template.hwp" \
  -F 'data={"placeholders":{"name":"홍길동","date":"2026-02-13"}}'
```

### MCP (AI Assistant)

Connect your AI assistant to:

```
https://lurid-alley--hwp-works.apify.actor/mcp?token=YOUR_TOKEN
```

## Input Configuration

| Parameter            | Type    | Default | Description                                   |
|---------------------|---------|---------|-----------------------------------------------|
| `sessionRateLimit`  | integer | 50      | Max MCP tool calls per session (0 = unlimited) |

## Rate Limits

- **MCP sessions**: 50 calls per session (configurable via input)
- **REST API (Free)**: 5 calls/day per API key
- **REST API (Pro)**: Unlimited

## Supported Formats

| Format             | Read | Write | Render |
|-------------------|------|-------|--------|
| HWP (.hwp)        | ✅    | ✅     | ✅ (SVG) |
| HWPX (.hwpx)      | 🔜    | 🔜     | 🔜      |

## Tech Stack

- **Language**: Rust
- **HTTP Framework**: Axum
- **MCP Protocol**: rmcp (official Rust SDK)
- **Document Engine**: hwpers
- **Database**: SQLite (usage tracking)