Content
# EggTart
MCBE WebSocket Toolset — Region Management, Building, Querying, MCP Services
## Features
- **Sword Tracking Selection** — Hold a Netherite Sword and right-click to select points 1→2→Create a region
- **Wooden Sword Deletion** — Hold a Wooden Sword and right-click on an existing region to directly delete it
- **Region Particle Frame** — Real-time particle frame visualization of region boundaries
- **Water Detection** — Detect if a block contains water
- **Scan to File** — Three-stage concurrent scanning of region block data, outputting JSON
- **JS Script Batch Building** — Execute JS in a VM sandbox using `setBlock`/`fillBlock` relative coordinates to place blocks
- **MCP Integration** — 7 tools for LLM to directly control the game
## Quick Start
```bash
npm install
```
Edit `config.json`:
```json
{
"playerName": "Your Game Name",
"port": "8000"
}
```
Start:
```bash
npm run build
npm start
```
In-game, execute `/wsserver localhost:8000` to connect, and if "EggTart is ready" appears in the console, it is successful.
## MCP Integration
EggTart has a built-in MCP server (stdio transmission) and has registered 7 tools:
| Tool | Description |
|------|-------------|
| `mcbe_create_region_at` | Select coordinates and create a region |
| `mcbe_list_regions` | List all regions and their sizes |
| `mcbe_get_region` | Query details of a specified region |
| `mcbe_delete_region` | Delete a region |
| `mcbe_scan_region` | Scan region blocks to a file (performance warning) |
| `mcbe_run_command` | Execute MCBE commands and return output |
| `mcbe_run_script` | Execute JS building scripts within a region |
| `mcbe_get_player_info` | Get player position, direction, and dimension |
### opencode.json Configuration
Project-level (`opencode.json`, placed in the EggTart directory):
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"eggtart": {
"type": "local",
"command": ["node", "dist/main.js"]
}
}
}
```
Global configuration (`~/.config/opencode/opencode.json`) requires an absolute path:
```json
{
"mcp": {
"eggtart": {
"type": "local",
"command": ["node", "<absolute path to EggTart>/dist/main.js"]
}
}
}
```
Other MCP clients (Claude Code, etc.) have a similar format:
```json
{
"mcpServers": {
"eggtart": {
"command": "node",
"args": ["<absolute path to EggTart>/dist/main.js"]
}
}
}
```
## In-game Operations
| Operation | Effect |
|-----------|--------|
| Hold a Netherite Sword and right-click on a block | Select point 1 → Select point 2 → Create a region |
| Switch to a different hotbar and back | State is preserved, continue selecting points |
| Hold a Wooden Sword and right-click on a region | Delete the pointed region |
| `!help` | View chat command list |
| `!setp1/!setp2` | Manually set selection points |
| `!block` | Query block information |
| `!waterlog` | Detect block waterlogging |
| `!scan` | Scan region to a file |
| `!ticking` | Manage constantly loaded chunks |
## Architecture
```
config.json → Server → GameLoop (limited to 100) → WorldInitialize
↓
MCP Server (stdio)
```
- **GameLoop** limits the queue to 100 concurrent operations, automatically queuing excess operations
- **Lane** system uses an independent channel for high-frequency operations like particles and region frames
- **Path Resolution** automatically adapts to `tsx` development mode and `node dist/` compilation mode
- **Language Data** lazily loads based on the detected game language, without pre-reading everything
- **MCP Service** and WS service start in the same process, accessible globally through `GameLoop.instance`
## Development
```bash
npm run dev # tsx watch with hot reloading (for development)
npm run build # Compile to dist/
npm run lint # ESLint check
npm run test # Vitest testing
```
Ensure `npm run lint` and `npm run build` have zero errors before submission.
## Acknowledgements
- [socket-be](https://github.com/tutinoko2048/SocketBE) (MIT) — MCBE WebSocket communication library
## License
MIT 1cyberlangke1
