Metadata-Version: 2.4
Name: slack-joke-agent
Version: 1.0.2
Summary: Daily Slack agent that sends jokes and trivia with MCP
Author-email: Jing Wang <jingwang.physics@gmail.com>
Maintainer-email: Jing Wang <jingwang.physics@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Jing Wang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
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.

## 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 (can be changed)
- 🔧 Uses MCP Slack server integration
- 🎯 Targets #random channel
- 🐍 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
   ```
   check https://api.slack.com/apps to create a new app and get the bot token.

2. **Install Python dependencies:**
   ```bash
   pip install -e .
   ```

3. **Or use the startup script (recommended):**
   ```bash
   ./start-agent.sh
   ```
   This creates a virtual environment and installs dependencies automatically.

4. **Ensure MCP Slack server is configured** (already done in your Cursor setup)

## 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 on demand
3. **Content Selection**: Randomly selects between jokes and trivia (60%/40% split)
4. **Fallback System**: Uses predefined content if AI generation fails or API key not provided
5. **MCP Integration**: Spawns the MCP Slack server process using subprocess
6. **Channel**: Posts to #random channel (`C1LLHJA4W`)
7. **Logging**: Logs to both console and `slack_agent.log` file with AI generation status

## Configuration

The agent uses environment variables from `.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**: Each message is freshly generated by Claude AI
- **Workplace Appropriate**: AI prompts ensure clean, professional content
- **Automatic Fallback**: Uses predefined content if AI generation fails
- **Smart Logging**: Tracks AI generation success/failure for monitoring

## 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

Managed via `pyproject.toml`:

**Runtime Dependencies:**
- Python 3.8+
- `schedule>=1.2.0` - Task scheduling library
- `python-dotenv>=1.0.0` - Environment variable loading
- `anthropic>=0.40.0` - Anthropic Claude AI SDK

**Development Dependencies (optional):**
- `pytest>=7.0.0` - Testing framework
- `black>=22.0.0` - Code formatter
- `flake8>=4.0.0` - Linting
- `mypy>=0.950` - Type checking

**Built-in modules:**
- `subprocess` - MCP server communication
- `json`, `random`, `logging`, `datetime` - Standard library

## 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:
```bash
./release.sh  # Complete build, test, and publish workflow
```

### 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
- `build.sh` - Simple build script
- `release.sh` - Full release workflow
