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.

Crate bevy_debugger_mcpCopy item path