slack-joke-agent 1.0.9

Daily Slack agent that sends jokes and trivia with MCP

Slack Joke Agent

An agent that sends jokes and trivia to your Slack channel daily.

Features

• AI-Generated Content - Fresh jokes and trivia powered by Claude AI
• Science/tech jokes (60% of messages)
• Science/tech history trivia facts (40% of messages)
• Automated posting at 9:00 AM daily (configurable)
• Uses MCP Slack server integration
• Targets #random channel by default
• Written in Python with robust error handling
• Comprehensive logging to file and console
• Graceful Fallback - Uses predefined content if AI generation fails

Setup

1. Configure environment variables:

   cp .env.example .env
   # Edit .env with your Slack bot tokens
   

   Create a Slack app at https://api.slack.com/apps to get the bot token.

2. Install dependencies:

   pip install -e .
   

3. Or use the startup script:

   ./start-agent.sh
   

4. Ensure MCP Slack server is configured

Usage

Start the daily agent:

python3 slack_agent.py

Start with custom time:

python3 slack_agent.py --time 12:00  # Daily at noon

Test with immediate message:

python3 slack_agent.py --test

Use custom channel:

python3 slack_agent.py --channel C1234567890

Enable verbose logging:

python3 slack_agent.py --verbose

How it Works

1. Scheduling: Uses Python schedule library to trigger daily at 9:00 AM
2. AI Generation: Uses Anthropic's Claude AI to generate fresh content
3. Content Selection: Randomly selects between jokes and trivia (60%/40% split)
4. Fallback System: Uses predefined content if AI generation fails
5. MCP Integration: Spawns the MCP Slack server process
6. Channel: Posts to #random channel by default
7. Logging: Logs to both console and slack_agent.log file

Configuration

Environment variables in .env file:

Required:

• SLACK_BOT_TOKEN - Your Slack bot token (xoxb-...)
• SLACK_TEAM_ID - Your Slack team/workspace ID
• ANTHROPIC_API_KEY - Your Anthropic API key for Claude AI (sk-ant-...)

Optional:

• SLACK_CHANNEL_IDS - Comma-separated list of allowed channels
• DEFAULT_CHANNEL_ID - Default channel to post

Security:

• All secrets loaded from .env file (excluded from git)
• No hardcoded API keys or tokens in source code
• Environment variable validation on startup
• Graceful handling of missing AI credentials

AI Features:

• Dynamic content freshly generated by Claude AI
• Workplace appropriate prompts ensure clean content
• Automatic fallback to predefined content if AI generation fails
• Smart logging tracks AI generation success/failure

Command Line Options

• --test: Send a test message immediately
• --test-ai: Test AI generation without sending to Slack
• --channel CHANNEL_ID: Override the default channel
• --time HH:MM: Set daily schedule time (default: 09:00)
• --verbose, -v: Enable verbose debug logging

Logs

The agent creates comprehensive logs:

• Console output: Real-time status and messages
• File logging: slack_agent.log with detailed information
• Timestamps: All log entries include precise timestamps
• Error tracking: Failed attempts are logged with details

Customization

Add more jokes/trivia:

Edit the jokes and trivia lists in slack_agent.py

Change schedule:

Modify the schedule configuration:

schedule.every().day.at("09:00").do(self.send_daily_message)  # Daily at 9 AM (current)
schedule.every().day.at("12:00").do(self.send_daily_message)  # Daily at noon
schedule.every().hour.at(":00").do(self.send_daily_message)   # Every hour
schedule.every().monday.at("09:00").do(self.send_daily_message)  # Weekly on Monday

Change channel:

Update the channel_id property or use --channel argument

Update Slack tokens:

Edit the .env file with your new tokens

Installation

From PyPI (Recommended):

pip install slack-joke-agent
slack-agent --help

From Source:

git clone <repository>
cd slack-joke-agent
pip install -e .

Quick Development Setup:

git clone <repository>
cd slack-joke-agent
./start-agent.sh

Dependencies

Runtime Dependencies:

• Python 3.8+
• schedule>=1.2.0 - Task scheduling
• python-dotenv>=1.0.0 - Environment variable loading
• anthropic>=0.57.1 - Anthropic Claude AI SDK

Development Dependencies:

• pytest>=7.0.0 - Testing framework
• black>=22.0.0 - Code formatter
• flake8>=4.0.0 - Linting
• mypy>=0.950 - Type checking

Error Handling

The agent includes robust error handling:

• MCP server timeouts (30-second limit)
• Network connectivity issues
• Invalid channel configurations
• Graceful shutdown on Ctrl+C

Development

Building and Publishing:

Automatic Release:

./release.sh 1.0.3  # Automated release to PyPI

Interactive Release:

./release.sh        # Interactive mode with prompts

Help:

./release.sh --help # Show usage information

Automatic mode will update version, run tests, build package, upload to PyPI, commit changes, create git tag, and push to repository.

Running Tests:

python test_slack_agent.py

Package Structure:

• slack_agent.py - Main application
• pyproject.toml - Modern Python packaging
• LICENSE - MIT license
• MANIFEST.in - Package file inclusion rules
• test_slack_agent.py - Test suite
• release.sh - Automated release script