@jtalk22/slack-mcp 1.2.0 → 1.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 jtalk22
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,18 +1,38 @@
-# Slack MCP Server
+<p align="center">
+  <a href="https://jtalk22.github.io/slack-mcp-server/public/demo.html"><img src="docs/assets/icon-512.png" alt="Slack MCP Server" width="80"></a>
+</p>
 
-*Full workspace access via local session mirroring. DMs, threads, and history—no admin approval required.*
+<h1 align="center">Slack MCP Server</h1>
 
-[![Live Demo](https://img.shields.io/badge/LIVE%20DEMO-Try%20It%20Now-00C853?style=for-the-badge&logo=slack&logoColor=white)](https://jtalk22.github.io/slack-mcp-server/public/demo.html)
-[![Claude Demo](https://img.shields.io/badge/CLAUDE%20DEMO-See%20MCP%20Tools-da7756?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6bTAgMThjLTQuNDEgMC04LTMuNTktOC04czMuNTktOCA4LTggOCAzLjU5IDggOC0zLjU5IDgtOCA4eiIvPjwvc3ZnPg==&logoColor=white)](https://jtalk22.github.io/slack-mcp-server/public/demo-claude.html)
+<p align="center">
+  <em>Give Claude the same Slack access you have.<br>
+  DMs, threads, history—no admin approval.</em>
+</p>
 
-[![npm](https://img.shields.io/npm/v/@jtalk22/slack-mcp?color=blue&label=npm)](https://www.npmjs.com/package/@jtalk22/slack-mcp)
-[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/jtalk22/slack-mcp-server/pkgs/container/slack-mcp-server)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
-[![GitHub Sponsors](https://img.shields.io/github/sponsors/jtalk22?label=Sponsor&logo=github)](https://github.com/sponsors/jtalk22)
+<p align="center">
+  <a href="https://jtalk22.github.io/slack-mcp-server/public/demo-video.html">
+    <img src="docs/images/demo-readme.gif" alt="Slack MCP tools in action" width="640">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@jtalk22/slack-mcp"><img src="https://img.shields.io/badge/npm-Install-blue?style=for-the-badge&logo=npm&logoColor=white" alt="npm"></a>
+  <a href="https://github.com/jtalk22/slack-mcp-server/pkgs/container/slack-mcp-server"><img src="https://img.shields.io/badge/Docker-Pull-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker"></a>
+</p>
 
 <p align="center">
-  <img src="https://assets-worker.james-20a.workers.dev/projects/slack-mcp-server/demo-claude.gif" alt="Claude Desktop using Slack MCP tools" width="800">
+  <a href="https://jtalk22.github.io/slack-mcp-server/public/demo.html"><img src="https://img.shields.io/badge/LIVE%20DEMO-Try%20It%20Now-00C853?style=for-the-badge&logo=slack&logoColor=white" alt="Live Demo"></a>
+  <a href="https://jtalk22.github.io/slack-mcp-server/public/demo-claude.html"><img src="https://img.shields.io/badge/CLAUDE%20DEMO-See%20MCP%20Tools-da7756?style=for-the-badge" alt="Claude Demo"></a>
+</p>
+
+<br>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@jtalk22/slack-mcp"><img src="https://img.shields.io/npm/dm/@jtalk22/slack-mcp?label=downloads&color=CB3837" alt="npm downloads"></a>
+  <a href="https://github.com/jtalk22/slack-mcp-server/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/jtalk22/slack-mcp-server/ci.yml?label=build" alt="Build Status"></a>
+  <a href="https://smithery.ai/server/jtalk22/slack-mcp-server"><img src="https://img.shields.io/badge/Smithery-Registry-4A154B" alt="Smithery"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://github.com/sponsors/jtalk22"><img src="https://img.shields.io/badge/Sponsor-♡-ea4aaa?logo=github" alt="Sponsor"></a>
 </p>
 
 ---
@@ -27,59 +47,17 @@ This server bridges the gap. It creates a secure, local bridge between Claude an
 
 ![Slack MCP Server Web UI](docs/images/demo-main.png)
 
-> **[Try the Interactive Demo](https://jtalk22.github.io/slack-mcp-server/public/demo.html)** - See the Web UI in action
->
-> **[See Claude Desktop Demo](https://jtalk22.github.io/slack-mcp-server/public/demo-claude.html)** - Watch MCP tools in action
-
 ---
 
 ## Architecture: Local Session Mirroring
 
 Instead of authenticating as a bot, this server leverages your existing Chrome session credentials (macOS) or manual token injection (Linux/Windows). It mirrors your user access exactly—if you can see it in Slack, Claude can see it too.
 
-```mermaid
-sequenceDiagram
-    participant Chrome as Chrome Browser
-    participant Script as AppleScript
-    participant Store as Token Store
-    participant MCP as MCP Server
-    participant Slack as Slack API
-
-    Note over Chrome: You're logged into Slack
-    Script->>Chrome: Execute JavaScript in Slack tab
-    Chrome-->>Script: xoxc- token + xoxd- cookie
-    Script->>Store: Save to ~/.slack-mcp-tokens.json
-    Store->>Store: Encrypt in macOS Keychain
-
-    Note over MCP: Claude asks for DMs
-    MCP->>Store: Load credentials
-    Store-->>MCP: Token + Cookie
-    MCP->>Slack: GET conversations.history
-    Slack-->>MCP: Full message history
-    MCP-->>MCP: Return to Claude
-```
+![Session Mirroring Flow](docs/images/diagram-session-flow.svg)
 
 ### Why Not OAuth?
 
-```mermaid
-flowchart LR
-    subgraph Traditional["Official Slack API (OAuth)"]
-        A[Create App] --> B[Request Scopes]
-        B --> C[Admin Approval]
-        C --> D[User Authorization]
-        D --> E[Limited Access]
-        E --> F["No DMs without<br/>per-conversation consent"]
-    end
-
-    subgraph ThisServer["Session Mirroring"]
-        G[Open Slack in Chrome] --> H[Mirror Session]
-        H --> I[Full Access]
-        I --> J["Your DMs, Channels,<br/>Search, History"]
-    end
-
-    style Traditional fill:#ffcccc
-    style ThisServer fill:#ccffcc
-```
+![OAuth vs Session Mirroring](docs/images/diagram-oauth-comparison.svg)
 
 **Trade-off:** Session tokens expire every 1-2 weeks. Auto-refresh (macOS) or manual update keeps things running.
 
@@ -120,6 +98,8 @@ flowchart LR
 
 ## Quick Start
 
+**Runtime:** Node.js 20+
+
 ### Option A: npm (Recommended)
 
 ```bash
@@ -297,9 +277,9 @@ finally { refreshInProgress = false; }
 
 ---
 
-## Web UI (for claude.ai)
+## Web UI (for claude.ai — no MCP support)
 
-Since claude.ai doesn't support MCP, use the REST server:
+If you're using claude.ai in a browser (which doesn't support MCP), you can use the REST server instead:
 
 ```bash
 npm run web
@@ -310,7 +290,7 @@ npm run web
 
 ```
 ════════════════════════════════════════════════════════════
-  Slack Web API Server v1.1.7
+  Slack Web API Server v1.2.1
 ════════════════════════════════════════════════════════════
 
   Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx

package/docs/SETUP.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- Node.js 18+
+- Node.js 20+
 - Google Chrome (for token extraction)
 - macOS (for Keychain storage - other platforms use file storage only)
 

package/docs/assets/icon.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#4A154B"/>
+      <stop offset="100%" style="stop-color:#3D1140"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Background rounded square -->
+  <rect x="0" y="0" width="512" height="512" rx="96" ry="96" fill="url(#bg)"/>
+
+  <!-- Stylized hashtag/channel symbol -->
+  <g fill="none" stroke="#FFFFFF" stroke-width="36" stroke-linecap="round">
+    <!-- Vertical lines -->
+    <line x1="180" y1="140" x2="160" y2="372"/>
+    <line x1="352" y1="140" x2="332" y2="372"/>
+    <!-- Horizontal lines -->
+    <line x1="120" y1="200" x2="392" y2="200"/>
+    <line x1="120" y1="312" x2="392" y2="312"/>
+  </g>
+
+  <!-- Slack-colored connection dots (representing MCP bridge) -->
+  <circle cx="420" cy="92" r="28" fill="#36C5F0"/>
+  <circle cx="92" cy="420" r="28" fill="#2EB67D"/>
+  <circle cx="420" cy="420" r="28" fill="#ECB22E"/>
+  <circle cx="92" cy="92" r="28" fill="#E01E5A"/>
+</svg>

package/docs/images/diagram-oauth-comparison.svg

@@ -0,0 +1,80 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 420">
+  <defs>
+    <linearGradient id="bgGrad2" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1a1a2e"/>
+      <stop offset="100%" style="stop-color:#16213e"/>
+    </linearGradient>
+    <marker id="arrowRed2" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#e94560"/>
+    </marker>
+    <marker id="arrowTeal2" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#4ecdc4"/>
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="900" height="420" fill="url(#bgGrad2)" rx="12"/>
+
+  <!-- Left Side: OAuth (Red-tinted) -->
+  <rect x="30" y="50" width="400" height="340" rx="12" fill="#e94560" opacity="0.1" stroke="#e94560" stroke-width="2"/>
+  <text x="230" y="85" text-anchor="middle" fill="#fca5a5" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="600">Official Slack API (OAuth)</text>
+
+  <!-- OAuth Flow - Row 1 -->
+  <rect x="45" y="110" width="120" height="45" rx="8" fill="#2d2d2d" stroke="#e94560" stroke-width="1"/>
+  <text x="105" y="138" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="12">Create App</text>
+
+  <path d="M 170 132 L 190 132" stroke="#e94560" stroke-width="2" marker-end="url(#arrowRed2)"/>
+
+  <rect x="195" y="110" width="120" height="45" rx="8" fill="#2d2d2d" stroke="#e94560" stroke-width="1"/>
+  <text x="255" y="138" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="12">Request Scopes</text>
+
+  <path d="M 320 132 L 340 132" stroke="#e94560" stroke-width="2" marker-end="url(#arrowRed2)"/>
+
+  <rect x="345" y="110" width="75" height="45" rx="8" fill="#e94560" opacity="0.4" stroke="#e94560" stroke-width="1"/>
+  <text x="382" y="128" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="11" font-weight="600">Admin</text>
+  <text x="382" y="144" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="11" font-weight="600">Approval</text>
+
+  <!-- Arrow down from Admin Approval -->
+  <path d="M 382 160 L 382 195" stroke="#e94560" stroke-width="2" marker-end="url(#arrowRed2)"/>
+
+  <!-- OAuth Flow - Row 2 -->
+  <rect x="95" y="205" width="140" height="45" rx="8" fill="#2d2d2d" stroke="#e94560" stroke-width="1"/>
+  <text x="165" y="233" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="12">User Authorization</text>
+
+  <path d="M 240 227 L 260 227" stroke="#e94560" stroke-width="2" marker-end="url(#arrowRed2)"/>
+
+  <rect x="265" y="205" width="140" height="45" rx="8" fill="#2d2d2d" stroke="#e94560" stroke-width="1"/>
+  <text x="335" y="233" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="12">Limited Access</text>
+
+  <!-- OAuth Result (blocked) -->
+  <rect x="70" y="280" width="290" height="60" rx="8" fill="#e94560" opacity="0.15" stroke="#e94560" stroke-width="2" stroke-dasharray="4"/>
+  <text x="215" y="305" text-anchor="middle" fill="#fca5a5" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="500">No DMs without</text>
+  <text x="215" y="325" text-anchor="middle" fill="#fca5a5" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="500">per-conversation consent</text>
+
+  <!-- Right Side: Session Mirroring (Green-tinted) -->
+  <rect x="470" y="50" width="400" height="340" rx="12" fill="#4ecdc4" opacity="0.1" stroke="#4ecdc4" stroke-width="2"/>
+  <text x="670" y="85" text-anchor="middle" fill="#5eead4" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="600">Session Mirroring</text>
+
+  <!-- Session Mirroring Flow -->
+  <rect x="495" y="120" width="160" height="50" rx="8" fill="#3b82f6" opacity="0.9"/>
+  <text x="575" y="150" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="12" font-weight="500">Open Slack in Chrome</text>
+
+  <path d="M 660 145 L 700 145" stroke="#4ecdc4" stroke-width="3" marker-end="url(#arrowTeal2)"/>
+
+  <rect x="705" y="120" width="140" height="50" rx="8" fill="#da7756" opacity="0.9"/>
+  <text x="775" y="150" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="12" font-weight="500">Mirror Session</text>
+
+  <path d="M 775 175 L 775 210" stroke="#4ecdc4" stroke-width="3" marker-end="url(#arrowTeal2)"/>
+
+  <rect x="605" y="220" width="160" height="50" rx="8" fill="#4ecdc4" opacity="0.9"/>
+  <text x="685" y="250" text-anchor="middle" fill="#1a1a2e" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600">Full Access</text>
+
+  <!-- Session Mirroring Result (success) -->
+  <rect x="510" y="295" width="340" height="60" rx="8" fill="#4ecdc4" opacity="0.2" stroke="#4ecdc4" stroke-width="2"/>
+  <text x="680" y="320" text-anchor="middle" fill="#5eead4" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="500">Your DMs, Channels, Search, History</text>
+  <text x="680" y="340" text-anchor="middle" fill="#5eead4" font-family="system-ui, -apple-system, sans-serif" font-size="11">✓ Same access as your browser</text>
+
+  <!-- VS divider -->
+  <circle cx="450" cy="210" r="24" fill="#1a1a2e" stroke="#ffffff" stroke-width="2" opacity="0.9"/>
+  <text x="450" y="216" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="700">vs</text>
+</svg>

package/docs/images/diagram-session-flow.svg

@@ -0,0 +1,105 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 400">
+  <defs>
+    <linearGradient id="bgGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1a1a2e"/>
+      <stop offset="100%" style="stop-color:#16213e"/>
+    </linearGradient>
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="2" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="900" height="400" fill="url(#bgGrad)" rx="12"/>
+
+  <!-- Title -->
+  <text x="450" y="35" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="600">Session Mirroring Flow</text>
+
+  <!-- Participants -->
+  <!-- Chrome -->
+  <rect x="50" y="60" width="120" height="40" rx="8" fill="#3b82f6" opacity="0.9"/>
+  <text x="110" y="85" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="500">Chrome</text>
+  <line x1="110" y1="100" x2="110" y2="360" stroke="#3b82f6" stroke-width="2" stroke-dasharray="4"/>
+
+  <!-- AppleScript -->
+  <rect x="220" y="60" width="120" height="40" rx="8" fill="#8b5cf6" opacity="0.9"/>
+  <text x="280" y="85" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="500">AppleScript</text>
+  <line x1="280" y1="100" x2="280" y2="360" stroke="#8b5cf6" stroke-width="2" stroke-dasharray="4"/>
+
+  <!-- Token Store -->
+  <rect x="390" y="60" width="120" height="40" rx="8" fill="#4ecdc4" opacity="0.9"/>
+  <text x="450" y="85" text-anchor="middle" fill="#1a1a2e" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="500">Token Store</text>
+  <line x1="450" y1="100" x2="450" y2="360" stroke="#4ecdc4" stroke-width="2" stroke-dasharray="4"/>
+
+  <!-- MCP Server -->
+  <rect x="560" y="60" width="120" height="40" rx="8" fill="#da7756" opacity="0.9"/>
+  <text x="620" y="85" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="500">MCP Server</text>
+  <line x1="620" y1="100" x2="620" y2="360" stroke="#da7756" stroke-width="2" stroke-dasharray="4"/>
+
+  <!-- Slack API -->
+  <rect x="730" y="60" width="120" height="40" rx="8" fill="#e94560" opacity="0.9"/>
+  <text x="790" y="85" text-anchor="middle" fill="#ffffff" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="500">Slack API</text>
+  <line x1="790" y1="100" x2="790" y2="360" stroke="#e94560" stroke-width="2" stroke-dasharray="4"/>
+
+  <!-- Note: Logged into Slack -->
+  <rect x="60" y="115" width="100" height="30" rx="4" fill="#3b82f6" opacity="0.2" stroke="#3b82f6" stroke-width="1"/>
+  <text x="110" y="135" text-anchor="middle" fill="#93c5fd" font-family="system-ui, -apple-system, sans-serif" font-size="10">Logged into Slack</text>
+
+  <!-- Arrow 1: Script → Chrome -->
+  <line x1="280" y1="160" x2="130" y2="160" stroke="#8b5cf6" stroke-width="2" marker-end="url(#arrowPurple)"/>
+  <text x="205" y="153" text-anchor="middle" fill="#c4b5fd" font-family="system-ui, -apple-system, sans-serif" font-size="10">Execute JS in tab</text>
+
+  <!-- Arrow 2: Chrome → Script (dashed return) -->
+  <line x1="130" y1="185" x2="260" y2="185" stroke="#3b82f6" stroke-width="2" stroke-dasharray="5" marker-end="url(#arrowBlue)"/>
+  <text x="195" y="200" text-anchor="middle" fill="#93c5fd" font-family="system-ui, -apple-system, sans-serif" font-size="10">xoxc- + xoxd- tokens</text>
+
+  <!-- Arrow 3: Script → Store -->
+  <line x1="300" y1="225" x2="430" y2="225" stroke="#8b5cf6" stroke-width="2" marker-end="url(#arrowPurple)"/>
+  <text x="365" y="218" text-anchor="middle" fill="#c4b5fd" font-family="system-ui, -apple-system, sans-serif" font-size="10">Save tokens</text>
+
+  <!-- Store self-arrow (Keychain) -->
+  <path d="M 470 245 Q 500 245 500 260 Q 500 275 470 275" fill="none" stroke="#4ecdc4" stroke-width="2"/>
+  <text x="515" y="265" fill="#5eead4" font-family="system-ui, -apple-system, sans-serif" font-size="10">Keychain encrypt</text>
+
+  <!-- Divider -->
+  <line x1="50" y1="300" x2="850" y2="300" stroke="#ffffff" stroke-width="1" opacity="0.2"/>
+  <text x="60" y="295" fill="#ffffff" opacity="0.5" font-family="system-ui, -apple-system, sans-serif" font-size="10">Claude requests data</text>
+
+  <!-- Arrow 4: MCP → Store -->
+  <line x1="600" y1="320" x2="470" y2="320" stroke="#da7756" stroke-width="2" marker-end="url(#arrowOrange)"/>
+  <text x="535" y="313" text-anchor="middle" fill="#fbbf8c" font-family="system-ui, -apple-system, sans-serif" font-size="10">Load creds</text>
+
+  <!-- Arrow 5: Store → MCP (return) -->
+  <line x1="470" y1="340" x2="600" y2="340" stroke="#4ecdc4" stroke-width="2" stroke-dasharray="5" marker-end="url(#arrowTeal)"/>
+
+  <!-- Arrow 6: MCP → Slack -->
+  <line x1="640" y1="355" x2="770" y2="355" stroke="#da7756" stroke-width="2" marker-end="url(#arrowOrange)"/>
+  <text x="705" y="348" text-anchor="middle" fill="#fbbf8c" font-family="system-ui, -apple-system, sans-serif" font-size="10">GET messages</text>
+
+  <!-- Arrow 7: Slack → MCP (return) -->
+  <line x1="770" y1="375" x2="640" y2="375" stroke="#e94560" stroke-width="2" stroke-dasharray="5" marker-end="url(#arrowRed)"/>
+  <text x="705" y="390" text-anchor="middle" fill="#fca5a5" font-family="system-ui, -apple-system, sans-serif" font-size="10">Full history</text>
+
+  <!-- Arrow markers -->
+  <defs>
+    <marker id="arrowPurple" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#8b5cf6"/>
+    </marker>
+    <marker id="arrowBlue" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#3b82f6"/>
+    </marker>
+    <marker id="arrowTeal" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#4ecdc4"/>
+    </marker>
+    <marker id="arrowOrange" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#da7756"/>
+    </marker>
+    <marker id="arrowRed" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <path d="M0,0 L0,6 L9,3 z" fill="#e94560"/>
+    </marker>
+  </defs>
+</svg>

package/lib/slack-client.js

@@ -24,6 +24,15 @@ const RETRYABLE_NETWORK_ERRORS = [
   'ECONNREFUSED', 'EPIPE', 'UND_ERR_CONNECT_TIMEOUT'
 ];
 
+// Slack API methods that require form-encoded params instead of JSON
+const FORM_ENCODED_METHODS = new Set([
+  "conversations.replies",
+  "search.messages",
+  "search.all",
+  "search.files",
+  "users.info",
+]);
+
 let lastRefreshAttempt = 0;
 
 // ============ LRU Cache with TTL ============
@@ -149,16 +158,36 @@ export async function slackAPI(method, params = {}, options = {}) {
     checkTokenHealth({ error: () => {} }).catch(() => {});
   }
 
+  const useForm = FORM_ENCODED_METHODS.has(method);
+
   let response;
   try {
+    const headers = {
+      "Authorization": `Bearer ${creds.token}`,
+      "Cookie": `d=${creds.cookie}`,
+    };
+
+    let body;
+    if (useForm) {
+      // URLSearchParams coerces non-primitives to "[object Object]",
+      // so stringify any arrays/objects before encoding.
+      const safeParams = {};
+      for (const [key, value] of Object.entries(params)) {
+        safeParams[key] = (typeof value === "object" && value !== null)
+          ? JSON.stringify(value)
+          : String(value);
+      }
+      headers["Content-Type"] = "application/x-www-form-urlencoded; charset=utf-8";
+      body = new URLSearchParams(safeParams).toString();
+    } else {
+      headers["Content-Type"] = "application/json; charset=utf-8";
+      body = JSON.stringify(params);
+    }
+
     response = await fetch(`https://slack.com/api/${method}`, {
       method: "POST",
-      headers: {
-        "Authorization": `Bearer ${creds.token}`,
-        "Cookie": `d=${creds.cookie}`,
-        "Content-Type": "application/json; charset=utf-8",
-      },
-      body: JSON.stringify(params),
+      headers,
+      body,
     });
   } catch (networkError) {
     // Retry on network errors with exponential backoff + jitter

package/lib/tools.js

@@ -2,6 +2,7 @@
  * MCP Tool Definitions
  *
  * All Slack MCP tools in one place for easy maintenance.
+ * Includes MCP annotations for better tool discovery and safety hints.
  */
 
 export const TOOLS = [
@@ -11,6 +12,12 @@ export const TOOLS = [
     inputSchema: {
       type: "object",
       properties: {}
+    },
+    annotations: {
+      title: "Token Status",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
     }
   },
   {
@@ -19,6 +26,12 @@ export const TOOLS = [
     inputSchema: {
       type: "object",
       properties: {}
+    },
+    annotations: {
+      title: "Health Check",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
     }
   },
   {
@@ -27,6 +40,13 @@ export const TOOLS = [
     inputSchema: {
       type: "object",
       properties: {}
+    },
+    annotations: {
+      title: "Refresh Tokens",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
     }
   },
   {
@@ -49,6 +69,12 @@ export const TOOLS = [
           description: "If true, actively discover all DMs (slower, may hit rate limits on large workspaces). Default false uses cached DMs."
         }
       }
+    },
+    annotations: {
+      title: "List Conversations",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
     }
   },
   {
@@ -79,6 +105,12 @@ export const TOOLS = [
         }
       },
       required: ["channel_id"]
+    },
+    annotations: {
+      title: "Conversation History",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
     }
   },
   {
@@ -113,6 +145,12 @@ export const TOOLS = [
         }
       },
       required: ["channel_id"]
+    },
+    annotations: {
+      title: "Full Conversation Export",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
     }
   },
   {
@@ -131,6 +169,12 @@ export const TOOLS = [
         }
       },
       required: ["query"]
+    },
+    annotations: {
+      title: "Search Messages",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
     }
   },
   {
@@ -145,6 +189,12 @@ export const TOOLS = [
         }
       },
       required: ["user_id"]
+    },
+    annotations: {
+      title: "User Info",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
     }
   },
   {
@@ -167,6 +217,13 @@ export const TOOLS = [
         }
       },
       required: ["channel_id", "text"]
+    },
+    annotations: {
+      title: "Send Message",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
     }
   },
   {
@@ -185,6 +242,12 @@ export const TOOLS = [
         }
       },
       required: ["channel_id", "thread_ts"]
+    },
+    annotations: {
+      title: "Get Thread",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
     }
   },
   {
@@ -198,6 +261,12 @@ export const TOOLS = [
           description: "Maximum users to return (default 500, supports pagination)"
         }
       }
+    },
+    annotations: {
+      title: "List Users",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
     }
   }
 ];

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@jtalk22/slack-mcp",
   "mcpName": "io.github.jtalk22/slack-mcp-server",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Full Slack access for Claude - DMs, channels, search. No OAuth. No admin approval. Just works.",
   "type": "module",
   "main": "src/server.js",
   "bin": {
+    "slack-mcp": "./src/cli.js",
     "slack-mcp-server": "./src/server.js",
     "slack-mcp-http": "./src/server-http.js",
     "slack-mcp-web": "./src/web-server.js",
@@ -88,7 +89,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "^1.27.0",
     "express": "^4.18.2"
   },
   "files": [

package/public/demo-video.html

@@ -0,0 +1,151 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Slack MCP Server Demo</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+      min-height: 100vh;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      padding: 2rem;
+    }
+    .container {
+      max-width: 900px;
+      width: 100%;
+    }
+    h1 {
+      color: #ffffff;
+      font-size: 1.75rem;
+      font-weight: 600;
+      text-align: center;
+      margin-bottom: 0.5rem;
+    }
+    .subtitle {
+      color: #94a3b8;
+      text-align: center;
+      margin-bottom: 1.5rem;
+      font-size: 1rem;
+    }
+    .video-wrapper {
+      position: relative;
+      border-radius: 12px;
+      overflow: hidden;
+      box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.5);
+      background: #0f0f1a;
+    }
+    video {
+      width: 100%;
+      display: block;
+      border-radius: 12px;
+    }
+    .controls {
+      display: flex;
+      justify-content: center;
+      gap: 1rem;
+      margin-top: 1.5rem;
+    }
+    .btn {
+      padding: 0.75rem 1.5rem;
+      border-radius: 8px;
+      border: none;
+      font-size: 0.875rem;
+      font-weight: 500;
+      cursor: pointer;
+      transition: all 0.2s;
+    }
+    .btn-primary {
+      background: #4ecdc4;
+      color: #1a1a2e;
+    }
+    .btn-primary:hover {
+      background: #5eead4;
+      transform: translateY(-1px);
+    }
+    .btn-secondary {
+      background: rgba(255, 255, 255, 0.1);
+      color: #ffffff;
+      border: 1px solid rgba(255, 255, 255, 0.2);
+    }
+    .btn-secondary:hover {
+      background: rgba(255, 255, 255, 0.15);
+    }
+    .back-link {
+      margin-top: 2rem;
+      text-align: center;
+    }
+    .back-link a {
+      color: #94a3b8;
+      text-decoration: none;
+      font-size: 0.875rem;
+    }
+    .back-link a:hover {
+      color: #ffffff;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Slack MCP Server</h1>
+    <p class="subtitle">Full workspace access via local session mirroring</p>
+
+    <div class="video-wrapper">
+      <video id="demo" poster="../docs/images/demo-poster.png" playsinline>
+        <source src="../docs/videos/demo-claude-v1.2.webm" type="video/webm">
+        <source src="../docs/images/demo-claude-v1.2.gif" type="image/gif">
+        Your browser does not support the video tag.
+      </video>
+    </div>
+
+    <div class="controls">
+      <button class="btn btn-primary" onclick="togglePlay()">Play / Pause</button>
+      <button class="btn btn-secondary" onclick="restart()">Restart</button>
+    </div>
+
+    <div class="back-link">
+      <a href="https://github.com/jtalk22/slack-mcp-server">← Back to Repository</a>
+    </div>
+  </div>
+
+  <script>
+    const video = document.getElementById('demo');
+
+    // Autoplay with 1 second delay
+    setTimeout(() => {
+      video.play().catch(() => {
+        // Autoplay blocked, user will need to click
+        console.log('Autoplay blocked, click to play');
+      });
+    }, 1000);
+
+    function togglePlay() {
+      if (video.paused) {
+        video.play();
+      } else {
+        video.pause();
+      }
+    }
+
+    function restart() {
+      video.currentTime = 0;
+      video.play();
+    }
+
+    // Loop the video
+    video.addEventListener('ended', () => {
+      video.currentTime = 0;
+      video.play();
+    });
+  </script>
+</body>
+</html>

package/scripts/record-demo.js

@@ -73,6 +73,10 @@ async function recordDemo() {
   await page.goto(`file://${demoPath}`);
   await page.waitForTimeout(1000);
 
+  // Hold on initial frame for a few seconds (visible first frame in GIF)
+  console.log('⏸️  Holding initial frame (3s)...');
+  await page.waitForTimeout(3000);
+
   // Set slow speed for video recording
   console.log(`⏱️  Setting speed to ${CONFIG.speed}x...`);
   await page.selectOption('#speedSelect', CONFIG.speed);

package/scripts/setup-wizard.js

@@ -16,7 +16,7 @@ import { loadTokens, saveTokens, extractFromChrome, isAutoRefreshAvailable, TOKE
 import { slackAPI } from "../lib/slack-client.js";
 
 const IS_MACOS = platform() === 'darwin';
-const VERSION = "1.2.0";
+const VERSION = "1.2.1";
 
 // ANSI colors
 const colors = {
@@ -69,24 +69,27 @@ async function pressEnterToContinue(rl) {
 }
 
 async function validateTokens(token, cookie) {
-  try {
-    // Temporarily set env vars for validation
-    const oldToken = process.env.SLACK_TOKEN;
-    const oldCookie = process.env.SLACK_COOKIE;
-    process.env.SLACK_TOKEN = token;
-    process.env.SLACK_COOKIE = cookie;
-
-    const result = await slackAPI("auth.test", {});
+  const hadOldToken = Object.prototype.hasOwnProperty.call(process.env, "SLACK_TOKEN");
+  const hadOldCookie = Object.prototype.hasOwnProperty.call(process.env, "SLACK_COOKIE");
+  const oldToken = process.env.SLACK_TOKEN;
+  const oldCookie = process.env.SLACK_COOKIE;
 
-    // Restore env vars
-    if (oldToken) process.env.SLACK_TOKEN = oldToken;
-    else delete process.env.SLACK_TOKEN;
-    if (oldCookie) process.env.SLACK_COOKIE = oldCookie;
-    else delete process.env.SLACK_COOKIE;
+  // Temporarily set env vars for validation
+  process.env.SLACK_TOKEN = token;
+  process.env.SLACK_COOKIE = cookie;
 
+  try {
+    const result = await slackAPI("auth.test", {});
     return { valid: true, user: result.user, team: result.team };
   } catch (e) {
     return { valid: false, error: e.message };
+  } finally {
+    // Always restore prior process env state
+    if (hadOldToken) process.env.SLACK_TOKEN = oldToken;
+    else delete process.env.SLACK_TOKEN;
+
+    if (hadOldCookie) process.env.SLACK_COOKIE = oldCookie;
+    else delete process.env.SLACK_COOKIE;
   }
 }
 
@@ -175,7 +178,7 @@ async function runManualSetup(rl) {
     "  .teams)[0]].token",
   ], 55);
   print();
-  print("         Copy the token (starts with ${colors.cyan}xoxc-${colors.reset})");
+  print(`         Copy the token (starts with ${colors.cyan}xoxc-${colors.reset})`);
   print();
 
   const token = await question(rl, `${colors.bold}Paste your token:${colors.reset} `);
@@ -187,7 +190,7 @@ async function runManualSetup(rl) {
 
   print();
   print(`${colors.bold}Step 4:${colors.reset} Go to ${colors.cyan}Application${colors.reset} tab → ${colors.cyan}Cookies${colors.reset} → slack.com`);
-  print("         Find the '${colors.cyan}d${colors.reset}' cookie and copy its value");
+  print(`         Find the '${colors.cyan}d${colors.reset}' cookie and copy its value`);
   print();
 
   const cookie = await question(rl, `${colors.bold}Paste your cookie:${colors.reset} `);

package/src/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * slack-mcp package entrypoint dispatcher.
+ *
+ * Supports:
+ * - default stdio server startup
+ * - web/http server modes
+ * - setup wizard and its status/help/version flags
+ */
+
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const args = process.argv.slice(2);
+const firstArg = args[0];
+
+const WIZARD_ARGS = new Set([
+  "--setup", "setup",
+  "--status", "status",
+  "--version", "-v",
+  "--help", "-h", "help",
+]);
+
+let scriptPath = join(__dirname, "server.js");
+let scriptArgs = args;
+
+if (firstArg === "web") {
+  scriptPath = join(__dirname, "web-server.js");
+  scriptArgs = args.slice(1);
+} else if (firstArg === "http") {
+  scriptPath = join(__dirname, "server-http.js");
+  scriptArgs = args.slice(1);
+} else if (WIZARD_ARGS.has(firstArg)) {
+  scriptPath = join(__dirname, "../scripts/setup-wizard.js");
+  scriptArgs = args;
+}
+
+const child = spawn(process.execPath, [scriptPath, ...scriptArgs], {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("error", (error) => {
+  console.error(`Failed to start ${scriptPath}: ${error.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/src/server-http.js

@@ -30,7 +30,7 @@ import {
 } from "../lib/handlers.js";
 
 const SERVER_NAME = "slack-mcp-server";
-const SERVER_VERSION = "1.2.0";
+const SERVER_VERSION = "1.2.1";
 const PORT = process.env.PORT || 3000;
 
 // Create MCP server

package/src/server.js

@@ -11,7 +11,7 @@
  * - Network error retry with exponential backoff
  * - Background token health monitoring
  *
- * @version 1.2.0
+ * @version 1.2.1
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -19,6 +19,10 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
 import { loadTokens } from "../lib/token-store.js";
@@ -43,12 +47,70 @@ const BACKGROUND_REFRESH_INTERVAL = 4 * 60 * 60 * 1000;
 
 // Package info
 const SERVER_NAME = "slack-mcp-server";
-const SERVER_VERSION = "1.2.0";
+const SERVER_VERSION = "1.2.1";
+
+// MCP Prompts - predefined prompt templates for common Slack operations
+const PROMPTS = [
+  {
+    name: "search-recent",
+    description: "Search workspace for messages from the past week",
+    arguments: [
+      {
+        name: "query",
+        description: "Search terms to look for",
+        required: true
+      }
+    ]
+  },
+  {
+    name: "summarize-channel",
+    description: "Get recent activity from a channel for summarization",
+    arguments: [
+      {
+        name: "channel_id",
+        description: "Channel ID to summarize",
+        required: true
+      },
+      {
+        name: "days",
+        description: "Number of days to look back (default 7)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "find-messages-from",
+    description: "Find all messages from a specific user",
+    arguments: [
+      {
+        name: "username",
+        description: "Username or display name to search for",
+        required: true
+      }
+    ]
+  }
+];
+
+// MCP Resources - data sources the server provides
+const RESOURCES = [
+  {
+    uri: "slack://workspace/info",
+    name: "Workspace Info",
+    description: "Current workspace name, team, and authenticated user",
+    mimeType: "application/json"
+  },
+  {
+    uri: "slack://conversations/list",
+    name: "Conversations",
+    description: "List of available channels and DMs",
+    mimeType: "application/json"
+  }
+];
 
 // Initialize server
 const server = new Server(
   { name: SERVER_NAME, version: SERVER_VERSION },
-  { capabilities: { tools: {} } }
+  { capabilities: { tools: {}, prompts: {}, resources: {} } }
 );
 
 // Register tool list handler
@@ -56,6 +118,103 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: TOOLS
 }));
 
+// Register prompts handlers
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: PROMPTS
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case "search-recent": {
+      const query = args?.query || "";
+      const oneWeekAgo = Math.floor(Date.now() / 1000) - (7 * 24 * 60 * 60);
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Search Slack for "${query}" from the past week. Use the slack_search_messages tool with query: "${query} after:${new Date(oneWeekAgo * 1000).toISOString().split('T')[0]}"`
+            }
+          }
+        ]
+      };
+    }
+    case "summarize-channel": {
+      const channelId = args?.channel_id || "";
+      const days = parseInt(args?.days) || 7;
+      const since = Math.floor(Date.now() / 1000) - (days * 24 * 60 * 60);
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Get the last ${days} days of messages from channel ${channelId} and provide a summary. Use slack_conversations_history with channel_id: "${channelId}" and oldest: "${since}"`
+            }
+          }
+        ]
+      };
+    }
+    case "find-messages-from": {
+      const username = args?.username || "";
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `Find messages from ${username}. Use slack_search_messages with query: "from:@${username}"`
+            }
+          }
+        ]
+      };
+    }
+    default:
+      throw new Error(`Unknown prompt: ${name}`);
+  }
+});
+
+// Register resources handlers
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: RESOURCES
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+
+  switch (uri) {
+    case "slack://workspace/info": {
+      const result = await handleHealthCheck();
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: result.content[0].text
+          }
+        ]
+      };
+    }
+    case "slack://conversations/list": {
+      const result = await handleListConversations({ types: "im,mpim,public_channel,private_channel", limit: 50 });
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: result.content[0].text
+          }
+        ]
+      };
+    }
+    default:
+      throw new Error(`Unknown resource: ${uri}`);
+  }
+});
+
 // Register tool call handler
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
@@ -149,3 +308,11 @@ main().catch(error => {
   console.error("Fatal error:", error);
   process.exit(1);
 });
+
+/**
+ * Smithery sandbox server for capability scanning
+ * Returns a server instance with mock config for tool discovery
+ */
+export function createSandboxServer() {
+  return server;
+}

package/src/web-server.js

@@ -5,7 +5,7 @@
  * Exposes Slack MCP tools as REST endpoints for browser access.
  * Run alongside or instead of the MCP server for web-based access.
  *
- * @version 1.2.0
+ * @version 1.2.1
  */
 
 import express from "express";
@@ -116,7 +116,7 @@ function extractContent(result) {
 app.get("/", (req, res) => {
   res.json({
     name: "Slack Web API Server",
-    version: "1.2.0",
+    version: "1.2.1",
     status: "running",
     endpoints: [
       "GET  /health",
@@ -295,7 +295,7 @@ async function main() {
   app.listen(PORT, '127.0.0.1', () => {
     // Print to stderr to keep logs clean (stdout reserved for JSON in some setups)
     console.error(`\n${"═".repeat(60)}`);
-    console.error(`  Slack Web API Server v1.2.0`);
+    console.error(`  Slack Web API Server v1.2.1`);
     console.error(`${"═".repeat(60)}`);
     console.error(`\n  Dashboard: http://localhost:${PORT}/?key=${API_KEY}`);
     console.error(`\n  API Key:   ${API_KEY}`);