# Blender MCP - Agent Guidelines
## Project Structure
```
blender-mcp/
├── addon.py # Blender addon with socket server
├── src/
│ ├── server.py # MCP server with @mcp.tool() decorators
│ ├── tools/ # Tools layer (formatting & validation)
│ ├── blender_handlers/ # Handler layer (Blender API calls)
│ ├── prompts/ # MCP prompts
│ └── retopo_tools/ # Retopology-specific tools
├── features/ # BDD Gherkin feature files
├── tests/ # pytest-bdd tests
└── patch_notes/ # Release notes and summaries
```
## Documentation Rules
### Patch Notes Location
All patch notes, summaries, and release documentation MUST be placed in:
```
./patch_notes/
```
File naming convention:
```
YYYY-MM-DD_<description>.md
```
Examples:
- `2025-12-08_api_optimization_for_retopo_agent.md`
- `2025-12-06_features_28-31_test_report.md`
**DO NOT** place patch notes in `./docs/` or other locations.
## Development Workflow
### Adding New Tools (BDD-First)
1. **Create BDD feature file** in `features/XX_tool_name.feature`
2. **Copy to agent repo**: `D:\repos\agent_retopologist\features\`
3. **Implement handler** in `src/blender_handlers/` module
4. **Update `__init__.py`** exports
5. **Add to `addon.py`**: import, handler dict, method
6. **Add tools layer** in `src/tools/`
7. **Register in `src/server.py`**: import and @mcp.tool()
### Three-Layer Architecture
```
src/server.py (@mcp.tool decorator - MCP interface)
↓
src/tools/*.py (Tools layer - formatting & validation)
↓
src/blender_handlers/* (Handler layer - Blender API calls)
↓
addon.py (Socket server running in Blender)
```
### Testing
- Run tests: `python -m pytest tests/`
- Verify syntax: `python -m py_compile <file>`
- **DO NOT** write tests for new features unless explicitly requested
## Feature Files Sync
BDD feature files must be synced to the agent repository:
```
Source: D:\repos\blender-mcp\features\
Target: D:\repos\agent_retopologist\features\
```
## Code Style
- Follow existing patterns in the codebase
- Use type hints for function parameters
- Include docstrings with Parameters section
- Handler functions return dicts, tools layer formats output strings
