Python Discord Bots

A modern Discord bot collection featuring three specialized bots: MTG Card Bot for Magic card lookups, Clippy Bot for interactive AI responses, and Music Bot for audio streaming with queue management.

Documentation

• Discord.py Update Guide - Managing the local discord.py repository
• Commands Cheatsheet - Quick command reference

Quick Start

Prerequisites

• uv - Fast Python package manager
• Discord Bot Token(s) - From Discord Developer Portal

Installation

# 1. Install uv and Python 3.12
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12

# 2. Clone and setup
git clone https://github.com/dunamismax/discord-py-bots.git
cd discord-py-bots

# 3. Configure environment
cp env.example .env
# Edit .env with your Discord bot tokens

# 4. Start bots
uv run python start_bots.py

Environment Configuration

# Required Discord tokens
CLIPPY_DISCORD_TOKEN=your_clippy_token_here
MUSIC_DISCORD_TOKEN=your_music_token_here
MTG_DISCORD_TOKEN=your_mtg_token_here

# Optional settings
LOG_LEVEL=info
MUSIC_MAX_QUEUE_SIZE=100
MTG_CACHE_TTL=3600

Bot Features

MTG Card Bot

Advanced Magic: The Gathering card lookup with fuzzy search and filtering.

!lightning bolt                    # Basic card lookup
!black lotus; sol ring; time walk  # Multi-card grid
!brainstorm e:ice is:foil          # Advanced filtering
!random                            # Random card discovery

Clippy Bot

Interactive AI assistant with modern Discord slash commands.

/clippy                   # Get quirky AI responses
/clippy_wisdom           # Questionable life advice
/clippy_help             # Interactive help with buttons

Music Bot

Full-featured audio streaming with YouTube integration and queue management.

/play <song/url>         # Play music from YouTube
/queue                   # Show current playlist
/skip, /pause, /resume   # Playback controls
/volume <0-100>          # Adjust volume

Architecture

discord-py-bots/
├── bots/                    # Independent bot applications
│   ├── clippy/             # Interactive AI assistant
│   ├── mtg-card-bot/       # Magic card lookups
│   └── music/              # Audio streaming
├── discord.py/             # Local discord.py (v8 voice fix)
├── docs/                   # Comprehensive documentation
├── start_bots.py          # Interactive bot launcher
└── troubleshoot_bots.sh   # Process management utility

Development

# Interactive bot launcher (recommended)
uv run python start_bots.py

# Individual bot execution
uv run --package clippy-bot python -m clippy
uv run --package mtg-card-bot python -m mtg_card_bot
uv run --package music-bot python -m music

# Development tools
uv run ruff format .       # Code formatting
uv run ruff check .        # Linting
uv run mypy bots/         # Type checking

Key Features

• Graceful Shutdown - Enhanced Ctrl+C handling and process management
• Fixed Voice Connections - Local discord.py with WebSocket 4006 fix
• Modern Packaging - uv-based dependency management
• Interactive Management - Menu-driven bot launcher with real-time logs
• Comprehensive Docs - Detailed guides for maintenance and updates

Important Notes

This project uses a local copy of discord.py with unreleased fixes for voice connection issues. See the Discord.py Update Guide for maintenance instructions.

📄 License

MIT License - see LICENSE for details.

---

Modern Discord Bot Collection
_{Built with Python 3.12+ • discord.py • uv • 2025 Best Practices}