claudetools/projects/discord-bot/README.md

# ClaudeTools Discord Bot

Discord bot providing MSP team access to ClaudeTools database, M365 remediation-tool, and Claude AI assistance through Discord channels.

## Features

- **Conversational AI**: Powered by Claude API with full context awareness
- **ClaudeTools Integration**: Query MSP database (clients, sessions, tasks, infrastructure)
- **M365 Security**: Run breach checks and tenant sweeps via remediation-tool
- **Thread-Based**: Isolated conversations with full history
- **Streaming Responses**: Real-time updates as Claude thinks and executes tools

## Architecture

```
Discord → Message Handler → Claude API (with Tools)
                                  ↓
                      ┌────────────┴────────────┐
                      ↓                         ↓
              ClaudeTools API          Remediation Scripts
              (HTTP Client)            (Bash Subprocess)
```

## Prerequisites

- **Python 3.11+**
- **Discord Bot** created in Discord Developer Portal
- **Anthropic API Key** for Claude access
- **ClaudeTools API** running at http://172.16.3.30:8001
- **Git Bash** (Windows) for remediation-tool scripts
- **SOPS Vault** accessible at D:\vault (Windows) or configured path

## Setup

### 1. Discord Bot Setup

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Create New Application
3. Go to "Bot" section
4. Click "Add Bot"
5. Enable these **Privileged Gateway Intents**:
   - Message Content Intent
   - Server Members Intent
6. Copy the bot token
7. Go to "OAuth2" → "URL Generator"
8. Select scopes: `bot`, `applications.commands`
9. Select bot permissions:
   - Send Messages
   - Send Messages in Threads
   - Create Public Threads
   - Read Message History
   - Use Slash Commands
10. Copy the generated URL and invite bot to your server

### 2. Environment Configuration

1. Copy `.env.example` to `.env`:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` and fill in your values:
   ```env
   DISCORD_TOKEN=your_bot_token_from_step_1
   DISCORD_GUILD_ID=your_server_id
   ANTHROPIC_API_KEY=your_anthropic_key
   CLAUDETOOLS_API_KEY=your_api_key

   # Windows paths (adjust for your system)
   VAULT_PATH=D:\vault
   CLAUDETOOLS_ROOT=D:\claudetools
   ```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

## Running the Bot

### Development (Command Line)

```bash
cd projects/discord-bot
python -m bot.main
```

### Production (Windows Service with NSSM)

1. Download [NSSM](https://nssm.cc/)

2. Install as service:
   ```powershell
   nssm install ClaudeToolsDiscordBot "C:\Python311\python.exe" "-m bot.main"
   nssm set ClaudeToolsDiscordBot AppDirectory "D:\claudetools\projects\discord-bot"
   nssm set ClaudeToolsDiscordBot Start SERVICE_AUTO_START
   nssm set ClaudeToolsDiscordBot AppStdout "D:\claudetools\projects\discord-bot\logs\stdout.log"
   nssm set ClaudeToolsDiscordBot AppStderr "D:\claudetools\projects\discord-bot\logs\stderr.log"
   ```

3. Start service:
   ```powershell
   nssm start ClaudeToolsDiscordBot
   ```

4. Check status:
   ```powershell
   nssm status ClaudeToolsDiscordBot
   ```

## Usage

### Mention-Based Conversations

Start a conversation by mentioning the bot:

```
@ClaudeTools hello!
@ClaudeTools list clients from last week
@ClaudeTools check john.trozzi@cascadestucson.com for breach
```

The bot will:
1. Create a dedicated thread for the conversation
2. Stream Claude's response with live updates
3. Execute tools as needed (database queries, breach checks)
4. Maintain full conversation context

### Example Queries

**ClaudeTools Database:**
```
@ClaudeTools show me GuruRMM sessions from April
@ClaudeTools list all Cascades tickets
@ClaudeTools what infrastructure do we manage for Dataforth?
```

**M365 Breach Checks:**
```
@ClaudeTools check user@domain.com for breach
@ClaudeTools sweep cascadestucson.com tenant for security issues
```

**General Questions:**
```
@ClaudeTools what projects are we working on?
@ClaudeTools summarize work from yesterday
```

## Project Structure

```
discord-bot/
├── bot/
│   ├── main.py                  # Entry point
│   ├── config.py                # Configuration
│   ├── handlers/
│   │   └── message_handler.py   # Discord message handling
│   ├── claude/
│   │   ├── client.py            # Claude API wrapper
│   │   └── tools.py             # Tool definitions
│   ├── services/               # (Phase 2) ClaudeTools API client
│   ├── auth/                   # (Phase 2) User permissions
│   └── formatting/             # (Phase 4) Embeds and tables
├── .env                        # Environment config (gitignored)
├── .env.example                # Template
├── requirements.txt
└── README.md
```

## Development Roadmap

### ✅ Phase 1: MVP (Current)
- [x] Discord bot connection
- [x] Claude API streaming
- [x] Thread-based conversations
- [x] Basic tool definitions
- [ ] **TODO:** Tool execution (ClaudeTools API)
- [ ] **TODO:** Tool execution (Remediation scripts)

### Phase 2: ClaudeTools API Integration
- [ ] HTTP client with JWT auth
- [ ] Implement `query_claudetools_api` tool
- [ ] User role mapping (admin vs tech)
- [ ] Audit logging

### Phase 3: Remediation-Tool Integration
- [ ] Bash subprocess runner
- [ ] Implement `run_breach_check` tool
- [ ] Implement `run_tenant_sweep` tool
- [ ] Progress streaming
- [ ] Artifact upload

### Phase 4: Polish
- [ ] Confirmation buttons for remediation
- [ ] Rich embeds for structured data
- [ ] Select menus for multi-choice
- [ ] Ephemeral messages for sensitive data
- [ ] Slash commands

## Troubleshooting

### Bot doesn't respond to mentions

1. Check bot is online: Look for green status in Discord
2. Check intents: Message Content Intent must be enabled in Discord Developer Portal
3. Check logs: `tail -f logs/bot.log`
4. Verify permissions: Bot needs "Send Messages" and "Send Messages in Threads"

### Path validation errors

```
FileNotFoundError: Vault not found at D:\vault
```

**Fix:** Update `VAULT_PATH` in `.env` to match your system.

### Module import errors

```
ModuleNotFoundError: No module named 'discord'
```

**Fix:** Install dependencies: `pip install -r requirements.txt`

## Contributing

This is Phase 1 MVP. Next steps:
1. Implement tool execution (see `bot/handlers/message_handler.py` `execute_tool` placeholder)
2. Add ClaudeTools API client (see `bot/services/`)
3. Add remediation script runner (see `bot/services/`)

## License

Internal Arizona Computer Guru project.