Mineflayer ChatGPT

Mineflayer ChatGPT is a Mineflayer plugin for sending and receiving messages with OpenAI ChatGPT.

Installation

npm install mineflayer-chatgpt

or as a dependency in package.json file:

"dependencies": {
    "mineflayer-chatgpt": "x.y.z"
}

Usage

Load the plugin:

import mineflayerChatgpt from 'mineflayer-chatgpt';

...

bot.loadPlugin(mineflayerChatgpt.chatgpt);

Set the configuration:

const chatGptApiKey = 'sk-1234567890abcdef';
bot.chatgpt.setConfig(chatGptApiKey, {
    model: 'gpt-5.2',
    historySize: 20,
    enableModeration: true,
    coolDownInSeconds: 15,
    minimumConfidenceScore: 0.9,
    enableMessageLogging: true
});

Send a message to ChatGPT:

bot.chatgpt.sendMessage('player', 'How to craft a diamond sword in Minecraft?');

Configuration

| Property | Description | Type | Required | Default | Example | |----------|-------------|------|----------|---------|---------| | model | Chat completion model name. | string | No | gpt-5.2 | gpt-4.1-mini | | instructions | Base developer instructions prepended to every conversation. Security instructions are appended internally when enableSecurityInstructions is true. | string | No | You are a helpful assistant in a Minecraft world. Answer questions and provide information relevant to the game. | You are a concise Minecraft redstone expert. | | historySize | Maximum number of messages kept per-player in memory. | number | No | 20 | 50 | | enableSecurityInstructions | Appends security instructions to the base instructions for hardening the model against prompt injection and other LLM threats. | boolean | No | true | false | | enableModeration | Enables outbound and inbound moderation checks. | boolean | No | true | false | | coolDownInSeconds | Minimum seconds required between a player's latest prior message and the next outbound message. | number | No | 15 | 30 | | minimumConfidenceScore | Minimum accepted reply confidence score. Replies below this threshold are replaced by fallbackMessage. | number | No | 0.9 | 0.8 | | enableMessageLogging | Logs model replies to console output. | boolean | No | false | true | | fallbackMessage | Response returned when moderation, cooldown, or confidence checks fail. | string | No | Sorry, I cannot provide a response to that message. | Please wait a moment before sending another message. |

Security

Mineflayer ChatGPT attempts to implement OWASP Top 10 LLM apps recommendations.

LLM01 - Prompt Injection

• Security instruction hardening is appended to base instructions when enableSecurityInstructions is true, including explicit anti-override rules.
• Jailbreak patterns are detected before outbound moderation via detectJailbreakAttempt.
• Jailbreak-like outbound content is blocked and replaced with fallbackMessage.

LLM02 - Sensitive Information Disclosure

• Player memory is isolated per player conversation to reduce cross-user leakage risk.
• Secret and credential pattern detection is applied to both outbound messages and inbound replies.
• Sensitive-looking content is blocked and replaced with fallbackMessage.

LLM03 - Supply Chain

• Trusted publisher on npmjs.com
• Please don't hack us. We're just an amateur family game lab.

LLM04 - Data and Model Poisoning

• Security instructions include guidance that external content may be untrusted.
• TODO: Explicit poisoning classifier, provenance validation, or trust scoring pipeline is implemented. This might be necessary on a modded Minecraft universe.

LLM05 - Improper Output Handling

• Slash commands are detected in inbound replies via detectSlashCommand.
• Replies containing slash commands are blocked and replaced with fallbackMessage.
• Security instructions include "Never generate executable commands."

LLM06 - Excessive Agency

• No tool-calling or autonomous action layer is exposed by Mineflayer ChatGPT.
• No additional explicit policy gate for agentic actions is implemented because actions are limited to returning chat text.

LLM07 - System Prompt Leakage

• Security instructions explicitly forbid revealing system prompts.
• Prompt leakage detection checks replies against security instruction strings.
• Suspected leakage is blocked and replaced with fallbackMessage.

LLM08 - Vector and Embedding Weaknesses

• Domain scoping instruction restricts responses to Minecraft-related topics.
• No vector database, hence no embedding retrieval or retrieval-integrity controls.

LLM09 - Misinformation

• Security instructions tell the model to avoid fabrication and acknowledge uncertainty.
• Inbound replies are confidence-gated; low-confidence replies are replaced with fallbackMessage.

LLM10 - Unbounded Consumption

• Security instructions enforce concise responses.
• Per-player history is bounded by historySize.
• Outbound message rate is gated with cooldown enforcement (coolDownInSeconds).

Colophon

Developer's Guide

Build reports:

• Code complexity report
• Unit tests report
• Test coverage report
• Integration tests report
• API Documentation

Related projects:

• minecraft-npc - CLI for running NPC bot on Minecraft, powered by Mineflayer