Auto-Update & Release System

This document describes the auto-update functionality and release automation system implemented for mcpproxy.

Update Modes

🔄 Auto-Update (Default - Recommended)

• Automatic Updates: Downloads and applies updates automatically
• Daily Checks: Background checks every 24 hours
• Manual Checks: "Check for Updates..." in system tray
• Smart Detection: Avoids conflicts with package managers

# Default mode - auto-update enabled
./mcpproxy serve --tray=true

🚫 Disabled Mode

• No Updates: Completely disables update checking
• Manual Only: User must update manually

# Disable auto-update completely
export MCPPROXY_DISABLE_AUTO_UPDATE=true
./mcpproxy serve --tray=true

# Or add to shell profile for permanent setting
echo 'export MCPPROXY_DISABLE_AUTO_UPDATE=true' >> ~/.zshrc

🔔 Notification-Only Mode

• Check Only: Checks for updates but doesn't download
• User Choice: Notifies user, lets them decide
• Log Messages: Shows update info in logs

# Notification-only mode
export MCPPROXY_UPDATE_NOTIFY_ONLY=true
./mcpproxy serve --tray=true

🧪 Prerelease/Canary Mode

• Prerelease Updates: Allows updates to RC and development versions
• Latest Available: Gets the newest version regardless of prerelease status
• For Testing: Ideal for early adopters and testing new features

# Enable prerelease updates (canary behavior)
export MCPPROXY_ALLOW_PRERELEASE_UPDATES=true
./mcpproxy serve --tray=true

# Or add to shell profile for permanent setting
echo 'export MCPPROXY_ALLOW_PRERELEASE_UPDATES=true' >> ~/.zshrc

Package Manager Integration

🍺 Homebrew (macOS)

Auto-update is automatically disabled when installed via Homebrew to prevent conflicts:

# Homebrew installation - auto-update disabled automatically.
# The fully-qualified name auto-taps smart-mcp-proxy/mcpproxy, so no
# separate `brew tap` step is needed.
brew install smart-mcp-proxy/mcpproxy/mcpproxy          # CLI
brew install --cask smart-mcp-proxy/mcpproxy/mcpproxy   # tray app

# Use Homebrew for updates
brew upgrade mcpproxy

📦 Other Package Managers

The system detects common package manager paths and disables auto-update accordingly.

Technical Details

Update Process Flow

1. Check for Updates (Daily timer or manual click)
2. Query GitHub API for latest release
3. Compare versions using semantic versioning
4. Detect installation type (standalone vs package manager)
5. Download appropriate archive for OS/architecture
6. Extract binary from archive
7. Replace current executable atomically
8. Restart application

File Format Support

• Windows: .zip archives
• macOS: .tar.gz archives
• Linux: .tar.gz archives

Asset Detection Priority

1. Latest Assets: mcpproxy-latest-{os}-{arch}.{ext}
2. Versioned Assets: mcpproxy-{version}-{os}-{arch}.{ext}

Security Features

• HTTPS Only: All downloads use HTTPS
• Atomic Updates: Safe binary replacement with rollback
• Version Validation: Semantic version checking prevents downgrades
• Package Manager Detection: Prevents conflicts with system package managers

Configuration

Environment Variables

System Tray Menu

mcpproxy
├── Status: Running (localhost:8080)
├── ─────────────────────────────
├── Start/Stop Server
├── ─────────────────────────────
├── Check for Updates...          ← Manual update check
│   ├── Auto-update: Enabled      ← Shows current mode
│   └── [Disabled for Homebrew]   ← If package manager detected
├── ─────────────────────────────
└── Quit

Troubleshooting

Common Issues

❌ "no suitable asset found for darwin-arm64.zip"

Fixed: Now looks for correct .tar.gz files on macOS/Linux

⚠️ "auto-update disabled for Homebrew installations"

Expected: Prevents conflicts with brew upgrade

🔄 Updates Not Working

1. Check network connectivity
2. Verify GitHub access: curl -I https://api.github.com/repos/smart-mcp-proxy/mcpproxy-go/releases/latest
3. Check logs for specific errors
4. Try notification-only mode to debug

Manual Update Methods

Standalone Installation

# Download from GitHub releases
curl -L -o mcpproxy.tar.gz https://github.com/smart-mcp-proxy/mcpproxy-go/releases/latest/download/mcpproxy-latest-darwin-arm64.tar.gz
tar -xzf mcpproxy.tar.gz
chmod +x mcpproxy
./mcpproxy --version

Homebrew

brew upgrade mcpproxy

Go Install (Development)

go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest

Best Practices

For End Users

• Use Default Mode: Auto-update provides the best experience
• Homebrew Users: Let Homebrew handle updates
• Corporate/Restricted: Use notification-only mode

For Developers

• Test Updates: Use development builds before releases
• Version Tags: Follow semantic versioning (v1.0.0)
• Asset Naming: Maintain consistent asset naming conventions

For System Administrators

• Disable Auto-Update: Use MCPPROXY_DISABLE_AUTO_UPDATE=true for controlled environments
• Monitor Logs: Watch for update notifications and errors
• Network Access: Ensure GitHub API access for update checks

Release Process

Creating a Release

# Tag a new version
git tag v1.0.0
git push origin v1.0.0

# GitHub Actions will:
# 1. Build cross-platform binaries
# 2. Create both versioned and latest assets
# 3. Create GitHub release with download links

Asset Structure

Each release includes:

• mcpproxy-v1.0.0-linux-amd64.tar.gz (versioned)
• mcpproxy-latest-linux-amd64.tar.gz (latest)
• Similar files for all supported platforms

The auto-updater prioritizes "latest" assets for consistency with website download links.