minecraft-bridge

Local HTTP bridge for Mineflayer-based live control of a Minecraft Java bot. Trigger when the user wants to connect a bot to their world, check bot status/in...

Security Scan

The skill's code and dependencies largely match its stated purpose (a local Mineflayer HTTP bridge), but there are a few mismatches and exposure risks you should verify before installing or running it.

Purpose & Capability

Name, description, required binary (node), and npm packages (mineflayer, mineflayer-pathfinder, vec3) align with a Mineflayer-based local bridge. The skill's files (bridge-server.js, start/stop scripts, API docs) are consistent with its claimed functionality. Minor mismatch: SKILL metadata lists MC_HOST, MC_PORT, MC_BOT_USERNAME as required, but the runtime also expects other environment variables (MC_BRIDGE_PORT, MC_VERSION, MC_AUTH) documented in config.example.json and SKILL.md.

Instruction Scope

Runtime instructions focus on starting a local HTTP bridge and calling localhost endpoints (status, move, mine, chat, command, etc.), which is within scope. Concerns: (1) The documentation repeatedly states the bridge is intended for localhost only, but the code snippet does not show an explicit bind address — if bridge-server.js calls server.listen(port) without a host, Node will typically bind to all interfaces (0.0.0.0), exposing the API to the network. Verify the server bind address in the full source. (2) /command forwards arbitrary slash commands (with some commands blocked); this is necessary for usefulness but is a high-risk capability if the bot has elevated permissions — the README warns about this, which is good.

Install Mechanism

start.sh will run 'npm install mineflayer mineflayer-pathfinder vec3' in the skill directory if the dependencies are not present. Installing npm packages from the public registry is expected here but carries the usual supply-chain risk (moderate). The install is not downloading arbitrary archives or running code from unknown URLs — it's npm, which is traceable.

Credentials

The declared required env vars (MC_HOST, MC_PORT, MC_BOT_USERNAME) are appropriate. However, the SKILL.md and config.example reference additional env vars (MC_BRIDGE_PORT, MC_VERSION, MC_AUTH) that are not listed in the metadata 'requires.env'. The skill does not request unrelated secrets (no API keys, AWS, etc.), which is good. Still: MC_AUTH may be used to select authentication mode (offline vs microsoft) — if you run against an authenticated server ensure you understand how credentials are supplied and that they are not being accidentally stored or transmitted.

Persistence & Privilege

The skill does not request always:true and does not modify other skills' configurations. It creates PID and log files under /tmp or XDG_RUNTIME_DIR and can install npm packages into the skill directory — this is normal for a local helper service. Autonomous invocation is allowed (default) but not combined with other high-risk factors here.

What to consider before installing

This skill appears to implement what it claims (a local Mineflayer HTTP bridge) but check a few things before installing or running it: 1) Verify the bridge binds only to localhost (127.0.0.1). If bridge-server.js calls server.listen(port) without a host, it may be reachable from the network — change it to server.listen(port, '127.0.0.1') or firewall it. 2) Confirm the environment-variables list: set MC_BRIDGE_PORT, MC_VERSION, and MC_AUTH as needed (these are referenced by the code/docs but not listed in metadata). 3) Be cautious with POST /command: it forwards arbitrary slash commands; do not run this against servers where the bot has operator privileges unless you trust commands being issued. 4) start.sh will run npm install locally; review the installed package versions and consider locking them (package-lock) or auditing packages before use. 5) Run the bridge under an unprivileged user, and avoid exposing the machine's network interface to untrusted networks. If you want me to, I can inspect the remainder of bridge-server.js (the truncated part) to confirm the server.listen call and any additional network or file operations.

Persistent local HTTP service that bridges OpenClaw to a live Minecraft Java Edition bot session. Exposes a REST API on http://localhost:${MC_BRIDGE_PORT|3001} for live state reads and in-game bot actions.

Boundary:

• Use this skill for live bot control and live game-state reads
• Use minecraft-wiki for knowledge questions
• Use minecraft-server-admin for RCON, server.properties, whitelist/ban/op, and generic server administration

Quick State Machine

UNSTARTED → run bridge-server.js → STARTING → bot spawns → CONNECTED
CONNECTED → game closes or kick → DISCONNECTED → auto-reconnect → CONNECTED

Check current state with: GET http://localhost:3001/status

---

Setup (first time)

1. Environment variables

Set in ~/.openclaw/openclaw.json or export in shell:

MC_HOST=localhost          # server IP (localhost for singleplayer LAN)
MC_PORT=25565              # game port
MC_BOT_USERNAME=ClawBot    # bot's in-game name (offline-mode servers)
MC_BRIDGE_PORT=3001        # bridge HTTP port (default 3001)
MC_VERSION=1.21.1          # Minecraft version string

2. Open Minecraft to LAN (singleplayer)

ESC → Open to LAN → Allow Cheats ON → Start LAN World Note the port shown (e.g. 54321) — set MC_PORT to that value.

3. Start the bridge

node ~/.openclaw/skills/minecraft-bridge/bridge-server.js

Wait for: 🎮 Bridge ready at http://localhost:3001

4. Verify

curl http://localhost:3001/status

---

Runtime Operations

When user gives a live-game command:

1. Check bridge health — GET /status; if unreachable → show setup instructions above
2. Execute action — call appropriate endpoint (see API Reference below)
3. Report result — format response conversationally; include coordinates, item names, counts
4. Persist context — write significant events to OpenClaw memory (coordinates found, items collected, goals achieved)

Interpreting /status response

{
  "connected": true,
  "username": "ClawBot",
  "position": {"x": -142, "y": 64, "z": 88},
  "health": 18.0,
  "food": 14,
  "gameTime": 6000,
  "inventoryCount": 12,
  "biome": "plains"
}

• gameTime 0–6000 = morning, 6000–12000 = day, 12000–18000 = dusk/night
• health max 20.0; below 6 = danger
• food max 20; below 6 = can't sprint, below 1 = taking damage

---

API Overview

See references/api-spec.md for the full schema.

Core endpoints:

• GET /status — bridge + bot connection state
• GET /inventory, GET /position, GET /nearby — live state reads
• POST /move, POST /mine, POST /collect, POST /craft, POST /follow, POST /stop — live bot actions
• POST /chat — send in-game chat
• POST /command — send arbitrary slash commands; use with caution

Security note: /command forwards arbitrary slash commands. On servers where the bot has elevated permissions, this may include destructive or admin-level commands. Prefer minecraft-server-admin for server administration tasks.

---

Dependent Skills

Dependent skills should health-check the bridge before using it. See references/dependency-guide.md for the canonical dependency-check pattern and degradation behavior.

---

Error Handling

Error	Cause	Recovery
ECONNREFUSED	Bridge not started	Run node bridge-server.js
{"connected":false}	Bridge up, bot offline	Open Minecraft, check MC_HOST/PORT
{"error":"pathfinding failed"}	Path blocked	Try /stop then retry with different coords
{"error":"no crafting table"}	Craft without workbench	Move near crafting table first
Bot stuck looping	Pathfinding bug	POST /stop, then resume

Auto-reconnect is built in — bridge retries every 5 s after disconnect.

---

Additional Resources

• references/api-spec.md — Full API schema with all request/response fields
• references/dependency-guide.md — How other skills should declare bridge dependency
• references/troubleshooting.md — Detailed error diagnosis
• scripts/start.sh / scripts/stop.sh — Convenience wrappers