@quadslab.io/discord-mcp 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] - 2026-02-22
+
+### Added
+
+- Troubleshooting section in README covering all common errors with fixes
+- Actionable startup error messages that point to `init` or `check` commands
+- More npm keywords for discoverability (cursor, windsurf, claude-desktop, ai-tools)
+- GitHub repo topics for better search visibility
+
+### Improved
+
+- Startup log messages use `[discord-mcp]` prefix for cleaner output
+- Error on missing token/guild now shows the exact command to fix it
+- Failed startup points to `npx @quadslab.io/discord-mcp check` for diagnostics
+
 ## [1.3.0] - 2026-02-22
 
 ### Fixed

package/README.md

@@ -478,6 +478,65 @@ These privileged intents must be enabled in the [Discord Developer Portal](https
 
 ---
 
+## Troubleshooting
+
+Run the health check to diagnose issues:
+
+```bash
+npx @quadslab.io/discord-mcp check
+```
+
+<details>
+<summary><strong>Common issues and fixes</strong></summary>
+
+### "DISCORD_TOKEN is not set"
+
+The MCP server can't find your bot token. Either:
+- Run `npx @quadslab.io/discord-mcp init` to set up automatically
+- Or check that your `.mcp.json` / MCP client config has the `DISCORD_TOKEN` in the `env` block
+
+### "Request with opcode 8 was rate limited"
+
+Discord rate-limited the gateway connection (usually from member caching on large servers). The server retries automatically — if you're still seeing this, wait 30 seconds and try again. This is a Discord-side limit, not a bug.
+
+### "Role @everyone not found"
+
+Fixed in v1.2.2+. Update to the latest version:
+```bash
+npx @quadslab.io/discord-mcp@latest init
+```
+
+### "Missing Access" or "Missing Permissions"
+
+The bot's role doesn't have the required permissions. Either:
+- Re-invite the bot using the URL from `npx @quadslab.io/discord-mcp init` (it includes all permissions)
+- Or go to **Server Settings > Roles** and grant the missing permissions to the bot's role
+- Run `npx @quadslab.io/discord-mcp check` to see exactly which permissions are missing
+
+### Bot can't manage a specific role
+
+Discord enforces role hierarchy — the bot can only manage roles **below** its own highest role. Move the bot's role higher in **Server Settings > Roles**.
+
+### Bot can't read messages
+
+Enable **Message Content Intent** in the [Discord Developer Portal](https://discord.com/developers/applications) > Bot tab.
+
+### "Used disallowed intents"
+
+Enable **Server Members Intent** and **Message Content Intent** in the [Discord Developer Portal](https://discord.com/developers/applications) > Bot tab. Both are required.
+
+### Tools work but are slow
+
+The first tool call after startup may be slow due to caching. Subsequent calls use the cached data and should be instant. If all calls are slow, check your network connection to Discord.
+
+### `.mcp.json` was created in the wrong directory
+
+If you ran `init` from Desktop or Downloads, update to v1.2.3+ which auto-detects this and writes to `~/.claude.json` (global config) instead. Or move the `.mcp.json` file to your project root.
+
+</details>
+
+---
+
 ## Architecture
 
 ```

package/dist/mcp-server.js

@@ -23,32 +23,45 @@ export async function main() {
     const token = process.env['DISCORD_TOKEN'] || process.env['BOT_TOKEN'];
     const guildId = process.env['DISCORD_GUILD_ID'];
     if (!token) {
-        console.error('Error: DISCORD_TOKEN or BOT_TOKEN environment variable is required');
+        console.error('');
+        console.error('  Error: DISCORD_TOKEN is not set.');
+        console.error('');
+        console.error('  Run the setup wizard to configure:');
+        console.error('    npx @quadslab.io/discord-mcp init');
+        console.error('');
+        console.error('  Or set it manually:');
+        console.error('    DISCORD_TOKEN=your-bot-token');
+        console.error('');
         process.exit(1);
     }
     if (!guildId) {
-        console.error('Error: DISCORD_GUILD_ID environment variable is required');
+        console.error('');
+        console.error('  Error: DISCORD_GUILD_ID is not set.');
+        console.error('');
+        console.error('  Run the setup wizard to configure:');
+        console.error('    npx @quadslab.io/discord-mcp init');
+        console.error('');
+        console.error('  Or set it manually:');
+        console.error('    DISCORD_GUILD_ID=your-server-id');
+        console.error('');
         process.exit(1);
     }
     // Set DISCORD_TOKEN for the discord-client module
     process.env['DISCORD_TOKEN'] = token;
-    console.error('Starting Discord MCP server...');
-    console.error(`Guild ID: ${guildId}`);
+    console.error('[discord-mcp] Starting...');
     try {
         // Initialize Discord client
-        console.error('Connecting to Discord...');
         const client = await initializeClient();
-        console.error(`Logged in as ${client.user?.tag}`);
+        console.error(`[discord-mcp] Logged in as ${client.user?.tag}`);
         // Pre-cache server data for fast lookups
-        console.error('Caching server data...');
         await refreshServerCache();
         // Create and start MCP server
         const mcpServer = createMCPServer();
         await startMCPServer(mcpServer);
-        console.error('MCP server ready and listening');
+        console.error(`[discord-mcp] Ready — guild ${guildId}`);
         // Handle graceful shutdown
         const shutdown = async (signal) => {
-            console.error(`\nReceived ${signal}, shutting down...`);
+            console.error(`[discord-mcp] ${signal} received, shutting down...`);
             await destroyClient();
             process.exit(0);
         };
@@ -56,7 +69,12 @@ export async function main() {
         process.on('SIGTERM', () => shutdown('SIGTERM'));
     }
     catch (error) {
-        console.error('Failed to start MCP server:', error);
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`[discord-mcp] Failed to start: ${msg}`);
+        console.error('');
+        console.error('  Troubleshoot with:');
+        console.error('    npx @quadslab.io/discord-mcp check');
+        console.error('');
         await destroyClient();
         process.exit(1);
     }

package/dist/mcp-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,6BAA6B;AAC7B,MAAM,CAAC,MAAM,EAAE,CAAC;AAEhB,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,0CAA0C;IAC1C,sDAAsD;IACtD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACvE,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAEhD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACpF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC1E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,kDAAkD;IAClD,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,GAAG,KAAK,CAAC;IAErC,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAChD,OAAO,CAAC,KAAK,CAAC,aAAa,OAAO,EAAE,CAAC,CAAC;IAEtC,IAAI,CAAC;QACH,4BAA4B;QAC5B,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,gBAAgB,EAAE,CAAC;QACxC,OAAO,CAAC,KAAK,CAAC,gBAAgB,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QAElD,yCAAyC;QACzC,OAAO,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;QACxC,MAAM,kBAAkB,EAAE,CAAC;QAE3B,8BAA8B;QAC9B,MAAM,SAAS,GAAG,eAAe,EAAE,CAAC;QACpC,MAAM,cAAc,CAAC,SAAS,CAAC,CAAC;QAEhC,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAEhD,2BAA2B;QAC3B,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAc,EAAE,EAAE;YACxC,OAAO,CAAC,KAAK,CAAC,cAAc,MAAM,oBAAoB,CAAC,CAAC;YACxD,MAAM,aAAa,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC;QAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IAEnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,CAAC,CAAC;QACpD,MAAM,aAAa,EAAE,CAAC;QACtB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,gEAAgE;AAChE,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;AACnF,IAAI,WAAW,EAAE,CAAC;IAChB,IAAI,EAAE,CAAC;AACT,CAAC"}
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadslab.io/discord-mcp",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Manage your entire Discord server from Claude Code, Claude Desktop, Cursor, or Windsurf via MCP. 99 admin tools across 14 categories. Interactive setup wizard included.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,10 +23,15 @@
     "model-context-protocol",
     "claude",
     "claude-code",
+    "claude-desktop",
+    "cursor",
+    "windsurf",
     "server-admin",
     "discord-bot",
     "discord-management",
-    "anthropic"
+    "discord-admin",
+    "anthropic",
+    "ai-tools"
   ],
   "author": "QuadsLab",
   "license": "MIT",