Content
# Tool List
> ⚠ **WIP / Experimental / For Author's Environment**
>
> This is a **development version (0.x)** of the "MCP Server for controlling RPG Maker MZ with AI".
> **Verified to work only on author's environment (Windows + Antigravity)**.
>
> **Important Notes:**
> - May not work on other environments or with other MCP clients.
> - Some settings may not work as expected due to Antigravity implementation and CWD issues.
> - Read the code and modify paths or settings as needed.
> - Recommended for use with test projects only.
> - Backup data before running.
## TL;DR
### Target Users
**People who want to control RPG Maker MZ with AI**
### Features
- ✅ Let AI create maps
- ✅ Add events
- ✅ Add and configure plugins
- ✅ Automate testing and screenshot capture
### Quick Start (Google Antigravity)
1. **No installation needed**: `npx` will automatically fetch the package.
2. **MCP Configuration**: Add the following to `mcp_config.json`:
```json
{
"mcpServers": {
"rpg-maker-mz": {
"command": "npx",
"args": ["-y", "@rein634/rpg-maker-mz-mcp"]
}
}
}
```
3. **Usage**: Restart Antigravity → MCP Servers → Refresh → Ask AI to analyze the project and add a conversation event to the first map.
> 💡 **Using other MCP clients (Cursor/Claude, etc.)**: Refer to the "Project Local" section in the setup.
## Overview
This MCP server is a tool for **fully automating** RPG Maker MZ game development. By giving instructions to AI in natural language, it can automatically create maps, place events, manage switches, check assets, and more.
**Key Features:**
- ✅ **Abstraction layer**: No need to know MZ's internal structure.
- ✅ **Automatic ID management**: Automatically resolves and assigns switch and map IDs.
- ✅ **Hallucination prevention**: Specifications can be referenced in MCP Resources.
- ✅ **Quality assurance**: Zod Validation and asset integrity checks.
- ✅ **Automatic backup**: Creates backups before file writes.
- ✅ **Undo functionality**: Easily revert to previous changes.
- ✅ **Security enhancements**: Whitelist-based code execution and path traversal protection.
## Setup
### Google Antigravity
> ⚠️ **Environment-dependent warning**: Due to Antigravity implementation and CWD issues, some settings may not work as expected.
> The following are **examples that work on the author's environment**. Modify paths as needed for your environment.
#### Configuration (Verified Example)
First, install globally:
```bash
npm install -g @rein634/rpg-maker-mz-mcp
```
Add the following to `mcp_config.json` (use **absolute paths**):
```json
{
"mcpServers": {
"rpg-maker-mz": {
"command": "node",
"args": [
"C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/@rein634/rpg-maker-mz-mcp/dist/index.js"
]
}
}
}
```
> ⚠️ **Important**:
> - Replace `C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/...` with the **actual path** on your environment (change `YOUR_USERNAME` to your Windows user name).
> - Use forward slashes (`/`) on Windows, not backslashes (`\`).
> - Paths are expanded from environment variables like `%APPDATA%\npm\node_modules\@rein634\rpg-maker-mz-mcp\dist\index.js`.
#### Other Setup Methods (May Not Work)
The following setup methods **may not work** due to Antigravity environment dependencies:
**Method A: via npx (Not Recommended)**
```json
{
"mcpServers": {
"rpg-maker-mz": {
"command": "npx",
"args": ["-y", "@rein634/rpg-maker-mz-mcp"]
}
}
}
```
**Method B: Direct Command (Not Recommended)**
```json
{
"mcpServers": {
"rpg-maker-mz": {
"command": "rpg-maker-mz-mcp"
}
}
}
```
**Method C: Relative Path (Does Not Work)**
```json
{
"mcpServers": {
"rpg-maker-mz": {
"command": "node",
"args": ["./node_modules/@rein634/rpg-maker-mz-mcp/dist/index.js"]
}
}
}
```
> ❌ Antigravity starts with `.gemini/antigravity` as the current directory, so relative paths won't work.
#### Confirmation
Restart Antigravity and execute **MCP Servers** → **Refresh**. You should see a log like this in the terminal:
```text
[2025-11-29T05:43:43.574Z] [INFO] RPG Maker MZ MCP Server running on stdio.
```
This is **normal** behavior. The server is waiting for requests from MCP clients.
> 💡 **Logs**: Logs are output to **stderr**, which does not affect MCP protocol JSON (stdout). Even if logs appear, it's not an issue.
### Project Local (Cursor / Claude Code, etc.)
> ⚠️ **Unverified**: The following settings are **not verified** on the author's environment. This is an assumed configuration for MCP clients that place configuration files in the project root. If it doesn't work, read the code and adjust for your environment.
#### 1. Install in Project
Run in the RPG Maker MZ project root directory:
```bash
npm install -D @rein634/rpg-maker-mz-mcp
```
#### 2. Configure MCP Settings File
Create a settings file in the project root (e.g., `.cursor/mcp.json` or `mcp_config.json`) and add:
```json
{
"mcpServers": {
"rpg-maker-mz": {
"command": "node",
"args": ["./node_modules/@rein634/rpg-maker-mz-mcp/dist/index.js"]
}
}
}
```
> ⚠️ **Note**:
> - This configuration is **not verified** by the author.
> - It may not work due to MCP client implementation or CWD issues.
> - If it doesn't work, use absolute paths or adjust for your environment.
### Other Methods
#### Global Installation (Optional, for Advanced Users)
Install globally and execute by command name:
```bash
npm install -g @rein634/rpg-maker-mz-mcp
```
Add the following to the MCP settings file:
```json
{
"mcpServers": {
"rpg-maker-mz": {
"command": "rpg-maker-mz-mcp"
}
}
}
```
> ⚠️ **Note**: Some clients (especially on Windows) may have issues with global wrapper scripts, resulting in `Error: calling "initialize": EOF`. Use the **Antigravity-specific** or **project-local** setup in this case.
#### Direct Execution from Source (for Developers)
No need to install npm packages. Clone the repository and install dependencies:
```bash
git clone https://github.com/rein1225/RPGMakerMZ_MCP.git
cd RPGMakerMZ_MCP
npm install
```
Add the following to the MCP settings file:
```json
{
"mcpServers": {
"rpg-maker-mz": {
"command": "npx",
"args": ["tsx", "C:/path/to/RPGMakerMZ_MCP/index.ts"],
"cwd": "C:/path/to/RPGMakerMZ_MCP"
}
}
}
```
> ⚠️ **Important**:
> - Replace `C:/path/to/RPGMakerMZ_MCP` with the **actual project path**.
> - Use forward slashes (`/`) on Windows, not backslashes (`\`).
> - Using `npx tsx` allows direct execution of TypeScript files (no build needed).
> - If `cwd` property is not allowed: Refer to Q1 in Troubleshooting.
## Available Tools
### Phase 1: Project Analysis and Data Manipulation
#### 1. `get_project_info` - Get Project Basic Information
**Description:** Retrieves basic information like game title, version, and currency unit from System.json.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
#### 2. `list_data_files` - List Data Files
**Description:** Lists JSON files in the data folder.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
#### 3. `read_data_file` - Read Data File
**Description:** Reads the contents of a specified data file (e.g., Actors.json).
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `filename` (required): File name (e.g., 'Actors.json')
#### 4. `write_data_file` - Write Data File
**Description:** Writes JSON content to a specified data file. Creates a backup automatically before writing.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `filename` (required): File name
- `content` (required): JSON string to write
#### 5. `search_events` - Search Events
**Description:** Searches for text or command codes in map events and common events.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `query` (required): Text or number to search for
#### 6. `get_event_page` - Get Event Page
**Description:** Retrieves the command list of a specified event page. Major commands (conversation, choices, switch operations, etc.) are given readable descriptions. This allows AI to understand and modify existing events.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `mapId` (required): Map ID
- `eventId` (required): Event ID
- `pageIndex` (required): Page number (0-based)
### Phase 2: Asset Management
#### 7. `list_assets` - List Assets
**Description:** Lists files in img and audio directories.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `assetType` (optional): 'img', 'audio', or 'all' (default: 'all')
#### 8. `check_assets_integrity` - Check Asset Integrity
**Description:** Checks if assets referenced in events actually exist in the project.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
### Phase 3: Plugin Management
#### 9. `write_plugin_code` - Create Plugin
**Description:** Creates a new plugin file (.js) in the js/plugins directory.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `filename` (required): Plugin file name (e.g., 'MyPlugin.js')
- `code` (required): JavaScript code
#### 10. `get_plugins_config` - Get Plugin Configuration
**Description:** Reads the current plugin configuration from js/plugins.js.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
#### 11. `update_plugins_config` - Update Plugin Configuration
**Description:** Updates the plugin configuration in js/plugins.js.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `plugins` (required): Array of plugin configuration objects
### Phase 4: Map and Event Operations (Abstraction Layer)
#### 12. `add_dialogue` - Add Dialogue Event
**Description:** Adds a dialogue to the message window.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `mapId` (required): Map ID
- `eventId` (required): Event ID
- `pageIndex` (required): Page number
- `insertPosition` (required): Insertion position (-1 for end)
- `text` (required): Display text
- `face`, `faceIndex`, `background`, `position` (optional)
**Request Example:**
```json
{
"tool": "add_dialogue",
"arguments": {
"projectPath": "C:/Games/MyProject",
"mapId": 1,
"eventId": 1,
"pageIndex": 0,
"insertPosition": -1,
"text": "Hello!\nNew ally."
}
}
```
**Response Example:**
```json
{
"content": [
{
"type": "text",
"text": "Added dialogue event."
}
]
}
```
#### 13. `add_choice` - Add Choices
**Description:** Adds choices to an event. Up to 6 choices can be set.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `mapId` (required): Map ID
- `eventId` (required): Event ID
- `pageIndex` (required): Page number
- `insertPosition` (required): Insertion position (-1 for end)
- `options` (required): Array of choice strings (up to 6)
- `cancelType` (optional): Cancel behavior (-1 = no cancel, 0-5 = branch to choice, default: -1)
**Request Example:**
```json
{
"tool": "add_choice",
"arguments": {
"projectPath": "C:/Games/MyProject",
"mapId": 1,
"eventId": 1,
"pageIndex": 0,
"insertPosition": -1,
"options": ["Yes", "No"],
"cancelType": -1
}
}
```
**Response Example:**
```json
{
"content": [
{
"type": "text",
"text": "Added choices."
}
}
}
```
#### 14. `add_loop` - Add Loop
**Description:** Adds a loop structure (Loop + Repeat Above) to the event commands.
**Parameters:**
- `projectPath`, `mapId`, `eventId`, `pageIndex`, `insertPosition` (required)
#### 15. `add_break_loop` - Break Loop
**Description:** Adds a command to break a loop.
**Parameters:**
- `projectPath`, `mapId`, `eventId`, `pageIndex`, `insertPosition` (required)
16. `add_conditional_branch` - Add Conditional Branch
**Description:** conditional branch (If-).
**Parameters:**
- `projectPath`, `mapId`, `eventId`, `page `insertPosition` (required)
- `condition` (required): Condition parameter object
- `includeElse` (optional Else branch (default: true)
#### 17. `_command` - Delete Event Command
**Description:** Deletes the at the specified index.
**Parameters:**
- `projectPath`, `mapId`, `event `pageIndex`,Index` (required)
18. `update_event - Update Event Command
:** Overwrites the event command at the specified index with.
**Parameters:**
- ``, `mapId`, `eventId`, `pageIndex`, `commandIndex`, `newCommand` (required)
. `add_actor` - Add Actor
**Description:** new actor to the database.
**Parameters:**
- `projectPath`, `name` (required)
- `classId`, `initialLevel`, `maxLevel` (optional)
#### 20. `add_item` Item
**Description:** new item to the databaseParameters:**
- `projectPath`, `name` (required)
- `price`, `consumable`, `scope`, `occasion` (optional)
#### 21. `add_skill` - Add Skill
**Description:** Adds a new skill to the database.
**Parameters:**
- `projectPath`, `name` (required)
- `mpCost`, `tpCostscope`, `occasion` (optional)
####. `draw_map - Draw Map Tile
**Description:** Places a the specified coordinates on the map.
**Parameters:**
- ``, `mapIdx`, `y`,tileId`)
#### 23._map` - Create New Map
**Description:** Creates map.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `mapName` (required): Map name
- `width` (optional): Map width (number of tiles, default: 17)
- ` (optional): Map height (number of tiles, default13)
- `parentMapId` (optional): Parent map ID (default: 0)
#### 24. `` - Show Picture
**Description:** Adds a picture display the event.
**- `projectPath`): Absolute path to the
- `map): Map ID
- `eventId` ( Event ID
-Index` (required): Page number
- `insertPositionrequired): Insertion position for end)
- `` (required): Picture number `pictureNamerequired): Image file name `x`, `y` (required): Display coordinates
- `origin` (optional position (0=top-left1=center, default0)
- `scale `scaleY` ( Scale ratio (%, 100)
- ` (optional): Opacity (255, default255)
- `blend (optional): Blend0-3, default0)
#### 25inspect_game_state` Game State
**Description variable and switch values from game (with Pupp).
**Security:** Uses approach, only allowing execution of permitted patterns. Input length characters) and ID range checks (1-999 are also implemented.
** patterns example:**
- `$gameVariables.value(1)` - Get variable value
- `$gameSwitches.value(1)` - Get switch value
- `$gameParty.gold()` - Get gold
- `$gameMap.mapId()` - Get current map ID
- `SceneManager._scene` - Get current scene
**Parameters:**
- `script` (required): JavaScript code to evaluate (only whitelisted patterns `port`): Debug port (default: 9222)
**Request example:**
```json
"tool": "_state",
" "scriptgameVariables.value(1 "port": 9222
}
}
```
example:**
```json
{
"content": [
{
"type": "text",
"text": "100"
}
]
}
```
> ⚠️ **Dangerous Tool**: This tool executes JavaScript code. See [Dangerous Tool Seal Guide](#dangerous-tool-seal-guide) for details.
### Phase 5: Testing & Automation
#### 26. `run_playtest` - Run Playtest
**Description:** Launches Game.exe and takes a screenshot after a specified time. If Game.exe is not found, a browser-based playtest (fallback mode) is executed automatically. A debug port for Puppeteer connection can also be specified.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `duration` (optional): Wait time before taking screenshot (ms, default: 5000)
- `autoClose` (optional): Automatically close the game after taking screenshot (default: false)
- `debugPort` (optional): Remote debug port (e.g., 9222) for Puppeteer connection
- `startNewGame` (optional): Start a new game, skipping the title screen (default: false)
- `postLaunchScript` (optional): JavaScript code to execute after game launch, for debugging UI display or event injection
**postLaunchScript example:**
```json
{
"projectPath": "C:/Games/MyProject",
"postLaunchScript": "Input._currentState['debug'] = true; setTimeout(() => { Input._currentState['debug'] = false; }, 100);"
}
```
### Phase 6: Backup & Undo
#### 27. `undo_last_change` - Undo Last Change
**Description:** Restores files from the latest backup. If `filename` is not specified, the most recently modified file is automatically restored.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `filename` (optional): File name to restore (e.g., 'Actors.json'). If omitted, the latest changed file is automatically detected
#### 28. `list_backups` - List Backups
**Description:** Displays a list of backups for the specified file or all files.
**Parameters:**
- `projectPath` (required): Absolute path to the project folder
- `filename` (optional): File name to display backups omitted, backups for all files are displayed
**Backup feature:**
- Automatic backups are created for all file write operations (`write_data_file`, `add_actor`, `add `add_skill`, `write`, `_config`, map operations,- Backup files are the `.{timestamp` format
- Old automatically cleaned up ( latest 5)
- Automatic rollback occurs in case of### Advanced Automated Testingeteer
By specifying `debugPort` in `run_playtest`, you can automate game UI operations and scenario testing.
See `docs/API_REFERENCE.md` for detailed API specifications.
### How to Run E2E Tests
(`automation/test_*.js`) are manual tests production game environments and are not executed in CI.
# Run a
npm run test:e
# Or run individually
node automation/test_full
node automation/test_add_dialogue.js
```
> **Caution**: Since this involves browser operations and.exe, **only a trusted local environment**.
Resources
### `mz://docs/event_commands` Command Reference
This is a resource for AI to MZ event command specifications.
## Practical Examples
### Example: Create a New Actor and Add a Conversation Eventjavascript
// 1 actor
add projectPath, name: "New Character" });
//. Add a conversation
add_dialogue({ projectPath: 1Id: 1, pageIndex: 0, insertPosition: -1, "Hello!\nI'm a new ally." });
Example 2: Events
```javascript
({ projectPath:path/to/project: "Potion" });
```
## Troubleshooting
: MCP Setting Error "invalid character '-' after array or "property cwd is not allowed"
> ✅ in v0.2**: The ` '-' after array element` error caused by MCP server logging has been resolved.
you encounter this error, **use version v0.1.2 or later**: `npm install -g @rein634/rpg-mz-mcp@latest`
**Cause:**
- **MCP server issue (before v0.1)**: Logging to stdout broke the JSON-R
- JSON syntax error (comments, trailing etc.)
- MCP client does not support `cwd
**Solution:**
#### Step 1: Check
1. **Remove comments**: JSON does not support comments (`//` or `#`)
2. **Remove**: No trailing commas after the last element in arrays or3. **Verify with online validator**: Check syntaxJSONLint](https://jsonlint.com/)
####2: Check Correct Settings
**For Google Antigrecommended):**
```json
{
"m": {
"rpg-maker-mz": "command": "npx",
" ["-y", "@rein634/rpg-m-mcp"]
}
}
}
```
> ✅ **Advantages of this method**:
> - No need for install` (npx automatically fetches the package)
> - Does not depend on CWD, works from `.gemini/antigravity`
> - Works with the same settings across different user environments
**For Project Local (Cursor / Claude Code, etc.):**
In project rootbash
npm install -D @rein634/rpg-maker-mz-mcp
```
Config file (placed in project root):
```json
{
"mcp {
"rpg-maker-mz": "command": "node",
"args":node_modules/@rein634/rpg-maker-mcp/dist/index.js"]
}
}
}
✅ **Advantages of this method**:
> - depend on global PATH or wrapper scripts
> - Windows / Mac / Linux
> - Uses relative paths project root, easier to handle that require configuration files project root
** Global Installation (may in some environmentsbash
npm install @rein634/rpg-maker-mz
```
```json "mcp {
"raker-mz": {
"command": "rpg-maker-mz-mcp"
}
}
}
```
> ⚠️ **Caution**: In some environments, such as Windows, the global wrapper script may not launch correctly, resulting in `Error: calling "initialize": EOF`. In use theravity** Local****Common mistakes:**
- ❌ **Use comments**: `// This is a comment` → JSON does not support comments
❌ **Trailing commas": ["tsx.ts",]` trailing commas
- **Single quotes**:'` → JSON only quotes
- Backslashes**: `\to\file Use slashes (`#### Step 3 Config File Location
Antigravity**: `%ATA%\Ant\mcp_config.json)
- ** Desktop**: `%AP%\Claude\claude_desktop_configWindows)
- Config file path varies depending on the MCP client used
####4: Debugging
1. Open the config file in a text editor
2 & paste to [](https://json/) for verification
3. Check error message line correct the corresponding4. Restart the after corrections
###: Switch Not FoundSolution:** The feature should work if you have write System.json.
###: Editor Conflict
:** Close the the project after.
### Q4.exe Not Found
Create a test play package with the deployment feature or manually place Game.exe.
v1.2 and later play can be executed via browser even without Game.exe.
### Q5: npm Found
**Solution- Global installation: `npm install -g @pg-makercp`
if the path is `which rpg-mz-mcp/Mac) or `where raker-mz-mcp` (Windows)
- For direct execution from source, use `npx tsx`
## Technical Specifications
### Architecture
```
[AI] ← → [MCP Server] ← → [RPG Maker MZ Project]
├ (28)
(1)
─ Schemas ( Validation)
└ System (automatic rollback)
```
###
- **Unit Using Vitest
Coverage report**: Generated with `npm run test:coverage`
- **CI Automated testing with Git coverage tracking with
### npm Publication is published on npm:
```bash
-g @rein-maker-mcp
```
Package https://www.npmjsrein634aker-mz-mcp
### File Structure
```
RPGツクールMZ＿MCP/
├── index.ts # MCP Server Body (TypeScript)
├── handlers/ # Handler Layer (TypeScript)
│ ├── project.ts
│ ├── database.ts
│ ├── plugins.ts
│ ├── map.ts
│ ├── events.ts
│ └── playtest.ts
├── utils/ # Utility Layer (TypeScript)
│ ├── validation.ts
│ ├── mapHelpers.ts
│ └── ...
├── types/ # Type Definitions
├── resources/
│ └── event_commands.json # Event Command Reference
├── schemas/
│ └── mz_structures.js # Zod Validation Schema
├── automation/ # Automation Scripts
└── package.json
```
---
## Security Notes
This MCP server is designed for use in local development environments.
### Implemented Security Measures
- **`inspect_game_state`**: Whitelist-based, only allows execution of permitted patterns. Input length limit (100 characters) and ID range checks (1-9999) are also implemented.
- **Path Traversal Protection**: Uses `path.normalize()` and `fs.realpath()` to prevent symbolic link attacks.
- **Filename Validation**: Only allows alphanumeric characters, underscores, and hyphens when writing plugins.
- **Automatic Backup**: Creates automatic backups for all file write operations and rolls back in case of errors.
### Recommendations
- Do not use in publicly exposed environments.
- Only use in trusted local environments.
- It is recommended to take manual backups before making significant changes.
---
## License
MIT License
## Typical Use Cases
### Scenario 1: Adding Sub-quests to an Existing Project
**Goal**: Add three sub-quest events to an existing village map.
**Steps**:
1. **Project Analysis**: Retrieve project information using `get_project_info`.
2. **Event Search**: Verify existing events using `search_events`.
3. **Event Page Retrieval**: Understand the structure of existing events using `get_event_page`.
4. **Add Dialogue**: Add NPC dialogue using `add_dialogue`.
5. **Add Choices**: Add quest choices using `add_choice`.
6. **Conditional Branching**: Set up quest completion conditions using `add_conditional_branch`.
7. **Playtest**: Verify functionality using `run_playtest`.
**Instructions for AI**:
```
Analyze this project and add three sub-quests to the village map.
Each quest should include dialogue, choices, and completion conditions.
```
### Scenario 2: Creating a New Map and Event Placement
**Goal**: Create a new dungeon map and place treasure chest events.
**Steps**:
1. **Map Creation**: Create a new map using `create_map`.
2. **Tile Placement**: Draw the map using `draw_map_tile`.
3. **Event Creation**: Add treasure chest messages using `add_dialogue`.
4. **Item Addition**: Create reward items using `add_item`.
5. **Event Linking**: Set up conditional branching for item rewards.
6. **Testing**: Verify functionality using `run_playtest`.
**Instructions for AI**:
```
Create a new dungeon map and place three treasure chest events.
Each chest should contain a different item.
```
### Scenario 3: Adding and Configuring Plugins
**Goal**: Add a custom plugin and update settings.
**Steps**:
1. **Plugin Creation**: Add plugin code using `write_plugin_code`.
2. **Settings Retrieval**: Retrieve current settings using `get_plugins_config`.
3. **Settings Update**: Enable the plugin using `update_plugins_config`.
4. **Testing**: Verify plugin functionality using `run_playtest`.
**Instructions for AI**:
```
Create a custom battle plugin and enable it.
```
---
## Dangerous Tools Guide
### List of Dangerous Tools
The following tools require **caution** due to security concerns:
- **`inspect_game_state`**: Executes JavaScript code (protected by whitelist, but may still pose risks)
### Recommended Settings
**Disable by default**. You can disable specific tools in the MCP client settings:
```json
{
"mcpServers": {
"rpg-maker-mz": {
"command": "rpg-maker-mz-mcp",
"disabledTools": ["inspect_game_state"]
}
}
}
```
> ⚠️ **Note**: Some MCP clients may not support the `disabledTools` property. Avoid using these tools or only use them in trusted environments.
### Security Measures
The `inspect_game_state` tool implements the following security measures:
- ✅ **Whitelist**: Only allows permitted patterns to execute.
- ✅ **Input Length Limit**: 100 characters.
- ✅ **ID Range Check**: Only allows IDs between 1 and 9999.
- ✅ **Path Traversal Protection**: Prevents unauthorized path access.
Still, **avoid executing untrusted code**.
---
## Update History
### v0.1.2 (2025-11-29)
- **Critical Fix**: Changed log output to stderr (MCP protocol compliance).
- Resolved `invalid character '-' after array element` error.
- Updated Logger.info() to use console.error().
- Updated tests (console.log spy changed to console.error).
### v0.1.1 (2025-11-29)
- Fixed tsconfig.build.json to include logger.js in build.
- Prepared for npm release (@rein634/rpg-maker-mz-mcp).
### v0.1.0 (2025-11-29)
- Initial npm release.
- Completed TypeScript migration: All handlers and entry points migrated.
- Integrated CI/CD: Added type checking to GitHub Actions.
- Implemented undo_last_change tool and list_backups tool.
- Improved test coverage (added tests for undo.ts and backup.ts).
- Refactored playtest.ts (reduced from 527 lines to 311 lines, ~41% reduction).
- Improved README (added TL;DR, request examples, and use cases).
- Enhanced security: Added path traversal protection and arbitrary code execution warnings.
- Added new tools: `add_choice`, `create_map`, `show_picture`, `check_assets_integrity`.
- Introduced unit tests (Vitest).
- Added logger utility.
- Added browser-based fallback to `run_playtest` (no Game.exe required).
- Implemented MCP Resources.
- Implemented Zod Validation.
---
## Roadmap for Additional Features
The following features are planned and will be implemented separately. See `docs/feature-roadmap.md` for details.
| Priority | Feature | Status |
| --- | --- | --- |
| ~~High~~ | ~~`undo` feature (JSON backup / rollback)~~ | ✅ Implemented |
| Medium | `validate_project` tool (batch integrity check) | 📋 Planned |
| Medium | Batch processing (execute multiple commands in a single request) | 📋 Planned |
| Low | WebSocket notifications (real-time logs / state notifications) | 📋 Planned |
## Development and Contributions
### Running Tests
```bash
# Unit tests
npm test
# Generate coverage report
npm run test:coverage
# Type checking
npm run typecheck
# E2E tests (manual execution)
npm run test:e2e
```
### Building
```bash
# Build all files (output to dist/)
npm run build
# Pre-release check
npm pack --dry-run
```
### Contributions
Pull requests are welcome! Please note the following:
- Code style: TypeScript strict mode.
- Tests: Add tests for new features.
- Security: Implement proper validation for file operations and code execution.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available