MCP Debug Mod for Minecraft 1.20.1

A powerful debugging mod for Minecraft 1.20.1 Forge that integrates with Claude Code via MCP (Model Context Protocol). Provides real-time game inspection, pause/resume control, performance monitoring, and more.

🎯 Features

Game Control

• Pause/Resume - Freeze the game loop for debugging
• Status Monitoring - Check if game is paused or running
• Toggle Control - Quick pause/resume switching

Debugging Tools

• Stack Traces - Get demangled stack traces for main thread or all threads
• Log Capture - Access recent log messages
• Error Tracking - Capture and view exceptions with full stack traces
• SRG Demangling - Automatic deobfuscation of Minecraft code

Performance Monitoring

• FPS/MSPT - Real-time performance metrics
• Memory Usage - JVM memory statistics
• OpenGL State - Graphics API information and error checking

World Inspection

• Entity List - View all entities in the world
• Entity Inspector - Detailed entity information (position, velocity, state)
• Player Info - Player position, dimension, and stats
• Chunk Count - Loaded chunk statistics

Code Inspection

• Class Info - Inspect Java classes (fields, methods)
• Reflection Support - Runtime class analysis

🚀 Quick Start

Prerequisites

• Minecraft 1.20.1
• Forge 47.2+
• Node.js 18+
• Claude Code

Installation

1. Build the Mod

   ./gradlew build

2. Install the Mod

   • Copy build/libs/mcpisnotmcp-1.0.0.jar to your .minecraft/mods/ folder
   • Launch Minecraft

3. Setup MCP Server

   cd mcp-server
   npm install

4. Configure Claude Code

   Add to ~/.claude/settings.json:

   {
     "mcpServers": {
       "minecraft-debug": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-server/index.js"]
       }
     }
   }

5. Restart Claude Code

⚙️ Configuration

The mod creates a configuration file at config/mcpisnotmcp.properties:

# TCP Server Port
tcp.port=25566

# Cache Sizes
cache.log.size=200
cache.error.size=50

# Network Settings
socket.timeout=5000

# Server Behavior
server.auto_start=true
logging.verbose=false

You can reload the configuration at runtime using the mc_reload_config command.

📋 Available Commands

All commands are accessible through Claude Code's MCP integration:

Control Commands

• mc_pause - Pause the game
• mc_resume - Resume the game
• mc_toggle - Toggle pause state
• mc_status - Get current state (PAUSED/RUNNING)

Debug Commands

• mc_get_stack - Main thread stack trace (demangled)
• mc_get_all_stacks - All threads stack traces (demangled)
• mc_get_logs - Recent log messages
• mc_get_errors - Recent errors with stack traces
• mc_clear_errors - Clear error cache

Performance Commands

• mc_get_performance - FPS, MSPT, memory usage
• mc_get_memory - Detailed memory statistics

World Commands

• mc_get_entities - List all entities
• mc_inspect_entity <id> - Inspect specific entity
• mc_get_player - Player information
• mc_get_chunks - Loaded chunk count

OpenGL Commands

• mc_get_gl_info - OpenGL vendor, renderer, version
• mc_get_gl_state - Current GL state flags
• mc_get_gl_errors - OpenGL error queue

Reflection Commands

• mc_get_class_info <className> - Class fields and methods
• mc_get_srg_status - SRG mapper statistics

System Commands

• mc_reload_config - Reload configuration file

🏗️ Architecture

Java Components

Core Classes

• MCPIsNotMCP - Main mod class, initialization
• DebugConfig - Configuration management
• DebugTcpService - TCP server with thread pool
• DebugCommands - Command implementations
• SRGMapper - Name deobfuscation

Mixins

• MixinMinecraftPause - Game pause functionality
• MixinLogCapture - Log message capture
• MixinExceptionCapture - Exception tracking

Node.js MCP Server

• Connection Pooling - Reuses TCP connections for performance
• Retry Logic - Automatic retry with exponential backoff
• Error Handling - Detailed error messages and recovery
• Graceful Shutdown - Proper cleanup on exit

🔧 Technical Details

Thread Safety

• Volatile fields for cross-thread visibility
• Synchronized blocks for shared state
• Wait/notify pattern for pause control
• Concurrent collections for caching

Resource Management

• Thread pool for request handling
• Proper socket cleanup
• Graceful shutdown procedures
• Timeout handling

Performance

• Connection pooling reduces overhead
• Circular buffers for log/error caching
• Lazy initialization where appropriate
• Efficient reflection caching

🐛 Troubleshooting

Pause Not Working

✅ Fixed in v2.0.0 - Now uses correct injection point (runTick())

Connection Timeout

• Verify Minecraft is running
• Check port configuration (default: 25566)
• Ensure no firewall blocking
• Check config/mcpisnotmcp.properties

Commands Failing

• View Minecraft logs for errors
• Enable verbose logging: logging.verbose=true
• Use mc_get_errors to see captured exceptions
• Verify mod is loaded: check mods list in-game

MCP Server Not Connecting

• Verify Node.js version (18+)
• Check npm install completed successfully
• Verify path in Claude Code settings is absolute
• Restart Claude Code after configuration changes

📝 Development

Building

./gradlew build

Running Dev Server

cd mcp-server
npm run dev  # Auto-reload on changes

Adding Custom Commands

1. Add command handler in DebugTcpService.java
2. Implement logic in DebugCommands.java
3. Add tool definition in mcp-server/index.js
4. Update documentation

📊 Version History

v2.0.0 (2026-04-29) - Major Refactor

• 🐛 Fixed pause functionality - Uses correct runTick() injection
• ✨ Configuration system - Runtime configurable settings
• ✨ Connection pooling - Improved performance and reliability
• ✨ Retry logic - Automatic retry with exponential backoff
• ✨ Thread safety - Proper synchronization throughout
• ✨ Better error handling - Detailed error messages and recovery
• ✨ SRG mapper improvements - Better deobfuscation support
• 📝 Complete refactor - Cleaner architecture and code quality

v1.0.0

• Initial release
• Basic debugging functionality
• MCP integration

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

See LICENSE.txt for details.

🙏 Acknowledgments

• Based on Techguns2 mod structure
• Uses Forge Mixin for bytecode manipulation
• Integrates with Claude Code via MCP protocol

📞 Support

For issues and questions:

• Check the troubleshooting section
• Review the logs
• Open an issue on GitHub

---

Note: This is a development/debugging tool. Use in production environments at your own risk.