@jtalk22/slack-mcp 3.0.0 → 3.2.0

package/README.md

@@ -1,43 +1,71 @@
 # Slack MCP Server
 
-Use your existing Slack session with Claude and other MCP clients.  
-Local-first by default (`stdio`/`web`), hosted HTTP when you need a remote endpoint.
+[![npm version](https://img.shields.io/npm/v/@jtalk22/slack-mcp)](https://www.npmjs.com/package/@jtalk22/slack-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@jtalk22/slack-mcp)](https://www.npmjs.com/package/@jtalk22/slack-mcp)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-v3.2.0-blue)](https://registry.modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-[Live demo](https://jtalk22.github.io/slack-mcp-server/public/demo-video.html) · [npm package](https://www.npmjs.com/package/@jtalk22/slack-mcp) · [Compatibility matrix](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/COMPATIBILITY.md)
+Session-based Slack MCP for Claude and MCP clients. Local-first `stdio`/`web` with secure-default hosted HTTP in v3.
 
-![Slack MCP tools in action](https://jtalk22.github.io/slack-mcp-server/docs/images/demo-readme.gif)
-
-## 30-Second Verify
+## Install + Verify
 
 ```bash
+npx -y @jtalk22/slack-mcp --setup
 npx -y @jtalk22/slack-mcp@latest --version
 npx -y @jtalk22/slack-mcp@latest --doctor
 npx -y @jtalk22/slack-mcp@latest --status
 ```
 
-Expected:
-- `--version` prints `slack-mcp-server v3.0.0`
-- `--doctor` exits with deterministic `0|1|2|3`
-- `--status` is read-only and non-mutating
+[Setup guide](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/SETUP.md) · [30-second verify reference](https://github.com/jtalk22/slack-mcp-server/blob/main/README.md#install--verify) · [Autoplay demo landing](https://jtalk22.github.io/slack-mcp-server/) · [Latest release](https://github.com/jtalk22/slack-mcp-server/releases/latest) · [npm package](https://www.npmjs.com/package/@jtalk22/slack-mcp)
 
-## Install
+[![Live demo poster](https://jtalk22.github.io/slack-mcp-server/docs/images/demo-poster.png)](https://jtalk22.github.io/slack-mcp-server/public/demo-video.html)
 
-```bash
-npm install -g @jtalk22/slack-mcp
-npx -y @jtalk22/slack-mcp --setup
-```
+Motion proof: [20-second mobile clip](https://jtalk22.github.io/slack-mcp-server/docs/videos/demo-claude-mobile-20s.mp4) · [Live demo walkthrough](https://jtalk22.github.io/slack-mcp-server/public/demo-video.html) · [Share card](https://jtalk22.github.io/slack-mcp-server/public/share.html)
 
-If this project saves you setup time, star the repo: https://github.com/jtalk22/slack-mcp-server
+Hosted migration note: `v3.1.0` keeps local `stdio`/`web` flows unchanged; hosted `/mcp` requires `SLACK_MCP_HTTP_AUTH_TOKEN` and `SLACK_MCP_HTTP_ALLOWED_ORIGINS`.
 
 Maintainer/operator: `jtalk22` (`james@revasser.nyc`)  
-Release notes: [v3.0.0 notes](https://github.com/jtalk22/slack-mcp-server/blob/main/.github/v3.0.0-release-notes.md)
+Release: [`v3.2.0`](https://github.com/jtalk22/slack-mcp-server/releases/tag/v3.2.0) · Notes: [v3.2.0 notes](https://github.com/jtalk22/slack-mcp-server/blob/main/.github/v3.2.0-release-notes.md) · Support: [deployment intake](https://github.com/jtalk22/slack-mcp-server/issues/new?template=deployment-intake.md)
+
+If this saved you setup time, consider starring the repo. Maintenance support: [GitHub Sponsors](https://github.com/sponsors/jtalk22) · [Ko-fi](https://ko-fi.com/jtalk22) · [Buy Me a Coffee](https://buymeacoffee.com/jtalk22)
+
+## v3.2.0 at a Glance
+
+- **16 tools** — added reactions, mark-as-read, unread inbox, and user search
+- All three transports (stdio, web, hosted HTTP) have full tool parity
+- No MCP tool renames or removals — fully backwards compatible
+
+## Slack MCP Cloud
+
+**No token management. No Docker. No Chrome extensions. One URL and you're connected.**
+
+Skip all local setup — paste one URL into Claude and get 16 Slack tools running in under 60 seconds. Encrypted token storage on Cloudflare's global edge (300+ PoPs). The only cloud-hosted session-based Slack MCP on the market.
 
-## v3.0.0 at a Glance
+| Plan | Price | Includes |
+|------|-------|----------|
+| Solo | $19/mo | 16 standard tools, AES-256-GCM encrypted storage, 5K requests/mo |
+| Team | $49/mo | 16 standard + 3 AI compound tools, 3 workspaces, 25K requests/mo |
 
-- Hosted HTTP `/mcp` now requires bearer auth by default (`SLACK_MCP_HTTP_AUTH_TOKEN`).
-- Hosted HTTP CORS now uses explicit allowlisting (`SLACK_MCP_HTTP_ALLOWED_ORIGINS`).
-- Local-first paths (`stdio`, `web`) stay compatible.
-- MCP tool names stay stable (no renames/removals).
+[Get Your API Key](https://jtalk22.github.io/slack-mcp-server/cloud.html) — live in 60 seconds. [Privacy Policy](https://jtalk22.github.io/slack-mcp-server/privacy.html).
+
+### Cloud Usage Examples
+
+Once configured, ask Claude naturally:
+
+1. **Catch up on a channel** — *"Summarize what happened in #engineering this week"*
+   Uses `slack_list_conversations` → `slack_conversations_history` → Claude synthesis.
+
+2. **Find a decision** — *"What did the team decide about the API migration?"*
+   Uses `slack_search_messages` with query `"API migration"`, then `slack_get_thread` to pull full context.
+
+3. **Export a conversation** — *"Export my full DM history with Sarah including threads"*
+   Uses `slack_list_conversations` to resolve Sarah's DM ID → `slack_get_full_conversation` with `include_threads: true`.
+
+4. **Send a standup update** — *"Post my standup in #daily-standup: shipped auth refactor, reviewing PR #42 today"*
+   Uses `slack_send_message` to the target channel.
+
+5. **AI-powered action items** *(Team plan)* — *"What action items came out of #product-sync today?"*
+   Uses `slack_extract_action_items` to identify owners, deadlines, and commitments.
 
 ## 60-Second Hosted Migration
 
@@ -96,7 +124,9 @@ Instead of authenticating as a bot, this server leverages your existing Chrome s
 - **Full Export** - Conversations with threads and resolved usernames
 - **Search** - Query across your entire workspace
 - **Send Messages** - DMs or channels, with thread support
-- **User Directory** - List and search 500+ users with pagination
+- **Reactions** - Add or remove emoji reactions on any message
+- **Unreads** - Priority-sorted unread inbox across all conversations
+- **User Directory** - List, search, and look up 500+ users with pagination
 
 ### Stability
 - **Auto Token Refresh** - Extracts fresh tokens from Chrome automatically *(macOS only)*
@@ -119,6 +149,11 @@ Instead of authenticating as a bot, this server leverages your existing Chrome s
 | `slack_get_thread` | Get thread replies |
 | `slack_users_info` | Get user details |
 | `slack_list_users` | List workspace users (paginated, 500+ supported) |
+| `slack_add_reaction` | Add an emoji reaction to a message |
+| `slack_remove_reaction` | Remove an emoji reaction from a message |
+| `slack_conversations_mark` | Mark a conversation as read up to a timestamp |
+| `slack_conversations_unreads` | Get channels/DMs with unread messages, priority-sorted |
+| `slack_users_search` | Search workspace users by name, display name, or email |
 
 ---
 
@@ -129,19 +164,19 @@ Instead of authenticating as a bot, this server leverages your existing Chrome s
 ### 30-Second Compatibility Check
 
 ```bash
-npx -y @jtalk22/slack-mcp --version
-npx -y @jtalk22/slack-mcp --doctor
 npx -y @jtalk22/slack-mcp --setup
+npx -y @jtalk22/slack-mcp --doctor
+npx -y @jtalk22/slack-mcp --status
 ```
 
 Expected:
-- `--version` prints `slack-mcp-server v3.0.x`
+- `--setup` launches the interactive wizard
 - `--doctor` returns one clear next action with exit code:
   - `0` ready
   - `1` missing credentials
   - `2` invalid/expired credentials
   - `3` connectivity/runtime issue
-- `--setup` launches the interactive wizard
+- `--status` is read-only and non-mutating
 
 Command reference: [HN launch kit](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/HN-LAUNCH.md)
 
@@ -366,7 +401,7 @@ npm run web
 
 ```
 ════════════════════════════════════════════════════════════
-  Slack Web API Server v3.0.0
+  Slack Web API Server v3.2.0
 ════════════════════════════════════════════════════════════
 
   Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx

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;