Skip to main content
Glama
README.md
# wdmcp

Python stdio MCP server for reading and writing Wonderdraft 1.1.8 `.wonderdraft_map` files.

## Install

```powershell
py -3.12 -m venv .venv          # Python >= 3.12
.venv\Scripts\pip install -e .[dev]
.venv\Scripts\python -m pytest  # unit tests, no Wonderdraft GUI needed
```

## Register with Claude Code

```powershell
claude mcp add wonderdraft -- C:\path\to\Wonderdraft-MCP\.venv\Scripts\wdmcp.exe
```

The server speaks MCP over stdio (logs go to stderr). `python tools/mcp_smoke.py` launches it
and drives a short tool flow as a self-check.

### Environment variables

| Variable | Default | Meaning |
| --- | --- | --- |
| `WDMCP_PCK` | `C:\Program Files\Wonderdraft\Wonderdraft.pck` | Wonderdraft's resource pack (built-in symbols, themes, names) |
| `WDMCP_USER_DIR` | `%APPDATA%\Wonderdraft\assets` | User asset packs |

## Tools

All coordinates are map pixels with the origin at the top left. Mutating tools return
`{"ids": [...], "summary": "..."}`. Symbol ids (`symbol:<n>`) are positional and shift when
symbols are inserted or removed; use the ids a tool returns, or `list_objects`.

- Map: `new_map`, `open_map` (read-only), `save_map` (timestamped `.bak` when overwriting),
  `map_summary`, `undo` (20 steps)
- Discovery: `list_themes`, `list_asset_sets`, `list_objects`
- Terrain: `paint_land`, `generate_landmass`, `raise_area`, `add_lake`, `add_river`, `paint_ground`
- Placement: `add_symbol`, `scatter_symbols`, `add_mountain_range`, `add_forest`,
  `add_settlement`, `add_label`, `add_path`, `add_territory`
- Editing: `update_object`, `move_objects`, `remove_objects`, `apply_theme`, `set_frame`
- Output: `render_preview` returns a PNG image and saves it (`<map>.preview.png` next to a saved
  map, otherwise in a temp dir); `export_image` writes a PNG/JPG file (see Export)

Points are `[[x, y], ...]`; colours are `[r, g, b]` / `[r, g, b, a]` floats 0-1 or `"#rrggbb"`.

## Export

`export_image(path, format="png"|"jpg", via="wonderdraft"|"preview")` never overwrites an
existing file.

- `via="wonderdraft"` (default) drives the real Wonderdraft app (Windows only) for a
  pixel-exact export: it launches Wonderdraft with the saved map, sends Ctrl+E and Enter, fills
  in the save dialog, then closes Wonderdraft. It takes about 15-20 seconds. **Do not type while it
  runs**: it sends Ctrl+E/Enter to the foreground window. Wonderdraft must not already be
  running, and the map must be saved with no unsaved edits (call `save_map` first). JPG is a PNG
  export converted with Pillow (quality 92). If automation is unavailable or fails, the tool
  returns instructions (open the map, press Ctrl+E). Set `WDMCP_EXE` if Wonderdraft is not at
  `C:\Program Files\Wonderdraft\Wonderdraft.exe`.
- `via="preview"` writes a full-scale render from this server's own renderer; it works anywhere
  and needs no saved map.

TDQS

B3.4/5.0

Scored across 32 tools

Disambiguation4/5

Most tools map to a distinct Wonderdraft primitive (paint_land, add_river, add_label, add_path), and descriptions clearly separate the terrain tools (paint_land vs generate_landmass vs raise_area) and the placement tools (add_symbol vs scatter_symbols vs add_forest). The main overlaps are render_preview vs export_image (whose "preview" mode duplicates it) and map_summary vs list_objects, plus the niche recolor_symbols repair tool, but none are likely to cause a serious misselection.

Naming Consistency4/5

Overwhelmingly consistent snake_case verb_noun pattern (open_map, add_lake, move_objects, remove_objects, list_themes, set_frame). Minor deviations: new_map is adjective_noun rather than verb_noun, and map_summary, region_spec_schema and undo are bare nouns/verbs, but the conventions remain readable and predictable.

Tool Count3/5

32 tools is heavy for an agent to navigate and sits above the comfortable range, partly inflated by meta-tools like region_spec_schema and recolor_symbols. Still, the breadth roughly tracks a genuinely rich domain (terrain, water, symbols, paths, territories, labels, themes, frames, export), so most tools earn their place.

Completeness4/5

Lifecycle coverage is strong: open/new/save/export, summary, terrain and water generation, all major object types with add/update/move/remove, theming, framing, undo, and even a one-shot build_region convenience. Minor gaps: no redo, no object duplication/copy, no get-by-id lookup beyond list_objects, and undo is capped at 20 steps.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues