zhongwei/gh-nice-wolf-studio-wolf-skills-marketplace-integrations

Fork 0

Files

Zhongwei Li d6cdda3f30 Initial commit

2025-11-30 08:43:40 +08:00

16 KiB

Raw Blame History

name, version, description, triggers

name

version

description

triggers

discord-integration

1.0.1

Use when sending Discord messages or encountering bot permission errors - provides three-tier integration methods with automatic fallback (MCP → REST API → Gateway); prevents wasted time on OAuth scope issues

discord

send message

permission error

bot access

discord.js

mcp discord

Discord Integration

Comprehensive skill for working with Discord from Claude Code using multiple methods with automatic fallback.

When to Use This Skill

Use this skill when the user wants to:

Send messages to Discord channels
Read messages from Discord channels
Troubleshoot Discord bot connection or permission issues
Set up or configure Discord bot access
Choose the best method for Discord interaction

Trigger phrases:

"Send a message to Discord"
"Post to #channel-name"
"Read messages from Discord"
"Discord bot isn't working"
"Can't access Discord channel"

When NOT to Use This Skill

Do NOT use this skill for:

Discord server management - Use Discord's admin panel for creating channels, managing roles, or configuring server settings
Complex bot features - For advanced slash commands, persistent state, or complex workflows, build a dedicated bot application
Real-time message listening - This skill focuses on sending/reading; continuous message monitoring requires a persistent Gateway connection outside this skill's scope
Voice channel interactions - This skill only handles text channels

Available Bots on This Machine

1. Sombra (Local MCP Bot)

Purpose: Claude Code MCP integration (this machine only)
Token Location: ~/.claude/discordmcp/.env
Client ID: 1435274653126889544
Guild: Nice Wolf Studio (745376918030909471)
Connection: discord.js Gateway via MCP server
Use For: Claude Code sessions, automated workflows

2. GladOSv3 (tjr-suite Bot)

Purpose: Trading bot application
Token Location: ~/Dev/tjr-suite/.env
Client ID: 1425850836277395506
Guild: Nice Wolf Studio (745376918030909471)
Connection: discord.js Gateway (always running)
Use For: Trading signals, slash commands, application-specific tasks

Important: These are separate bots. Do not confuse their configurations.

Three Integration Methods (Priority Order)

Method 1: MCP Tools (PREFERRED)

Availability: After Claude Code full restart Tools: mcp__discord__send-message, mcp__discord__read-messages

Pros:

Clean, native Claude Code integration
No manual script execution
Persistent connection via discord.js Gateway
Smart auto-discovery (find channels by name or ID)

Cons:

Requires full Claude Code restart to load
Not available immediately after config changes

Method 2: Discord.js Gateway Script (FALLBACK)

Availability: Always (if bot token configured) Script: ~/.claude/discordmcp/send-test-message.js

Pros:

Works immediately, no restart needed
Direct access to discord.js library
Can be customized easily
Reliable connection

Cons:

Requires manual script execution
Less integrated than MCP tools

Method 3: REST API (LAST RESORT)

Availability: Always Method: Direct curl to Discord API v10

Pros:

No dependencies
Quick for testing

Cons:

Often gets "Missing Access" (OAuth scope issues)
Requires exact permissions
Less reliable than Gateway methods

Integration Method Selection (MANDATORY)

ALWAYS follow this priority order - do NOT skip steps:

User requests Discord interaction
  ↓
STEP 1: Are MCP tools available? (mcp__discord__send-message)
  YES → REQUIRED: Use MCP tools (Method 1)
  NO ↓
  ↓
STEP 2: Can we use send-test-message.js? (file exists, token configured)
  YES → REQUIRED: Use Gateway script (Method 2)
  NO ↓
  ↓
STEP 3: Try REST API (Method 3) with warning about limitations
  ↓
FALLBACK LOGIC:
  - If Method 1 fails → Immediately try Method 2
  - If Method 2 fails → Try Method 3
  - If Method 3 fails → Report error with troubleshooting steps

CRITICAL: You MUST attempt Method 1 (MCP) first, even if you think it won't work. Only fall back after confirming failure.

Step-by-Step Instructions

Step 1: Check Method Availability

Before attempting any Discord interaction, determine which method is available:

Try MCP tools first:

// Attempt to use MCP tool
mcp__discord__send-message({
  channel: "CHANNEL_ID",
  message: "Test"
})

If you get "No such tool available" error → MCP not loaded

Fall back to Gateway script:

# Check if script exists
ls -la ~/.claude/discordmcp/send-test-message.js

# Check if token configured
grep DISCORD_TOKEN ~/.claude/discordmcp/.env

REST API as last resort (expect permission issues)

Step 2: Execute Based on Available Method

Using Method 1: MCP Tools

Send Message:

mcp__discord__send-message({
  channel: "1420759585349697710",  // Channel ID or name
  message: "Your message here"
})

Read Messages:

mcp__discord__read-messages({
  channel: "1420759585349697710",
  limit: 10  // 1-100
})

Using Method 2: Gateway Script

Send Message:

cd ~/.claude/discordmcp
node send-test-message.js CHANNEL_ID "Optional custom message"

# Example:
node send-test-message.js 1420759585349697710 "Hello from Claude Code"

Custom Message: Create a modified version of the script or pass message as argument.

Using Method 3: REST API

Send Message:

curl -X POST "https://discord.com/api/v10/channels/CHANNEL_ID/messages" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Your message"}'

Note: Will likely fail with "Missing Access" - see troubleshooting.

Step 3: Handle Errors

See troubleshooting section below for specific error codes and solutions.

Red Flags - STOP

If you encounter these situations, STOP and address them immediately:

❌ Skipping MCP method without trying first

Why it's bad: MCP is the most reliable method; skipping wastes time with inferior fallbacks
Fix: Always attempt mcp__discord__send-message before assuming it won't work

❌ Not checking bot permissions before sending

Why it's bad: Results in repeated "Missing Access" errors and wasted API calls
Fix: Verify bot has "View Channel" and "Send Messages" permissions first

❌ Retrying same failed method repeatedly

Why it's bad: Same input = same output; you're wasting time and rate limits
Fix: After one failure, switch to next method in priority order

❌ Missing token/credentials setup

Why it's bad: Nothing will work without valid authentication
Fix: Verify token exists in appropriate .env file and test with /users/@me endpoint

❌ Not handling 403 Forbidden errors properly

Why it's bad: 403 means permission issue, not connection issue
Fix: Check channel-specific permissions or switch to Gateway method (better permission handling)

❌ Using REST API when Gateway methods are available

Why it's bad: REST API has OAuth scope limitations that cause "Missing Access" errors
Fix: Use MCP tools or Gateway script instead - they have proper intents

Verification Checklist

Before marking Discord integration as complete, verify:

MCP tools attempted first - You tried mcp__discord__send-message before other methods
Permissions verified for channel - Bot has "View Channel" and "Send Messages" in target channel
Message sent successfully - Received confirmation (not just "no error")
Error handling implemented - Code handles failures gracefully with fallback or clear error message
Correct bot used - Sombra for MCP/local, GladOSv3 for tjr-suite (not mixed up)
Token validated - Tested token with /users/@me endpoint returns valid bot info

Prerequisites

General Requirements

Bot must be in the target Discord server
Bot must have proper permissions in the target channel
Valid bot token must be configured

For MCP Tools

Claude Code must be fully restarted after mcp.json changes
MCP server must be configured in ~/.claude/mcp.json
Discord MCP server must be built: cd ~/.claude/discordmcp && npm run build

For Gateway Script

Node.js installed
discord.js package available (in discordmcp directory)
Token in ~/.claude/discordmcp/.env

For REST API

DISCORD_BOT_TOKEN environment variable set
Bot must have been added with proper OAuth2 scopes

Troubleshooting

Error: "No such tool available: mcpdiscordsend-message"

Cause: Discord MCP server not loaded in Claude Code.

Solutions:

Verify MCP configuration exists:

grep -A 5 '"discord"' ~/.claude/mcp.json

Should show:

"discord": {
  "type": "stdio",
  "command": "node",
  "args": ["/Users/USERNAME/.claude/discordmcp/build/index.js"]
}

Verify MCP server is built:

ls -la ~/.claude/discordmcp/build/index.js

Test MCP server manually:
```
cd ~/.claude/discordmcp
node build/index.js
```
Should see: "Discord bot is ready!" and "Discord MCP Server running on stdio"
Fully restart Claude Code:
- Quit completely (Cmd+Q or equivalent)
- Relaunch application
- Start new session
If still not available, use Method 2 (Gateway script) instead.

Error: "Missing Access" (Code 50001)

Cause: Bot doesn't have permission to access that channel.

Solutions:

Verify bot is in the server:

curl -H "Authorization: Bot TOKEN" \
  https://discord.com/api/v10/users/@me/guilds

Check channel-specific permissions:
- Right-click channel in Discord
- Edit Channel → Permissions
- Add the bot (Sombra or GladOSv3)
- Enable: View Channel, Send Messages, Read Message History
Grant server-wide permissions:
- Server Settings → Roles
- Find bot's role
- Enable Send Messages permission
If using REST API, switch to Gateway method (discord.js or MCP tools)

Error: "Unknown Guild" (Code 10004)

Cause: Bot is not in that Discord server.

Solutions:

Verify bot membership:

curl -H "Authorization: Bot TOKEN" \
  https://discord.com/api/v10/users/@me/guilds

Invite bot to server using OAuth2 URL:

For Sombra (Local MCP):

https://discord.com/api/oauth2/authorize?client_id=1435274653126889544&permissions=69632&scope=bot

For GladOSv3 (tjr-suite):

https://discord.com/api/oauth2/authorize?client_id=1425850836277395506&permissions=69632&scope=bot

After inviting, wait a few seconds for bot to join
Verify the bot appears in server member list

Error: Connection Timeout or "Discord bot is ready!" but MCP fails

Cause: Token invalid or bot permissions insufficient.

Solutions:

Verify token is correct:

curl -H "Authorization: Bot TOKEN" \
  https://discord.com/api/v10/users/@me

Should return bot user info, not error.

Check token hasn't been regenerated:
- Go to Discord Developer Portal
- Applications → Your Bot → Bot
- If token was regenerated, update configs
Verify bot has proper Gateway intents:
- In Developer Portal: Bot → Privileged Gateway Intents
- Enable: Guilds, Guild Messages (Message Content if reading)
Check .env file syntax:
```
cat ~/.claude/discordmcp/.env
```
No extra spaces, quotes, or newlines around token.

Error: "Channel not found or not a text channel"

Cause: Invalid channel ID or bot can't see it.

Solutions:

Verify channel ID is correct:
- Right-click channel in Discord
- Copy Channel ID (enable Developer Mode if needed)
- Channel IDs are 17-19 digit numbers
Check bot can see the channel:
- Bot must have "View Channel" permission
- Channel must not be in a category the bot can't access

Try using channel name instead of ID (if using MCP tools):

mcp__discord__send-message({
  channel: "bot-testing-grounds",  // Name instead of ID
  message: "Test"
})

Bot Configuration Reference

Sombra (Local MCP) Configuration

Files:

Token: ~/.claude/discordmcp/.env
MCP Config: ~/.claude/mcp.json (lines 55-61)
Source: ~/.claude/discordmcp/src/index.ts
Built: ~/.claude/discordmcp/build/index.js

Environment Variables:

DISCORD_TOKEN=MTQzNTI3NDY1MzEyNjg4OTU0NA...
DISCORD_CLIENT_ID=1435274653126889544
DISCORD_GUILD_ID=745376918030909471
DISCORD_ENABLED=true

Rebuild after changes:

cd ~/.claude/discordmcp
npm run build

GladOSv3 (tjr-suite) Configuration

Files:

Token: ~/Dev/tjr-suite/.env
Source: ~/Dev/tjr-suite/packages/app/src/services/discord/
HTTP API: Running on http://localhost:3000

Environment Variables:

DISCORD_TOKEN=MTQyNTg1MDgzNjI3NzM5NTUwNg...
DISCORD_CLIENT_ID=1425850836277395506
DISCORD_GUILD_ID=745376918030909471
DISCORD_ENABLED=true

Note: GladOSv3 is always running as part of tjr-suite. Do not confuse with Sombra.

Common Channel IDs

Nice Wolf Studio Server:

Guild ID: 745376918030909471
#bot-testing-grounds: 1420759585349697710

Permission Reference

Required Bot Permissions

Minimum (for message sending):

View Channels (1024)
Send Messages (2048)

Recommended:

Read Message History (65536)
Add Reactions (64)

Permission Integer: 69632 (includes all recommended)

How to Calculate Custom Permissions

Visit: https://discordapi.com/permissions.html

Enter desired permissions, copy the integer for OAuth2 URL.

Testing Checklist

When setting up or troubleshooting Discord integration:

Bot token is valid (test with /users/@me endpoint)
Bot is in the correct server (check /users/@me/guilds)
Bot has View Channel permission
Bot has Send Messages permission in target channel
Channel ID is correct (17-19 digit number)
Token configured in correct .env file
MCP server built (if using MCP tools)
Claude Code restarted (if using MCP tools)

Quick Reference Commands

Verify Token

curl -H "Authorization: Bot TOKEN" https://discord.com/api/v10/users/@me

List Guilds

curl -H "Authorization: Bot TOKEN" https://discord.com/api/v10/users/@me/guilds

Test MCP Server

cd ~/.claude/discordmcp && node build/index.js

Send via Gateway Script

cd ~/.claude/discordmcp && node send-test-message.js CHANNEL_ID "Message"

Check MCP Config

grep -A 5 '"discord"' ~/.claude/mcp.json

Examples

See examples.md in this skill directory for complete working examples.

Setup Guide: ~/.claude/discordmcp/SETUP_COMPLETE.md
Validation Report: ~/.claude/discordmcp/VALIDATION_REPORT.md
Gateway Script: ~/.claude/discordmcp/send-test-message.js
Discord.js Docs: https://discord.js.org/
Discord API: https://discord.com/developers/docs

After Using This Skill

REQUIRED NEXT STEPS:

Verify message sent successfully - Check verification checklist (6 items) to confirm integration worked
Document method used - Record which method succeeded (MCP/Gateway/REST) for future reference
Test error handling - Verify fallback logic works if primary method fails

OPTIONAL NEXT STEPS:

Set up logging - Track Discord API calls, errors, and response times for debugging
Create reusable wrapper - Build abstraction around working method for consistent usage
Monitor bot health - Set up alerts for token expiration or permission changes

Changelog

Version 1.0.1 (2025-11-14)

Added superpowers-style improvements for better agent guidance
Added "When NOT to Use" section to prevent misuse
Enhanced Integration Method Selection with MANDATORY fallback logic
Added "Red Flags - STOP" section with 6 common anti-patterns
Added "Verification Checklist" for completion validation
Improved frontmatter with version, triggers, and clearer description
Updated description to emphasize automatic fallback and OAuth scope issue prevention

Version 1.0.0 (Initial)

Initial discord-integration skill
Three-tier integration methods (MCP, Gateway, REST API)
Comprehensive troubleshooting for common errors
Configuration reference for Sombra and GladOSv3 bots

16 KiB Raw Blame History

Discord Integration

When to Use This Skill

When NOT to Use This Skill

Available Bots on This Machine

1. Sombra (Local MCP Bot)

2. GladOSv3 (tjr-suite Bot)

Three Integration Methods (Priority Order)

Method 1: MCP Tools (PREFERRED)

Method 2: Discord.js Gateway Script (FALLBACK)

Method 3: REST API (LAST RESORT)

Integration Method Selection (MANDATORY)

Step-by-Step Instructions

Step 1: Check Method Availability

Step 2: Execute Based on Available Method

Using Method 1: MCP Tools

Using Method 2: Gateway Script

Using Method 3: REST API

Step 3: Handle Errors

Red Flags - STOP

Verification Checklist

Prerequisites

General Requirements

For MCP Tools

For Gateway Script

For REST API

Troubleshooting

Error: "No such tool available: mcp__discord__send-message"

Error: "Missing Access" (Code 50001)

Error: "Unknown Guild" (Code 10004)

Error: Connection Timeout or "Discord bot is ready!" but MCP fails

Error: "Channel not found or not a text channel"

Bot Configuration Reference

Sombra (Local MCP) Configuration

GladOSv3 (tjr-suite) Configuration

Common Channel IDs

Permission Reference

Required Bot Permissions

How to Calculate Custom Permissions

Testing Checklist

Quick Reference Commands

Verify Token

List Guilds

Test MCP Server

Send via Gateway Script

Check MCP Config

Examples

Related Documentation

After Using This Skill

Changelog

Version 1.0.1 (2025-11-14)

Version 1.0.0 (Initial)

16 KiB

Raw Blame History

Error: "No such tool available: mcpdiscordsend-message"