# Contributing to Godot MCP

Thank you for considering contributing to Godot MCP! This document outlines the process for contributing to the project.

## Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.

## How Can I Contribute?

### Reporting Bugs

- Check if the bug has already been reported in the Issues section
- Use the bug report template if available
- Include detailed steps to reproduce the bug
- Include any relevant logs or screenshots
- Specify your environment (OS, Godot version, Python version, etc.)

### Suggesting Enhancements

- Check if the enhancement has already been suggested in the Issues section
- Use the feature request template if available
- Clearly describe the enhancement and its benefits
- Consider how the enhancement fits into the project's scope

### Pull Requests

1. Fork the repository
2. Create a new branch for your feature or bugfix (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests to ensure everything is working
5. Commit your changes with clear commit messages
6. Push to your branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## Development Process

### Setting Up the Development Environment

1. Clone the repository
2. Install [uv](https://docs.astral.sh/uv/) package manager
3. Sync dependencies:
   ```bash
   uv sync
   ```
4. Run the server locally:
   ```bash
   uv run python godot_mcp/server.py
   ```

### Project Structure

```
godot-mcp/
├── godot_mcp/         # Source code
│   ├── scripts/       # GDScript helpers (godot_operations.gd)
│   └── server.py      # Main MCP server implementation
├── tests/             # Test files
├── LICENSE            # MIT License
├── README.md          # Documentation
├── README.zh-CN.md    # Chinese Documentation
├── CONTRIBUTING.md    # Contribution guidelines
└── pyproject.toml     # Project configuration
```

### Code Style

- Follow PEP 8 guidelines for Python code
- **Type Hinting**: All functions and variables must be fully type-hinted
- **Docstrings**: All functions and classes must have standard docstrings
- Use clear and descriptive variable and function names
- Handle errors gracefully with detailed error messages

### Debugging

For debugging the MCP server:

1. Set the `DEBUG` environment variable to `true`
2. Run the server with `mcp dev` for interactive debugging:
   ```bash
   uv run mcp dev godot_mcp/server.py
   ```
3. Check the logs for detailed information about what's happening

### Adding New Tools

When adding new tools to the MCP server:

1. Define the tool in `godot_mcp/server.py` using the `@mcp.tool()` decorator
2. Add proper type hints and docstrings (these are used for the tool schema)
3. Implement the logic, calling Godot operations if necessary
4. Update the README.md with documentation for the new tool

#### Example Tool Implementation

```python
@mcp.tool()
async def my_new_tool(param1: str, param2: int = 10) -> str:
    """
    Description of what the tool does.
    
    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2
    """
    # implementation here
    server_instance.log_debug(f"Running my_new_tool with {param1}")
    
    if not validate(param1):
        raise ValueError("Invalid parameter")
        
    return f"Result: {param1} * {param2}"
```

### Cross-Platform Compatibility

When making changes, ensure they work across different platforms:

- Use `pathlib` or `os.path` for file paths instead of hardcoded strings
- Test on different operating systems if possible
- Consider different Godot installation locations

## Testing

- Run tests using pytest:
  ```bash
  uv run pytest
  ```
- Add new tests in the `tests/` directory for new features
- Ensure all tests pass before submitting a Pull Request

## Documentation

- Keep README.md (and README.zh-CN.md) up to date with new features
- Document all tools and their parameters
- Include examples for new functionality

## Questions?

If you have any questions about contributing, feel free to open an issue for discussion.

Thank you for your contributions!
