AI-Assisted Development

This guide documents the MCC AI-assisted development workflow as a real working loop, not a patch generator running on guesses. The goal is to give the agent an environment it can drive on its own: build MCC, start a local server, send commands, inspect logs, and repeat. Once that loop is in place, iteration is faster and regressions are easier to catch.

If you are looking for the broader contributor entry point first, start with Contributing and then come back here for the agent workflow.

The practical goal is a closed loop:

Index

• What This Workflow Covers
• Setup
• How The Harness Works
• Repository Tools
• Skills
• Standard Development Loop
• Testing And Validation
• Version Adaptation Notes
• Example Workflows

What This Workflow Covers

This is the workflow for:

• local MCC development
• local offline server testing
• AI-assisted debugging
• bot authoring
• protocol and version adaptation work
• documentation work that should still follow the same disciplined loop

It is built around two layers:

• repo tools in tools/, which do the actual work
• AI skills in .skills/, which tell the agent when and how to use those tools

Setup

You only do most of this once.

wsl --install

wsl --install -d Ubuntu

wsl --install --web-download -d Ubuntu

echo $SHELL

sudo apt update
sudo apt install git

sudo pacman -S git

brew install git

git --version

sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0

wget https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0

wget https://packages.microsoft.com/config/debian/13/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0

sudo pacman -S dotnet-sdk

brew install --cask dotnet-sdk

dotnet --version

sudo apt update
sudo apt install openjdk-21-jdk

sudo pacman -S jdk21-openjdk

brew install openjdk@21
sudo ln -sfn "$(brew --prefix openjdk@21)/libexec/openjdk.jdk" /Library/Java/JavaVirtualMachines/openjdk-21.jdk

java -version

sudo apt update
sudo apt install python3

sudo pacman -S python

brew install python@3.14

python3 --version

sudo apt update
sudo apt install tmux

sudo pacman -S tmux

brew install tmux

tmux -V

git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive

git submodule update --init --recursive

tools/decompile.sh --version 1.20.6

source "$HOME/Minecraft/Minecraft-Console-Client/tools/mcc-env.sh"

source ~/.bashrc

source "$HOME/Minecraft/Minecraft-Console-Client/tools/mcc-env.sh"

source ~/.zshrc

git --version
dotnet --version
java -version
python3 --version
tmux -V

type mc-start
type mcc-build
type mcc-run

How The Harness Works

AI agents do not get a rich interactive terminal in the same way a human does. That is why this workflow uses a harness instead of relying on live keyboard input.

The moving parts are:

• a local Minecraft server running in tmux
• mc-rcon for server-side commands such as /op, /give, /summon, or gamerule setup
• MCC started with MCC_FILE_INPUT=1
• FileInputBot, which watches mcc_input.txt and turns file lines into MCC commands or server chat
• logs from MCC and the local server, which the agent can inspect between runs

The result is simple: the agent can change code, rebuild, start the app, inject commands, and read the result without waiting for a human to sit in the terminal.

Repository Tools

These are the repo-level tools that make the workflow practical.

There is one more piece worth calling out:

• MinecraftClient/ChatBots/FileInputBot.cs is what makes file-driven command injection possible.
• It is loaded when MCC_FILE_INPUT=1 is set.
• mcc-run in tools/mcc-env.sh already sets that flag for you.

Skills

The tools above do the work. The skills in .skills/ tell the AI when to use them and what good output looks like.

The important distinction is this:

• repo tools are executable scripts and source files
• skills are instructions, references, templates, and workflow constraints for the AI

Some skills also carry their own bundled resources:

• mcc-integration-testing bundles scripts and a command matrix reference
• mcc-chatbot-authoring bundles references and bot templates
• skill-creator bundles scripts, eval tooling, and reviewer assets

Standard Development Loop

This is the core loop you should expect an agent to follow.

1. Start the local server

mc-start 1.20.6

Check the recent server output:

mc-log 1.20.6

2. Build MCC

mcc-build

3. Run MCC with file input enabled

mcc-run

The raw form looks like this:

MCC_FILE_INPUT=1 dotnet run --project MinecraftClient -c Release -- CursorBot - localhost:25565

4. Set up server state through RCON

Examples:

mc-rcon "op CursorBot"
mc-rcon "gamerule sendCommandFeedback true"
mc-rcon "give CursorBot diamond_sword 1"
mc-rcon "summon minecraft:armor_stand ~ ~ ~"

5. Drive MCC through mcc_input.txt

Examples:

mcc-cmd "inventory player list"
mcc-cmd "entity"
mcc-cmd "/gamemode creative"

Behavior:

• lines starting with / are sent as server commands or chat
• lines without / are treated as MCC internal commands first
• if a line is not an MCC internal command, it falls back to normal chat sending

6. Inspect the result

Read the MCC output and the server log, decide what changed, and either keep iterating or stop.

7. Rebuild and restart fast

mcc-reload

That is the usual tight loop for regression work.

Testing And Validation

There are two main testing styles in this workflow.

Manual validation

This is enough for smaller changes:

• join the local server
• grant operator privileges with mc-rcon
• run internal MCC commands through mcc-cmd
• trigger gameplay or server state changes through mc-rcon
• inspect logs for parsing errors, disconnects, or wrong output

Typical manual checks:

• inventory listing and creative item injection
• entity tracking after summon
• terrain and chunk handling after join
• chat and command flow
• explosion, particle, and sound events

Scripted full-spectrum testing

The mcc-integration-testing skill goes further. It bundles its own scripts under .skills/mcc-integration-testing/scripts/ and expects the shell helpers from ~/.zshrc.

Treat those scripts as skill-owned resources. Read the skill before running them directly, and do not assume they behave like top-level repo tools.

That skill is designed for repeatable offline validation of:

• chat
• slash commands
• MCC internal commands
• inventory handling
• entity handling
• particles and sounds
• TNT and explosion handling

Server settings that matter for AI-driven offline testing:

• eula=true
• online-mode=false
• enforce-secure-profile=false
• enable-rcon=true
• rcon.password=test123

If those are wrong, the loop gets noisy fast.

Version Adaptation Notes

Version work needs a stricter process than normal bug fixing.

The important rule is simple:

• for newer versions, especially 1.21.9+, use server data reports as the authority for items and blocks
• use decompiled source for implementation details, field order, codecs, and serializer logic
• do not stop at a palette diff; finish with a build and a live server test

The usual order is:

1. tools/decompile.sh --version <ver>
2. generate server reports from server.jar
3. run tools/diff_registries.py
4. regenerate the palettes that actually changed
5. update version routing and packet handling
6. build MCC
7. test against the real target version

That is exactly the sort of work mcc-version-adaptation is meant to guide.

Example Workflows

These are four common patterns this guide is meant to support.

Example 1: Debug a runtime regression

Use skills:

• mcc-dev-workflow
• csharp-best-practices

Typical loop:

mc-start 1.20.6
mcc-build
mcc-run
mc-rcon "op CursorBot"
mcc-cmd "inventory player list"
mcc-cmd "entity"

Then inspect the MCC output, patch the code, and use:

mcc-reload

Example 2: Build or repair a bot

Use skills:

• mcc-chatbot-authoring
• csharp-best-practices
• mcc-dev-workflow

Typical flow:

1. Decide whether this should be a standalone /script bot or a built-in bot.
2. Use the authoring skill's references and templates.
3. Build MCC.
4. Start a local server and join it.
5. Test the bot behavior through live commands, chat, or event-driven actions.
6. Make sure cleanup paths such as OnUnload() are correct.

For standalone script work, the skill defaults to /script unless built-in repo wiring is explicitly needed.

Example 3: Adapt MCC to a new Minecraft version

Use skills:

• mcc-version-adaptation
• mcc-dev-workflow
• mcc-integration-testing

Typical flow:

tools/decompile.sh --version 26.1

Generate server reports:

cd /tmp
java -DbundlerMainClass=net.minecraft.data.Main \
  -jar "$MCC_SERVERS/26.1/server.jar" \
  --reports --output /tmp/mc_reports

Run the registry diff:

python3 tools/diff_registries.py 1.21.10 26.1 --registry /tmp/mc_reports/reports/registries.json

Then regenerate the palettes that changed, update routing, build MCC, start a local server for the target version, and run live validation before calling the work done.

Example 4: Write or update documentation for the workflow itself

Use skills:

• humanizer
• skill-creator, if you are changing the skills rather than just the docs

Typical flow:

1. Re-read the relevant skill files and repo tools.
2. Update the guide so the written process matches the real process.
3. Keep the instructions concrete enough that another contributor can follow them without guessing.
4. If the workflow itself changed, update the relevant skill too instead of leaving the docs ahead of the automation.