# Eye of Sauron - Discord Bot
A Discord bot with AI-powered chat, voice TTS, World of Warships stats, and MCP (Model Context Protocol) integration for AI assistants.
## Features
- **AI Chat** - Powered by OpenRouter with 34+ free AI models (Gemini, Llama, Qwen, etc.)
- **Voice TTS** - Natural text-to-speech with 20+ Microsoft Edge neural voices
- **WoWS Stats** - Look up player stats and clan info from Wargaming API
- **Moderation** - Ban, kick, timeout, bulk delete messages
- **Server Management** - Create channels, roles, categories
- **MCP Integration** - 93 tools for AI assistant control (Claude, etc.)
- **HTTP API** - Optional REST API mode for web integrations
- **DM Support** - Bot responds automatically in private messages (no prefix needed)
## Quick Start
### Prerequisites
- Node.js 18+
- A Discord bot token
- (Optional) OpenRouter API key for AI features
### 1. Clone & Install
```bash
git clone https://github.com/DawnReaverWOWS/TheFinalDiscordMCP.git
cd TheFinalDiscordMCP
npm install
```
### 2. Configure
Copy the example environment file and edit it:
```bash
cp .env.example .env
```
Edit `.env`:
```env
# Required
DISCORD_TOKEN=your_bot_token_here
DISCORD_GUILD_ID=your_server_id_here
# AI Features (Optional but recommended)
OPENROUTER_API_KEY=your_openrouter_api_key_here
# Creator Configuration (Optional)
BOT_CREATOR_ID=your_discord_user_id
BOT_CREATOR_NAME=YourName
# Notifications (Optional)
BOT_NOTIFY_CHANNEL_ID=channel_id_for_bot_notifications
```
### 3. Build & Run
```bash
npm run build
npm start
```
For development with hot reload:
```bash
npm run dev
```
## Getting a Discord Bot Token
1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application" and give it a name
3. Go to "Bot" tab -> "Add Bot"
4. Click "Reset Token" and copy it (this is your `DISCORD_TOKEN`)
5. Enable these Privileged Gateway Intents:
- Presence Intent
- Server Members Intent
- Message Content Intent
6. Go to "OAuth2" -> "URL Generator"
7. Select scopes: `bot`, `applications.commands`
8. Select permissions: `Administrator` (or select individual permissions)
9. Copy the generated URL and open it to invite the bot to your server
## AI Integration
Uses OpenRouter to access 34+ free AI models. Get your API key at [openrouter.ai/keys](https://openrouter.ai/keys).
### Supported Free Models
| Model | Context | Best For |
|-------|---------|----------|
| `google/gemini-2.0-flash-exp:free` | 1.05M | Fast, multimodal (default) |
| `meta-llama/llama-3.3-70b-instruct:free` | 131K | Multilingual chat |
| `qwen/qwen3-235b-a22b:free` | 131K | Reasoning, 100+ languages |
| `nousresearch/hermes-3-llama-3.1-405b:free` | 131K | 405B frontier model |
| `qwen/qwen3-coder:free` | 262K | Coding tasks |
See [context/openrouterAiModels.md](context/openrouterAiModels.md) for the full list of 34 free models.
### Using AI
- **Mention the bot**: `@BotName what's the best ship for ranked?`
- **DM the bot**: Just send a message directly - no prefix needed
- The bot will respond with context-aware answers
## Bot Commands
All commands use the `!` prefix (except DMs which work without prefix).
### AI & Chat
| Command | Description | Example |
|---------|-------------|---------|
| `@BotName <message>` | Chat with AI | `@BotName help me with builds` |
| DM the bot | AI responds automatically | Just send a message |
### Voice
| Command | Description | Example |
|---------|-------------|---------|
| `!join <channel>` | Join a voice channel | `!join War Room` |
| `!leave` | Leave voice channel | `!leave` |
| `!say <text>` | Speak text via TTS | `!say Hello everyone!` |
| `!voices` | List available TTS voices | `!voices` |
| `!setvoice <name>` | Change TTS voice | `!setvoice guy` |
| `!lockvoice` | Lock voice to creator only | `!lockvoice` |
| `!unlockvoice` | Unlock voice for everyone | `!unlockvoice` |
| `!voicestatus` | Check voice lock status | `!voicestatus` |
**Aliases:** `!vc` (join), `!disconnect` (leave), `!speak`/`!tts` (say)
### Available TTS Voices
20+ natural Microsoft Edge neural voices:
**US Female:** aria (default), jenny, sara, ana, michelle
**US Male:** guy, davis, tony, jason
**UK Female:** sonia, maisie, libby
**UK Male:** ryan, thomas, alfie
**Australian:** natasha, william
### World of Warships
| Command | Description | Example |
|---------|-------------|---------|
| `!wows <username>` | Look up player stats | `!wows PlayerName` |
| `!ships <username>` | Top 10 ships by battles | `!ships PlayerName` |
| `!allships <username>` | ALL ships grouped by tier | `!allships PlayerName` |
| `!clan <tag/name>` | Look up clan info | `!clan DROVA` |
**Aliases:** `!player`, `!lookup` (for wows), `!topships` (for ships), `!claninfo`, `!clanlookup` (for clan)
**Ships Command Options:**
- Filter by tier: `!ships PlayerName tier:10`
- Filter by type: `!ships PlayerName type:bb` (dd, ca, bb, cv, ss)
- Sort options: `!ships PlayerName sort:winrate` (battles, winrate, damage, recent)
### Info
| Command | Description |
|---------|-------------|
| `!ping` | Check bot latency |
| `!serverinfo` | Server information |
| `!members [limit]` | List server members |
| `!memberinfo @user` | Get user information |
### Moderation (Requires Permissions)
| Command | Description | Example |
|---------|-------------|---------|
| `!ban @user [reason]` | Ban a member | `!ban @user spamming` |
| `!unban <userId>` | Unban a member | `!unban 123456789` |
| `!kick @user [reason]` | Kick a member | `!kick @user warning` |
| `!timeout @user [seconds] [reason]` | Timeout a member | `!timeout @user 300 cool down` |
| `!bulkdelete <count>` | Delete messages (1-100) | `!bulkdelete 10` |
**Aliases:** `!b` (ban), `!k` (kick), `!mute`/`!to` (timeout), `!clear`/`!purge` (bulkdelete)
### Messages
| Command | Description | Example |
|---------|-------------|---------|
| `!send #channel <message>` | Send a message | `!send #general Hello!` |
| `!read [limit]` | Read recent messages | `!read 20` |
### Channels (Admin Only)
| Command | Description | Example |
|---------|-------------|---------|
| `!createchannel <name>` | Create text channel | `!createchannel announcements` |
| `!createvoice <name>` | Create voice channel | `!createvoice Gaming` |
| `!deletechannel #channel` | Delete a channel | `!deletechannel #old-channel` |
| `!createcategory <name>` | Create a category | `!createcategory Projects` |
### Roles
| Command | Description | Example |
|---------|-------------|---------|
| `!createrole <name> [color]` | Create a role (Admin) | `!createrole VIP #ff0000` |
| `!addrole @user @role` | Add role to user (Mod) | `!addrole @user @Member` |
| `!removerole @user @role` | Remove role from user (Mod) | `!removerole @user @Member` |
### Utility
| Command | Description | Cooldown |
|---------|-------------|----------|
| `!createinvite` | Create server invite | 30s |
| `!exportchat` | Export channel chat log | 60s |
| `!createthread [#channel] <name>` | Create a thread (Mod) | - |
### Fun
| Command | Description | Example |
|---------|-------------|---------|
| `!8ball <question>` | Ask the magic 8-ball | `!8ball Will I win today?` |
| `!bread` | Get a random breadstick picture | `!bread` |
**Aliases:** `!breadsticks`, `!breadstick`, `!carbs`
## Creator Mode
The bot supports a "creator priority" system for voice commands:
- Set `BOT_CREATOR_ID` in `.env` to your Discord user ID
- Use `!lockvoice` to lock voice commands to creator only
- While locked, only the creator can control voice features
- Use `!unlockvoice` to allow everyone again
When asked about its creator, the bot will speak highly of them!
## MCP Integration (For AI Assistants)
This bot also functions as an MCP server, allowing AI assistants like Claude to control Discord.
### Claude Desktop Configuration
Add to your Claude Desktop config (`~/.claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"discord": {
"command": "node",
"args": ["/path/to/FinalDiscordMCP/dist/index.js"],
"env": {
"DISCORD_TOKEN": "your_token_here",
"DISCORD_GUILD_ID": "your_server_id",
"OPENROUTER_API_KEY": "your_openrouter_key"
}
}
}
}
```
### HTTP API Mode
Start with HTTP API enabled:
```bash
MCP_HTTP_PORT=3001 npm start
```
Or run in HTTP-only mode (no Discord bot, just API):
```bash
HTTP_ONLY=true MCP_HTTP_PORT=3001 npm start
```
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `DISCORD_TOKEN` | Yes | Your Discord bot token |
| `DISCORD_GUILD_ID` | No | Default server ID |
| `OPENROUTER_API_KEY` | No | OpenRouter API key for AI features |
| `OPENROUTER_MODEL` | No | Override default AI model |
| `BOT_CREATOR_ID` | No | Creator's Discord user ID (for voice lock) |
| `BOT_CREATOR_NAME` | No | Creator's display name |
| `BOT_NOTIFY_CHANNEL_ID` | No | Channel for startup/shutdown notifications |
| `BOT_OWNER_ID` | No | User ID for DM notifications (fallback) |
| `MCP_HTTP_PORT` | No | Enable HTTP API on this port |
| `HTTP_ONLY` | No | Run without Discord bot (API only) |
| `ENABLE_LOGGING` | No | Enable operation logging |
| `RATE_LIMIT_PROTECTION` | No | Enable rate limiting (default: true) |
## Project Structure
```text
TheFinalDiscordMCP/
├── src/
│ ├── index.ts # Entry point
│ ├── discord-service.ts # Discord.js wrapper
│ ├── ai-service.ts # OpenRouter AI integration
│ ├── voice-settings.ts # TTS voice configuration
│ ├── voice-priority.ts # Creator voice lock system
│ ├── commands/
│ │ ├── decorated-commands.ts # Bot commands
│ │ └── prefix-handler.ts # Command routing & AI
│ ├── services/
│ │ └── wargaming-api.ts # WoWS API integration
│ ├── decorators/
│ │ └── prefix.ts # Command decorators
│ └── core/
│ ├── DiscordController.ts
│ ├── ConfigManager.ts
│ ├── RateLimiter.ts
│ └── ...
├── context/
│ └── openrouterAiModels.md # Full list of 34 free AI models
├── dist/ # Compiled JS
├── .env # Your config (not committed)
├── .env.example # Example config
└── package.json
```
## Deployment
The bot includes GitHub Actions workflows for automated deployment:
- **CI** - Runs on all pushes, builds and tests
- **Deploy** - Deploys to VM1 and VM2 on push to main
See `.github/workflows/` for configuration.
## Development
```bash
# Install dependencies
npm install
# Run in dev mode (hot reload)
npm run dev
# Build for production
npm run build
# Run production build
npm start
# Type check
npx tsc --noEmit
```
## License
MIT - See [LICENSE](LICENSE)
