# RPG Maker MCP

RPG Maker MCP is an MVP toolkit for RPG Maker MZ. It builds a high-level
`EventSpec` from a `.scene` tag DSL file and applies the generated managed event
to an RPG Maker MZ `data/MapXXX.json` file.

RPG Maker MZ向けの `.scene` タグDSLから高レベル `EventSpec` を生成し、MZ
`data/MapXXX.json` に管理イベントを反映するMVP実装です。

The MCP server does not read story text bodies or image contents. `.scene`
parsing/building is handled by the Builder CLI/API, while the MCP stdio server
only handles `EventSpec` objects and ID manifests under `mcp/*-manifest.json`.

MCPサーバは本文や画像実体を読みません。`.scene` のparse/buildはBuilder側のCLI/APIで行い、MCP
stdioサーバは `EventSpec` と `mcp/*-manifest.json` のID台帳だけを扱います。

## Concept: Writer AI and Content-Blind MCP

This project assumes that the scenario has already been written in `.scene`
format by either a Writer AI or a human author. That `.scene` file may contain
adult scenario text, dialogue, staging notes, and other sensitive creative
content.

The Writer AI is the creative authoring side of the workflow. It may generate
or edit `.scene` files from prompts, and it may work with adult scenario content
when the user intentionally uses it for writing. The Writer AI is not
content-blind.

This MCP is the structural application side of the workflow. It is designed so
that a separate AI worker can apply, validate, diff, back up, restore, and
inspect RPG Maker MZ events without reading adult scenario text or image
contents.

Recommended separation:

```text
Writer AI or human author
  -> writes adult or sensitive scenario as .scene
  -> local Builder converts .scene to EventSpec / manifests
  -> content-blind MCP worker applies EventSpec to RPG Maker MZ JSON
```

It is possible to ask a Writer AI to create `.scene` files from prompts, or to
describe `.scene`-equivalent event structure in a prompt. However, once the work
moves to this MCP worker, pass redacted `EventSpec`, IDs, and manifests instead
of raw scenario text.

## コンセプト: Writer AI と内容非参照 MCP

このプロジェクトは、Writer AI または人間の作者が、成人向けシナリオを含み得る内容を
すでに `.scene` 形式で記述している、という前提のツールです。`.scene` ファイルには、
成人向け本文、会話、演出メモ、その他の秘匿したい創作内容が含まれる可能性があります。

Writer AI は創作・執筆側の役割です。ユーザーが意図して執筆用途に使う場合、Writer AI は
プロンプトから `.scene` を生成・編集でき、成人向けシナリオ本文を扱うことがあります。
つまり Writer AI は内容非参照ではありません。

この MCP は構造適用側の役割です。別の作業AIが成人向け本文や画像内容を読まずに、
RPGツクールMZ のイベントを適用・検証・差分確認・バックアップ・復元・調査できるように
設計されています。

推奨する分担:

```text
Writer AI または人間の作者
  -> 成人向けまたは秘匿シナリオを .scene として記述
  -> ローカル Builder が .scene を EventSpec / manifest に変換
  -> 内容非参照 MCP worker が EventSpec を RPGツクールMZ JSON に適用
```

Writer AI にプロンプト経由で `.scene` を作らせることや、`.scene` 相当のイベント構造を
プロンプトで記述することは可能です。ただし、この MCP worker に作業を渡す段階では、
raw scenario text ではなく、redacted `EventSpec`、ID、manifest を渡してください。

## Files

```text
src/sceneParser.js      .scene tag DSL parser
src/builder.js          .scene -> EventSpec builder
src/validator.js        EventSpec / manifest validator
src/mzCommands.js       EventSpec -> RPG Maker MZ event commands
src/mapStore.js         data/MapXXX.json read/write helpers
src/project.js          apply, backup, restore, dry-run, diff
src/mcp-server.js       MCP stdio server
src/cli.js              local CLI
schemas/                JSON Schema
fixtures/               sample .scene and RPG Maker MZ project data
tests/                  node:test coverage
```

## Usage - English

### Requirements

- Node.js 18 or later
- An RPG Maker MZ project directory with `data/MapXXX.json`

This package has no runtime npm dependencies. Run commands from this repository
root, or use the installed bin names if you install/link the package.

### Quick start with the sample project

```sh
npm test
node src/cli.js build-scene fixtures/story/ch03/S03_014.scene --project fixtures/project
node src/cli.js dry-run fixtures/story/ch03/S03_014.scene --project fixtures/project
node src/cli.js apply-scene fixtures/story/ch03/S03_014.scene --project fixtures/project
```

### Initialize an RPG Maker project for MCP

Create the default manifest files under `<project>/mcp/`:

```sh
node src/cli.js init --project /path/to/rpg-maker-project
```

The generated files are:

```text
mcp/text-manifest.json
mcp/image-manifest.json
mcp/anchor-manifest.json
mcp/project-manifest.json
```

### Build and validate a scene

Convert a `.scene` file into an `EventSpec`:

```sh
node src/cli.js build-scene story/ch03/S03_014.scene --project /path/to/project --out /tmp/S03_014.event.json
```

Validate an existing `EventSpec` JSON file against schemas and project manifests:

```sh
node src/cli.js validate-event /tmp/S03_014.event.json --project /path/to/project
```

Use `--update-manifest` with `build-scene` when you want generated text IDs from
the scene to be merged into `mcp/text-manifest.json`:

```sh
node src/cli.js build-scene story/ch03/S03_014.scene --project /path/to/project --update-manifest
```

### Preview, diff, and apply

Preview changes without writing to the RPG Maker project:

```sh
node src/cli.js dry-run story/ch03/S03_014.scene --project /path/to/project
```

Show a compact diff summary for the managed event:

```sh
node src/cli.js diff story/ch03/S03_014.scene --project /path/to/project
```

Apply the scene to the target map JSON:

```sh
node src/cli.js apply-scene story/ch03/S03_014.scene --project /path/to/project
```

If an existing managed event has a different stored hash, the update is rejected
by default. Use `--force` only when you intentionally want to overwrite it:

```sh
node src/cli.js apply-scene story/ch03/S03_014.scene --project /path/to/project --force
```

### Inspect project data

```sh
node src/cli.js list-maps --project /path/to/project
node src/cli.js read-map --project /path/to/project --map 12
node src/cli.js list-events --project /path/to/project --map 12
node src/cli.js list-anchors --project /path/to/project --map 12
node src/cli.js resolve-anchor bed_side --project /path/to/project --map 12
```

### Back up and restore

Create a backup for one map file:

```sh
node src/cli.js backup-project --project /path/to/project --map 12
```

Restore a backup created by `backup-project` or `apply-scene`:

```sh
node src/cli.js restore-backup <backupId> --project /path/to/project
```

`save-project` is a no-op acknowledgement because file writes are flushed
immediately:

```sh
node src/cli.js save-project
```

### Run the MCP stdio server

```sh
node src/mcp-server.js
```

If the package is installed or linked, these bin names are also available:

```sh
rpgmaker-mcp help
rpgmaker-mcp-server
```

The MCP server exposes tools for applying, diffing, validating, reading maps,
listing events/anchors, backing up, and restoring. It expects already-built
`EventSpec` input; build `.scene` files with the CLI/API first.

### Configure static AI worker instructions

The content-blind rule should be saved as static project instructions whenever
your AI client supports it. Do not rely on pasting the same system prompt at the
start of every session.

Use the instruction mechanism supported by your client, for example:

```text
AGENTS.md                  Codex-style repository instructions
CLAUDE.md                  Claude Code-style repository instructions
.cursor/rules/*.mdc        Cursor project rules
Project instructions       Hosted or desktop AI client settings
```

Recommended static instruction:

```text
This repository is a content-blind RPG Maker MZ MCP tool.

Do not read, summarize, infer, rewrite, translate, classify, or quote adult
story text, dialogue bodies, image contents, CG descriptions, or other sensitive
creative content.

You may only work with EventSpec JSON, mcp/*-manifest.json files, RPG Maker MZ
data/*.json structure, IDs, validation results, diffs, backups, and tool outputs
that do not expose story text or image contents.

Do not open .scene files unless the user explicitly confirms that the file is
safe and non-sensitive. Prefer redacted EventSpec input over raw scene content.

Use dry-run before applying changes. Report IDs and structural changes, not
story content.
```

After saving the static instructions, normal user prompts can stay short, such
as:

```text
Apply this already-built EventSpec to the project. Run dry-run first, then apply
if validation passes. Report the map ID, event name, backup ID, and validation
result.
```

### Minimal `.scene` example

```text
@scene S03_014
@title Inn Night
@map 12
@anchor bed_side
@trigger autorun
@actors hero heroine

@say heroine
"Welcome back."

@choice
- "Rest" -> rest
- "Leave" -> leave

@label rest
@switch 42 true
@jump end

@label leave
@call_common_event CE_LEAVE_INN
@jump end

@label end
@end
```

## 使用方法 - 日本語

### 必要なもの

- Node.js 18 以上
- `data/MapXXX.json` を含む RPGツクールMZ プロジェクト

このパッケージには実行時 npm 依存はありません。コマンドはこのリポジトリのルートで実行してください。
インストールまたはリンク済みの場合は bin 名も使えます。

### サンプルプロジェクトで試す

```sh
npm test
node src/cli.js build-scene fixtures/story/ch03/S03_014.scene --project fixtures/project
node src/cli.js dry-run fixtures/story/ch03/S03_014.scene --project fixtures/project
node src/cli.js apply-scene fixtures/story/ch03/S03_014.scene --project fixtures/project
```

### RPGツクールプロジェクトを初期化する

`<project>/mcp/` に既定の manifest ファイルを作成します。

```sh
node src/cli.js init --project /path/to/rpg-maker-project
```

作成されるファイルは以下です。

```text
mcp/text-manifest.json
mcp/image-manifest.json
mcp/anchor-manifest.json
mcp/project-manifest.json
```

### シーンをビルド・検証する

`.scene` ファイルを `EventSpec` に変換します。

```sh
node src/cli.js build-scene story/ch03/S03_014.scene --project /path/to/project --out /tmp/S03_014.event.json
```

既存の `EventSpec` JSON をスキーマとプロジェクト manifest に対して検証します。

```sh
node src/cli.js validate-event /tmp/S03_014.event.json --project /path/to/project
```

シーンから生成されたテキストIDを `mcp/text-manifest.json` に反映したい場合は、
`build-scene` に `--update-manifest` を付けます。

```sh
node src/cli.js build-scene story/ch03/S03_014.scene --project /path/to/project --update-manifest
```

### プレビュー・差分確認・適用

RPGツクールプロジェクトに書き込まずに適用結果を確認します。

```sh
node src/cli.js dry-run story/ch03/S03_014.scene --project /path/to/project
```

管理イベントの差分サマリを表示します。

```sh
node src/cli.js diff story/ch03/S03_014.scene --project /path/to/project
```

シーンを対象マップJSONへ適用します。

```sh
node src/cli.js apply-scene story/ch03/S03_014.scene --project /path/to/project
```

既存の管理イベントに保存された hash と入力の hash が異なる場合、通常は更新が拒否されます。
意図して上書きする場合だけ `--force` を使ってください。

```sh
node src/cli.js apply-scene story/ch03/S03_014.scene --project /path/to/project --force
```

### プロジェクト情報を確認する

```sh
node src/cli.js list-maps --project /path/to/project
node src/cli.js read-map --project /path/to/project --map 12
node src/cli.js list-events --project /path/to/project --map 12
node src/cli.js list-anchors --project /path/to/project --map 12
node src/cli.js resolve-anchor bed_side --project /path/to/project --map 12
```

### バックアップ・復元

マップファイル単位でバックアップを作成します。

```sh
node src/cli.js backup-project --project /path/to/project --map 12
```

`backup-project` または `apply-scene` が作成したバックアップを復元します。

```sh
node src/cli.js restore-backup <backupId> --project /path/to/project
```

`save-project` は、書き込みが即時反映されるため no-op の確認応答です。

```sh
node src/cli.js save-project
```

### MCP stdio サーバを起動する

```sh
node src/mcp-server.js
```

パッケージをインストールまたはリンクしている場合は、以下の bin 名も使えます。

```sh
rpgmaker-mcp help
rpgmaker-mcp-server
```

MCPサーバは、適用・差分・検証・マップ読み取り・イベント/アンカー一覧・バックアップ・復元のツールを提供します。
入力にはビルド済みの `EventSpec` が必要です。`.scene` ファイルは先に CLI/API でビルドしてください。

### 作業AIへの静的 instruction 設定

内容非参照ルールは、利用しているAIクライアントが対応している場合、静的な project instructions
として保存してください。セッション開始ごとに同じシステムプロンプトを貼る運用には依存しない方が安全です。

利用中のクライアントがサポートする instruction 機構を使います。例:

```text
AGENTS.md                  Codex系のリポジトリ指示
CLAUDE.md                  Claude Code系のリポジトリ指示
.cursor/rules/*.mdc        Cursorのプロジェクトルール
Project instructions       ホスト型/デスクトップ型AIクライアントの設定
```

保存する静的 instruction の例:

```text
このリポジトリは、内容非参照型の RPGツクールMZ MCP ツールです。

成人向け本文、会話本文、画像内容、CG説明、その他の秘匿したい創作内容を読んだり、
要約・推測・改稿・翻訳・分類・引用したりしてはいけません。

扱ってよいものは EventSpec JSON、mcp/*-manifest.json、RPGツクールMZ の data/*.json 構造、
各種ID、本文や画像内容を含まない検証結果、差分、バックアップ、ツール出力のみです。

ユーザーが安全かつ非秘匿であると明示しない限り、.scene ファイルを開かないでください。
raw scene content ではなく redacted EventSpec を優先してください。

変更適用前には dry-run を実行してください。報告するのはIDと構造的な変更であり、本文内容ではありません。
```

静的 instruction を保存した後は、通常のユーザープロンプトは短くできます。

```text
このビルド済み EventSpec をプロジェクトへ適用してください。先に dry-run を実行し、
検証に通ったら適用してください。map ID、event名、backup ID、検証結果を報告してください。
```

### 最小 `.scene` 例

```text
@scene S03_014
@title 宿屋の夜
@map 12
@anchor bed_side
@trigger autorun
@actors hero heroine

@say heroine
「おかえり。」

@choice
- 「休む」 -> rest
- 「外へ出る」 -> leave

@label rest
@switch 42 true
@jump end

@label leave
@call_common_event CE_LEAVE_INN
@jump end

@label end
@end
```

## Safety

Before writing a map JSON file, `applyEventSpec()` creates a backup under `mcp/backups/`.

Managed events are identified by both event name and the leading `@AI_META` comment. If the stored hash differs from the incoming normalized `.scene` hash, updates are rejected unless `force` is passed.

## 安全性

マップJSONを書き込む前に、`applyEventSpec()` は `mcp/backups/` 配下へバックアップを作成します。

管理イベントはイベント名と先頭の `@AI_META` コメントの両方で識別されます。保存済み hash が入力された正規化済み
`.scene` hash と異なる場合、`force` を指定しない限り更新は拒否されます。