zhongwei/gh-nice-wolf-studio-wolf-skills-marketplace-integrations
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:43:40 +08:00
commit d6cdda3f30
13 changed files with 4664 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

564
skills/discord-integration/SKILL.md Normal file
View File

@@ -0,0 +1,564 @@
---
name: discord-integration
version: 1.0.1
description: 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
triggers:
- 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:**
1. **Try MCP tools first:**
```javascript
// 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
2. **Fall back to Gateway script:**
```bash
# Check if script exists
ls -la ~/.claude/discordmcp/send-test-message.js
# Check if token configured
grep DISCORD_TOKEN ~/.claude/discordmcp/.env
```
3. **REST API as last resort** (expect permission issues)
### Step 2: Execute Based on Available Method
#### Using Method 1: MCP Tools
**Send Message:**
```javascript
mcp__discord__send-message({
channel: "1420759585349697710", // Channel ID or name
message: "Your message here"
})
```
**Read Messages:**
```javascript
mcp__discord__read-messages({
channel: "1420759585349697710",
limit: 10 // 1-100
})
```
#### Using Method 2: Gateway Script
**Send Message:**
```bash
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:**
```bash
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: mcp__discord__send-message"
**Cause:** Discord MCP server not loaded in Claude Code.
**Solutions:**
1. **Verify MCP configuration exists:**
```bash
grep -A 5 '"discord"' ~/.claude/mcp.json
```
Should show:
```json
"discord": {
"type": "stdio",
"command": "node",
"args": ["/Users/USERNAME/.claude/discordmcp/build/index.js"]
}
```
2. **Verify MCP server is built:**
```bash
ls -la ~/.claude/discordmcp/build/index.js
```
3. **Test MCP server manually:**
```bash
cd ~/.claude/discordmcp
node build/index.js
```
Should see: "Discord bot is ready!" and "Discord MCP Server running on stdio"
4. **Fully restart Claude Code:**
- Quit completely (Cmd+Q or equivalent)
- Relaunch application
- Start new session
5. **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:**
1. **Verify bot is in the server:**
```bash
curl -H "Authorization: Bot TOKEN" \
https://discord.com/api/v10/users/@me/guilds
```
2. **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
3. **Grant server-wide permissions:**
- Server Settings → Roles
- Find bot's role
- Enable Send Messages permission
4. **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:**
1. **Verify bot membership:**
```bash
curl -H "Authorization: Bot TOKEN" \
https://discord.com/api/v10/users/@me/guilds
```
2. **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
```
3. **After inviting, wait a few seconds for bot to join**
4. **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:**
1. **Verify token is correct:**
```bash
curl -H "Authorization: Bot TOKEN" \
https://discord.com/api/v10/users/@me
```
Should return bot user info, not error.
2. **Check token hasn't been regenerated:**
- Go to Discord Developer Portal
- Applications → Your Bot → Bot
- If token was regenerated, update configs
3. **Verify bot has proper Gateway intents:**
- In Developer Portal: Bot → Privileged Gateway Intents
- Enable: Guilds, Guild Messages (Message Content if reading)
4. **Check .env file syntax:**
```bash
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:**
1. **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
2. **Check bot can see the channel:**
- Bot must have "View Channel" permission
- Channel must not be in a category the bot can't access
3. **Try using channel name instead of ID** (if using MCP tools):
```javascript
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:**
```env
DISCORD_TOKEN=MTQzNTI3NDY1MzEyNjg4OTU0NA...
DISCORD_CLIENT_ID=1435274653126889544
DISCORD_GUILD_ID=745376918030909471
DISCORD_ENABLED=true
```
**Rebuild after changes:**
```bash
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:**
```env
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
```bash
curl -H "Authorization: Bot TOKEN" https://discord.com/api/v10/users/@me
```
### List Guilds
```bash
curl -H "Authorization: Bot TOKEN" https://discord.com/api/v10/users/@me/guilds
```
### Test MCP Server
```bash
cd ~/.claude/discordmcp && node build/index.js
```
### Send via Gateway Script
```bash
cd ~/.claude/discordmcp && node send-test-message.js CHANNEL_ID "Message"
```
### Check MCP Config
```bash
grep -A 5 '"discord"' ~/.claude/mcp.json
```
## Examples
See `examples.md` in this skill directory for complete working examples.
## Related Documentation
- **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:**
1. **Verify message sent successfully** - Check verification checklist (6 items) to confirm integration worked
2. **Document method used** - Record which method succeeded (MCP/Gateway/REST) for future reference
3. **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