v0.2.0

Highlights

• Compact region reads: tiled_get_region accepts format: "gids" on TMJ maps — raw encoded GID rows plus a firstgid legend (external entries carry assetId and source, embedded entries sourceIndex), ~35x smaller than the resolved-cell shape, with every GID still decoded and validated. Advertised via tileDataReadCapabilities.regionReadFormats.
• PLAN_NO_CHANGES: automap and terrain-paint plans that net out to zero changes fail with a dedicated error code instead of INVALID_ARGUMENT, making idempotency/parity checks branchable on the code. Advertised as automapCapabilities.emptyPlanErrorCode.
• Tiled 1.12.2 CLI hardening: subprocess locale pins are C.UTF-8 (1.12.2's Qt warns on stderr under non-UTF-8 locales) and the --export-formats parser only accepts indented format lines, so stderr noise can no longer contaminate the reported export formats.

Verified with pnpm verify and the hard verify:tiled-1.12.2 gate against real Tiled 1.12.2 + TmxRasterizer: 1587/1587 tests.

v0.0.2 — zero-config sandbox via MCP roots

No more --project-dir. The server now resolves its sandbox from the connected client's MCP roots, so Claude Code setup is just:

claude mcp add tiled -- npx -y tiled-mcp-server

Open Claude Code inside your Tiled project and the server sandboxes itself to that folder automatically.

Resolution order: --project-dir → TILED_PROJECT_DIR → the client's first file:// root. If none yields a directory, startup fails closed — the server never guesses. Clients without a working-directory concept (Claude Desktop and other JSON-config hosts) keep passing --project-dir explicitly.

Under the hood, a gated transport answers the MCP handshake before the sandbox exists, buffers all other traffic while the client's roots are fetched and the tools wire up, then replays it — so an early tools/list always sees the full 50-tool surface. The root is fixed for the session; later roots/list_changed notifications do not move it.

Upgrade: nothing to do — npx -y tiled-mcp-server picks up 0.0.2 automatically. Existing --project-dir configurations behave exactly as before.

v0.0.1 — first npm release

TiledMCP is now on npm as tiled-mcp-server. No clone, no build:

claude mcp add tiled -- npx -y tiled-mcp-server --project-dir /absolute/path/to/your/tiled-project

Or for Claude Desktop / any JSON-config MCP client:

{
  "mcpServers": {
    "tiled": {
      "command": "npx",
      "args": ["-y", "tiled-mcp-server", "--project-dir", "/absolute/path/to/your/tiled-project"]
    }
  }
}

Requires Node.js 20.19+. Tiled itself is not required — 50 tools run on the built-in JSON/PNG path; installing Tiled adds tiled_render_map and tiled_preview_export.

What's in 0.0.1

• 52 tools covering read, edit, procedural generation, native PNG rendering (all four projections), byte-exact TMX/TSX/TX writing, checkpoints, and cross-file transactions
• Every write goes preview → human approval → apply under a revision guard; undefined Tiled semantics fail closed instead of being approximated
• Four MCP prompts carry whole workflows (create_map_from_tilesheet, build_from_floor_plan, set_up_tile_roles, review_map)
• A sectioned guide resource (tiled://guide/{section}), a 106-code stable error registry, and cursor pagination across the listing tools
• 1,524 tests; the machine contract in contracts/mcp-contract.v1.json is generated from real discovery and drift-gated in CI

The interface is a draft and not yet frozen.