Guide: How to Become a Contributor to blender-mcp

[elfenlieds7]

How to Become a Contributor to blender-mcp

A step-by-step guide for developers who want to contribute to this project.

Overview

This guide will walk you through the complete process of making your first contribution to blender-mcp, from forking the repository to submitting your pull request.

Prerequisites

• Git installed on your system
• GitHub account
• GitHub CLI (gh) installed (recommended)
  • Windows: winget install GitHub.cli
  • Mac: brew install gh
• Basic knowledge of Git and GitHub workflow

Step 1: Fork the Repository

Option A: Using GitHub CLI (Recommended)

The easiest way is to fork and clone in one command:

# This will fork the repo to your account and clone it locally
gh repo fork ahujasid/blender-mcp --clone --remote

This automatically sets up:

• origin → Your fork (where you push changes)
• upstream → Original repo (where you sync updates)

Option B: Manual Fork

If you prefer to do it manually or already have the original repo cloned:

1. Fork on GitHub: Go to https://github.com/ahujasid/blender-mcp and click "Fork"

2. Clone your fork:

git clone https://github.com/YOUR-USERNAME/blender-mcp.git blender-mcp-fork
cd blender-mcp-fork

3. Add upstream remote:

git remote add upstream https://github.com/ahujasid/blender-mcp.git

4. Verify setup:

git remote -v

You should see:

origin    https://github.com/YOUR-USERNAME/blender-mcp.git (fetch)
origin    https://github.com/YOUR-USERNAME/blender-mcp.git (push)
upstream  https://github.com/ahujasid/blender-mcp.git (fetch)
upstream  https://github.com/ahujasid/blender-mcp.git (push)

Step 2: Keep Your Fork Up-to-Date

Before starting any new work, always sync with upstream:

# Fetch latest changes from original repo
git fetch upstream

# Switch to main branch
git checkout main

# Merge upstream changes
git merge upstream/main

# Push to your fork (optional but recommended)
git push origin main

Step 3: Create a Feature Branch

Never work directly on main. Always create a new branch:

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/bug-description

Branch naming conventions:

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• refactor/ - Code refactoring

Step 4: Make Your Changes

Now you can make your contributions:

1. Find something to work on:

   • Check existing Issues
   • Look for "good first issue" labels
   • Join the Discord for ideas
   • Improve documentation
   • Fix bugs you've encountered

2. Make your changes:

   • Edit files
   • Test your changes
   • Follow existing code style

3. Commit your changes:

git add .
git commit -m "Brief description of your changes"

Good commit message examples:

• ✅ Add support for viewport screenshots
• ✅ Fix connection timeout issue
• ✅ Update installation instructions for Windows
• ❌ fix stuff
• ❌ update

Step 5: Push to Your Fork

git push origin feature/your-feature-name

Step 6: Create a Pull Request

Option A: Using GitHub CLI

gh pr create --repo ahujasid/blender-mcp --base main --head YOUR-USERNAME:feature/your-feature-name

Follow the prompts to add:

• Title (clear, descriptive)
• Description (what, why, how)

Option B: Using GitHub Web Interface

1. Go to your fork on GitHub
2. Click "Compare & pull request" button
3. Fill in:
   • Title: Clear, concise description
   • Description:
     • What problem does this solve?
     • What changes did you make?
     • How to test it?
     • Screenshots (if UI changes)

Step 7: Respond to Feedback

• Maintainers may request changes
• Make updates on the same branch
• Push changes - PR updates automatically
• Be patient and respectful

Common Scenarios

Sync Fork with Latest Upstream Changes

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Update Your PR Branch with Latest Main

git checkout feature/your-feature-name
git merge main
# Resolve any conflicts
git push origin feature/your-feature-name

Fixing Mistakes in Your PR

# Make more changes
git add .
git commit -m "Address review feedback"
git push origin feature/your-feature-name

Project-Specific Guidelines

Technology Stack

• Python - MCP server implementation
• Blender Python API - Addon development
• Socket communication - Client-server protocol
• Model Context Protocol (MCP) - Claude integration

Areas to Contribute

• 🐛 Bug fixes
• ✨ New features (e.g., new Blender operations)
• 📚 Documentation improvements
• 🎨 UI/UX enhancements
• 🧪 Tests
• 🔧 Performance optimizations
• 🌐 Internationalization

Getting Help

• Discord: https://discord.gg/z5apgR8TFU
• GitHub Issues: For bug reports and feature requests
• Maintainer: @ahujasid

Tips for Success

1. ✅ Start small - Fix typos, improve docs, add comments
2. ✅ Test thoroughly - Make sure your changes work
3. ✅ One feature per PR - Don't bundle multiple changes
4. ✅ Clear communication - Explain your changes well
5. ✅ Be patient - Maintainers are volunteers
6. ✅ Stay engaged - Respond to comments promptly

Example Workflow Summary

# One-time setup
gh repo fork ahujasid/blender-mcp --clone --remote
cd blender-mcp

# For each contribution
git fetch upstream
git checkout main
git merge upstream/main
git checkout -b feature/my-awesome-feature

# Make changes, test, commit
git add .
git commit -m "Add awesome feature"
git push origin feature/my-awesome-feature

# Create PR
gh pr create --repo ahujasid/blender-mcp

What Happens After Your PR is Merged?

1. 🎉 Congratulations! You're now a contributor!
2. Your username appears in the Contributors page
3. You can add this to your portfolio/resume
4. You've helped make AI + 3D more accessible!

Questions?

• Check existing Issues
• Ask in Discord
• Open a Discussion

---

Happy contributing! 🚀

This guide was created by the community to help new contributors get started. Feel free to suggest improvements!