---
title: Introduction
description: What mc-protocol is, what it does for you, and what it leaves to you.
---

Build a custom Minecraft server, connect a bot, or inspect packets through a proxy. mc-protocol handles the network encoding so you can work with named packets and JavaScript objects.

It ships **Minecraft Java 26.2 (protocol 776)**, with readers and writers for 257 packets. The protocol version is negotiated per connection at the handshake, and `import { Server } from "mc-protocol/26.2"` pins a version explicitly; the root import always tracks the newest one. You own the game logic; the library handles framing, compression, and packet encoding.

It gives you three classes and a few helpers:

- `Server` accepts TCP connections, parses packets, and by default walks each player through login and configuration for you.
- `Client` opens a connection to a server (or wraps a socket the server accepted) and gives you `sendPacket` plus events for everything it receives.
- `Proxy` accepts players, opens an upstream connection for each one, and forwards packets by name with optional handlers.
- `helpers.ChunkHelper` builds lit `LevelChunkWithLight` payloads so you can put a player on solid ground without writing a chunk serializer.
- `helpers.createSlot("diamond_sword", options)` builds a custom item stack by name. `helpers.emptySlot()` clears a slot, and `helpers.getItemId(name)` resolves names for fields that need a numeric ID.
- `helpers.createCommandTree([...])` turns nested `literal` / `argument` nodes into the Commands packet, indices and flags included.
- `helpers.createParticle("dust", { color: "#ff8800" })` and `helpers.createParticlePacket(...)` build particle values and the LevelParticles payload by name.
- `helpers.createEntityMetadata("player", { glowing: true, health: 20 })` produces SetEntityData entries from named fields for verified entity kinds.

```ts
import { Server } from "mc-protocol";

const server = new Server({ port: 25565 });

server.on("playerJoin", (client, session) => {
  console.log(`${session.username} joined`);
});
```

## What it handles

- Frame length prefixes and zlib compression, including the `LoginCompression` switch.
- Connection state tracking on both directions independently (see [Connection states](/docs/connection-states)).
- Protocol version negotiation from `Intension`, with a clear `LoginDisconnect` for versions that are not built in (see [Versions](/docs/versions)).
- Offline-mode login, known packs, registry data, tags, and `FinishConfiguration` when `autoInit` is on.
- Keep-alive pings, latency measurement, and dropping clients that stop answering when `autoKeepAlive` is on.
- Parsing every packet into a plain object with named fields. Most fields also accept the vanilla name as an alias when you write them.

## What it does not handle

- Online mode. There is no encryption or Mojang session verification; `autoInit` assigns each player an offline profile.
- Game logic. Nothing moves, ticks, or persists. You send the packets; the library encodes them.
- Vanilla world generation. `createNoiseWorld` can make deterministic terrain, caves, ores, trees, and reusable structures, but uses one biome ID and does not reproduce vanilla terrain, aquifers, loot, or mobs.

See [Limitations](/docs/limitations) for the current list of known gaps.

## Where to go next

- [Installation](/docs/installation) to add the library to a project.
- [Your first server](/docs/server) for a complete join sequence that puts a player on generated terrain.
- [Packets](/packets) for the field-level reference of every packet.
- [Types](/types) for the primitive wire types the packets are built from.