# RPG Maker MZ MCP Server

A high-quality Model Context Protocol (MCP) server for RPG Maker MZ integration. This server provides comprehensive tools for managing game data, maps, events, and system settings through the MCP protocol.

## Features

- **Actor Management**: Create, read, update, and search actors
- **Item/Equipment Management**: Manage items, weapons, armors, and skills
- **Skill Creation**: Create custom skills with natural language (NEW!)
  - Damage skills, healing skills, buffs, debuffs, status effects
  - Simplified helpers for common skill types
  - Full customization support
- **Map Management**: Access and modify map data, tiles, and properties
- **Event Management**: Create, update, and manage map events and commands
- **System Configuration**: Update game settings, variables, switches, and vocabulary
- **Type Safety**: Full TypeScript support with comprehensive type definitions
- **Error Handling**: Robust error handling and validation

## Installation

```bash
npm install
npm run build
```

## Configuration

Set the RPG Maker MZ project path as an environment variable:

```bash
# Windows
set RPGMAKER_PROJECT_PATH=C:\path\to\your\rpgmaker\project

# macOS/Linux
export RPGMAKER_PROJECT_PATH=/path/to/your/rpgmaker/project
```

## Usage

### Running the Server

```bash
npm start
```

Or directly:

```bash
node dist/index.js
```

### Configuring in Claude Desktop

Add to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "rpgmaker-mz": {
      "command": "node",
      "args": ["C:/path/to/rpgmaker-mz-mcp/dist/index.js"],
      "env": {
        "RPGMAKER_PROJECT_PATH": "C:/path/to/your/rpgmaker/project"
      }
    }
  }
}
```

## Available Tools

### Actor Tools

- `get_actors` - Get all actors from the project
- `get_actor` - Get a specific actor by ID
- `update_actor` - Update an actor's properties
- `create_actor` - Create a new actor
- `search_actors` - Search actors by name or nickname

### Item Tools

- `get_items` - Get all items from the project
- `get_weapons` - Get all weapons from the project
- `get_armors` - Get all armors from the project
- `get_skills` - Get all skills from the project
- `update_item` - Update an item's properties
- `search_items` - Search items by name or description

### Skill Tools (NEW!)

- `get_skill` - Get a specific skill by ID
- `create_skill` - Create a custom skill with full control
- `create_damage_skill` - Create a damage-dealing skill (simplified)
- `create_healing_skill` - Create a healing skill (simplified)
- `create_buff_skill` - Create a buff skill (simplified)
- `create_state_skill` - Create a state-inflicting skill (simplified)
- `update_skill` - Update a skill's properties
- `search_skills` - Search skills by name or description

### Map Tools

- `get_map` - Get map data by ID
- `get_map_infos` - Get information about all maps
- `get_map_events` - Get all events from a specific map
- `get_map_event` - Get a specific event from a map
- `update_map_event` - Update a map event's properties
- `create_map_event` - Create a new event on a map
- `search_map_events` - Search events on a map by name
- `add_event_command` - Add a command to an event page

### System Tools

- `get_system` - Get system data
- `get_variables` - Get all game variable names
- `set_variable_name` - Set a variable name
- `get_switches` - Get all game switch names
- `set_switch_name` - Set a switch name
- `get_game_title` - Get the game title
- `update_game_title` - Update the game title
- `update_starting_position` - Update the game starting position

## Example Usage

Once configured, you can use Claude to interact with your RPG Maker MZ project:

### Example 1: Get All Actors

```
Show me all actors in my RPG Maker MZ project
```

Claude will use the `get_actors` tool to retrieve and display all actors.

### Example 2: Update an Actor

```
Update actor 1's name to "Hero" and initial level to 5
```

Claude will use the `update_actor` tool with the appropriate parameters.

### Example 3: Create a New Item

```
Create a new item called "Health Potion" that restores 50 HP
```

Claude will help you create the item with the proper structure.

### Example 4: Search Map Events

```
Find all events on map 1 that contain "treasure" in their name
```

Claude will use the `search_map_events` tool to find matching events.

### Example 5: Update Game Settings

```
Change the game title to "My Epic Adventure"
```

Claude will use the `update_game_title` tool to update the system data.

### Example 6: Create a Custom Skill

```
Create a fire magic skill called "Fireball" that costs 15 MP,
targets a single enemy, and deals "a.mat * 4 - b.mdf * 2" damage
```

Claude will use the `create_damage_skill` tool to create the skill.

### Example 7: Create a Healing Skill

```
Create a group healing spell called "Mass Heal" that costs 30 MP,
targets all allies, and heals "a.mat * 3 + 100" HP
```

Claude will use the `create_healing_skill` tool to create the healing skill.

## Data Structure Reference

### Actor Structure

```typescript
{
  id: number;
  name: string;
  nickname: string;
  profile: string;
  classId: number;
  initialLevel: number;
  maxLevel: number;
  characterName: string;
  characterIndex: number;
  faceName: string;
  faceIndex: number;
  battlerName: string;
  traits: Trait[];
  equips: number[];
  note: string;
}
```

### Map Event Structure

```typescript
{
  id: number;
  name: string;
  note: string;
  pages: EventPage[];
  x: number;
  y: number;
}
```

### Event Command Structure

```typescript
{
  code: number;        // Command code (see RPG Maker MZ documentation)
  indent: number;      // Indentation level
  parameters: any[];   // Command parameters
}
```

## Common Event Command Codes

- `101` - Show Text
- `102` - Show Choices
- `111` - Conditional Branch
- `112` - Loop
- `113` - Break Loop
- `121` - Control Switches
- `122` - Control Variables
- `125` - Change Gold
- `126` - Change Items
- `201` - Transfer Player
- `356` - Plugin Command

For a complete list, refer to the RPG Maker MZ documentation.

## Development

### Building

```bash
npm run build
```

### Watch Mode

```bash
npm run dev
```

## Project Structure

```
rpgmaker-mz-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── tools/
│   │   ├── actorTools.ts     # Actor management functions
│   │   ├── itemTools.ts      # Item/equipment management
│   │   ├── mapTools.ts       # Map and event management
│   │   └── systemTools.ts    # System settings management
│   └── utils/
│       ├── fileHandler.ts    # File I/O utilities
│       └── types.ts          # TypeScript type definitions
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

## Safety and Best Practices

1. **Backup Your Project**: Always backup your RPG Maker MZ project before making changes
2. **Close RPG Maker MZ Editor**: Close the RPG Maker MZ editor when using this server to avoid conflicts
3. **Validate Changes**: Test your game after making changes to ensure everything works correctly
4. **Version Control**: Use git or another version control system for your project

## Limitations

- This server modifies JSON files directly. Make sure the RPG Maker MZ editor is closed when using it
- Some advanced features may require manual editing in the RPG Maker MZ editor
- Plugin-specific data structures may not be fully supported

## Troubleshooting

### "Invalid RPG Maker MZ project path"

Make sure the `RPGMAKER_PROJECT_PATH` environment variable points to a valid RPG Maker MZ project directory containing:
- `game.rmmzproject` file
- `data/` directory with `System.json`

### Changes Not Appearing

1. Make sure the RPG Maker MZ editor is closed
2. Verify the project path is correct
3. Check that the JSON files have write permissions

### Tool Not Found

Restart Claude Desktop after updating the configuration file.

## Contributing

Contributions are welcome! Please ensure:
- Code follows TypeScript best practices
- All functions include proper error handling
- Type definitions are updated for new features
- Documentation is updated accordingly

## License

MIT

## Resources

- [RPG Maker MZ Official Website](https://www.rpgmakerweb.com/products/rpg-maker-mz)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [RPG Maker MZ Database Structure](https://github.com/rpgtkoolmv/rmmz-api-reference)

## Support

For issues and feature requests, please open an issue on the project repository.