# 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.