RPG Maker MZ MCP Server

Instructions

Implementation Reference

• src/index.ts:830-858 (handler)

  The handler function for the 'list_projects' tool. It scans a specified directory (default: ~/Documents) for RPG Maker MZ projects by checking for the presence of 'Game.rpgproject' files and returns a list of matching project directories.
  case "list_projects": { const searchDir = (args?.directory as string) || path.join(process.env.HOME!, "Documents"); const entries = await fs.readdir(searchDir, { withFileTypes: true }); const projects = []; for (const entry of entries) { if (entry.isDirectory()) { const projectFile = path.join(searchDir, entry.name, "Game.rpgproject"); try { await fs.access(projectFile); projects.push({ name: entry.name, path: path.join(searchDir, entry.name), }); } catch { // Not an RPG Maker project } } } return { content: [ { type: "text", text: JSON.stringify(projects, null, 2), }, ], }; }
• src/index.ts:82-93 (schema)

  The input schema definition for the 'list_projects' tool, specifying an optional 'directory' parameter.
  name: "list_projects", description: "List all RPG Maker MZ projects in a directory", inputSchema: { type: "object", properties: { directory: { type: "string", description: "Directory path to search for projects (defaults to ~/Documents)", }, }, }, },
• src/index.ts:78-822 (registration)

  Registration of the 'list_projects' tool in the ListTools response handler, making it discoverable by MCP clients.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "list_projects", description: "List all RPG Maker MZ projects in a directory", inputSchema: { type: "object", properties: { directory: { type: "string", description: "Directory path to search for projects (defaults to ~/Documents)", }, }, }, }, { name: "read_project_info", description: "Read RPG Maker MZ project information (Game.rpgproject file)", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, }, required: ["project_path"], }, }, { name: "list_maps", description: "List all maps in an RPG Maker MZ project", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, }, required: ["project_path"], }, }, { name: "read_map", description: "Read a specific map file from an RPG Maker MZ project", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, map_id: { type: "string", description: "Map ID (e.g., 'Map001')", }, }, required: ["project_path", "map_id"], }, }, { name: "list_plugins", description: "List all plugins in an RPG Maker MZ project", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, }, required: ["project_path"], }, }, { name: "generate_project_context", description: "Generate comprehensive context documentation for an RPG Maker MZ project including structure, maps, events, and plugin information", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, include_maps: { type: "boolean", description: "Include detailed map information (default: true)", }, include_events: { type: "boolean", description: "Include event data (default: true)", }, include_plugins: { type: "boolean", description: "Include plugin information (default: true)", }, }, required: ["project_path"], }, }, { name: "analyze_project_structure", description: "Analyze RPG Maker MZ project structure and provide insights about maps, connections, events, and game flow", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, }, required: ["project_path"], }, }, { name: "extract_game_design_patterns", description: "Extract common game design patterns from the project (event patterns, map layouts, etc.)", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, }, required: ["project_path"], }, }, { name: "create_project", description: "Create a new RPG Maker MZ project from scratch", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path where the project will be created", }, game_title: { type: "string", description: "Title of the game", }, }, required: ["project_path", "game_title"], }, }, { name: "create_map", description: "Create a new map in the project", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, map_id: { type: "number", description: "Map ID number", }, name: { type: "string", description: "Map name", }, width: { type: "number", description: "Map width in tiles (default: 17)", }, height: { type: "number", description: "Map height in tiles (default: 13)", }, }, required: ["project_path", "map_id", "name"], }, }, { name: "update_map_tile", description: "Update a tile on a map", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, map_id: { type: "number", description: "Map ID", }, x: { type: "number", description: "X coordinate", }, y: { type: "number", description: "Y coordinate", }, layer: { type: "number", description: "Layer index (0-5)", }, tile_id: { type: "number", description: "Tile ID from tileset", }, }, required: ["project_path", "map_id", "x", "y", "layer", "tile_id"], }, }, { name: "add_event", description: "Add a new event to a map", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, map_id: { type: "number", description: "Map ID", }, event_id: { type: "number", description: "Event ID", }, name: { type: "string", description: "Event name", }, x: { type: "number", description: "X coordinate", }, y: { type: "number", description: "Y coordinate", }, }, required: ["project_path", "map_id", "event_id", "name", "x", "y"], }, }, { name: "add_event_command", description: "Add a command to an event page (e.g., show text, transfer player, etc.)", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, map_id: { type: "number", description: "Map ID", }, event_id: { type: "number", description: "Event ID", }, page_index: { type: "number", description: "Page index (0-based)", }, code: { type: "number", description: "Command code (e.g., 101=Show Text, 201=Transfer Player, 122=Control Variables)", }, parameters: { type: "array", description: "Command parameters", }, }, required: ["project_path", "map_id", "event_id", "page_index", "code", "parameters"], }, }, { name: "add_actor", description: "Add a new actor to the database", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, id: { type: "number", description: "Actor ID", }, name: { type: "string", description: "Actor name", }, }, required: ["project_path", "id", "name"], }, }, { name: "add_class", description: "Add a new class to the database", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, id: { type: "number", description: "Class ID", }, name: { type: "string", description: "Class name", }, }, required: ["project_path", "id", "name"], }, }, { name: "add_skill", description: "Add a new skill to the database", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, id: { type: "number", description: "Skill ID", }, name: { type: "string", description: "Skill name", }, }, required: ["project_path", "id", "name"], }, }, { name: "add_item", description: "Add a new item to the database", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, id: { type: "number", description: "Item ID", }, name: { type: "string", description: "Item name", }, }, required: ["project_path", "id", "name"], }, }, { name: "update_database", description: "Update an entry in any database (Actors, Classes, Skills, Items, Weapons, Armors, etc.)", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, database: { type: "string", description: "Database name (e.g., 'Actors', 'Classes', 'Skills', 'Items')", }, id: { type: "number", description: "Entry ID", }, updates: { type: "object", description: "Object containing fields to update", }, }, required: ["project_path", "database", "id", "updates"], }, }, { name: "generate_asset", description: "Generate RPG Maker MZ asset using Gemini 2.5 Flash (characters, faces, tilesets, etc.)", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, asset_type: { type: "string", enum: ["character", "face", "tileset", "battleback", "enemy", "sv_actor", "picture"], description: "Type of asset to generate", }, prompt: { type: "string", description: "Description of the asset to generate", }, filename: { type: "string", description: "Filename for the generated asset (with extension)", }, api_key: { type: "string", description: "Gemini API key (optional, uses GEMINI_API_KEY env var if not provided)", }, }, required: ["project_path", "asset_type", "prompt", "filename"], }, }, { name: "generate_asset_batch", description: "Generate multiple RPG Maker MZ assets in batch", inputSchema: { type: "object", properties: { requests: { type: "array", description: "Array of asset generation requests", items: { type: "object", properties: { project_path: { type: "string" }, asset_type: { type: "string" }, prompt: { type: "string" }, filename: { type: "string" }, api_key: { type: "string" }, }, }, }, }, required: ["requests"], }, }, { name: "describe_asset", description: "Analyze and describe an existing RPG Maker MZ asset using Gemini 2.5 Flash", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, asset_type: { type: "string", description: "Type of asset", }, filename: { type: "string", description: "Filename of the asset to analyze", }, api_key: { type: "string", description: "Gemini API key (optional)", }, }, required: ["project_path", "asset_type", "filename"], }, }, { name: "generate_scenario", description: "Generate a complete RPG game scenario using Gemini AI (story, maps, characters, events, items)", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, theme: { type: "string", description: "Theme or genre of the game (e.g., 'fantasy adventure', 'sci-fi', 'horror')", }, style: { type: "string", description: "Style or tone (e.g., 'lighthearted', 'dark', 'comedic', 'epic')", }, length: { type: "string", enum: ["short", "medium", "long"], description: "Length of the game scenario", }, api_key: { type: "string", description: "Gemini API key (optional)", }, }, required: ["project_path", "theme", "style", "length"], }, }, { name: "implement_scenario", description: "Implement a generated scenario into the RPG Maker MZ project", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, scenario: { type: "object", description: "Generated scenario object", }, }, required: ["project_path", "scenario"], }, }, { name: "generate_and_implement_scenario", description: "Generate and immediately implement a complete RPG scenario (all-in-one)", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, theme: { type: "string", description: "Theme or genre of the game", }, style: { type: "string", description: "Style or tone", }, length: { type: "string", enum: ["short", "medium", "long"], description: "Length of the game scenario", }, api_key: { type: "string", description: "Gemini API key (optional)", }, }, required: ["project_path", "theme", "style", "length"], }, }, { name: "generate_scenario_variations", description: "Generate multiple variations of a scenario for comparison", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to the RPG Maker MZ project directory", }, theme: { type: "string", description: "Theme or genre", }, style: { type: "string", description: "Style or tone", }, length: { type: "string", enum: ["short", "medium", "long"], description: "Length of scenarios", }, count: { type: "number", description: "Number of variations to generate", }, api_key: { type: "string", description: "Gemini API key (optional)", }, }, required: ["project_path", "theme", "style", "length", "count"], }, }, { name: "autonomous_create_game", description: "Autonomously create a complete RPG game from a concept. This tool orchestrates all game creation steps: project setup, scenario generation, battle system, quests, assets, balancing, and optimization. Perfect for rapid game prototyping with minimal input.", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path where the game project will be created", }, concept: { type: "string", description: "Game concept/theme (e.g., 'fantasy adventure with dragons', 'cyberpunk detective story', 'space opera epic')", }, game_title: { type: "string", description: "Game title (auto-generated from concept if not provided)", }, length: { type: "string", enum: ["short", "medium", "long"], description: "Game length - short: 1-2hrs, medium: 3-5hrs, long: 8-12hrs", }, difficulty: { type: "string", enum: ["easy", "normal", "hard"], description: "Game difficulty level", }, generate_assets: { type: "boolean", description: "Whether to generate game assets using AI (default: true)", }, asset_count: { type: "object", properties: { characters: { type: "number", description: "Number of character sprites to generate", }, enemies: { type: "number", description: "Number of enemy sprites to generate", }, tilesets: { type: "number", description: "Number of tilesets to generate", }, }, description: "Asset generation counts", }, optimize: { type: "boolean", description: "Whether to optimize the project after creation (default: true)", }, api_key: { type: "string", description: "Gemini API key (optional, uses GEMINI_API_KEY env var if not provided)", }, }, required: ["project_path", "concept"], }, }, { name: "register_resource", description: "Register a resource (template, asset, data) for reuse across the project", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Project path" }, resource_id: { type: "string", description: "Unique resource ID" }, resource_type: { type: "string", enum: ["template", "asset", "scenario", "data", "custom"], description: "Resource type" }, name: { type: "string", description: "Resource name" }, description: { type: "string", description: "Resource description" }, content: { type: "object", description: "Resource content (any JSON data)" }, tags: { type: "array", items: { type: "string" }, description: "Tags for categorization" }, }, required: ["project_path", "resource_id", "resource_type", "name", "content"], }, }, { name: "register_prompt_template", description: "Register a reusable prompt template with variable placeholders and resource references", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Project path" }, prompt_id: { type: "string", description: "Unique prompt ID" }, name: { type: "string", description: "Prompt name" }, description: { type: "string", description: "Prompt description" }, template: { type: "string", description: "Prompt template with {{variable}} placeholders" }, variables: { type: "array", items: { type: "string" }, description: "List of variable names" }, resource_refs: { type: "array", items: { type: "string" }, description: "Referenced resource IDs" }, }, required: ["project_path", "prompt_id", "name", "template", "variables"], }, }, { name: "execute_prompt", description: "Execute a prompt template with provided variables and resource references", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Project path" }, prompt_id: { type: "string", description: "Prompt template ID" }, variables: { type: "object", description: "Variables to fill in the template" }, }, required: ["project_path", "prompt_id", "variables"], }, }, { name: "list_resources", description: "List all registered resources with optional filtering", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Project path" }, type: { type: "string", description: "Filter by resource type" }, tags: { type: "array", items: { type: "string" }, description: "Filter by tags" }, }, required: ["project_path"], }, }, { name: "search_database", description: "Search game database (actors, enemies, skills, items, etc.) with filters", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Project path" }, types: { type: "array", items: { type: "string" }, description: "Database types to search" }, name_contains: { type: "string", description: "Filter by name containing text" }, id_min: { type: "number", description: "Minimum ID" }, id_max: { type: "number", description: "Maximum ID" }, }, required: ["project_path"], }, }, { name: "analyze_assets", description: "Analyze all project assets, detect usage, find unused assets, and generate optimization recommendations", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Project path" }, }, required: ["project_path"], }, }, ], }; });