v1.3.0 — The placeable library, token-instance editing & the identity-mask read

Everything since v1.2.5, headlined by the completed placeable tool library (130 tools total).

Placeables — the library is complete

• Full CRUD for AmbientSound / Drawing / Wall / Tile / AmbientLight, plus place-tokens / delete-tokens (14 new tools).
• Region and Note tools retrofitted onto the same shared placeable kernel (same tool names, unified item/patch/id bridge shapes).
• Only MeasuredTemplate remains, deferred to Phase 2 (combat).

Token editing

• update-token — edit a placed token instance: per-token HP, nameplate/bar/ring visibility, rotation, scale.
• Token-instance targeting — pass a placed token id as actorIdentifier and every fuzzy actor tool (update-actor/-item, add-item/-feature, manage-activity/-effect, apply-condition, get-actor, …) edits that token'''s own delta; siblings and the base actor stay untouched.
• update-actor — tokenName (prototype nameplate decoupled from the actor name), tokenScale, tokenRotation, tokenAutoRotate, tokenRing.
• set-actor-art — tokenImagePath for animated video (webm) tokens, and a fix for the silent no-op when a video path landed on the image-only actor portrait.
• House token rules baked into every creation path (disposition at create time, auto-rotate on, ring off, randomImg off) + table-ready prototype-token defaults.

Items & content

• trueName — item reads see through the dnd5e identity mask on unidentified items, so GM renames land instead of echoing as silent no-ops.
• update-rolltable editResults — surgical per-entry edits, no more whole-set replace; get-rolltable deterministic entry reader.
• list-folders — the folder-tree read the folder write tools were missing; update-folder; journal page-visibility; create-scene folder/nav/thumbnail.
• Region + teleporter authoring on existing scenes; content-audit now enforces rule 12 (no GM spoilers in player-visible item descriptions).

Skills

• token-cutout — background→alpha token prep (rembg AI matte with an offline chroma-key fallback, magenta-preview verification, optional in-world upload + assignment).

Fixes

• Teleporter destinations as Sets + remap no-op handling; update-scene parity.
• WebDAV MOVE/COPY now creates destination parents.
• create-pc no longer crashes on a folder-name folder arg.
• Every bridge script passes FOUNDRY_PASSWORD.

130 tools · 1216 unit tests green · live-verified against the running world (43/43 placeables, 21/21 token-instance, 17/17 trueName, 10/10 video token art, 9/9 tokenName).

Full changelog: v1.2.5...v1.3.0

v1.2.2 — Asset-path validation: no more broken icons, portraits & backgrounds

Hardening release — closes a rule-8 gap across the whole authoring surface.

The bug

A caller-supplied asset path (an item icon, an actor portrait/token, a scene background, an audio track, a journal image, a card face, a user avatar) was written to the Foundry document verbatim, with no check that it actually resolves. A guessed or typo'd path shipped as a broken 404 — isPlaceholderIcon only caught blank / icons/svg/ placeholders, never a non-blank path that 404s. Only add-item was guarded; every other asset-write site was not.

The fix

New shared guard — src/page/img-resolve.ts:

• imgResolves(path) — HEAD-checks the path on the Foundry static server (trusts remote http/data URLs; fails open on a network error so a transient hiccup never strips a good path).
• badAssetWarning(...) — one consistent warning string everywhere.
• GENERIC_ICON for the no-kind-context substitution sites.

Applied at every caller-supplied asset write (13 sites, was 1):

• Substitute a real icon + warn (icon/portrait/token): add-item, create-item/update-item, update-actor-item, set-actor-art (portrait + token), update-actor, set-user-avatar.
• Drop to Foundry's default pin + warn: create-scene-notes / update-note icons.
• Keep path + warn loudly (content-defining, no sensible substitute): create-scene/update-scene background + thumb, create-playlist tracks, create-journal image pages, add-journal-image, create-cards faces.

Each page handler returns its warnings; each tool wrapper surfaces them. Non-blocking throughout (soft-validation: warn, never block). Valid inputs write byte-identically — the new check only fires on a 404.

Confirmed no-ops: update-playlist writes no asset path; create-quest-journal has no image src; author-npc / create-actor-from-compendium already auto-resolve real art.

Gate

biome + typecheck + 992 unit tests (+11) + knip + build all green. Live integration (RELEASE.md steps 2–3) not run this cycle — valid-input live-write behavior is unchanged; the new validation only affects 404 inputs the integration suite does not exercise.

v1.2.1 — Doc reconcile, add-feature dedup & effect-change tests

Maintenance patch — no runtime behavior change. Live write-path payloads are byte-identical and all existing tests pass unchanged.

Docs

• README: tool count 85 → 95 (+ corrected Plane-A/Plane-B split), added the missing upload-asset-tree row, and rewrote the Contributing recipe to the real registry.ts handlers-map + generated zod → JSON-Schema mechanism (the old allTools/switch(dispatch) path it described was removed long ago).
• design.md §9: added the shipped tom-cartos-import skill (11 → 12).
• architecture-review.md: marked as a superseded 2026-06-24 snapshot so its already-closed findings aren't read as open.

Refactor

• add-feature: single-sourced every enum value set and the shared field fragments (featureHeaderFields / attackCoreFields / sourceMetaFields / refineRangedAttack) between the umbrella and per-mode schemas, and extracted the damageList / warningBlock formatter boilerplate. Closes the file's own documented drift CAVEAT. 37 existing tests pass.

Tests

• effects: extracted the pure, Foundry-v14-coupled change mapping (normalizeChange / summarizeChanges) into src/page/effect-changes.ts with 10 new unit tests, mirroring the activities.ts ↔ manage-activity.ts split — a Foundry mode-renumber now fails offline instead of silently mis-authoring effects live.

Gate

biome · typecheck · 980 unit tests · knip · build — all green.

⚠️ Live integration + MCP smoke (RELEASE.md steps 2–3) were not run this cycle, as no live-write behavior changed.

Full diff: v1.2.0...v1.2.1

v1.2.0 — Complete-NPC builder: inventory, loot & currency

No Foundry module required — standalone headless MCP server for D&D 5e on Foundry VTT.

This release closes the inventory/loot gap so an NPC can be authored completely — stats, traits, actions, spells, effects, and its gear/loot/coins.

Highlights

• add-item (new tool, #75) — a structured physical-item builder, the inventory counterpart to add-feature. One tool discriminated by itemType: weapon · armor · shield · wondrous · consumable · tool · loot · container, with named params + soft-validation for the fields a GM expects (price, weight, quantity, rarity, attunement + attuned, equipped, identified, the magical +N bonus, properties). Targets an actor's inventory or the world Items sidebar, nests items in a container, and a weapon's attack routes through the same shared activity builder. Build a +1 flame-tongue longsword the creature actually fights with in one call.
• update-actor currency — set or adjust an NPC's coins (pp/gp/ep/sp/cp); previously there was no way to give a creature money at all.
• physical-item-builder skill — judgment layer over add-item (item-type choice, rarity↔price sanity, the magic-item rule, attunement defaults, container nesting). Reusable for treasure hoards.
• stat-block-builder rewritten into the full 11-step NPC pipeline: stats → traits (prefer compendium import) → actions (the wielded weapon as a real item) → spells → effects → inventory/loot/coins → biography → art/ownership/folder finish → read-back.

Quality

• 75 tools; 615 tests + build · biome · typecheck · knip green.
• Live-verified 11/11 against a real Molten world; a 15-finding adversarial review (0 false positives) all addressed, including a HIGH fix where wireAc on a shield could clobber an authored natural-armor AC.

Install (source)

Download the zip → npm install → npx playwright install chromium → npm run build → wire dist/index.js as your MCP server. See the README and .env.example / .mcp.json.example.

v1.1.0

No Foundry module required — standalone headless MCP server (Playwright headless Chromium).

Actor tooling — full D&D 5e creature authoring & editing (69 → 74 tools)

New tools:

• update-actor — edit an existing actor's whole stat block: abilities, saving throws, skills, HP/AC/initiative, movement, senses, defenses (damage/condition immunities & resistances with replace/add/remove), languages + telepathy, NPC resources (legendary actions/resistances, lair), and 2024 habitat/treasure.
• apply-condition — apply or remove conditions, including leveled exhaustion.
• update-actor-item — dot-path patch + deletePaths on an item embedded on an actor.
• manage-activity — add / edit / remove / list activities (attack, damage, save, heal, check, utility) on world or embedded items (authors a Multiattack, a heal, a save ability, etc.).
• manage-effect — create / edit / delete / list ActiveEffects on an actor or item (e.g. +1 AC, resist fire).

Also in this release:

• add-feature gains a homebrew-spell mode (author a spell from scratch with method/components/optional activity) plus feat widening (featType / requirements).
• get-actor now reports real ability & skill modifiers, AC, legendary actions, and XP (it previously showed zeros — a derived-field read fix), and surfaces spell casting method.
• New stat-block-builder skill that composes the above into a full creature build.

Quality: 578 unit tests; live-verified end-to-end (28/28) against Foundry 14.364 / dnd5e 5.3.3; the existing attack/save builders were routed through one shared activity builder with a byte-equivalence test (no behavioral drift); a multi-agent adversarial review found and fixed two edge-case bugs before release.

Install (source)

Download the zip → npm install → npx playwright install chromium → npm run build → wire dist/index.js as your MCP server. See the README for .env / .mcp.json setup.

v1.0.1

Maintenance release addressing a multi-dimension code review: robustness fixes, offline test coverage for the page-side layer, and internal cleanup. No new tools (still 62) and no breaking changes.

Robustness

• WebDAV requests now time out (AbortSignal) so a half-awake Molten box can't hang a tool indefinitely.
• The headless bridge self-heals a wiped window.__fvtt after an in-world reload (re-inject or reconnect + retry) instead of wedging until a process restart.
• bulk-delete records per-item failures and keeps going — no lost partial progress on a permanent op.
• Central error mapping for every tool (cold-box / permission / not-found guidance), with curated messages passed through unchanged and zod/specific messages preserved.
• Added process-level unhandledRejection / uncaughtException handlers.

Testing

• Extracted the deterministic page-side logic (SRD spell-slot tables, NPC system-data construction, attack assembly) into pure helpers and unit-tested them offline. 423 → 464 tests.
• Added tests for the previously-untested error classifier.

Cleanup & tooling

• Tool wiring extracted to a single src/registry.ts: the handlers map is the source of truth and the advertised tool list is derived from it (no more drift between a registration list and a 180-line dispatch switch).
• Removed a dead event-push subsystem; removed dead exports; wired knip into CI.
• Node floor set to 22+; CI now tests Node 22 + 24.

Security

• The Magic-URL startup token is redacted from logs.
• copy-asset now guards the source path as well as the destination.

Full changelog: v1.0.0...v1.0.1

v1.0.0

fvtt-mcp-molten5e 1.0.0 — a D&D 5e–only, Molten Hosting–optimized MCP server for Foundry VTT, driven by Claude Code.

No Foundry module required. This is now a standalone MCP server that runs on your PC. It drives a headless Chromium Foundry client (via Playwright) — it authenticates and joins your live world exactly as a normal user would. There is nothing to install inside Foundry. (The old module-based releases are gone.)

What it does

Lets an AI GM assistant read and edit a live Foundry world (actors, items, journals, scenes, compendia, roll tables, cards, ownership) and manage a Molten-hosted server's static files.

• Plane A — live bridge (53 tools): world introspection + editing over the headless Foundry client.
• Plane B — Molten WebDAV (9 tools): asset file library (upload/list/move/delete, reference-aware).
• 62 tools total.

Install

1. Download and unzip the source asset below (or clone the repo).
2. npm install
3. npx playwright install chromium
4. npm run build
5. Wire dist/index.js into Claude Code (see .mcp.json.example) and configure .env (see .env.example).

Full setup, configuration, and the tool reference are in the README.

Requirements

Node.js 20+, a Playwright Chromium, and Foundry VTT 14.x with the D&D 5e system on Molten (plus a dedicated passwordless Foundry user for the MCP to join as).