RPG Maker MZ MCP Server

Instructions

Implementation Reference

• src/index.ts:553-583 (registration)

  Registration of the generate_scenario MCP tool in the ListToolsRequestHandler, defining the tool name, description, input schema matching ScenarioGenerationRequest.
  { 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"], }, },
• src/index.ts:1290-1302 (handler)

  MCP server handler dispatch for generate_scenario tool call, which extracts arguments, creates ScenarioGenerationRequest, calls the implementation function, and returns JSON result.
  case "generate_scenario": { const request: ScenarioGenerationRequest = { projectPath: args.project_path as string, theme: args.theme as string, style: args.style as string, length: args.length as "short" | "medium" | "long", apiKey: args.api_key as string | undefined, }; const result = await generateScenarioWithGemini(request); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], }; }
• src/scenario-generation.ts:68-131 (handler)

  Primary handler function implementing generate_scenario logic: validates input, builds detailed JSON prompt for RPG scenario, calls Gemini API with structured generation config, parses JSON response into GeneratedScenario structure.
  export async function generateScenarioWithGemini(request: ScenarioGenerationRequest): Promise<{ success: boolean; scenario?: GeneratedScenario; error?: string }> { try { // Validate inputs await validateProjectPath(request.projectPath); Validator.requireString(request.theme, "theme"); Validator.requireString(request.style, "style"); Validator.requireEnum(request.length, "length", ["short", "medium", "long"] as const); const apiKey = validateGeminiAPIKey(request.apiKey); await Logger.info("Generating scenario with Gemini", { projectPath: request.projectPath, theme: request.theme, style: request.style, length: request.length }); const prompt = buildScenarioPrompt(request); const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp:generateContent?key=${apiKey}`; const response = await APIHelper.fetchWithRetry( url, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ contents: [{ parts: [{ text: prompt }] }], generationConfig: { temperature: 1.0, topK: 40, topP: 0.95, maxOutputTokens: 8192, responseMimeType: "application/json" } }) }, 3 ); const data = await response.json(); const scenarioText = data.candidates?.[0]?.content?.parts?.[0]?.text; if (!scenarioText) { return { success: false, error: "No scenario generated" }; } const scenario = JSON.parse(scenarioText) as GeneratedScenario; await Logger.info("Scenario generated successfully", { mapsCount: scenario.maps?.length, charactersCount: scenario.characters?.length, eventsCount: scenario.events?.length }); return { success: true, scenario }; } catch (error) { await Logger.error("Failed to generate scenario", { request, error }); return createErrorResponse(error); } }
• src/scenario-generation.ts:21-27 (schema)

  Input schema definition (TypeScript interface) for generate_scenario tool parameters, matching the MCP inputSchema.
  export interface ScenarioGenerationRequest { projectPath: string; theme: string; style: string; length: "short" | "medium" | "long"; apiKey?: string; }
• src/scenario-generation.ts:29-131 (schema)

  Output schema (GeneratedScenario interface) defining the structure of the generated RPG scenario JSON.
  export interface GeneratedScenario { title: string; synopsis: string; maps: Array<{ id: number; name: string; description: string; width: number; height: number; }>; characters: Array<{ id: number; name: string; classId: number; className: string; description: string; }>; events: Array<{ mapId: number; eventId: number; name: string; x: number; y: number; dialogues: string[]; }>; items: Array<{ id: number; name: string; description: string; type: string; }>; skills: Array<{ id: number; name: string; description: string; mpCost: number; }>; } export async function generateScenarioWithGemini(request: ScenarioGenerationRequest): Promise<{ success: boolean; scenario?: GeneratedScenario; error?: string }> { try { // Validate inputs await validateProjectPath(request.projectPath); Validator.requireString(request.theme, "theme"); Validator.requireString(request.style, "style"); Validator.requireEnum(request.length, "length", ["short", "medium", "long"] as const); const apiKey = validateGeminiAPIKey(request.apiKey); await Logger.info("Generating scenario with Gemini", { projectPath: request.projectPath, theme: request.theme, style: request.style, length: request.length }); const prompt = buildScenarioPrompt(request); const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp:generateContent?key=${apiKey}`; const response = await APIHelper.fetchWithRetry( url, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ contents: [{ parts: [{ text: prompt }] }], generationConfig: { temperature: 1.0, topK: 40, topP: 0.95, maxOutputTokens: 8192, responseMimeType: "application/json" } }) }, 3 ); const data = await response.json(); const scenarioText = data.candidates?.[0]?.content?.parts?.[0]?.text; if (!scenarioText) { return { success: false, error: "No scenario generated" }; } const scenario = JSON.parse(scenarioText) as GeneratedScenario; await Logger.info("Scenario generated successfully", { mapsCount: scenario.maps?.length, charactersCount: scenario.characters?.length, eventsCount: scenario.events?.length }); return { success: true, scenario }; } catch (error) { await Logger.error("Failed to generate scenario", { request, error }); return createErrorResponse(error); } }