@jtalk22/slack-mcp 3.1.0 → 3.2.1

package/docs/API.md

@@ -321,3 +321,137 @@ List all workspace users.
   ]
 }
 ```
+
+---
+
+### slack_add_reaction
+
+Add an emoji reaction to a message.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| channel_id | string | *required* | Channel or DM ID |
+| timestamp | string | *required* | Message timestamp to react to |
+| reaction | string | *required* | Emoji name without colons (e.g. `thumbsup`, `heart`, `eyes`) |
+
+**Returns:**
+```json
+{
+  "status": "added",
+  "channel": "D063M4403MW",
+  "timestamp": "1767368030.607599",
+  "reaction": "thumbsup"
+}
+```
+
+---
+
+### slack_remove_reaction
+
+Remove an emoji reaction from a message.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| channel_id | string | *required* | Channel or DM ID |
+| timestamp | string | *required* | Message timestamp |
+| reaction | string | *required* | Emoji name without colons |
+
+**Returns:**
+```json
+{
+  "status": "removed",
+  "channel": "D063M4403MW",
+  "timestamp": "1767368030.607599",
+  "reaction": "thumbsup"
+}
+```
+
+---
+
+### slack_conversations_mark
+
+Mark a conversation as read up to a specific message timestamp.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| channel_id | string | *required* | Channel or DM ID to mark as read |
+| timestamp | string | *required* | Message timestamp to mark as read up to |
+
+**Returns:**
+```json
+{
+  "status": "marked",
+  "channel": "D063M4403MW",
+  "read_up_to": "1767368030.607599"
+}
+```
+
+---
+
+### slack_conversations_unreads
+
+Get channels and DMs with unread messages, sorted by unread count (highest first).
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| types | string | "im,mpim,public_channel,private_channel" | Comma-separated conversation types |
+| limit | number | 50 | Maximum conversations to return |
+
+**Returns:**
+```json
+{
+  "total_unread_conversations": 3,
+  "conversations": [
+    {
+      "id": "C05GPEVH7J9",
+      "name": "engineering",
+      "type": "public_channel",
+      "unread_count": 12,
+      "latest_ts": "1767368030.607599"
+    },
+    {
+      "id": "D063M4403MW",
+      "name": "Gwen Santos",
+      "type": "dm",
+      "unread_count": 5,
+      "latest_ts": "1767368025.123456"
+    }
+  ]
+}
+```
+
+---
+
+### slack_users_search
+
+Search workspace users by name, display name, or email. Case-insensitive partial match.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| query | string | *required* | Search term to match against name, display name, real name, or email |
+| limit | number | 20 | Maximum results to return |
+
+**Returns:**
+```json
+{
+  "query": "gwen",
+  "count": 1,
+  "total_matches": 1,
+  "users": [
+    {
+      "id": "U05GPEVH7J9",
+      "name": "gwen",
+      "real_name": "Gwen Santos",
+      "display_name": "Gwen",
+      "email": "gwen@example.com",
+      "title": "Assistant",
+      "is_admin": false
+    }
+  ]
+}
+```

package/docs/SETUP.md

@@ -1,29 +1,68 @@
 # Setup Guide
 
-## Prerequisites
+## Cloud (Fastest — No Local Setup)
+
+If you want to skip local setup entirely, use **Slack MCP Cloud**:
+
+1. Go to [cloud.html](https://jtalk22.github.io/slack-mcp-server/cloud.html) and purchase a plan ($19/mo Solo, $49/mo Team)
+2. After checkout, you'll receive an API key and ready-to-paste config for Claude Desktop / Claude Code
+3. No Node.js, no Docker, no token management — one URL, 16 tools
+
+**Claude Desktop config (Cloud):**
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "url": "https://mcp.revasserlabs.com/oauth/mcp"
+    }
+  }
+}
+```
+
+**Claude Code config (Cloud):**
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "type": "sse",
+      "url": "https://mcp.revasserlabs.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+If you prefer self-hosting (free), continue below.
+
+---
+
+## Self-Hosted Setup
+
+### Prerequisites
 
 - Node.js 20+
-- Google Chrome (for token extraction)
+- Google Chrome (for token extraction on macOS)
 - macOS (for Keychain storage - other platforms use file storage only)
 
-## Installation
-
-### 1. Clone or Copy the Project
+### 1. Install via npm (Recommended)
 
 ```bash
-cd ~
-git clone https://github.com/jtalk22/slack-mcp-server.git
-# or if already exists:
-cd ~/slack-mcp-server
+npm install -g @jtalk22/slack-mcp
+# or use npx (no install):
+npx -y @jtalk22/slack-mcp --version
 ```
 
-### 2. Install Dependencies
+### 1b. Or Clone the Repository
 
 ```bash
+git clone https://github.com/jtalk22/slack-mcp-server.git
+cd slack-mcp-server
 npm install
 ```
 
-### 2.5 Verify Install Path in a Clean Directory
+### 2. Verify Installation
 
 ```bash
 tmpdir="$(mktemp -d)"
@@ -76,45 +115,41 @@ npm run tokens:auto
    ```
    And paste both values when prompted.
 
-### 4. Configure Claude Desktop (GUI App)
+### 4. Configure Claude Desktop
 
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+**macOS:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** Edit `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
     "slack": {
-      "command": "/opt/homebrew/bin/node",
-      "args": ["/Users/YOUR_USERNAME/slack-mcp-server/src/server.js"],
-      "env": {
-        "SLACK_TOKEN": "xoxc-your-token-here",
-        "SLACK_COOKIE": "xoxd-your-cookie-here",
-        "PATH": "/opt/homebrew/bin:/usr/bin:/bin"
-      }
+      "command": "npx",
+      "args": ["-y", "@jtalk22/slack-mcp"]
     }
   }
 }
 ```
 
-**Important:**
-- Replace `YOUR_USERNAME` with your actual username
-- Copy tokens from `~/.slack-mcp-tokens.json` into the env section
-- Fully restart Claude Desktop (Cmd+Q, then reopen)
+Fully restart Claude Desktop (Cmd+Q on macOS, then reopen).
 
-**Verify it's working:** Check `~/Library/Logs/Claude/mcp-server-slack.log`
+**Verify it's working:** Check `~/Library/Logs/Claude/mcp-server-slack.log` (macOS)
 
 ### 5. Configure Claude Code (CLI)
 
-Edit `~/.claude.json` and add under `mcpServers`:
+```bash
+claude mcp add slack npx -y @jtalk22/slack-mcp
+```
+
+Or manually edit `~/.claude.json`:
 
 ```json
 {
   "mcpServers": {
     "slack": {
       "type": "stdio",
-      "command": "node",
-      "args": ["/Users/YOUR_USERNAME/slack-mcp-server/src/server.js"],
-      "env": {}
+      "command": "npx",
+      "args": ["-y", "@jtalk22/slack-mcp"]
     }
   }
 }

package/docs/TROUBLESHOOTING.md

@@ -29,6 +29,34 @@ If `--version` fails here, the issue is install/runtime path, not Slack credenti
 
 ---
 
+## Cloud Issues
+
+### API Key Not Working
+
+**Symptom:** `401 Unauthorized` or `403 Forbidden` when using Cloud endpoint.
+
+**Solutions:**
+1. Verify your API key starts with `stmh_` (team) or `smsh_` (solo)
+2. Check the key hasn't been revoked — contact james@revasser.nyc for key issues
+3. Ensure you're using the correct endpoint: `https://mcp.revasserlabs.com/mcp`
+
+### Cloud Tools Not Available
+
+**Symptom:** Only seeing fewer tools than expected.
+
+**Cause:** AI compound tools (`slack_channel_summary`, `slack_extract_action_items`, `slack_find_decisions`) are Team plan only ($49/mo).
+
+**Solution:** Upgrade to Team plan for AI compound tools, or use the standard 16 tools available on all plans.
+
+### Cloud Endpoint Health Check
+
+```bash
+curl -s https://mcp.revasserlabs.com/health | jq .
+# Expected: {"status":"healthy","server":"slack-mcp-hosted","version":"0.5.0"}
+```
+
+---
+
 ## DMs Not Showing Up
 
 **Symptom:** `slack_list_conversations` returns channels but no DMs.

package/lib/handlers.js

@@ -617,3 +617,159 @@ export async function handleListUsers(args) {
     }]
   };
 }
+
+/**
+ * Add reaction handler
+ */
+export async function handleAddReaction(args) {
+  await slackAPI("reactions.add", {
+    channel: args.channel_id,
+    timestamp: args.timestamp,
+    name: args.reaction
+  });
+
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        status: "added",
+        channel: args.channel_id,
+        timestamp: args.timestamp,
+        reaction: args.reaction
+      }, null, 2)
+    }]
+  };
+}
+
+/**
+ * Remove reaction handler
+ */
+export async function handleRemoveReaction(args) {
+  await slackAPI("reactions.remove", {
+    channel: args.channel_id,
+    timestamp: args.timestamp,
+    name: args.reaction
+  });
+
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        status: "removed",
+        channel: args.channel_id,
+        timestamp: args.timestamp,
+        reaction: args.reaction
+      }, null, 2)
+    }]
+  };
+}
+
+/**
+ * Mark conversation as read handler
+ */
+export async function handleConversationsMark(args) {
+  await slackAPI("conversations.mark", {
+    channel: args.channel_id,
+    ts: args.timestamp
+  });
+
+  return asMcpJson({
+    status: "marked",
+    channel: args.channel_id,
+    read_up_to: args.timestamp
+  });
+}
+
+/**
+ * Unread conversations handler - returns channels/DMs with unread messages
+ */
+export async function handleConversationsUnreads(args) {
+  const types = args.types || "im,mpim,public_channel,private_channel";
+  const limit = args.limit || 50;
+
+  const result = await slackAPI("conversations.list", {
+    types,
+    limit: 200,
+    exclude_archived: true
+  });
+
+  // Filter to conversations with unreads and resolve names
+  const unreads = [];
+  for (const c of (result.channels || [])) {
+    const unreadCount = c.unread_count_display || c.unread_count || 0;
+    if (unreadCount === 0) continue;
+
+    let displayName = c.name;
+    if (c.is_im && c.user) {
+      displayName = await resolveUser(c.user);
+    }
+
+    unreads.push({
+      id: c.id,
+      name: displayName,
+      type: c.is_im ? "dm" : c.is_mpim ? "group_dm" : c.is_private ? "private_channel" : "public_channel",
+      unread_count: unreadCount,
+      latest_ts: c.latest?.ts || null
+    });
+  }
+
+  // Sort by unread count descending
+  unreads.sort((a, b) => b.unread_count - a.unread_count);
+
+  return asMcpJson({
+    total_unread_conversations: unreads.length,
+    conversations: unreads.slice(0, limit)
+  });
+}
+
+/**
+ * Search users handler - client-side filter on users.list
+ */
+export async function handleUsersSearch(args) {
+  const query = (args.query || "").toLowerCase();
+  const limit = args.limit || 20;
+
+  // Fetch all users (paginated)
+  const allUsers = [];
+  let cursor;
+
+  do {
+    const result = await slackAPI("users.list", {
+      limit: 200,
+      cursor
+    });
+
+    for (const u of (result.members || [])) {
+      if (u.deleted || u.is_bot || u.id === "USLACKBOT") continue;
+
+      const searchFields = [
+        u.name,
+        u.real_name,
+        u.profile?.display_name,
+        u.profile?.email
+      ].filter(Boolean).map(s => s.toLowerCase());
+
+      if (searchFields.some(f => f.includes(query))) {
+        allUsers.push({
+          id: u.id,
+          name: u.name,
+          real_name: u.real_name,
+          display_name: u.profile?.display_name,
+          email: u.profile?.email,
+          title: u.profile?.title,
+          is_admin: u.is_admin
+        });
+      }
+    }
+
+    cursor = result.response_metadata?.next_cursor;
+    if (cursor) await sleep(100);
+  } while (cursor && allUsers.length < 500);
+
+  return asMcpJson({
+    query: args.query,
+    count: Math.min(allUsers.length, limit),
+    total_matches: allUsers.length,
+    users: allUsers.slice(0, limit)
+  });
+}

package/lib/slack-client.js

@@ -193,7 +193,8 @@ export async function slackAPI(method, params = {}, options = {}) {
       // so stringify any arrays/objects before encoding.
       const safeParams = {};
       for (const [key, value] of Object.entries(params)) {
-        safeParams[key] = (typeof value === "object" && value !== null)
+        if (value === undefined || value === null) continue;
+        safeParams[key] = (typeof value === "object")
           ? JSON.stringify(value)
           : String(value);
       }
@@ -228,7 +229,12 @@ export async function slackAPI(method, params = {}, options = {}) {
     throw networkError;
   }
 
-  const data = await response.json();
+  let data;
+  try {
+    data = await response.json();
+  } catch (parseError) {
+    throw new Error(`Slack API ${method} returned non-JSON (HTTP ${response.status}): ${parseError.message}`);
+  }
 
   if (!data.ok) {
     // Handle rate limiting with exponential backoff
@@ -297,7 +303,9 @@ export function getUserCacheStats() {
  * Format a Slack timestamp to ISO string
  */
 export function formatTimestamp(ts) {
-  return new Date(parseFloat(ts) * 1000).toISOString();
+  const parsed = parseFloat(ts);
+  if (!Number.isFinite(parsed)) return null;
+  return new Date(parsed * 1000).toISOString();
 }
 
 /**

package/lib/token-store.js

@@ -11,7 +11,7 @@
 import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync } from "fs";
 import { homedir, platform } from "os";
 import { join } from "path";
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 
 const TOKEN_FILE = join(homedir(), ".slack-mcp-tokens.json");
 const KEYCHAIN_SERVICE = "slack-mcp-server";
@@ -28,8 +28,9 @@ let lastExtractionError = null;
 export function getFromKeychain(key) {
   if (!IS_MACOS) return null; // Keychain is macOS-only
   try {
-    const result = execSync(
-      `security find-generic-password -s "${KEYCHAIN_SERVICE}" -a "${key}" -w 2>/dev/null`,
+    const result = execFileSync(
+      "security",
+      ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", key, "-w"],
       { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
     );
     return result.trim();
@@ -43,11 +44,11 @@ export function saveToKeychain(key, value) {
   try {
     // Delete existing entry
     try {
-      execSync(`security delete-generic-password -s "${KEYCHAIN_SERVICE}" -a "${key}" 2>/dev/null`, { stdio: 'pipe' });
+      execFileSync("security", ["delete-generic-password", "-s", KEYCHAIN_SERVICE, "-a", key], { stdio: 'pipe' });
     } catch (e) { /* ignore */ }
 
     // Add new entry
-    execSync(`security add-generic-password -s "${KEYCHAIN_SERVICE}" -a "${key}" -w "${value}"`, { stdio: 'pipe' });
+    execFileSync("security", ["add-generic-password", "-s", KEYCHAIN_SERVICE, "-a", key, "-w", value], { stdio: 'pipe' });
     return true;
   } catch (e) {
     return false;

package/lib/tools.js

@@ -221,7 +221,7 @@ export const TOOLS = [
     annotations: {
       title: "Send Message",
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: false,
       openWorldHint: true
     }
@@ -268,5 +268,136 @@ export const TOOLS = [
       idempotentHint: true,
       openWorldHint: true
     }
+  },
+  {
+    name: "slack_add_reaction",
+    description: "Add an emoji reaction to a message",
+    inputSchema: {
+      type: "object",
+      properties: {
+        channel_id: {
+          type: "string",
+          description: "Channel or DM ID containing the message"
+        },
+        timestamp: {
+          type: "string",
+          description: "Message timestamp to react to"
+        },
+        reaction: {
+          type: "string",
+          description: "Emoji name without colons (e.g., 'thumbsup', 'eyes', 'white_check_mark')"
+        }
+      },
+      required: ["channel_id", "timestamp", "reaction"]
+    },
+    annotations: {
+      title: "Add Reaction",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  {
+    name: "slack_remove_reaction",
+    description: "Remove an emoji reaction from a message",
+    inputSchema: {
+      type: "object",
+      properties: {
+        channel_id: {
+          type: "string",
+          description: "Channel or DM ID containing the message"
+        },
+        timestamp: {
+          type: "string",
+          description: "Message timestamp to remove reaction from"
+        },
+        reaction: {
+          type: "string",
+          description: "Emoji name without colons (e.g., 'thumbsup', 'eyes')"
+        }
+      },
+      required: ["channel_id", "timestamp", "reaction"]
+    },
+    annotations: {
+      title: "Remove Reaction",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  {
+    name: "slack_conversations_mark",
+    description: "Mark a conversation as read up to a specific message timestamp",
+    inputSchema: {
+      type: "object",
+      properties: {
+        channel_id: {
+          type: "string",
+          description: "Channel or DM ID to mark as read"
+        },
+        timestamp: {
+          type: "string",
+          description: "Message timestamp to mark as read up to (all messages at or before this are marked read)"
+        }
+      },
+      required: ["channel_id", "timestamp"]
+    },
+    annotations: {
+      title: "Mark as Read",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  {
+    name: "slack_conversations_unreads",
+    description: "Get channels and DMs with unread messages, sorted by unread count (highest first)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        types: {
+          type: "string",
+          description: "Comma-separated types: im, mpim, public_channel, private_channel (default all)",
+          default: "im,mpim,public_channel,private_channel"
+        },
+        limit: {
+          type: "number",
+          description: "Maximum conversations to return (default 50)"
+        }
+      }
+    },
+    annotations: {
+      title: "Unread Conversations",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  {
+    name: "slack_users_search",
+    description: "Search workspace users by name, display name, or email. Case-insensitive partial match.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search term to match against name, display name, real name, or email"
+        },
+        limit: {
+          type: "number",
+          description: "Maximum results to return (default 20)"
+        }
+      },
+      required: ["query"]
+    },
+    annotations: {
+      title: "Search Users",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   }
 ];