bevy_debugger_mcp 0.1.5

AI-assisted debugging for Bevy games through Claude Code using Model Context Protocol
Documentation

Bevy Debugger MCP Server

Build Status License: GPL v3 Rust Bevy

A powerful Model Context Protocol (MCP) server that enables AI-assisted debugging of Bevy games through Claude Code. Debug your game state, analyze performance, and test hypotheses with natural language commands.

🎯 Quick Start (5 minutes)

# 1. Install the debugger
cargo install bevy_debugger_mcp

# 2. Add RemotePlugin to your Bevy game
# In your game's main.rs:
# .add_plugins(RemotePlugin::default())

# 3. Configure Claude Code (add to ~/.config/claude/claude_code_config.json)
echo '{
  "mcpServers": {
    "bevy-debugger": {
      "command": "bevy-debugger-mcp",
      "args": []
    }
  }
}' >> ~/.config/claude/claude_code_config.json

# 4. Run your game and start debugging!
cargo run  # In your game directory
# Then open Claude Code and say: "Help me debug my Bevy game"

✨ Features

  • 🔍 Real-time Observation: Monitor entities, components, and resources as your game runs
  • 🧪 Smart Experimentation: Test game behavior changes with automatic rollback
  • 📊 Performance Analysis: Identify bottlenecks and optimize game performance
  • 🚨 Anomaly Detection: Automatically spot unusual patterns in game behavior
  • 📹 Session Recording: Record and replay debugging sessions for analysis
  • 📸 Screenshot Capture: Take window-specific screenshots of your game for visual debugging
  • 🛡️ Error Recovery: Robust error handling with automatic diagnostics

🚀 Quick Start

Prerequisites

  • Rust 1.70+ and Cargo
  • Claude Code CLI
  • A Bevy game with RemotePlugin enabled

Installation

# Install from crates.io (recommended)
cargo install bevy_debugger_mcp

# Or clone and build from source
git clone https://github.com/ladvien/bevy_debugger_mcp.git
cd bevy_debugger_mcp
cargo build --release

# Install (macOS/Linux)
./scripts/install.sh

# Setup Claude Code integration
./scripts/setup-claude.sh

Server Management with bevy-debugger-control

The bevy-debugger-control script is automatically installed with the package and provides complete lifecycle management for the MCP server. This solves the common issue of the server hanging when run directly.

Basic Commands

# Start the server in the background
bevy-debugger-control start

# Stop the server gracefully
bevy-debugger-control stop

# Restart the server (useful after configuration changes)
bevy-debugger-control restart

# Check if the server is running and view details
bevy-debugger-control status

# View server logs
bevy-debugger-control logs

# Follow logs in real-time (like tail -f)
bevy-debugger-control logs -f

# Clean up old log files
bevy-debugger-control clean

# Show help and all available commands
bevy-debugger-control help

Advanced Usage

# Start server on a different port
BEVY_DEBUGGER_PORT=3002 bevy-debugger-control start

# Start with custom Bevy host/port
BEVY_BRP_HOST=192.168.1.100 BEVY_BRP_PORT=15703 bevy-debugger-control start

# Clean all logs including current
bevy-debugger-control clean --all

# Check server status with process details
bevy-debugger-control status
# Output shows:
# - PID of running process
# - CPU and memory usage
# - Port binding status
# - Recent log entries

File Locations

The control script manages the following files:

  • Logs: ~/.bevy-debugger/bevy-debugger.log
  • PID file: ~/.bevy-debugger/bevy-debugger.pid
  • Rotated logs: ~/.bevy-debugger/bevy-debugger.log.*

Troubleshooting

If the server fails to start:

# Check the logs for errors
bevy-debugger-control logs

# Ensure no other instance is running
bevy-debugger-control stop
bevy-debugger-control start

# Verify the binary is installed
which bevy-debugger-mcp

# Check if port is already in use
lsof -i :3001  # or your configured port

Setup Your Bevy Game

Add the RemotePlugin to your Bevy app:

use bevy::prelude::*;
use bevy::remote::{RemotePlugin, BrpResult};
use bevy::render::view::screenshot::{save_to_disk, Screenshot};
use serde_json::Value;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(
            RemotePlugin::default()
                .with_method("bevy_debugger/screenshot", screenshot_handler)
        )
        .run();
}

// Enable screenshot functionality
fn screenshot_handler(
    In(params): In<Option<Value>>, 
    mut commands: Commands,
) -> BrpResult {
    let path = params
        .as_ref()
        .and_then(|p| p.get("path"))
        .and_then(|p| p.as_str())
        .unwrap_or("./screenshot.png")
        .to_string();

    commands
        .spawn(Screenshot::primary_window())
        .observe(save_to_disk(path.clone()));
    
    Ok(serde_json::json!({
        "path": path,
        "success": true
    }))
}

# Cargo.toml
[dependencies]
bevy = { version = "0.16", features = ["default", "bevy_remote"] }

Start Debugging

  1. Run your Bevy game: cargo run
  2. Open Claude Code in your project directory
  3. Start debugging: Try commands like:
    • "Show me all entities in the game"
    • "Monitor the player's health component"
    • "Test what happens when I spawn 100 enemies"
    • "Take a screenshot of the current game state"
    • "Record this gameplay session for analysis"

🤖 Claude Code Integration Guide

Setting Up Claude Code

  1. Install the MCP Server:
cargo install bevy_debugger_mcp
  1. Configure Claude Code - Add to your claude_code_config.json:
{
  "mcpServers": {
    "bevy-debugger": {
      "command": "bevy-debugger-mcp",
      "args": []
    }
  }
}
  1. Verify Installation:
# Test the MCP server responds correctly
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"capabilities": {}}, "id": 1}' | bevy-debugger-mcp
# Should return: {"id":1,"jsonrpc":"2.0","result":{"capabilities":...}}

How Claude Uses the MCP Tools

When you ask Claude to debug your Bevy game, it has access to powerful MCP tools that communicate with your running game:

🔍 Observation Tools

Claude can monitor your game state in real-time:

You: "Show me all enemies in the game"
Claude: [Uses observe tool to query entities with Enemy component]
        "I found 5 enemies. Here are their positions and health values..."

You: "Track the player's velocity over time"
Claude: [Uses observe tool with continuous monitoring]
        "The player's velocity spikes to 500 units when jumping, which seems abnormal..."

🧪 Experimentation Tools

Claude can test hypotheses by modifying game state:

You: "Test what happens if we spawn 100 enemies at once"
Claude: [Uses experiment tool to spawn entities and measure performance]
        "Spawning 100 enemies causes frame rate to drop to 15 FPS. The bottleneck is..."

You: "Try doubling the player's speed and see if collision still works"
Claude: [Uses experiment tool to modify components with automatic rollback]
        "At 2x speed, the player clips through thin walls. The physics system needs..."

🚨 Anomaly Detection

Claude can identify unusual patterns:

You: "Something is causing random lag spikes"
Claude: [Uses anomaly tool to monitor performance metrics]
        "I detected memory allocations spike every 5 seconds, coinciding with..."

You: "Find any entities behaving strangely"
Claude: [Uses anomaly tool with pattern matching]
        "Entity #42 is teleporting between positions, likely due to..."

📊 Performance Analysis

Claude can profile and optimize:

You: "Why is my game running slowly?"
Claude: [Uses stress tool to identify bottlenecks]
        "The render system is taking 45ms per frame. The main issue is..."

You: "Optimize the enemy AI system"
Claude: [Uses performance profiling tools]
        "The pathfinding is recalculating every frame. We can cache results..."

Real-World Debugging Sessions

Example 1: Physics Bug

Human: My character falls through the floor randomly

Claude: I'll investigate this physics issue. Let me start by observing the player's Transform and Collider components.

[Uses observe tool to monitor player entity]
I'm tracking the player's Y position... I notice it suddenly changes from 0.0 to -100.0 without intermediate values.

[Uses experiment tool to test collision]
Let me test the collision system by spawning a test entity at the player's position...
The collision detection is failing when the player's velocity exceeds 1000 units/frame.

Solution: Add a velocity cap or use continuous collision detection for high-speed entities.

Example 2: Performance Investigation

Human: The game freezes every few seconds

Claude: I'll analyze the performance patterns to identify the cause of these freezes.

[Uses anomaly detection on frame times]
I've detected periodic spikes in frame time every 3.2 seconds, lasting about 200ms.

[Uses observe tool on system metrics]
Monitoring system activity... The "EnemySpawnSystem" is creating 50 entities at once every 3 seconds.

[Uses experiment tool to test optimization]
Let me test spreading the spawning over multiple frames...
Spawning 5 entities per frame over 10 frames eliminates the freezes.

Solution: Implement batched spawning to distribute the load across frames.

Example 3: Visual Debugging

Human: Can you show me what the AI sees?

Claude: I'll visualize the AI's perception system for you.

[Uses visual overlay tools]
I'm enabling debug overlays for:
- AI vision cones (showing field of view)
- Pathfinding waypoints (showing planned routes)  
- Detection ranges (showing awareness zones)

[Takes screenshot]
Here's a screenshot showing the AI's perception. The red cones are vision, blue lines are paths.

The AI at position (100, 50) can't see the player because there's an obstacle blocking line of sight.

Advanced Usage Patterns

Continuous Monitoring

Human: Monitor the game for any issues while I playtest

Claude: I'll set up continuous monitoring for common issues.

[Sets up multiple observe and anomaly detection tasks]
Monitoring:
- Memory usage (alerting if >2GB)
- Frame time (alerting if >16ms)
- Entity count (alerting if >10000)
- Error patterns in components

[After 5 minutes]
Alert: Memory usage increased by 500MB in the last minute.
Investigating... Found 5000 orphaned bullet entities not being destroyed.

Automated Testing

Human: Test if my save system works correctly

Claude: I'll test the save/load system comprehensively.

[Uses orchestration tool to chain operations]
1. Capturing current game state...
2. Modifying player position, inventory, and score...
3. Triggering save...
4. Resetting game...
5. Triggering load...
6. Comparing states...

Results: Save system works correctly for position and score, but inventory items are duplicated on load.

Troubleshooting Claude Code Connection

If Claude can't connect to your game:

# 1. Ensure your Bevy game is running with RemotePlugin
# 2. Check the MCP server can connect to Bevy:
bevy-debugger-control start
bevy-debugger-control logs

# 3. Verify Claude Code configuration:
cat ~/.config/claude/claude_code_config.json

# 4. Test manual connection:
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}' | bevy-debugger-mcp

# 5. Check Bevy is listening:
curl -X POST http://localhost:15702/query -d '{"data": "list"}'

🛠️ Configuration

The server uses environment variables for configuration:

export BEVY_BRP_HOST=localhost    # Bevy Remote Protocol host
export BEVY_BRP_PORT=15702        # Bevy Remote Protocol port  
export MCP_PORT=3000              # MCP server port (not used in stdio mode)
export RUST_LOG=info              # Logging level

📁 Project Structure

bevy_debugger_mcp/
├── src/
│   ├── main.rs              # Entry point with stdio/TCP transport
│   ├── mcp_server.rs        # MCP protocol implementation
│   ├── brp_client.rs        # Bevy Remote Protocol client
│   ├── tools/               # Debugging tool implementations
│   │   ├── observe.rs       # Entity/component observation
│   │   ├── experiment.rs    # Game state experimentation
│   │   ├── stress.rs        # Performance stress testing
│   │   └── ...
│   └── ...
├── scripts/                 # Installation and management scripts
├── docs/                    # Documentation
├── tests/                   # Integration tests
└── README.md

📚 Complete Developer Workflow

Step 1: Prepare Your Bevy Game

// In your main.rs or lib.rs
use bevy::prelude::*;
use bevy::remote::RemotePlugin;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(RemotePlugin::default()) // Essential for debugging
        .add_systems(Update, your_game_systems)
        .run();
}

Step 2: Install and Configure

# Install the debugger
cargo install bevy_debugger_mcp

# Add to Claude Code config (~/.config/claude/claude_code_config.json)
{
  "mcpServers": {
    "bevy-debugger": {
      "command": "bevy-debugger-mcp",
      "args": []
    }
  }
}

Step 3: Start Debugging Session

  1. Run your Bevy game: cargo run
  2. Open Claude Code in your project
  3. Start debugging with natural language:
    • "What entities are in my game?"
    • "Why is performance dropping?"
    • "Monitor the player's health"
    • "Test spawning 1000 enemies"

🧪 Available MCP Tools

Tool Description Example Usage
observe Monitor game entities, components, and resources "Show me all entities with Health component"
experiment Test changes to game state with automatic rollback "Set player speed to 2x and test collision"
stress Performance testing and bottleneck identification "Stress test the physics system with 500 objects"
anomaly Detect unusual patterns in game behavior "Find any entities with abnormal velocities"
replay Record and replay debugging sessions "Record the next 30 seconds of gameplay"
orchestrate Chain multiple debugging operations "Test save, modify state, load, and compare"
screenshot Capture game visuals "Take a screenshot of the current scene"

🖥️ Platform Support

Platform Installation Status
macOS ./scripts/install.sh ✅ Full support with LaunchAgent service
Linux ./scripts/install.sh ✅ Full support
Windows Manual build ⚠️ Basic support (help wanted)

macOS Service Management

On macOS, the debugger can run as a background service:

# Service management
./scripts/service.sh start      # Start background service
./scripts/service.sh stop       # Stop service
./scripts/service.sh status     # Check status
./scripts/service.sh logs       # View logs

🤝 Contributing

We welcome contributions! Please see our contribution guidelines.

# Development setup
git clone https://github.com/ladvien/bevy_debugger_mcp.git
cd bevy_debugger_mcp
cargo test                      # Run basic tests
cargo test --ignored           # Run full integration tests
cargo test screenshot_integration_wrapper::test_screenshot_ci_suite  # Fast screenshot tests
cargo fmt                       # Format code
cargo clippy                    # Lint code

Running Screenshot Tests

The screenshot functionality has comprehensive test coverage:

# Fast screenshot tests (suitable for CI/development)
cargo test screenshot_integration_wrapper::test_screenshot_ci_suite

# Full screenshot integration suite  
cargo test screenshot_integration_wrapper::test_screenshot_integration_suite -- --ignored

# Individual test categories
cargo test screenshot_integration_wrapper::test_screenshot_utilities
cargo test screenshot_integration_wrapper::test_screenshot_basic_functionality
cargo test screenshot_integration_wrapper::test_screenshot_parameter_validation
cargo test screenshot_integration_wrapper::test_screenshot_timing_controls

# Performance testing
cargo test screenshot_integration_wrapper::test_screenshot_performance

📚 Documentation

🔒 Security & Privacy

  • All communication happens locally between your game and Claude Code
  • No game data is transmitted externally
  • Sensitive information is automatically redacted from logs
  • Debug recordings are stored locally and encrypted

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🙏 Acknowledgments

Questions? Open an issue or join the discussion in Bevy's Discord.