minecraft-java-fabric-claude-plugin CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

node scripts/validate-plugin.mjs       # validate manifests, frontmatter, and skill/folder name alignment (Node 20+)
python -m pip install -r tools/requirements.txt   # one-time: deps for the voxel + terrain toolkits (numpy, Pillow, scipy; optional opensimplex)
python tools/examples/example_bean.py  # smoke-test the voxel toolkit (renders 3 PNGs + a fills JSON)

No build step for the markdown content — skills and agents are plain markdown and take effect in the next Claude Code session after the plugin is reloaded. The tools/ directory adds a small Python helper layer (the voxel and terrain toolkits) that the builder skills run locally; the voxel toolkit is numpy + Pillow, the terrain toolkit adds scipy (+ optional opensimplex), and the builder harness is stdlib-only. They are referenced from skills via ${CLAUDE_PLUGIN_ROOT}/tools/…. These helpers run in Claude Code (CLI or desktop app), where the agent has local Bash and can read the PNGs they produce.

Architecture

This is the Claude-facing piece of a two-repository system. The MCP server is embedded in the Fabric mod and runs inside Minecraft — there is no separate server process and no behavior pack.

The mod has two entrypoints / two MCP endpoints from one jar:

Claude (Code / Desktop)
  │ MCP over Streamable HTTP                 │ MCP over Streamable HTTP
  │ minecraft-java  (127.0.0.1:8765/mcp)     │ minecraft-java-client (127.0.0.1:8766/mcp)
  ▼                                          ▼
McpServerMod (main entrypoint)              McpClientMod (client entrypoint)
  │ server API, server main thread            │ client API, client/render thread
  │ WORLD tools (level_/block_/entity_…)      │ INSPECTION tools (view_capture, sense_*, client_status)
  ▼                                          ▼
the Minecraft world  ◄──── same world, the client joins as a player ────►