Metadata-Version: 2.4
Name: slack-joke-agent
Version: 1.0.9
Summary: Daily Slack agent that sends jokes and trivia with MCP
Author-email: Jing Wang <jingwang.physics@gmail.com>
Project-URL: Homepage, https://github.com/wangjing0/slack-joke-agent
Project-URL: Documentation, https://github.com/wangjing0/slack-joke-agent#readme
Project-URL: Repository, https://github.com/wangjing0/slack-joke-agent.git
Project-URL: Bug Tracker, https://github.com/wangjing0/slack-joke-agent/issues
Keywords: slack,mcp,automation,jokes
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: schedule>=1.2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: anthropic>=0.57.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=3.0.0; extra == "test"
Dynamic: license-file

# Slack Joke Agent

An agent that sends jokes and trivia to your Slack channel daily.
![alt text](https://github.com/wangjing0/slack-joke-agent/blob/main/jokes.png)

## 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:
   ```bash
   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:
   ```bash
   pip install -e .
   ```

3. Or use the startup script:
   ```bash
   ./start-agent.sh
   ```

4. Ensure MCP Slack server is configured

## Usage

### Start the daily agent:
```bash
python3 slack_agent.py
```

### Start with custom time:
```bash
python3 slack_agent.py --time 12:00  # Daily at noon
```

### Test with immediate message:
```bash
python3 slack_agent.py --test
```

### Use custom channel:
```bash
python3 slack_agent.py --channel C1234567890
```

### Enable verbose logging:
```bash
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:
```python
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):
```bash
pip install slack-joke-agent
slack-agent --help
```

### From Source:
```bash
git clone <repository>
cd slack-joke-agent
pip install -e .
```

### Quick Development Setup:
```bash
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:
```bash
./release.sh 1.0.3  # Automated release to PyPI
```

Interactive Release:
```bash
./release.sh        # Interactive mode with prompts
```

Help:
```bash
./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:
```bash
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
