# Minecraft Agent Body

Give an AI agent a bounded, inspectable body in **Minecraft Java Edition**.

This project is deliberately model-neutral. It does not contain an LLM, an API key, a Discord bot, or JNAIQ. Instead, it exposes one Mineflayer-controlled Minecraft player through:

- **MCP over stdio** for Claude, Codex, and other MCP hosts.
- A **loopback-only JSON adapter** for JNAIQ, Discord bots, and custom agent loops.

The model remains the decision-maker. The body reports observations and executes named actions.

## Current status

**Implemented and locally tested without Minecraft:** configuration validation, event cursors, in-band tool failures, MCP startup, loopback-only HTTP transport, and package checks.

**Requires your live environment to validate:** joining your server, Microsoft device-code login, pathfinding, mining, crafting, placing, combat, eating, and sleeping. Minecraft protocol support follows Mineflayer's supported versions.

## Requirements

- Node.js 20 or newer
- A Minecraft Java server you are allowed to join
- For online-mode servers, a Microsoft account that owns Minecraft Java Edition
- An MCP host or a custom program that can call the JSON adapter

## Install

```bash
git clone https://github.com/several-dozen-lizards/minecraft-agent-body.git
cd minecraft-agent-body
npm install
npm test
```

Copy `.env.example` to `.env` if your launcher loads environment files, or set the variables in the MCP host configuration. The program does not parse `.env` by itself so secrets stay under the control of the host that launches it.

## Fast local test

Start a local Minecraft Java server in offline mode, then:

```bash
npm run start:http
```

In another terminal:

```bash
curl http://127.0.0.1:31822/health
curl -X POST http://127.0.0.1:31822/call -H "Content-Type: application/json" -d '{"name":"minecraft_connect","arguments":{}}'
curl -X POST http://127.0.0.1:31822/call -H "Content-Type: application/json" -d '{"name":"minecraft_status","arguments":{}}'
```

PowerShell equivalents are in [docs/QUICKSTART_WINDOWS.md](docs/QUICKSTART_WINDOWS.md).

## Tools

The first public cut includes:

`minecraft_connect`, `minecraft_disconnect`, `minecraft_status`, `minecraft_inventory`, `minecraft_events`, `minecraft_look`, `minecraft_goto`, `minecraft_follow`, `minecraft_stop`, `minecraft_collect`, `minecraft_dig`, `minecraft_place`, `minecraft_craft`, `minecraft_equip`, `minecraft_eat`, `minecraft_sleep`, `minecraft_attack`, and `minecraft_say`.

`minecraft_say` refuses messages beginning with `/`. This prevents the chat tool from silently becoming a server-operator console.

## Connect a brain

- [Claude and generic MCP hosts](docs/CONNECT_MCP.md)
- [JNAIQ or a Discord bot](docs/CONNECT_HTTP.md)
- [Windows quick start](docs/QUICKSTART_WINDOWS.md)
- [Minecraft server and live acceptance](docs/SERVER_SETUP.md)
- [Publishing as its own GitHub repository](docs/PUBLISHING.md)
- [Safety and threat boundaries](SECURITY.md)

## Design promises

- The core has no provider SDK and no model preference.
- Credentials are read from the launching environment and never returned by a tool.
- The JSON adapter refuses non-loopback binds.
- Long actions do not silently stack; a second action receives `BUSY` until the current action finishes or `minecraft_stop` is called.
- Optional coordinate bounds constrain movement and world mutation.
- Every action returns structured success or a structured, actionable error.
- Events and action receipts can be consumed incrementally by cursor.

## Not the same as the 141-hour visual benchmark

That experiment had the model operate ordinary keyboard and mouse controls from visual observations. This project gives the agent a structured Minecraft body, which is more reliable and dramatically cheaper to run. A later optional visual module can add screenshots without making them the only sense available.

## License

MIT. Minecraft is a trademark of Microsoft/Mojang; this independent project is not affiliated with or endorsed by them.