minecraft-toolkit

Lightweight Mojang player utilities (profile, skin, UUID) for Node, Vite, and edge projects.

This toolkit wraps Mojang APIs. Rate limits and availability still apply. Write endpoints (name change, skin upload) are not yet included.

Installation

# ✨ Auto-detect
npx nypm install minecraft-toolkit

# npm
npm install minecraft-toolkit

# yarn
yarn add minecraft-toolkit

# pnpm
pnpm install minecraft-toolkit

# bun
bun install minecraft-toolkit

# deno
deno install minecraft-toolkit

Core Helpers

import {
  fetchPlayerProfile,
  fetchPlayerSkin,
  fetchPlayerUUID,
  fetchPlayerSummary,
  fetchNameHistory,
  fetchPlayers,
  resolvePlayer,
  fetchSkinMetadata,
} from "minecraft-toolkit";

const profile = await fetchPlayerProfile("26bz");
const summary = await fetchPlayerSummary("26bz");
const skin = await fetchPlayerSkin("26bz");
const uuid = await fetchPlayerUUID("26bz");
const history = await fetchNameHistory("069a79f444e94726a5befca90e38aaf5");
const batch = await fetchPlayers(["Notch", "26bz"], { delayMs: 50 });
const resolved = await resolvePlayer("069a79f444e94726a5befca90e38aaf5");
const skinMeta = await fetchSkinMetadata("26bz");

Helpers are HTTP-agnostic and run anywhere fetch exists (Node 18+, Bun, Workers). All errors surface as MinecraftToolkitError.

Texture & Identity Utilities

import {
  isValidUsername,
  isUUID,
  normalizeUUID,
  uuidWithDashes,
  uuidWithoutDashes,
  getSkinURL,
  getCapeURL,
  getSkinModel,
  extractTextureHash,
} from "minecraft-toolkit";

isValidUsername("26bz"); // true
uuidWithDashes("069a79f444e94726a5befca90e38aaf5");
const skinUrl = getSkinURL(await fetchPlayerProfile("26bz"));
const hash = extractTextureHash(skinUrl);
const model = getSkinModel(skinUrl); // "slim" | "classic"

Skin Metadata & Color Sampling

import { fetchSkinMetadata, computeSkinDominantColor } from "minecraft-toolkit";

const meta = await fetchSkinMetadata("26bz", {
  dominantColor: true,
  sampleRegion: { x: 8, y: 8, width: 8, height: 8 },
});

console.log(meta.dominantColor); // e.g. "#f2d2a9"

const accent = await computeSkinDominantColor(meta.skin.url, {
  x: 40,
  y: 8,
  width: 8,
  height: 8,
});

Account Helpers

A valid Microsoft/Xbox Live access token is required for minecraftservices.com endpoints. Missing or expired tokens throw MinecraftToolkitError with statusCode: 401.

import {
  fetchNameChangeInfo,
  checkNameAvailability,
  validateGiftCode,
  fetchBlockedServers,
} from "minecraft-toolkit";

const accessToken = process.env.MC_ACCESS_TOKEN;

const windowInfo = await fetchNameChangeInfo(accessToken);
const availability = await checkNameAvailability("fresh_name", accessToken);
const isGiftValid = await validateGiftCode("ABCD-1234", accessToken);
const blockedServer = await fetchBlockedServers(); // no token required

validateGiftCode returns true/false for 200/404 responses without throwing.

Server Status Helpers

Probe Java and Bedrock servers without bringing your own RakNet/TCP logic.

import {
  fetchServerStatus,
  fetchJavaServerStatus,
  fetchBedrockServerStatus,
} from "minecraft-toolkit";

const javaStatus = await fetchJavaServerStatus({ host: "mc.hypixel.net", port: 25565 });
const bedrockStatus = await fetchBedrockServerStatus({ host: "play.example.net", port: 19132 });

// fetchServerStatus picks the right probe based on the `edition` field
const autoStatus = await fetchServerStatus({ host: "my.realm.net", edition: "bedrock" });

console.log(javaStatus.players.online, bedrockStatus.motd.text);

Both helpers normalize MOTD text, favicon/Base64 icons, latency, and version info. Errors surface as MinecraftToolkitError with contextual status codes.

Minecraft Formatting Renderer

Convert legacy § or & codes into safe HTML fragments or CSS class spans.

import { toHTML, generateCSS, stripCodes, hasCodes, convertPrefix } from "minecraft-toolkit";

const motd = "§aWelcome §lHeroes§r!";

const inline = toHTML(motd); // <span style="color: #55ff55">Welcome ...</span>

const classes = toHTML(motd, { mode: "class", classPrefix: "mc" });
const css = generateCSS(); // drop into a <style> tag

stripCodes(motd); // "Welcome Heroes!"
hasCodes(motd); // true
convertPrefix("&aHi", "toSection"); // "§aHi"

getMaps() exposes the color and format metadata if you want to build custom renderers.

License

Published under the MIT license. Made by 26bz