HeroLink — RPG Maker MV/MZ Content Bridge

A local, file-based bridge that lets an AI client read, draft, validate, and safely write content into an RPG Maker MV or MZ project. Supports both engines (auto-detected via Game.rpgproject or Game.mzproject).

Quick Start

1. Electron Desktop App (recommended)

npm install
npm run electron

Set your project folder in Project Settings, start the server, and use an AI client to draft content. Review and apply changes from the Pending Changes view.

2. CLI

# Project info
npx tsx src/cli.ts status path/to/project
npx tsx src/cli.ts list path/to/project Item

# Validate
npx tsx src/cli.ts validate path/to/project

# Draft + apply
npx tsx src/cli.ts pending path/to/project
npx tsx src/cli.ts diff path/to/project
npx tsx src/cli.ts apply path/to/project
npx tsx src/cli.ts rollback path/to/project

3. MCP Server (for AI clients)

RPGMV_PROJECT_DIR=path/to/project npx tsx src/index.ts

Exposes all 27+ tools for reading, drafting, validating, and applying changes.

4. HTTP API

# Start server
RPGMV_PROJECT_DIR=path/to/project npx tsx src/http/server.ts

# List tools
curl http://localhost:8866/tools

# Call a tool
curl -X POST http://localhost:8866/api/tools/get_project_status \
  -H 'Content-Type: application/json' -d '{}'

# Draft an item
curl -X POST http://localhost:8866/api/tools/create_item_draft \
  -H 'Content-Type: application/json' \
  -d '{"fields": {"name": "Hi-Potion", "itypeId": 1}}'

# Apply changes
curl -X POST http://localhost:8866/api/tools/apply_patch \
  -H 'Content-Type: application/json' -d '{"confirm": true}'

Features

• Read & Summarize — browse project database, maps, events, plugins, notes
• Audit & Validate — reference-integrity checking with error/warn severity
• Safe Mutation — propose → validate → diff → apply → rollback pipeline; atomic writes, backups, staleness detection
• Event Authoring — constrained event-command builder for common events and map events
• Plugin Management — add plugins, set parameters
• In-Engine Integration — runtime inspection via BridgeInspector.js plugin (optional, see below)
• Electron Desktop App — 5-view control panel: Dashboard, Project Settings, Pending Changes, Documentation, Logs
• Cross-Engine — full support for both MV and MZ

In-Engine Integration (BridgeInspector)

HeroLink includes an optional RPG Maker MV plugin called BridgeInspector.js (src/plugin/BridgeInspector.js). When installed in your project and loaded in-game, it enables two extra tools:

• inspect_runtime — reads live game state (current map, party, switches, variables) while the game is running
• preview_entity — triggers in-game previews of database entities

To use it:

1. Copy src/plugin/BridgeInspector.js from this repo into your project's js/plugins/ folder
2. Add BridgeInspector to your project's plugin list in RPG Maker MV
3. Start the game — BridgeInspector will report status back to HeroLink

This plugin is not required for any other functionality. All read, draft, validate, and apply tools work without it. The plugin only affects the inspect_runtime and preview_entity tools.

The Draft & Apply Workflow

Every change follows: propose (AI client creates a draft) → review (view pending changes with diffs) → apply (backup + validate + atomic write) → rollback (restore from backup if needed).

Key safety guarantees:

• No draft modifies files on disk until you explicitly apply
• Every apply creates a full backup and transaction journal
• Atomic writes (temp + rename) prevent corrupt files on crash
• Staleness detection refuses to apply if files changed on disk
• Rollback restores files byte-for-identical to pre-apply state

Development

npm install
npm run check            # lint + typecheck + tests + coverage
npm run test             # tests only
npm run http             # start HTTP server only
npm run electron         # start Electron desktop app

Project Structure

electron/                # Desktop app (main.cjs, preload, renderer SPA)
src/
  cli.ts                 # CLI entrypoint
  index.ts               # MCP server entrypoint
  http/server.ts         # HTTP API server
  io/                    # Project I/O + normalized model
  schema/                # Zod schemas for entities + event commands
  validate/              # Reference-integrity validation
  mutate/                # Staging, apply, rollback, backup, journal
  tools/                 # Tool handlers (one per file)
  engine/                # MV/MZ engine adapter
  plugin/                # BridgeInspector runtime plugin
test/                    # Vitest unit + integration tests

Version Roadmap

Version	Capability	Status
v1	Read & Summarize	Complete
v2	Audit & Validate	Complete
v3	Safe Database Mutation	Complete
v4	Events, Maps & Plugins	Complete
v5	In-Engine Integration	Complete
v6	Full Surface (HTTP API, MZ adapter, Advanced Events, Electron)	Complete
v7	Review & Polish	Complete