# Foreman > A multi-tool for Minecraft server owners, admins and plugin developers. A Fabric client mod (any server) and an optional Paper plugin for Minecraft: a packet viewer, a HUD inspector, plugin locations in the world, dev-server tools, AI chats in game, MCP servers for outside agents, world tools, skills and integrations for other plugins, and APIs for plugin developers. Every page in one file: https://qore-games.github.io/foreman/llms-full.txt ## Overview - [Home](https://raw.githubusercontent.com/qore-games/foreman/main/docs/index.md): A multi-tool for Minecraft server owners, admins and plugin developers. See what your server sends and draws, debug your plugins on a running server, and work with an AI that can do the same: in game, or from your terminal. ## Getting started - [Getting started](https://raw.githubusercontent.com/qore-games/foreman/main/docs/getting-started/index.md): 1. Install the client mod. That's all you need on any server. 2. Install the server plugin on servers where you want the server tools. 3. First run: the hub, a first packet recording, a first chat. 4. Using a Flatpak launcher? Let it start Claude Code or opencode. - [Install the client](https://raw.githubusercontent.com/qore-games/foreman/main/docs/getting-started/install-client.md): Put `foreman-1.0.0.jar` in your instance's `mods/` folder, with: - [Install the server plugin](https://raw.githubusercontent.com/qore-games/foreman/main/docs/getting-started/install-server.md): The plugin is optional: the client mod works on any server. Install it where you want the dev-server tools, the world tools or tools other plugins publish. - [First run](https://raw.githubusercontent.com/qore-games/foreman/main/docs/getting-started/first-run.md): Press ++h++. The hub has everything on one screen: a rail of sections on the left, grouped by what they're for (AI, World, Debug), with Keys and Settings at the bottom. ++l++ opens it on Locations. See The hub. - [Flatpak launchers](https://raw.githubusercontent.com/qore-games/foreman/main/docs/getting-started/flatpak.md): If your launcher is a Flatpak (Prism Launcher from Flathub, for example), it can't start programs on your computer by default, so chats can't start Claude Code or opencode. Let it, once, then restart the launcher: ## Client - [Client](https://raw.githubusercontent.com/qore-games/foreman/main/docs/client/index.md): The mod works on any server. Everything it adds starts from the hub (++h++): - [The hub](https://raw.githubusercontent.com/qore-games/foreman/main/docs/client/hub.md): ++h++ opens the hub, ++l++ opens it on Locations. A rail of sections on the left, grouped by what they're for, with each feature's settings on its own page: - [Packet viewer](https://raw.githubusercontent.com/qore-games/foreman/main/docs/client/packets.md): Records what the server and your client send each other, and helps find what floods the connection or stutters the client. Nothing runs while it isn't recording. - [HUD inspector](https://raw.githubusercontent.com/qore-games/foreman/main/docs/client/hud-inspector.md): Shows how the client lays out your server's HUD texts, glyph by glyph: what you need to build HUDs out of font glyphs without them shifting when the text changes. - [Locations and local sets](https://raw.githubusercontent.com/qore-games/foreman/main/docs/client/locations.md): Plugins send their locations (NPCs, spawns, regions, waypoints…) to players with the permission, and the mod draws them in the world: each **source** (a plugin) has **categories**, each shown or hidden. Staff can teleport to them and move them; the plugin receives the move and saves it. To send locations from your plugin, see the location API. - [Selection](https://raw.githubusercontent.com/qore-games/foreman/main/docs/client/selection.md): A box in the world, for the AI or your own commands. Press ++b++ (or use the hub's Selection section), then left click and right click the two corners, and drag the gizmo to adjust it. - [Plugin messages and helpers](https://raw.githubusercontent.com/qore-games/foreman/main/docs/client/plugin-messages.md): Logs the plugin messages (custom payloads) your client sends and receives, both ways: in the hub's **Debug → Plugin messages**, the last 500 as a row each — time, direction, a colour per channel, size and a preview. The header counts them (in / out / channels), **Pause** freezes the list so a fast stream holds still while you read, and you can filter by channel or text. Nothing is kept while logging is off. - [Keys and commands](https://raw.githubusercontent.com/qore-games/foreman/main/docs/client/keys-commands.md): Change any of them in the hub's Keys section (click the key, then press the new one: ++esc++ cancels, ++backspace++ unbinds) or in Minecraft's controls. ## AI - [AI](https://raw.githubusercontent.com/qore-games/foreman/main/docs/ai/index.md): Foreman doesn't ship a model or an account. The AI runs on your computer with **your own** Claude Code, opencode or OpenRouter account, and Foreman gives it tools: - [Chats](https://raw.githubusercontent.com/qore-games/foreman/main/docs/ai/chats.md): Press ++y++ (or `/ai`) to open the chats. Each chat has its own transcript and backend, and runs on its own: start one, switch to another while it works. The hub's Chats section lists them all, whatever the server, and the HUD shows the ones at work. - [Examples](https://raw.githubusercontent.com/qore-games/foreman/main/docs/ai/examples.md): Real runs, recorded in game and sped up. Each is one prompt in a chat (++y++) with Claude Code, on a dev server with the Foreman plugin; the transcript shows every tool the AI calls. - [Ask your AI to use Foreman](https://raw.githubusercontent.com/qore-games/foreman/main/docs/ai/ask-your-ai.md): Your AI (Claude Code, opencode, Cursor, any agent with MCP) can set Foreman up and build on it for you. These prompts are written for it: paste one into a session in your plugin's or server's folder. - [Workspaces](https://raw.githubusercontent.com/qore-games/foreman/main/docs/ai/workspaces.md): A workspace is a named set of folders that chats work in: a plugin's configs, its sources, a datapack, a resource pack. Make them in the hub's Workspaces section: - [Backends](https://raw.githubusercontent.com/qore-games/foreman/main/docs/ai/backends.md): Pick the backend of new chats in the hub's **AI → Agents**, with its settings under it. Each chat keeps the backend it started with. - [Outside agents (client MCP)](https://raw.githubusercontent.com/qore-games/foreman/main/docs/ai/outside-agents.md): The client runs a small MCP server on your computer (loopback only). Chats use it, and when you allow it, so can **AI sessions outside the game**: Claude Code in a terminal, or another agent on this computer. That's how you implement fast and test end to end: the agent edits your plugin in your editor, deploys it to your dev server, then plays the change in the running client (screens, commands, entities, items, packets, HUD) and reads what happened. - [Tool reference](https://raw.githubusercontent.com/qore-games/foreman/main/docs/ai/tools.md): Every tool the AI can use, by provider. In game, the hub's AI section (Tools) lists them with their full descriptions; `/ai tools` prints them to chat, and `/foreman tools [filter]` on the server lists the server's. ## Server plugin - [Server plugin](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/index.md): The Paper plugin runs an MCP server inside your Minecraft server. The client mod's chats connect to it, and so can any MCP client (Claude Code, opencode…). It brings: - [Setup and configuration](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/setup.md): 1. Put `foreman-server-1.0.0.jar` in `plugins/` (with FastAsyncWorldEdit for the world tools) and start the server. The log shows the MCP address, `http://127.0.0.1:25599/mcp` by default. 2. Join with the client mod and press ++y++, or connect another MCP client with the token Foreman made in `plugins/Foreman/mcp-token.txt` (from the server's folder): ```sh claude mcp add --transport http minecraft http://127.0.0.1:25599/mcp \ --header "Authorization: Bearer $(cat plugins/Foreman/mcp-token.txt)" ``` 3. For players on other machines, set `mcp.host: 0.0.0.0`. Each player with `foreman.client` gets their own token through the mod. The MCP server speaks plain HTTP: beyond a network you trust, put it behind TLS (a reverse proxy) or a VPN. - [Permissions and tokens](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/permissions.md): - **Personal tokens:** each player with `foreman.client` gets one through the mod when they join, kept in `tokens.yml`. Calls with it act as that player: the tools above then need `foreman.admin`. A player who loses `foreman.client` can't use theirs any more, and it's revoked when they next join. `/foreman token revoke ` revokes one; a new one comes on their next join. - **The server's token** (`mcp.token`, or `mcp-token.txt` that Foreman makes when it's empty): for other MCP clients (Claude Code in a terminal, scripts). It needs no permission: it's the console's. - [Dev-server tools](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/dev-tools.md): For an AI (or you) working on plugins against a dev server: they replace RCON, log files and guesses. With a personal token, the player needs `foreman.admin` (ops have it). - [Dupe testing](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/dupe-testing.md): Item duplication is the bug that wrecks an economy, and it almost always comes from a plugin mishandling an inventory. Foreman turns a dupe hunt into something you run on purpose: **count every item on the server, do the suspect action, count again.** A bigger total is a dupe, and the tools tell you which action and which plugin caused it. - [Skills](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/skills.md): A skill teaches the AI how to do one kind of task on your server: a plugin's commands and conventions, a workflow of yours ("open the market for the day", "set up a new arena"). It's a markdown file. - [Plugin integrations](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/integrations.md): Foreman works with other plugins through skills: for each plugin below, a skill teaches the AI its commands, files and pitfalls, and the AI runs them with `server_command`. Each skill is offered only while its plugin is enabled, and costs one line of the AI's instructions until a request needs it. A few plugins also get code tools, where their commands fall short. ## Server plugin / World building - [World tools](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/world-tools.md): With the plugin and FastAsyncWorldEdit, the AI can read and edit the world. It looks before it builds, works in steps, checks its work the way a player would walk it, and every change can be undone. Without FastAsyncWorldEdit these tools are off (`/foreman status` says so), and so are the areas, overlays and furniture that go with them. - [Building templates](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/building-templates.md): `build_structure` builds a whole building in one call: site levelling, foundation, walls, storeys, rooms and doors, walkable stairs, roof, furniture by room type, then a `check` of the result. Its layouts are built in (the archetypes); what goes into them comes from templates you can edit: - [World context](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/world-context.md): Each world carries its own settings, saved in the world itself (its persistent data), so they travel with the world file. The AI reads them with `get_context`; your plugins read them with `ForemanWorlds`. - [Schematic library](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/assets.md): `plugins/Foreman/assets/` holds your schematics for the AI: houses, stalls, trees, rocks, ruins… WorldEdit's schematics (`FastAsyncWorldEdit/schematics`) are listed too. - [Lessons and prompts](https://raw.githubusercontent.com/qore-games/foreman/main/docs/server/lessons-prompts.md): `plugins/Foreman/lessons.md` holds what the AI learned on your server, one `- ` line each: a mistake the checks missed, a rule of a zone, a tool trick. The AI records them with `learn` when you correct it, reads them at the start of every session, and `lessons` lists or removes them. Edit the file by hand too. ## For developers - [For developers](https://raw.githubusercontent.com/qore-games/foreman/main/docs/developers/index.md): Start with Add Foreman to your plugin: the repository, the dependency for Gradle (Kotlin or Groovy) or Maven, and a first tool or location in Java or Kotlin. - [Add Foreman to your plugin](https://raw.githubusercontent.com/qore-games/foreman/main/docs/developers/install.md): Foreman publishes three artifacts. Most plugins need one of the first two: - [Skills for your plugin](https://raw.githubusercontent.com/qore-games/foreman/main/docs/developers/skills.md): Teach the AI your plugin: its commands, its config files, how to test a change. A skill is markdown the AI reads when a request is about your plugin; it costs one line of the AI's instructions until then. - [ForemanTools](https://raw.githubusercontent.com/qore-games/foreman/main/docs/developers/foreman-tools.md): Publish tools the AI can call, next to Foreman's own, with your plugin as their provider. They show up in `/foreman tools`, in the client's hub and in every chat on the server. - [Location API](https://raw.githubusercontent.com/qore-games/foreman/main/docs/developers/locations-api.md): Show your plugin's locations (NPCs, spawns, regions, waypoints…) in the client mod, by **source** (your plugin) and **category**, and receive what staff do with them in the location editor: moves, renames, new locations. It works on any Paper server, with or without the Foreman plugin. - [ForemanWorlds](https://raw.githubusercontent.com/qore-games/foreman/main/docs/developers/foreman-worlds.md): Read what Foreman keeps in each world: its areas, points and profile. Use them to fill containers with loot, spawn NPCs at the spawns builds recorded, or turn areas into regions. The service is there when the Foreman plugin runs with FastAsyncWorldEdit (the world tools); otherwise `load` returns `null`. - [FurnitureProvider](https://raw.githubusercontent.com/qore-games/foreman/main/docs/developers/furniture.md): Foreman has no furniture of its own, and its furniture tools are world tools: they need FastAsyncWorldEdit on the server. A furniture plugin offers its furniture (models shown by display entities, with collision cells) by registering a `FurnitureProvider`. The AI then gets `list_furniture`, `place_furniture`, `remove_furniture` and furniture previews; `build_structure` furnishes rooms with `furniture:` entries of the room templates; `check`, `transform_region` and undo take the furniture into account. - [Network profiles](https://raw.githubusercontent.com/qore-games/foreman/main/docs/developers/network-profiles.md): The hardest item dupes need the client and server to disagree for a tick. Foreman's dupe testing runs the input side of that (action bursts in one tick), and two stock network profiles run the network side: `burst` holds the client's sends and sends them together at the end, and `ping_` adds n ms to each. A test names one as `network` on `inventory_actions`, and the profile is held around the burst only. The hook is open too: implement another condition against the client connection and register it. - [Building from source](https://raw.githubusercontent.com/qore-games/foreman/main/docs/developers/building.md): Requirements: JDK 25. ## Overview - [Security and privacy](https://raw.githubusercontent.com/qore-games/foreman/main/docs/security.md): Foreman gives an AI the hands of an admin: it runs commands, edits the world and reads logs. This page lists what it can reach, what leaves your computer and your server, and how to keep it to the people you trust. - [FAQ and known limits](https://raw.githubusercontent.com/qore-games/foreman/main/docs/faq.md): No. Packet recordings run only while you record, overlays are drawn only when they're on, and the client's MCP server only answers outside agents when you allow them. On the server, the dev-server tools only do work when called.