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

Go to Discord Developer Portal
Click "New Application" and give it a name
Go to "Bot" tab -> "Add Bot"
Click "Reset Token" and copy it (this is your DISCORD_TOKEN)
Enable these Privileged Gateway Intents:
- Presence Intent
- Server Members Intent
- Message Content Intent
Go to "OAuth2" -> "URL Generator"
Select scopes: bot, applications.commands
Select permissions: Administrator (or select individual permissions)
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

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

Go to Discord Developer Portal
Click "New Application" and give it a name
Go to "Bot" tab -> "Add Bot"
Click "Reset Token" and copy it (this is your DISCORD_TOKEN)
Enable these Privileged Gateway Intents:
- Presence Intent
- Server Members Intent
- Message Content Intent
Go to "OAuth2" -> "URL Generator"
Select scopes: bot, applications.commands
Select permissions: Administrator (or select individual permissions)
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

Eye of Sauron - Discord Bot MCP

Eye of Sauron - Discord Bot

Features

Quick Start

Prerequisites

1. Clone & Install

2. Configure

3. Build & Run

Getting a Discord Bot Token

AI Integration

Supported Free Models

Using AI

Bot Commands

AI & Chat

Voice

Available TTS Voices

World of Warships

Info

Moderation (Requires Permissions)

Messages

Channels (Admin Only)

Roles

Utility

Fun

Creator Mode

MCP Integration (For AI Assistants)

Claude Desktop Configuration

HTTP API Mode

Environment Variables

Project Structure

Deployment

Development

License

Eye of Sauron - Discord Bot

Features

Quick Start

Prerequisites

1. Clone & Install

2. Configure

3. Build & Run

Getting a Discord Bot Token

AI Integration

Supported Free Models

Using AI

Bot Commands

AI & Chat

Voice

Available TTS Voices

World of Warships

Info

Moderation (Requires Permissions)

Messages

Channels (Admin Only)

Roles

Utility

Fun

Creator Mode

MCP Integration (For AI Assistants)

Claude Desktop Configuration

HTTP API Mode

Environment Variables

Project Structure

Deployment

Development

License