Crate bevy_debugger_mcp

Expand description

§Bevy Debugger MCP

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

This crate provides a comprehensive debugging toolkit for Bevy games, enabling natural language interaction with game state through Claude Code. It bridges the gap between AI assistance and game development by offering intelligent observation, experimentation, and analysis capabilities.

§Quick Start

Add BRP to your Bevy game:

[dependencies]
bevy = { version = "0.12", features = ["bevy_remote_protocol"] }

Enable BRP in your game:

use bevy::prelude::*;
use bevy::remote::RemotePlugin;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(RemotePlugin::default())
        .run();
}

Install and configure the MCP server:

cargo install bevy_debugger_mcp
bevy-debugger-mcp --help

Configure Claude Code:

{
  "mcpServers": {
    "bevy-debugger-mcp": {
      "command": "bevy-debugger-mcp",
      "args": [],
      "type": "stdio"
    }
  }
}

§Features

🔍 Natural Language Queries: Ask about your game state in plain English
🧪 Controlled Experiments: Test hypotheses with systematic variations
📊 Performance Analysis: Monitor and analyze game performance in real-time
⏱️ Time-Travel Debugging: Record, replay, and branch timelines
🚨 Anomaly Detection: Automatically detect unusual patterns in game behavior
📈 Stress Testing: Systematically test your game under various loads
🔧 Tool Orchestration: Chain debugging operations into complex workflows

§Core Modules

§Observation and Query

query_parser - Natural language to game queries
semantic_analyzer - Semantic understanding of game concepts
brp_client - Bevy Remote Protocol communication

§Experimentation and Testing

experiment_system - Controlled game state experiments
hypothesis_system - Property-based testing for games
stress_test_system - Systematic stress testing

§Time and State Management

recording_system - Game state recording and persistence
playback_system - Deterministic replay capabilities
timeline_branching - Multi-timeline debugging with branching
checkpoint - Save/restore debugging sessions

§Analysis and Monitoring

anomaly_detector - Pattern recognition for unusual behavior
state_diff - Intelligent state comparison and diffing
diagnostics - System health monitoring and reporting

§Infrastructure

mcp_server - Model Context Protocol server implementation
tool_orchestration - Complex debugging workflow coordination
error - Comprehensive error handling and recovery
config - Configuration management

§Example Usage

use bevy_debugger_mcp::prelude::*;

// Connect to your Bevy game
let mut client = BrpClient::connect("ws://localhost:15702").await?;

// Parse natural language queries
let parser = RegexQueryParser::new();
let request = parser.parse("find entities with Transform and Velocity")?;

// Execute the query
let response = client.send_request(request).await?;
println!("Found entities: {:?}", response);

§Architecture

The system follows a modular architecture:

Claude Code ←→ MCP Protocol ←→ MCP Server ←→ BRP Protocol ←→ Bevy Game
                                   ↓
                             Tool Modules
                          (observe, experiment,
                           stress, replay, etc.)

§Error Handling

All operations return Result<T, Error> types. The system includes comprehensive error recovery with automatic reconnection, dead letter queues for failed operations, and checkpoint/restore capabilities.

Modules§

Macros§

concat_strs: Compile-time string concatenation for efficiency
debug_only: Zero-cost abstraction for debug-only operations
fast_path: Fast path for common cases with minimal overhead
feature_enabled: Zero-overhead feature flag checks
feature_stub: No-op implementations for disabled features
if_optimized: Conditional compilation based on optimization level
likely_if: Branch prediction hints for hot paths
profile_async_block: Async version of profile_block macro
profile_block: Macro for easy profiling of code blocks
release_only: Zero-cost abstraction for release-only operations
static_assert_config: Compile-time assertions for configuration validation
unlikely_if
with_feature: Conditional compilation for different feature sets
without_feature