personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
da628a3774999bec84a396abce2bbe624a25bc6c
leo-claude-mktplace/docs/UPDATING.md

5.7 KiB
Raw Blame History

Updating Leo Claude Marketplace

This guide covers how to update your local installation when new versions are released.

⚠️ CRITICAL: Run Setup in Installed Location

When Claude Code installs a marketplace, it copies files to ~/.claude/plugins/marketplaces/ but does NOT create Python virtual environments. You must run setup manually after installation or update.

After installing or updating the marketplace:

cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh

This creates the required .venv directories for MCP servers. Without this step, all MCP servers will fail to start.

Quick Update (Source Repository)

# 1. Pull latest changes to source
cd /path/to/leo-claude-mktplace
git pull origin main

# 2. Run post-update script (updates source repo venvs)
./scripts/post-update.sh

# 3. CRITICAL: Run setup in installed marketplace location
cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh

Then restart your Claude Code session to load any changes.

What the Post-Update Script Does

  1. Updates Python dependencies for MCP servers (gitea, netbox)
  2. Shows recent changelog entries so you know what changed
  3. Validates your configuration is still compatible

After Updating: Re-run Setup if Needed

When to Re-run Setup

You typically don't need to re-run setup after updates. However, re-run your plugin's setup command (e.g., /pm-setup, /pr-setup, /cmdb-setup) if:

  • Changelog mentions new required environment variables
  • Changelog mentions breaking changes to configuration
  • MCP tools stop working after update

For Existing Projects

If an update requires new project-level configuration:

/project-init

This will detect existing settings and only add what's missing.

Manual Steps After Update

Some updates may require manual configuration changes:

New Environment Variables

If the changelog mentions new environment variables:

  1. Check the variable name and purpose in the changelog
  2. Add it to the appropriate config file:
    • System variables → ~/.config/claude/gitea.env or netbox.env
    • Project variables → .env in your project root

New MCP Server Features

If a new MCP server tool is added:

  1. The post-update script handles dependency installation
  2. Check plugin documentation for usage
  3. New tools are available immediately after session restart

Breaking Changes

Breaking changes will be clearly marked in CHANGELOG.md with migration instructions.

Setup Script and Configuration Workflow Changes

When updating, review if changes affect the setup workflow:

  1. Check for setup command changes:

    git diff HEAD~1 plugins/*/commands/*-setup.md
git diff HEAD~1 plugins/*/commands/project-init.md
git diff HEAD~1 plugins/*/commands/project-sync.md

  2. Check for hook changes:

    git diff HEAD~1 plugins/*/hooks/hooks.json

  3. Check for configuration structure changes:

    git diff HEAD~1 docs/CONFIGURATION.md

If setup commands changed:

  • Review what's new (new validation steps, new prompts, etc.)
  • Consider re-running your plugin's setup command or /project-init to benefit from improvements
  • Existing configurations remain valid unless changelog notes breaking changes

If hooks changed:

  • Restart your Claude Code session to load new hooks
  • New hooks (like SessionStart validation) activate automatically

If configuration structure changed:

  • Check if new variables are required
  • Run /project-sync if repository detection logic improved

Troubleshooting Updates

Dependencies fail to install

# Install missing dependencies (do NOT delete .venv)
cd mcp-servers/gitea
source .venv/bin/activate
pip install -r requirements.txt
deactivate

Configuration no longer works

  1. Check CHANGELOG.md for breaking changes
  2. Run your plugin's setup command (e.g., /pm-setup) to re-validate and fix configuration
  3. Compare your config files with documentation in docs/CONFIGURATION.md

MCP server won't start after update

Most common cause: Virtual environments don't exist in the installed marketplace.

# Fix: Run setup in installed location
cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh

If that doesn't work:

  1. Check Python version: python3 --version (requires 3.10+)
  2. Verify venv exists in INSTALLED location: 
    ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/gitea/.venv
ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/netbox/.venv
  3. If missing, run setup.sh as shown above.
  4. Restart Claude Code session
  5. Check logs for specific errors

"X MCP servers failed" on startup

This almost always means the venvs don't exist in the installed marketplace:

cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh

Then restart Claude Code.

New commands not available

  1. Restart your Claude Code session
  2. Verify the plugin is still installed
  3. Check if the command requires additional setup

Version Pinning

To stay on a specific version:

# List available tags
git tag

# Checkout specific version
git checkout v3.0.0

# Run post-update
./scripts/post-update.sh

Checking Current Version

The version is displayed in the main README.md title and in CHANGELOG.md.

# Check version from changelog
head -20 CHANGELOG.md

Getting Help

  • Check docs/CONFIGURATION.md for setup guide
  • Check docs/COMMANDS-CHEATSHEET.md for command reference
  • Review CHANGELOG.md for recent changes
  • Search existing issues in Gitea
Reference in New Issue View Git Blame Copy Permalink