gh-superclaude-org-superclaude-plugin/commands/setup-mcp.md

description

description
Interactive MCP server setup wizard

MCP Server Setup Wizard

You are now in MCP Setup Wizard Mode. Guide the user through checking prerequisites, verifying the automatic MCP configuration, and setting up optional features.

Setup Process

Step 1: Welcome & Overview

Explain the MCP server architecture:

🚀 SuperClaude MCP Setup Wizard

SuperClaude plugin automatically configures AIRIS MCP Gateway, which provides
unified access to 10 powerful tools:

Essential (Free):
  • sequential-thinking - Multi-step problem solving
  • context7 - Official documentation search
  • git - Repository operations
  • puppeteer - Browser automation
  • playwright - Cross-browser testing
  • chrome-devtools - Browser debugging

Optional (API Key Required):
  • tavily - Web search ($)
  • magic - UI component generation ($)
  • serena - Context-aware intelligence
  • morphllm - Multi-model orchestration

Let's verify your setup...

Step 2: Backup Existing MCP Configuration (Safety First!)

IMPORTANT: Before proceeding, check if the user has existing MCP servers configured.

# Check for existing MCP configuration
if [ -f ~/.claude/settings.local.json ]; then
    echo "⚠️  Found existing Claude Code settings"
    echo ""
    echo "RECOMMENDED: Backup your settings before enabling the plugin:"
    echo "  cp ~/.claude/settings.local.json ~/.claude/settings.local.json.backup"
    echo ""
    read -p "Have you backed up your settings? (y/n): " backup_done

    if [ "$backup_done" != "y" ]; then
        echo ""
        echo "Creating backup now..."
        cp ~/.claude/settings.local.json ~/.claude/settings.local.json.backup
        echo "✅ Backup created: ~/.claude/settings.local.json.backup"
    fi
else
    echo "✅ No existing settings found (fresh installation)"
fi

# Check for project-specific MCP config
if [ -f .mcp.json ]; then
    echo ""
    echo "⚠️  Found project-specific MCP configuration (.mcp.json)"
    echo "RECOMMENDED: Backup before proceeding:"
    echo "  cp .mcp.json .mcp.json.backup"
fi

Step 3: Check Prerequisites

# Check uvx installation
if command -v uvx &> /dev/null; then
    echo "✅ uvx is installed ($(uvx --version))"
else
    echo "❌ uvx is not installed"
    echo ""
    echo "Install with:"
    echo "  pip install uv"
    echo "  # or"
    echo "  brew install uv"
fi

Step 4: Verify Plugin MCP Configuration

# Check if plugin is installed
/plugin list | grep "sc" || echo "⚠️ SuperClaude plugin not found"

# Test MCP server availability
claude mcp list 2>/dev/null || echo "⚠️ MCP CLI not available (check Claude Code version)"

Step 5: Interactive Configuration (Optional Features)

Present an interactive menu for optional API keys:

📝 Optional API Key Configuration

Some MCP tools require API keys for full functionality.
Would you like to configure them now?

Available services:
  1. Tavily (Web Search) - Get key: https://tavily.com
  2. 21st.dev (Magic UI) - Get key: https://21st.dev

Select options (comma-separated, or 'skip'): _

If user wants to configure:

# Guide them through setting environment variables
echo "Add these to your shell profile (~/.zshrc or ~/.bashrc):"
echo ""
echo "export TAVILY_API_KEY='your-tavily-key'"
echo "export TWENTYFIRST_API_KEY='your-21st-key'"
echo ""
echo "Then restart your terminal or run: source ~/.zshrc"

Step 6: Test MCP Connection

# Try to invoke AIRIS MCP Gateway
echo "Testing MCP server connection..."

# This would test if the MCP server responds
claude mcp get airis-mcp-gateway 2>&1 | head -20

# Check if tools are available
echo ""
echo "Available MCP tools:"
# List available tools from the server

Step 7: Troubleshooting Guide

If any issues are detected, provide specific solutions:

Issue: uvx not found

# Solution 1: Install via pip
pip install uv

# Solution 2: Install via Homebrew (macOS)
brew install uv

# Verify installation
uvx --version

Issue: MCP server not responding

# Check Claude Code version (needs v1.5+)
claude --version

# Test direct uvx execution
uvx --from git+https://github.com/agiletec-inc/airis-mcp-gateway airis-mcp-gateway --help

# Check plugin installation
/plugin list

# Reinstall plugin if needed
/plugin update sc@superclaude-official

Issue: Plugin MCP not in settings

The plugin's MCP configuration should be automatic.
If it's not working:

1. Restart Claude Code completely
2. Check plugin is enabled: /plugin list
3. Look for errors in Claude Code console
4. Report issue: https://github.com/SuperClaude-Org/SuperClaude_Plugin/issues

Step 8: Final Summary

Provide a setup summary:

✅ MCP Setup Complete!

Status:
  • Prerequisites: ✅ All installed
  • AIRIS MCP Gateway: ✅ Connected
  • Available Tools: 10 tools ready
  • API Keys: 2 configured, 8 free tools ready

Quick Test:
  Try: /sc:research "test query"
  Or: /sc:implement "test feature"

Documentation:
  https://superclaude.netlify.app/mcp-servers

Need help? Run: /sc:verify-mcp

Best Practices

• Always check prerequisites before attempting configuration
• Provide copy-paste ready commands
• Explain what each tool does and why it's useful
• Make API key setup optional and clear about costs
• Offer a quick verification test at the end

Exit

After completing the setup wizard and providing the summary, exit setup mode.

The user can re-run this wizard anytime by using /sc:setup-mcp.