Minecraft Server MCP

Instructions

Implementation Reference

• src/core/BackupManager.ts:126-162 (handler)

  The restoreBackup method handles the logic of verifying the backup, creating a safety backup of the existing world folder, and extracting the selected backup.

  /** Restore a world from backup */
  restoreBackup(backupName: string): string {
    const tarName = backupName.endsWith(".tar.gz")
      ? backupName
      : `${backupName}.tar.gz`;
    const backupPath = path.join(this.backupDir, tarName);
  
    if (!fs.existsSync(backupPath)) {
      throw new Error(`Backup not found: ${backupPath}`);
    }
  
    // Extract the world name
    const baseName = tarName.replace(".tar.gz", "");
    const underscoreIdx = baseName.indexOf("_");
    const worldName =
      underscoreIdx > 0 ? baseName.substring(0, underscoreIdx) : baseName;
    const worldPath = path.join(this.serverDir, worldName);
  
    // Remove existing world if present
    if (fs.existsSync(worldPath)) {
      // Create a safety backup before overwriting
      const safetyName = `${worldName}_pre-restore_${Date.now()}`;
      const safetyPath = path.join(this.backupDir, `${safetyName}.tar.gz`);
      execSync(
        `tar -czf "${safetyPath}" -C "${this.serverDir}" "${worldName}"`,
        { timeout: 300000 }
      );
      fs.rmSync(worldPath, { recursive: true, force: true });
    }
  
    // Extract backup
    execSync(`tar -xzf "${backupPath}" -C "${this.serverDir}"`, {
      timeout: 300000,
    });
  
    return `World "${worldName}" restored from backup "${backupName}". The server must be restarted if it was running.`;
  }

• src/tools/backup-tools.ts:99-147 (registration)

  The restore_backup tool is registered here, including input validation via Zod and calling the BackupManager's restoreBackup method.

  server.tool(
    "restore_backup",
    "Restore a world from a backup. Creates a safety backup of the current world before overwriting. The server MUST be stopped first.",
    {
      backup_name: z
        .string()
        .describe("Backup name (with or without .tar.gz extension)"),
      confirm: z.boolean().describe("Must be true to confirm restoration"),
    },
    async ({ backup_name, confirm }) => {
      if (!confirm) {
        return {
          content: [
            {
              type: "text",
              text: "Restore cancelled. Set confirm=true to proceed.",
            },
          ],
        };
      }
  
      if (manager.isRunning()) {
        return {
          content: [
            {
              type: "text",
              text: "Cannot restore while the server is running. Stop the server first.",
            },
          ],
          isError: true,
        };
      }
  
      try {
        const result = backupManager.restoreBackup(backup_name);
        return { content: [{ type: "text", text: result }] };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Restore failed: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    }
  );