250 lines
7.5 KiB
Markdown
250 lines
7.5 KiB
Markdown
# 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
|
|
|
|
As of Phase 1.5, the bot is "Claude Code in a Discord channel." Each Discord
|
|
thread is a persistent `ClaudeSDKClient` session whose `cwd` is the ClaudeTools
|
|
repo root, with `.claude/CLAUDE.md` as the system prompt. The agent uses the
|
|
Claude Agent SDK's native tools (Read, Edit, Write, Bash, Glob, Grep, etc.) —
|
|
the bot does not hand-write tool definitions or call the ClaudeTools HTTP API.
|
|
|
|
```
|
|
Discord thread ──> MessageHandler ──> ClaudeAgentManager
|
|
│
|
|
v
|
|
ClaudeSDKClient (per thread)
|
|
cwd = ClaudeTools repo
|
|
system_prompt = .claude/CLAUDE.md
|
|
│
|
|
v
|
|
Native SDK tools:
|
|
Read / Edit / Write / Bash / Glob / Grep / ...
|
|
```
|
|
|
|
## 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.5: Claude Agent SDK refactor (Current)
|
|
- [x] Discord bot connection
|
|
- [x] Claude Agent SDK streaming (replaces raw Anthropic SDK)
|
|
- [x] Per-thread persistent agent sessions (`ClaudeSDKClient`)
|
|
- [x] Workspace = ClaudeTools repo; system prompt = `.claude/CLAUDE.md`
|
|
- [x] Native SDK tools (Read/Edit/Write/Bash/Glob/Grep) — no hand-written tools
|
|
- The hand-written `query_claudetools_api`, `run_breach_check`, and
|
|
`run_tenant_sweep` tools from the Phase 1 scaffold were removed. The agent
|
|
invokes those workflows via the existing skills under `.claude/skills/` and
|
|
via Bash + the vault wrapper, the same way Claude Code does.
|
|
|
|
### 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.
|