RPG Maker MZ/MV MCP Server

Instructions

Implementation Reference

• src/tools/mapTools.ts:23-88 (handler)

  The 'createMap' function in src/tools/mapTools.ts implements the tool logic for creating a new map in the project.

  export async function createMap(
    projectPath: string,
    options: {
      displayName?: string;
      width?: number;
      height?: number;
      tilesetId?: number;
      scrollType?: number;
      disableDashing?: boolean;
      encounterStep?: number;
      note?: string;
      parentId?: number;
      name?: string;
    } = {}
  ): Promise<{ mapId: number; map: MapData }> {
    const width = options.width || 17;
    const height = options.height || 13;
    const tilesetId = options.tilesetId || 1;
    const displayName = options.displayName || '';
    const scrollType = options.scrollType || 0;
    const disableDashing = options.disableDashing || false;
    const encounterStep = options.encounterStep || 30;
    const note = options.note || '';
    const parentId = options.parentId !== undefined ? options.parentId : 0;
    const mapName = options.name || '';
  
    // Find next available map ID
    const mapId = await getNextMapId(projectPath);
  
    // Create the data array (width * height * 6 layers, all zeros)
    const data = new Array(width * height * 6).fill(0);
  
    // Build the map object
    const map: MapData = {
      autoplayBgm: false,
      autoplayBgs: false,
      battleback1Name: '',
      battleback2Name: '',
      bgm: { name: '', pan: 0, pitch: 100, volume: 90 },
      bgs: { name: '', pan: 0, pitch: 100, volume: 90 },
      disableDashing,
      displayName,
      encounterList: [],
      encounterStep,
      height,
      width,
      parallaxLoopX: false,
      parallaxLoopY: false,
      parallaxName: '',
      parallaxShow: true,
      parallaxSx: 0,
      parallaxSy: 0,
      scrollType,
      specifyBattleback: false,
      tilesetId,
      data,
      events: [null],
      ...(note ? { note } : {}),
    };
  
    // Write the map file
    const mapPath = getMapPath(projectPath, mapId);
    await writeJsonFile(mapPath, map);
  
    // Update MapInfos.json to register the new map
    const mapInfosPath = getDataPath(projectPath, 'MapInfos.json');

• src/index.ts:474-521 (schema)

  The 'create_map' tool definition and schema are registered in src/index.ts within the tool list.

    name: 'create_map',
    description: 'Create a new map with specified dimensions and properties. Returns the new map ID and map data.',
    inputSchema: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          description: 'Map name as shown in the editor (e.g. "Fantasy City"). Defaults to "MAP{NNN}"',
        },
        width: {
          type: 'number',
          description: 'Map width in tiles (default: 17)',
        },
        height: {
          type: 'number',
          description: 'Map height in tiles (default: 13)',
        },
        displayName: {
          type: 'string',
          description: 'Display name shown to the player when entering the map',
        },
        tilesetId: {
          type: 'number',
          description: 'Tileset ID to use. 1=Overworld, 2=Outside, 3=Inside, 4=Dungeon, 5=SF Outside, 6=SF Inside (default: 2)',
        },
        scrollType: {
          type: 'number',
          description: 'Scroll type: 0=No Loop, 1=Loop Vertically, 2=Loop Horizontally, 3=Loop Both (default: 0)',
        },
        disableDashing: {
          type: 'boolean',
          description: 'Whether to disable dashing on this map (default: false)',
        },
        encounterStep: {
          type: 'number',
          description: 'Steps between random encounters, 0 to disable (default: 30)',
        },
        note: {
          type: 'string',
          description: 'Note field for plugin metadata or comments',
        },
        parentId: {
          type: 'number',
          description: 'Parent map ID in the editor hierarchy. 0 = root level (default: 0)',
        },
      },
    },
  },

• src/index.ts:756-757 (registration)

  The 'create_map' tool is handled in the 'executeToolFunction' method in src/index.ts, which delegates to the 'mapTools.createMap' handler.

  case 'create_map':
    return await mapTools.createMap(this.projectPath, args);