generate_scenario

Create complete RPG game scenarios with story, maps, characters, events, and items for RPG Maker MZ projects using AI generation based on theme, style, and length specifications.

Instructions

Generate a complete RPG game scenario using Gemini AI (story, maps, characters, events, items)

Input Schema

TableJSON Schema

Name	Required	Description
`api_key`	No	Gemini API key (optional)
`length`	Yes	Length of the game scenario
`project_path`	Yes	Path to the RPG Maker MZ project directory
`style`	Yes	Style or tone (e.g., 'lighthearted', 'dark', 'comedic', 'epic')
`theme`	Yes	Theme or genre of the game (e.g., 'fantasy adventure', 'sci-fi', 'horror')

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);
  }
}

RPG Maker MZ MCP Server