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

git clone https://github.com/DawnReaverWOWS/TheFinalDiscordMCP.git
cd TheFinalDiscordMCP
npm install

2. Configure

Copy the example environment file and edit it:

cp .env.example .env

Edit .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

npm run build
npm start

For development with hot reload:

npm run dev

Getting a Discord Bot Token

1. Go to Discord Developer Portal
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.

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 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):

{
  "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:

MCP_HTTP_PORT=3001 npm start

Or run in HTTP-only mode (no Discord bot, just API):

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

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

# 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