Godot Scene Analyzer

# Custom Godot Scene Analyzer MCP Server ## What It Is An MCP (Model Context Protocol) server that gives Claude deep, semantic understanding of your Godot scenes—specifically designed to enforce and validate your ECS-driven architecture where Godot handles visuals and your custom ECS handles all game logic. **Not a generic scene reader.** This server knows your architectural rules and actively helps you maintain separation between presentation and logic. ## The Problem It Solves ### Without This Server **You:** "Check if any of my scenes have game logic in scripts" **Claude:** "I'd need you to paste each .tscn file and script. Can you share them?" *You paste 30 files...* **Claude:** "In player.gd line 47, there's a velocity calculation. That might be game logic?" #### Problems: - ❌ Manual file dumping every time - ❌ Claude guesses what's "game logic" vs "visual sync" - ❌ No systematic validation across your project - ❌ You maintain the rules in your head ### With This Server **You:** "Check if any of my scenes have game logic in scripts" **Claude:** *Automatically scans your Godot project, understands your ECS architecture rules, and provides:* - ✅ Instant analysis of all scenes - ✅ Precise identification of architecture violations - ✅ Clear distinction between valid visual sync code and improper game logic - ✅ Systematic validation with your architectural rules built-in - ✅ Actionable recommendations for fixes ## Features ### Architectural Enforcement - **ECS-Aware Analysis**: Understands the separation between Godot (presentation) and your ECS (logic) - **Rule Validation**: Automatically detects when scripts contain game logic that should be in ECS - **Pattern Recognition**: Distinguishes between acceptable visual synchronization code and architectural violations ### Deep Scene Understanding - **Scene Hierarchy Analysis**: Maps node structures and relationships - **Script Inspection**: Analyzes attached GDScript files for logic patterns - **Resource Tracking**: Identifies dependencies and connections between scenes ### Smart Reporting - **Violation Detection**: Flags scripts that break the ECS architecture - **Context-Aware Suggestions**: Provides specific guidance on moving logic to ECS - **Project-Wide Insights**: Summarizes architectural health across all scenes ## How It Works The MCP server integrates with Claude to provide: 1. **Automatic Project Scanning**: Reads your Godot project structure 2. **Rule-Based Analysis**: Applies your ECS architectural patterns 3. **Semantic Understanding**: Gives Claude context about what each scene does and how it fits your architecture 4. **Interactive Queries**: Answer questions about scenes without manual file sharing ## Use Cases ### Architecture Validation ``` "Are there any scenes violating the ECS pattern?" "Which scripts are doing game logic calculations?" "Show me all scenes that directly modify game state" ``` ### Refactoring Support ``` "Help me move the logic from player.gd to the ECS" "Which visual sync patterns am I using consistently?" "Find duplicate logic across scenes" ``` ### Code Review ``` "Review the enemy scenes for architecture compliance" "Check if the new UI scenes follow our patterns" "Validate that no scenes are managing their own state" ``` ## Installation **Requirements**: Python 3.14 or higher ```bash # Clone the repository git clone https://github.com/PurlieuStudios/godot-mcp.git cd godot-mcp # Verify Python version python --version # Should show Python 3.14.x # Create virtual environment python -m venv venv # Activate virtual environment # On Windows: venv\Scripts\activate # On macOS/Linux: source venv/bin/activate # Install dependencies pip install -e . # Configure for your Godot project python setup.py ``` ## Configuration Create a `.mcp-config.json` in your Godot project root: ```json { "projectPath": "/path/to/your/godot/project", "ecsRules": { "allowedVisualPatterns": [ "sync_position", "update_animation", "apply_visual_effect" ], "forbiddenLogicPatterns": [ "calculate_damage", "update_velocity", "manage_state", "ai_decision" ] } } ``` ## Usage with Claude Once the MCP server is running, you can ask Claude: ``` "Analyze my Godot scenes for ECS compliance" "Show me which scripts need refactoring" "Help me understand the scene hierarchy for the combat system" "Are there any scripts doing physics calculations?" ``` Claude will automatically use the MCP server to access your project structure and provide informed, accurate answers based on your actual code. ## Architecture Principles This server enforces the following separation: ### Godot Should Handle: - ✅ Visual representation and rendering - ✅ Animation playback - ✅ Audio playback - ✅ Input event routing - ✅ Syncing visual state from ECS data ### ECS Should Handle: - ✅ Game state management - ✅ Game logic and rules - ✅ Physics and collision logic - ✅ AI decisions - ✅ Combat calculations ### The Boundary: Scripts attached to Godot nodes should only **read** from ECS and **update** visuals. They should never contain game logic or state management. ## Benefits ### For You - Maintain architectural consistency across your project - Catch violations early in development - Reduce cognitive load—let the server remember the rules - Faster code reviews and refactoring ### For Claude - Deep understanding of your project structure - Accurate analysis without manual file sharing - Context-aware suggestions that respect your architecture - Ability to help with large-scale refactoring ## Requirements - Python 3.14+ - Godot 4.x project - Claude with MCP support ## License MIT ## Contributing Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## Support - Issues: [GitHub Issues](https://github.com/purlieu-studios/godot-mcp/issues) - Discussions: [GitHub Discussions](https://github.com/purlieu-studios/godot-mcp/discussions) --- Built with ❤️ for developers who believe in clean architecture and the power of AI-assisted development.