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

Go to Discord Developer Portal
Create New Application
Go to "Bot" section
Click "Add Bot"
Enable these Privileged Gateway Intents:
- Message Content Intent
- Server Members Intent
Copy the bot token
Go to "OAuth2" → "URL Generator"
Select scopes: bot, applications.commands
Select bot permissions:
- Send Messages
- Send Messages in Threads
- Create Public Threads
- Read Message History
- Use Slash Commands
Copy the generated URL and invite bot to your server

2. Environment Configuration

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

Edit .env and fill in your values:

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

pip install -r requirements.txt

Running the Bot

Development (Command Line)

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

Production (Windows Service with NSSM)

Download NSSM

Install as service:

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"

Start service:
```
nssm start ClaudeToolsDiscordBot
```
Check status:
```
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:

Create a dedicated thread for the conversation
Stream Claude's response with live updates
Execute tools as needed (database queries, breach checks)
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)

Discord bot connection
Claude API streaming
Thread-based conversations
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

Check bot is online: Look for green status in Discord
Check intents: Message Content Intent must be enabled in Discord Developer Portal
Check logs: tail -f logs/bot.log
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:

Implement tool execution (see bot/handlers/message_handler.py execute_tool placeholder)
Add ClaudeTools API client (see bot/services/)
Add remediation script runner (see bot/services/)

License

Internal Arizona Computer Guru project.