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

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

Voice

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

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

Moderation (Requires Permissions)

Aliases: !b (ban), !k (kick), !mute/!to (timeout), !clear/!purge (bulkdelete)

Messages

Channels (Admin Only)

Roles

Utility

Fun

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

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