mcp-server-mod: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

This is a Minecraft Fabric mod that implements an MCP (Model Context Protocol) server, allowing LLMs like Claude to execute Minecraft commands through HTTP requests. The mod runs on Fabric 26.2 and creates an HTTP server on port 8080 that accepts MCP protocol messages.

Development Commands

Building the Mod

./gradlew build                 # Build the mod JAR
./gradlew clean build          # Clean build from scratch

Running in Development

./gradlew runClient            # Run Minecraft client with the mod loaded
./gradlew runServer            # Run Minecraft server with the mod loaded

Code Quality

./gradlew check                # Run all checks and tests
./gradlew test                 # Run unit tests only

Architecture Overview

Core Components

• MCPServerModClient: Client-side entry point that starts the HTTP MCP server
• HTTPMCPServer: HTTP server implementation (port 8080) that handles MCP protocol
• CommandExecutor: Executes Minecraft commands with safety validation and result capture
• SafetyValidator: Validates commands against security rules and size limits
• BlockCompressor: Optimizes block change representations by grouping connected regions
• BlockScanner: Scans world areas to detect block changes and structures
• MCPConfig: Configuration management for server settings and safety rules

Package Structure

The mod uses Fabric's split environment feature with separate client and main source sets:

src/
├── main/java/cuspymd/mcp/mod/   # Server-side and shared code
│   ├── MCPServerMod.java        # Main mod class
│   ├── MCPServerModServer.java  # Dedicated server entry point
│   ├── config/MCPConfig.java    # Configuration management
│   ├── server/MCPProtocol.java  # MCP protocol definitions
│   ├── bridge/HTTPMCPServer.java # HTTP server implementation
│   ├── command/                 # Shared command safety/executor interfaces
│   └── utils/                   # Shared utility interfaces and compression
├── client/java/cuspymd/mcp/mod/ # Client-side code
│   ├── MCPServerModClient.java  # Client mod initializer
│   ├── command/                 # Client command execution system
│   │   ├── CommandExecutor.java
│   │   ├── SafetyValidator.java
│   │   ├── CommandResult.java
│   │   └── ChatMessageCapture.java
│   └── utils/                   # Utility classes
│       ├── BlockCompressor.java
│       ├── BlockScanner.java
│       ├── CommandParser.java
│       ├── CoordinateUtils.java
│       └── PlayerInfoProvider.java
└── test/java/cuspymd/mcp/mod/   # Unit tests
    └── BlockCompressorTest.java