MCC.js

⚠️ Experimental: This project is under active development and is not yet published to NPM. Use it by building from source as described below.

Typed multi-runtime WebSocket SDK for the Minecraft Console Client WebSocket bot.

What It Provides

• Typed MccClient for everyday use
• Low-level MccProtocolClient for raw protocol access
• Current MCC WebSocket command and event coverage, including:
  • SendPrivateMessage
  • GetItemTypeMappings
  • GetEntityTypeMappings
  • OnMccCommandResponse
  • OnWsConnectionClose
• Standard WebSocket transport design for Node.js, Bun, Deno, and browser-compatible builds

MCC Setup

Configure and load MCC's WebSocket bot:

MCC.LoadBot(new WebSocketBot("127.0.0.1", 8043, "CHANGE_THIS_PASSWORD"));

Then run the script from MCC.

• Typical MCC setup: script ChatBots/WebSocketBot.cs
• From this repository checkout: script MinecraftClient/config/ChatBots/WebSocketBot.cs

The bot listens at the root endpoint, for example ws://127.0.0.1:8043/.

Quick Setup

Build from Source

Because the package is not yet on NPM, clone the repository and compile it first:

git clone https://github.com/milutinke/MCC.js.git
cd MCC.js
npm install
npm run build

The compiled output is placed in the dist/ directory. All examples below import from that directory.

Node.js

import { MccClient, createMccUrl } from "./dist/index.js";

const client = new MccClient({
  url: createMccUrl({ host: "127.0.0.1", port: 8043 }),
  password: "CHANGE_THIS_PASSWORD",
  sessionId: "node-demo",
});

await client.connect();
console.log(await client.getUsername());
client.disconnect();

Bun

import { MccClient, createMccUrl } from "./dist/index.js";

const client = new MccClient({
  url: createMccUrl(),
  password: "CHANGE_THIS_PASSWORD",
  sessionId: "bun-demo",
});

await client.connect();
await client.logToConsole("hello from bun");
client.disconnect();

Deno

import { MccClient, createMccUrl } from "./dist/index.js";

const client = new MccClient({
  url: createMccUrl(),
  password: "CHANGE_THIS_PASSWORD",
  sessionId: "deno-demo",
});

await client.connect();
console.log(await client.getProtocolVersion());
client.disconnect();

Run with:

deno run --allow-net app.ts

Web Browser

Use a bundler such as Vite and point it at the local dist/ output:

npm create vite@latest mcc-browser-demo -- --template vanilla-ts
cd mcc-browser-demo
npm install

import { MccClient, createMccUrl } from "./dist/index.js";

const client = new MccClient({
  url: createMccUrl({ host: "127.0.0.1", port: 8043 }),
  password: "CHANGE_THIS_PASSWORD",
  sessionId: "browser-demo",
});

await client.connect();
console.log(await client.getUsername());
client.disconnect();

Browser execution testing is still deferred in this repository, but the package is structured around the standard browser WebSocket API.

Example: Basic Client

import { MccClient, createMccUrl } from "./dist/index.js";

const client = new MccClient({
  url: createMccUrl(),
  password: "CHANGE_THIS_PASSWORD",
  sessionId: "example-bot",
  reconnect: { attempts: 3, delayMs: 1_000 },
});

client.on("ready", () => {
  console.log("connected");
});

client.on("OnChatRaw", ({ text }) => {
  console.log(text);
});

await client.connect();

const username = await client.getUsername();
const protocolVersion = await client.getProtocolVersion();
const itemMappings = await client.getItemTypeMappings();

console.log({ username, protocolVersion, itemCount: Object.keys(itemMappings).length });

client.sendChat("hello from mcc.js");
await client.sendPrivateMessage("PlayerName", "private hello");

const response = await client.sendMccCommand("help");
console.log(response.status, response.result);

client.disconnect();

Example: Low-Level Protocol Client

import { MccProtocolClient, createMccUrl } from "./dist/index.js";

const client = new MccProtocolClient({
  url: createMccUrl(),
});

client.on("rawProtocolEvent", ({ event, rawData }) => {
  console.log(event, rawData);
});

await client.open();

const auth = await client.sendCommand("Authenticate", ["CHANGE_THIS_PASSWORD"]);
console.log(auth);

const session = await client.sendCommand("ChangeSessionId", ["low-level-demo"]);
console.log(session);

const username = await client.sendCommand("GetUsername");
console.log(username.message);

client.close();

Notes

• sendMccCommand() is serialized because OnMccCommandResponse has no request ID.
• The current MCC wire format uses OnWsCommandResponse.message, not result.
• OnChatPublic and OnChatPrivate use sender.
• Use getItemTypeMappings() and getEntityTypeMappings() instead of hard-coded version-sensitive numeric tables.

Documentation

• Package Guide
• Command Surface
• Event Surface

License

LGPL-2.0-only