# GitHub Repository Setup Guide
This guide will help you create and push the MCP Home Assistant server to GitHub.
## Prerequisites
1. GitHub account
2. Git installed on your system
3. GitHub CLI (optional but recommended)
## Option 1: Using GitHub CLI (Recommended)
### Install GitHub CLI
- **Windows**: `winget install --id GitHub.cli`
- **macOS**: `brew install gh`
- **Linux**: See [GitHub CLI installation](https://github.com/cli/cli#installation)
### Authenticate
```bash
gh auth login
```
### Create Repository and Push
```bash
cd C:\Users\Administrator\mcp-homeassistant
# Initialize git repository
git init
# Add all files (excluding .env due to .gitignore)
git add .
# Create initial commit
git commit -m "Initial commit: Home Assistant MCP server with 13 tools for smart home control
Features:
- Entity state management and discovery
- Service calls for device control
- Historical data retrieval
- Full automation management (create, update, delete, enable, disable)
- 13 tools total for comprehensive Home Assistant integration"
# Create GitHub repository and push
gh repo create mcp-homeassistant --public --source=. --remote=origin --push
# Set description
gh repo edit --description "Model Context Protocol (MCP) server for Home Assistant integration - enables AI assistants to control smart home devices, manage automations, and query entity states"
```
## Option 2: Using Git + GitHub Web UI
### Step 1: Create Repository on GitHub
1. Go to https://github.com/new
2. Repository name: `mcp-homeassistant`
3. Description: `Model Context Protocol (MCP) server for Home Assistant integration - enables AI assistants to control smart home devices, manage automations, and query entity states`
4. Visibility: Public
5. Do NOT initialize with README, .gitignore, or license (we already have these)
6. Click "Create repository"
### Step 2: Initialize Local Repository
```bash
cd C:\Users\Administrator\mcp-homeassistant
# Initialize git repository
git init
# Add all files (excluding .env due to .gitignore)
git add .
# Create initial commit
git commit -m "Initial commit: Home Assistant MCP server with 13 tools for smart home control"
```
### Step 3: Push to GitHub
Replace `YOUR_USERNAME` with your GitHub username:
```bash
git remote add origin https://github.com/YOUR_USERNAME/mcp-homeassistant.git
git branch -M main
git push -u origin main
```
## Files That Will Be Pushed
The following files will be included in your repository:
- `server.py` - Main MCP server implementation
- `requirements.txt` - Python dependencies
- `README.md` - Comprehensive documentation
- `LICENSE` - MIT License
- `.gitignore` - Git ignore rules
- `.env.example` - Example environment configuration
**Note**: The `.env` file (containing your actual token) will NOT be pushed due to `.gitignore`.
## Post-Push Steps
### Add Topics (Tags)
```bash
gh repo edit --add-topic home-assistant --add-topic mcp --add-topic python --add-topic smart-home --add-topic ai --add-topic claude
```
Or manually via GitHub web UI:
1. Go to your repository page
2. Click the gear icon next to "About"
3. Add topics: `home-assistant`, `mcp`, `python`, `smart-home`, `ai`, `claude`
### Enable Issues
```bash
gh repo edit --enable-issues
```
### Add Repository Social Image (Optional)
1. Go to Settings → Options
2. Scroll to "Social preview"
3. Upload an image (1280x640px recommended)
## Verification Checklist
After pushing, verify:
- [ ] README.md displays correctly on repository home page
- [ ] LICENSE file is recognized (shows "MIT License" on repo page)
- [ ] `.env` file is NOT visible in repository
- [ ] All 6 files are present (server.py, requirements.txt, README.md, LICENSE, .gitignore, .env.example)
- [ ] Repository description is set
- [ ] Topics/tags are added
## Troubleshooting
### Authentication Issues
If you get authentication errors:
```bash
# For HTTPS
git remote set-url origin https://YOUR_USERNAME@github.com/YOUR_USERNAME/mcp-homeassistant.git
# Or use SSH (requires SSH key setup)
git remote set-url origin git@github.com:YOUR_USERNAME/mcp-homeassistant.git
```
### Accidentally Pushed .env File
If you accidentally pushed your `.env` file with secrets:
1. Remove from repository:
```bash
git rm --cached .env
git commit -m "Remove .env file with secrets"
git push
```
2. Rotate your Home Assistant token immediately:
- Go to Home Assistant → Profile
- Delete the compromised token
- Create a new token
- Update your local `.env` file
3. Consider using git-filter-repo to remove from history:
```bash
pip install git-filter-repo
git filter-repo --path .env --invert-paths
git push --force
```
## Next Steps
After successfully pushing to GitHub:
1. **Star your own repository** (to track changes)
2. **Share with the community** (Home Assistant forums, Reddit, etc.)
3. **Consider adding GitHub Actions** for automated testing
4. **Monitor issues** for bug reports and feature requests
5. **Keep dependencies updated** with Dependabot
## Additional Resources
- [GitHub Docs](https://docs.github.com/)
- [Git Documentation](https://git-scm.com/doc)
- [GitHub CLI Manual](https://cli.github.com/manual/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
