Comparator

!(https://www.dropbox.com/scl/fi/qk3sqt46garmoyoqei3pa/comparator-banner.png?rlkey=mt61gg70qxlvond5sys82jac6&st=z7pytba9&raw=1)

> ### The AI agent built for Minecraft.

[!(https://img.shields.io/badge/github-comparator-FFBD59?logo=github)](https://github.com/fletchly/comparator) [!(https://img.shields.io/badge/modrinth-comparator-00AF5C?logo=modrinth)](https://modrinth.com/project/MQoLAFN8) !(https://img.shields.io/github/v/release/fletchly/comparator) [!(https://img.shields.io/badge/read%20the%20docs-gray?logo=gitbook&logoColor=FFBD59)](https://fletchly.gitbook.io/comparator-docs/) !(https://img.shields.io/badge/minecraft-26.x-brightgreen) !(https://img.shields.io/badge/license-Apache%202. 0-blue) [!(https://github.com/fletchly/comparator/actions/workflows/build.yml/badge.svg)](https://github.com/fletchly/comparator/actions/workflows/build.yml)

Comparator brings a fully conversational AI agent to your Paper server; with multi-turn memory, built-in tools, and an API to extend it on your own.

## Features

### 🤖 Conversational AI Agent Embed a fully conversational AI agent directly into your Minecraft server. Comparator maintains context across messages for natural, coherent dialogue; not just one-shot responses.

### 🔧 Built-In Tools The agent can to more than just chat. Comparator ships with several built-in tools the AI can invoke to give accurate, grounded answers:

| Tool | Description | |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | Web Search | Searches the web for up-to-date information, so the agent isn't limited to its training data | | Current Date | Retrieves the current date, helping the agent reason about how recent its knowledge is | | Game Version | Fetches the server's running Minecraft version so answers are version-accurate | | Player Info | Retrieves the player's surroundings, inventory, nearby entities, biome, game mode, and what they're looking at. This enables contextual in-game assistance |

### 🌐 Embedded Web Panel Comparator includes a built-in web panel served directly from the plugin via an embedded server. It gives server admins a live view into conversations, tool runs, and registered tools with real-time updates. No separate deployment needed; just configure the host and port in `comparator.conf` and run `/comparator panel start` to launch it.

### 🧩 Extensible Tool API Third-party plugins can register their own tools using the Comparator API. Defining a tool is as simple as annotating a function:

```kotlin @ToolFunction("give_item", "Gives an item to the requesting player") suspend fun giveItem( @ToolParameter("The item to give") item: String, context: ToolContext ): GiveResult { val player = context.bukkitPlayer ?: throw ToolException("No player context", null) // ... }

// Register during ToolRegistrationEvent event.registry.register(tool(::giveItem)) ```

The API handles parameter validation, type checking, serialization, and error reporting automatically. See the (https://fletchly.github.io/comparator/) for full details.

### 🔒 Designed for Responsible AI Use Comparator was built with safety and transparency in mind. This sets it apart from plugins that simply wrap an AI API with no guardrails:

• Permission-gated access — All commands and public chat interactions respect Bukkit permissions, giving server admins fine-grained control over who can use the agent and who can manage it.
• Configurable system prompt — The agent's behavior, persona, and constraints are fully configurable. The default prompt explicitly instructs the agent to stay on-topic, avoid fabricating information, and flag when its knowledge may be outdated.
• Context scoping — Conversations are isolated per-player, per-console, and for public chat. A player cannot read or pollute another player's conversation history.
• Automatic context expiry — Conversation history expires after a configurable period of inactivity, limiting unintended data retention.
• Tool result and parameter validation — Tool inputs are validated against declared parameter types and constraints before execution. The agent cannot invoke a tool with malformed arguments.
• Queue-based message handling — Each conversation runs through a bounded channel. If a player floods the agent with messages, excess requests are rejected gracefully rather than queued unboundedly.
• **Structured error