Bevy Debugger MCP Server

Bevy Debugger MCP Server

⚠️ Vibe Coded — written by an AI agent working from a human's direction. It is used against a shipping game and covered by tests, but it has had no line-by-line human audit. Read it before you trust it.

Lets an agent inspect and drive a running Bevy game: query entities, components and resources live, capture frames from an offscreen render target, inject keyboard and mouse input — including cursor position, so a click-drag is expressible, and typed text, so a text field can be filled and committed — and post a walkthrough the app renders one step at a time, watching a named condition and recording what actually happened. None of it touches your desktop, your window manager, or the OS input stack.

This repo is a read-only mirror. It is split out of Ladvien/foundation_vs_slop at crates/bevy_debugger_mcp/ with git subtree split, history intact. Issues and PRs belong upstream — changes made here cannot be pulled back.

For agents working in the monorepo: this is first-party code, not a dependency. It lives under crates/ alongside everything else and is edited exactly the same way. A capability it lacks is a feature to add, not a constraint to design around — the cursor injection above was added precisely because two rounds of work had treated its absence as fixed. The one part that is not an ordinary change is the OS boundary below.

Two halves

They are independent — the server does not depend on the plugin. The plugin is what a game links; the server is what an agent talks to.

Three directions

The third is the newest and the least obvious. An agent could already drive an app and look at it; what it could not do was say a sentence to the person at the keyboard, so every instruction went to a terminal they had to look away from their work to read, and every answer came back as prose the agent then had to guess its way from.

Examples

The three that demonstrate what this crate actually does — no window, no GPU, no mouse; all print to the terminal:

cargo run -p bevy_debugger_bevy --example injected_input_lands
cargo run -p bevy_debugger_bevy --example cursor_drag_lands
cargo run -p bevy_debugger_bevy --example guided_steps_land

The first shows the property the plugin exists to provide: an injected key is visible to just_pressed for exactly one frame and just_released on the next, the same shape a physical key produces.

The second shows a click-drag — move, press, move, move, release queued in one batch — and the property that makes it mean anything: the press is read where it was aimed. Apply the queued move and the queued press in the same frame and the game reads the press at the destination, so the drag starts wherever it ended and selects nothing. It earned its keep immediately: it caught a real ordering bug where a release overtook two still-pending moves and committed the box at the wrong corner.

The third posts a three-step script and drives it to completion against a stand-in author, printing the transcript an agent would receive.

Guiding a person through an exercise

Post a script; the app shows one step, never the list. Each step is a guided-exploration card — hints, a checkpoint, and recovery:

{"steps": [{
  "label": "drop a floor and a wall",
  "goal": "a tile needs two pieces before the solver has anything to match on",
  "do": ["walk the library with up and down", "press Enter to bring the selected row in"],
  "checkpoint": "tile has two members",
  "recovery": "if nothing lands, the library filter is hiding every row: press Backspace"
}]}

Then curl -N on bevy_debugger/guide+watch and get a frame each time something happens — nothing at all while the condition is unmet.

Checkpoints are the host's words. This plugin cannot know what a tile is and must not learn, so a host registers one-shot systems answering bool:

let has_two = app.register_system(|tile: Res<Tile>| tile.members >= 2);
app.world_mut().resource_mut::<Checkpoints>().register("tile has two members", has_two);

A step may have no checkpoint — "does this look right?" is not a machine question — and that is a supported state, not a gap: the stream says waiting_on_a_person and holds until an explicit {"skip": true}.

What comes back is k/n per step, never a boolean, plus how long each took. A step nobody can complete shows up as a stall rather than a silence.

The design is grounded rather than guessed, and two of the findings are negative: an on-demand help button costs completion, and restricting input to force the step buys nothing at all. See the design notes for the citations.

Injecting a cursor

bevy_debugger/input takes kind: "Cursor" with x/y in logical window pixels, or clear: true to hand the pointer back to the real mouse. The position is state, not an edge — it stays where it was put until moved again, so there is no per-frame stream to keep up with.

{"kind": "Cursor", "x": 640, "y": 360}   // aim
{"kind": "Mouse", "button": "Left", "action": "Press"}
{"kind": "Cursor", "x": 720, "y": 400}   // drag
{"kind": "Mouse", "button": "Left", "action": "Release"}
{"kind": "Cursor", "clear": true}        // give it back

A host has to read the pointer through bevy_debugger_bevy::cursor_position(&window, &debug_cursor). A host that calls Window::cursor_position directly cannot be driven, and that is not a bug in the plugin — the window's own cursor is deliberately never written, because Bevy's windowing backend turns a change to it into a request to move the physical pointer. That would drag the mouse out from under whoever is at the machine, which is the one thing this crate exists to prevent.

Two older examples ship with the server, and it is worth being precise about them, because neither demonstrates DebuggerPlugin:

[!WARNING]

⚠️ 100% VIBE CODED ⚠️

This entire project was developed through "vibe coding" with AI assistance.

This means:

• The code was written iteratively through natural language descriptions
• No traditional software design process was followed
• Testing may be incomplete or absent in some areas
• There might be unconventional patterns or unexpected behaviors
• USE AT YOUR OWN RISK

While functional, this codebase should be treated as experimental. We recommend:

• Thoroughly testing in a development environment first
• Not using in production without extensive review
• Being prepared for potential edge cases or unusual behavior
• Contributing fixes if you find issues!

That said, it's pretty cool and mostly works! 🚀

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.

📚 Table of Contents

• Quick Start
• Features
• Installation
  • Method 1: Homebrew
  • Method 2: Cargo
  • Method 3: From Source
  • Post-Installation Setup
• Configuration
• Usage Examples
• Architecture
• Troubleshooting
• Contributing

🎯 Quick Start

# 1. Install the debugger (pick your preferred method)
cargo install bevy_debugger_mcp

# 2. Run the setup script (IMPORTANT!)
curl -sSL https://raw.githubusercontent.com/ladvien/bevy_debugger_mcp/main/setup-claude.sh | bash

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

# 4. Restart Claude Code 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
• 🤖 ML-Powered Suggestions: Learn from debugging patterns to provide better recommendations
• 📈 Performance Budgets: Set and monitor performance targets with automatic alerts
• 🔄 Workflow Automation: Automate common debugging tasks with safety checkpoints

🏗️ How It Works

The Bevy Debugger MCP creates a bridge between Claude Code and your Bevy game:

┌─────────────┐     MCP Protocol      ┌──────────────────┐     BRP Protocol    ┌─────────────┐
│ Claude Code │ ◄──────────────────► │ bevy-debugger-mcp │ ◄─────────────────► │ Your Bevy   │
│   (AI)      │    stdio/TCP          │    (Server)       │    WebSocket       │    Game     │
└─────────────┘                       └──────────────────┘                      └─────────────┘
     │                                         │                                       │
     │ "Find memory leaks"                    │                                       │
     └────────────────────►                   │                                       │
                                              │ Query entities & components           │
                                              └──────────────────────────────────────►│
                                              │                                       │
                                              │◄──────────────────────────────────────┤
                                              │     Entity data & metrics             │
     │◄────────────────────                   │                                       │
     │ "Found 500 orphaned                    │                                       │
     │  bullet entities"                      │                                       │

Architecture Components

1. Claude Code (AI Agent): Natural language interface for debugging commands
2. MCP Server: Translates AI requests into game debugging operations
3. BRP Client: Communicates with your Bevy game via WebSocket
4. RemotePlugin: Bevy plugin that exposes game internals for debugging
5. Debug Tools: 11 specialized tools for different debugging tasks

🚀 Quick Start

Prerequisites

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

Installation

Method 1: Homebrew (macOS) - Recommended

brew tap ladvien/bevy-debugger-mcp
brew install bevy-debugger-mcp

# Run setup for Claude integration
bevy-debugger-setup

Method 2: Cargo Install

cargo install bevy_debugger_mcp

# Run setup script for Claude integration
curl -sSL https://raw.githubusercontent.com/ladvien/bevy_debugger_mcp/main/setup-claude.sh | bash

Method 3: From Source

git clone https://github.com/ladvien/bevy_debugger_mcp.git
cd bevy_debugger_mcp
./install.sh  # Handles everything automatically

Method 4: Claude Desktop Extension

Coming soon - Will be available in the Claude Desktop extension marketplace.

Post-Installation Setup

Important: After installation via ANY method, run the setup script:

# If installed via Homebrew
bevy-debugger-setup

# If installed via other methods
~/.cargo/bin/bevy-debugger-mcp-setup || ./setup-claude.sh

This setup script will:

1. Find your bevy-debugger-mcp installation
2. Create necessary symlinks for Claude Code compatibility
3. Generate the configuration you need to add to Claude

Why the Setup Script?

Claude Code may look for binaries in different locations depending on your system:

• ~/.local/bin/ (Claude Code default)
• ~/.cargo/bin/ (Cargo installation)
• /usr/local/bin/ (System-wide)
• /opt/homebrew/bin/ (Homebrew on Apple Silicon)

The setup script ensures Claude can find the binary regardless of installation method.

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 (v0.1.6 or later):

cargo install bevy_debugger_mcp

2. Configure Claude Code - Add to your Claude Code settings:

macOS/Linux: ~/.config/claude/claude_code_config.json Windows: %APPDATA%\claude\claude_code_config.json

{
  "mcpServers": {
    "bevy-debugger": {
      "command": "bevy-debugger-mcp",
      "args": ["--stdio"],
      "type": "stdio",
      "env": {
        "BEVY_BRP_HOST": "localhost",
        "BEVY_BRP_PORT": "15702",
        "RUST_LOG": "info"
      }
    }
  }
}

3. Verify Installation:

# Check version
bevy-debugger-mcp --help

# Test the MCP server responds correctly
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"capabilities": {}}, "id": 1}' | bevy-debugger-mcp --stdio
# Should return: {"id":1,"jsonrpc":"2.0","result":{"capabilities":...}}

# Verify tools are available
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}' | bevy-debugger-mcp --stdio
# Should list: observe, experiment, stress, anomaly, replay, hypothesis, screenshot

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
# Check if Bevy is listening on the correct port:
lsof -i :15702  # Should show your Bevy game process

# 2. Test the MCP server standalone:
bevy-debugger-mcp --help  # Should show version 0.1.6
bevy-debugger-mcp --stdio  # Should wait for input (Ctrl+C to exit)

# 3. Verify Claude Code configuration:
cat ~/.config/claude/claude_code_config.json
# Should contain the bevy-debugger configuration

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

# 5. Check direct Bevy connection:
curl -X POST http://localhost:15702/query \
  -H "Content-Type: application/json" \
  -d '{"method": "bevy/list", "params": {}}'
# Should return Bevy data

# 6. Enable debug logging:
RUST_LOG=debug bevy-debugger-mcp --stdio

# 7. Common issues:
# - Port 15702 blocked by firewall
# - Bevy game not compiled with bevy_remote feature
# - Multiple MCP servers running on same port
# - Claude Code needs restart after config changes

Performance Characteristics

The debugger is designed for minimal impact on your game:

Common Issues and Solutions

🛠️ 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"

🧪 Complete Debugging Toolkit (v0.1.6)

Core MCP Tools

Internal Debug Commands (11 Integrated Tools)

The debugger provides 11 specialized debugging tools accessible through the MCP protocol:

🖥️ Platform Support

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

• Usage Guide - Detailed feature documentation
• Claude Prompts - Effective prompting strategies
• macOS Service Setup - Background service configuration

🔒 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

📦 Changelog

v0.1.6 (Latest) - Production Ready

• ✅ All 11 debugging tools fully integrated and operational
• ✅ Fixed critical async initialization issues
• ✅ Enhanced error handling and sensitive data sanitization
• ✅ Performance optimizations with lazy initialization
• ✅ Comprehensive test coverage (232+ tests)
• ✅ Machine learning pattern recognition with privacy preservation
• ✅ Workflow automation for common debugging tasks
• ✅ Production-ready with <3% performance overhead

v0.1.5

• Added GPL-3.0 license compliance
• Initial pattern learning system
• Enhanced error context

v0.1.4

• Improved Claude Code integration
• Added suggestion engine
• Bug fixes

📄 License

Licensed under either of MIT or Apache-2.0 at your option.

It was GPL-3.0 until it was adopted into Ladvien/foundation_vs_slop, and relicensed on the way in to match the other bevy_* crates there: a GPL crate in the Bevy ecosystem cannot be adopted, and being adoptable is the entire reason these are published.

🙏 Acknowledgments

• Built for the Bevy Engine community
• Powered by Anthropic's MCP
• Inspired by the need for better game debugging tools

---

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