@jtalk22/slack-mcp 1.1.9 → 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,14 +1,39 @@
-# Slack MCP Server
-
-*Full workspace access via local session mirroring. DMs, threads, and history—no admin approval required.*
-
-[![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)
-
-[![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%3D18.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.html"><img src="docs/assets/icon-512.png" alt="Slack MCP Server" width="80"></a>
+</p>
+
+<h1 align="center">Slack MCP Server</h1>
+
+<p align="center">
+  <em>Give Claude the same Slack access you have.<br>
+  DMs, threads, history—no admin approval.</em>
+</p>
+
+<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">
+  <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>
 
 ---
 
@@ -22,57 +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
-
 ---
 
 ## 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.
 
@@ -113,6 +98,8 @@ flowchart LR
 
 ## Quick Start
 
+**Runtime:** Node.js 20+
+
 ### Option A: npm (Recommended)
 
 ```bash
@@ -139,32 +126,37 @@ docker pull ghcr.io/jtalk22/slack-mcp-server:latest
 
 ### Step 1: Get Your Tokens
 
-#### macOS (Automatic)
+#### Setup Wizard (Recommended)
+
+The interactive setup wizard handles token extraction and validation automatically:
+
 ```bash
-# Have Chrome open with Slack (app.slack.com) logged in
-npx @jtalk22/slack-mcp tokens:auto
-# Or if cloned: npm run tokens:auto
+npx @jtalk22/slack-mcp --setup
 ```
 
-#### Linux/Windows (Manual)
-
-Auto-refresh requires macOS + Chrome. On other platforms, extract tokens manually:
-
-1. Open https://app.slack.com in your browser
-2. Press F12 → Console → Run:
-   ```javascript
-   // Get token
-   JSON.parse(localStorage.localConfig_v2).teams[Object.keys(JSON.parse(localStorage.localConfig_v2).teams)[0]].token
-   ```
-3. Press F12 → Application → Cookies → Copy the `d` cookie value (starts with `xoxd-`)
-4. Create `~/.slack-mcp-tokens.json`:
-   ```json
-   {
-     "SLACK_TOKEN": "xoxc-your-token-here",
-     "SLACK_COOKIE": "xoxd-your-cookie-here",
-     "updated_at": "2024-01-01T00:00:00.000Z"
-   }
-   ```
+- **macOS**: Auto-extracts tokens from Chrome (have Slack open in a tab)
+- **Linux/Windows**: Guides you through manual extraction step-by-step
+- Validates tokens against Slack API before saving
+- Stores tokens securely at `~/.slack-mcp-tokens.json`
+
+#### Check Token Status
+
+```bash
+npx @jtalk22/slack-mcp --status
+```
+
+#### Alternative: Manual Token Scripts
+
+```bash
+# macOS auto-extraction
+npm run tokens:auto
+
+# Manual entry (all platforms)
+npm run tokens:refresh
+
+# Check health
+npm run tokens:status
+```
 
 ### Step 2: Configure Claude
 
@@ -285,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
@@ -298,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/API.md

@@ -199,7 +199,7 @@ Search messages across the workspace.
       "ts": "1767368030.607599",
       "channel": "general",
       "channel_id": "C05GPEVH7J9",
-      "user": "James Lambert",
+      "user": "Example User",
       "text": "Here's the project update...",
       "datetime": "2026-01-02T15:33:50.000Z",
       "permalink": "https://..."

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