MCAI Assistant

MCAI – Minecraft AI Assistant

MCAI is a Fabric mod that lets AI manage your Minecraft server. This entire project is AI-developed.

TL;DR: Players type /ai how do I enchant a diamond sword?, AI answers. Someone swears? AI warns or kicks. Dangerous ops need admin approval.

Quick Start

| What | How |
|——|—–|
| Chat with AI | /ai <question> or !ai <question> |
| AI executes commands | /ai give me a diamond sword (admin approval) |
| AI batch commands | /ai build a redstone circuit (command chain, one approval) |
| Check behavior score | /aiscore |
| Search wiki | /aikb enchantment (online Wiki available) |
| Admin approve | /aiaccept <id> approve / /aireject <id> reject |
| Cancel pending | /aicancel cancel latest / /aicancel all cancel all |

Features

AI Chat

• Players use !ai or /ai to chat with AI
• AI has full server context (chat logs, weather, time, players)
• Multi-turn conversation with history
• Persona mode: switch AI persona with /aipersona — built-in villager, piglin, ender dragon, creeper themes, bilingual (ZH/EN), admins can add custom personas in config/mcai/personas/

Auto Behavior Review

• AI analyzes chat every 30 minutes
• Three-tier penalty: score deduction -> yellow card -> red card (kick)
• Admin messages are trusted; admins can declare server rules

Admin Approval

• Dangerous commands (op, ban, kick) require manual admin approval
• 3-minute timeout auto-cancels pending approvals
• Strict mode: only whitelisted safe commands skip approval
• AI text starting with / is blocked; all commands must go through the Tool system and the unified approval flow
• Command Chain: AI can batch multiple commands into a single approval unit (execute_command_chain), admin approves once to execute all, with configurable intervals between commands
• Player Cancel: Players can use /aicancel to cancel their own pending commands; AI receives cancellation notice and won’t retry the same command

Game Knowledge Base

• AI searches minecraft.wiki / zh.minecraft.wiki online for up-to-date game knowledge (language via wikiLanguage)
• Supports Chinese and English search, returns summaries and full page links

Installation

Requirements

• Minecraft Fabric server 26.x
• Java 25
• A DeepSeek API Key (or any OpenAI-compatible API)

Steps

1. Download the latest JAR
2. Place it in mods/ folder
3. Start the server to auto-generate config
4. Edit config/mcai/config.json, fill in your API Key
5. Config auto-reloads; or run /aireload manually

Single-Player Usage

The mod works in single-player too (no dedicated server required):

1. Install Fabric client (same version 26.x)
2. Place the JAR in .minecraft/mods/ folder
3. Launch the game and enter a single-player world
4. Config and commands are identical to the server setup
5. You are the world owner with full admin permissions by default
6. (Optional) Install Mod Menu for in-game config editing

Tip: The behavior review system is auto-disabled in single-player (no need to review yourself).

Commands

Player Commands

| Command | Description |
|———|————-|
| !ai <msg> /ai <msg> | Chat with AI |
| /aiscore | Check behavior score |
| /aicancel [id/all] | Cancel your own pending commands |

Admin Commands

| Command | Description |
|———|————-|
| /aiaccept <id> | Approve pending action |
| /aireject <id> | Reject pending action |
| /aiquery | List pending approvals (shows unique ids) |
| /aiclear | Clear AI chat history |
| /aireload | Manually reload config (auto-reloads on file change) |
| /airesetprompts | Reset prompt files to current built-in defaults |
| /aikb <keyword> | Search Wiki knowledge base |
| /aicontrol [chat/review] [on/off] | Toggle AI chat/review |
| /aikill | Destroy all AI threads |
| /aidebug start/stop/show/list/clear | Debug logging |
| /aipersona [list/set/current/view/reload] | Switch/view/reload AI persona |

Review Management

| Command | Description |
|———|————-|
| /aireview start | Trigger manual review |
| /aireview approve <id> | Approve kick |
| /aireview reject <id> | Reject kick |
| /aireview last | View last review result |
| /aireview last reasoning | View AI reasoning |

Test Commands (OP only)

| Command | Description |
|———|————-|
| /aitest score <player> | Check player behavior score |
| /aitest set <player> <score> | Set player behavior score |
| /aitest penalty <player> <points> | Simulate penalty |
| /aitest reset <player> | Reset player behavior score |
| /aitest review | Trigger manual review |
| /aitest chatlog | View chat log |

Configuration

File: config/mcai/config.json. Auto-reloads on change (or use /aireload).

| Key | Default | Description |
|—–|———|————-|
| apiEndpoint | https://api.deepseek.com | API endpoint (without /chat/completions, format varies by provider) |
| apiKey | "" | API key |
| model | deepseek-v4-flash | Model name |
| triggerPrefix | !ai | Chat trigger prefix |
| maxTokens | 2048 | Max response tokens |
| temperature | 0.75 | Response randomness (0-1) |
| thinkingLevel | 1 | Thinking level 0-3 |
| strictMode | true | Strict mode |
| aiCooldownSeconds | 60 | Non-admin AI cooldown (seconds) |
| aiMaxConcurrent | 3 | Max concurrent non-admin AI calls |
| compatibilityMode | false | Compatibility mode: send only basic fields for local APIs like LM Studio |
| enableStream | false | Streaming output (SSE), some APIs only support streaming mode |
| reviewIntervalMinutes | 30 | Review interval (min) |
| yellowCardThreshold | -30 | Yellow card threshold |
| redCardThreshold | -60 | Red card threshold |
| scoreRecoveryPerInterval | 5 | Score recovery per cycle |
| approvalTimeoutMinutes | 10 | Approval timeout (min) |
| wikiLanguage | "zh_cn" | AI online search language: zh_cn Chinese, en_us English (online search enabled by default) |
| apiConnectTimeoutSeconds | 10 | API connect timeout (seconds) |
| apiRequestTimeoutSeconds | 60 | API per-request timeout (seconds) |
| apiLoopTimeoutSeconds | 300 | Tool-call loop total timeout (seconds) |
| commandExecTimeoutSeconds | 30 | Per-command execution timeout (seconds) |
| wikiConnectTimeoutSeconds | 5 | Wiki search connect timeout (seconds) |
| wikiRequestTimeoutSeconds | 8 | Wiki search request timeout (seconds) |
| maxChainCommands | 10 | Max commands per chain |
| contextMaxChars | 20000 | Max context chars for AI (auto-truncated) |
| maxToolCalls | 15 | Max tool calls per conversation turn |
| activePersona | "default" | Current persona ID |
| personaLanguage | "" | Persona language override, empty=follow client language |
| promptLanguage | "zh_cn" | Built-in prompt language |
| enableChatInterception | true | Intercept chat and forward to AI |
| enableCommandExecution | true | Allow AI to execute commands |
| enableAutoReview | true | Enable auto behavior review |
| maxReviewCycles | 4 | Max review analysis cycles |
| systemPromptPath | "" | System prompt file (under config/mcai/) |
| reviewPromptPath | "" | Review prompt file |
| reviewApiEndpoint | "" | Review system API endpoint, empty=follow chat config |
| reviewApiKey | "" | Review system API key, empty=follow chat config |
| reviewModel | "" | Review system model, empty=follow chat config |

Prompt files system_prompt.txt / review_prompt.txt are auto-created on first start. Run /airesetprompts to force-sync them to the current built-in versions.

Knowledge Base

AI knowledge search is done via online Wiki — no manual data import needed.

Links

Github

License

MIT License