mcp-client-discord

Discord Event Listener with Claude-Powered Auto-Response via KADI Broker.

Overview

mcp-client-discord is a TypeScript-based MCP server that listens for Discord @mentions and queues them for template-agent-typescript to process. It uses Discord Gateway to receive real-time events.

Architecture

Discord Channel → Gateway Event → Mention Queue → template-agent-typescript → Claude API → mcp-server-discord → Discord Reply

Components

• Discord Gateway: Real-time WebSocket connection for receiving events
• Mention Queue: In-memory queue (max 100) of unprocessed @mentions
• MCP Server: Exposes get_discord_mentions tool for KADI broker integration
• Tool Registration: Available to any KADI agent via broker

Setup

1. Install Dependencies

npm install

2. Configure Environment

Copy .env.example to .env:

cp .env.example .env

Edit .env with your Discord bot token:

DISCORD_TOKEN=your_discord_bot_token_here
DISCORD_GUILD_ID=your_discord_guild_id_here  # Optional
MCP_LOG_LEVEL=info

3. Get Discord Bot Token

1. Go to Discord Developer Portal
2. Create a new application
3. Go to "Bot" section
4. Click "Reset Token" and copy the token
5. Enable "Message Content Intent" in bot settings
6. Invite bot to your server with proper permissions (Send Messages, Read Messages, etc.)

4. Build

npm run build

5. Run

Development mode (with hot-reload):

npm run dev

Production mode:

npm start

MCP Tools

get_discord_mentions

Retrieve pending Discord @mentions from the queue.

Input:

• limit (optional): Maximum number of mentions to retrieve (1-50, default: 10)

Output:

{
  "mentions": [
    {
      "id": "message_id",
      "user": "user_id",
      "username": "username",
      "text": "message text without @bot mention",
      "channel": "channel_id",
      "channelName": "channel_name",
      "guild": "guild_id",
      "ts": "ISO_timestamp"
    }
  ],
  "count": 1,
  "retrieved_at": "ISO_timestamp"
}

Integration with KADI Broker

The MCP server is registered in kadi-broker/config/mcp-upstreams.json:

{
  "id": "discord-client",
  "name": "Discord Event Listener (mcp-client-discord)",
  "type": "stdio",
  "prefix": "discord_client",
  "enabled": true,
  "stdio": {
    "command": "node",
    "args": ["C:\\p4\\Personal\\SD\\mcp-client-discord\\dist\\index.js"],
    "env": {
      "DISCORD_TOKEN": "your_token",
      "DISCORD_GUILD_ID": "your_guild_id"
    }
  },
  "networks": ["discord"]
}

Event Topics

Topic Pattern Standard

All KĀDI events follow the standardized topic pattern: {platform}.{event_type}.{bot_id}

• {platform}: Platform identifier (slack, discord, etc.)
• {event_type}: Event type (app_mention, mention, etc.)
• {bot_id}: Bot unique identifier (critical for multi-bot deployments)

Why bot_id is required:

• ✅ Enables multiple bot instances in the same server
• ✅ Routes events only to the intended bot
• ✅ Prevents cross-bot event delivery
• ✅ Supports multi-tenant deployments

Validation: Topics are automatically validated by @agents/shared package. Invalid patterns will log warnings but still publish.

See TOPIC_PATTERN.md for complete documentation.

discord.mention.{BOT_USER_ID}

Published when the bot is @mentioned in Discord.

Event Payload (DiscordMentionEvent):

{
  id: string;           // Unique message ID
  user: string;         // Discord user ID who mentioned the bot
  username: string;     // Discord username
  text: string;         // Message text (with @bot mention removed)
  channel: string;      // Discord channel ID
  channelName: string;  // Discord channel name
  guild: string;        // Discord guild/server ID
  ts: string;           // ISO 8601 timestamp
  timestamp: string;    // ISO 8601 datetime when event was published
}

---

Usage with Agent_TypeScript

Agent_TypeScript polls this MCP server for new @mentions:

// In Agent_TypeScript
const protocol = client.getBrokerProtocol();

const result = await protocol.invokeTool({
  targetAgent: 'discord-client',
  toolName: 'discord_client_get_discord_mentions',
  toolInput: { limit: 5 },
  timeout: 10000
});

const mentions = JSON.parse(result.content[0].text).mentions;

Discord Bot Permissions

Required bot permissions:

• View Channels
• Send Messages
• Read Message History
• Add Reactions (optional)

Required Gateway Intents:

• Guilds
• Guild Messages
• Message Content

Logging

The server logs to console with emoji indicators:

• 🚀 Startup messages
• 📬 Mention queued
• 📤 Mentions retrieved
• ✅ Success messages
• ❌ Error messages
• 💬 Received mention

Troubleshooting

"Discord client not ready after timeout"

• Check DISCORD_TOKEN is valid
• Verify bot has been invited to server
• Ensure internet connection is stable

"Channel not found" errors

• Verify bot has access to the channel
• Check channel permissions

Bot not responding to mentions

• Verify "Message Content Intent" is enabled
• Check bot has "Send Messages" permission
• Ensure bot is not muted or blocked

License

MIT