# Contributing to MCP ComfyUI FLUX
Thank you for your interest in contributing! We welcome contributions of all kinds.
## How to Contribute
### Reporting Issues
- Check existing issues first to avoid duplicates
- Include system information (OS, Docker version, GPU)
- Provide clear reproduction steps
- Include relevant logs from `docker-compose logs`
### Submitting Pull Requests
1. **Fork and Clone**
```bash
git clone https://github.com/yourusername/mcp-comfyui-flux.git
cd mcp-comfyui-flux
```
2. **Create a Branch**
```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description
```
3. **Make Your Changes**
- Follow the existing code style
- Update documentation if needed
- Test your changes locally
4. **Test Your Changes**
```bash
# Build and test
./build.sh
docker-compose -p mcp-comfyui up -d
# Run any tests
docker exec mcp-comfyui-flux-mcp-server-1 npm test
```
5. **Commit Your Changes**
```bash
git add .
git commit -m "feat: add new feature"
# or "fix: resolve issue with..."
# or "docs: update README"
```
Follow [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` new feature
- `fix:` bug fix
- `docs:` documentation changes
- `style:` formatting, missing semicolons, etc.
- `refactor:` code restructuring
- `test:` adding tests
- `chore:` maintenance tasks
6. **Push and Create PR**
```bash
git push origin your-branch-name
```
Then create a Pull Request on GitHub.
## Development Setup
### Prerequisites
- Docker 20.10+
- Docker Compose 2.0+
- Node.js 20+ (for MCP server development)
- NVIDIA GPU with 12GB+ VRAM (optional, for GPU testing)
### Local Development
1. **Install Dependencies**
```bash
./install.sh --debug
```
2. **Development Mode**
```bash
# Build with debug output
./build.sh --debug
# Watch logs
docker-compose -p mcp-comfyui logs -f
```
3. **Testing Changes**
- For Dockerfile changes: rebuild with `./build.sh --no-cache`
- For MCP server changes: restart container with `docker-compose -p mcp-comfyui restart mcp-server`
- For ComfyUI workflows: test in the web UI at http://localhost:8188
## Code Style Guidelines
### Docker
- Use multi-stage builds for optimization
- Pin versions for reproducibility
- Add comments for complex operations
- Use BuildKit cache mounts where appropriate
### JavaScript/Node.js
- Use ES6+ features
- Add JSDoc comments for functions
- Handle errors gracefully
- Use async/await over callbacks
### Shell Scripts
- Use `set -euo pipefail` for safety
- Add error handling and logging
- Make scripts idempotent
- Use shellcheck for validation
### Python
- Follow PEP 8
- Use type hints where applicable
- Document functions and classes
- Keep compatibility with Python 3.11+
## Testing
### Manual Testing Checklist
- [ ] Builds successfully with `./build.sh`
- [ ] Containers start without errors
- [ ] ComfyUI web interface loads
- [ ] MCP server connects to ComfyUI
- [ ] Image generation works
- [ ] Custom nodes load properly
### Automated Tests
```bash
# Run MCP server tests
docker exec mcp-comfyui-flux-mcp-server-1 npm test
# Test image generation
docker exec mcp-comfyui-flux-mcp-server-1 node examples/example.js
```
## Documentation
- Update README.md for user-facing changes
- Update CLAUDE.md for AI assistant context
- Add inline comments for complex logic
- Include examples for new features
## Questions?
Feel free to open an issue for discussion or join our community:
- GitHub Issues: [Project Issues](https://github.com/yourusername/mcp-comfyui-flux/issues)
- Discussions: [Project Discussions](https://github.com/yourusername/mcp-comfyui-flux/discussions)
## License
By contributing, you agree that your contributions will be licensed under the same license as the project (MIT).
