@jtalk22/slack-mcp 3.1.0 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/README.md +82 -426
  2. package/docs/API.md +134 -0
  3. package/docs/SETUP.md +64 -29
  4. package/docs/TROUBLESHOOTING.md +28 -0
  5. package/lib/handlers.js +156 -0
  6. package/lib/slack-client.js +11 -3
  7. package/lib/token-store.js +6 -5
  8. package/lib/tools.js +132 -1
  9. package/package.json +15 -8
  10. package/public/index.html +10 -6
  11. package/public/share.html +6 -5
  12. package/scripts/setup-wizard.js +2 -2
  13. package/server.json +8 -2
  14. package/src/server-http.js +16 -1
  15. package/src/server.js +31 -7
  16. package/src/web-server.js +117 -4
  17. package/docs/CLOUDFLARE-BROWSER-TOOLKIT.md +0 -67
  18. package/docs/COMMUNICATION-STYLE.md +0 -66
  19. package/docs/COMPATIBILITY.md +0 -19
  20. package/docs/DEPLOYMENT-MODES.md +0 -55
  21. package/docs/HN-LAUNCH.md +0 -72
  22. package/docs/INDEX.md +0 -41
  23. package/docs/INSTALL-PROOF.md +0 -18
  24. package/docs/LAUNCH-COPY-v3.0.0.md +0 -101
  25. package/docs/LAUNCH-MATRIX.md +0 -22
  26. package/docs/LAUNCH-OPS.md +0 -71
  27. package/docs/RELEASE-HEALTH.md +0 -77
  28. package/docs/SUPPORT-BOUNDARIES.md +0 -49
  29. package/docs/USE_CASE_RECIPES.md +0 -69
  30. package/docs/WEB-API.md +0 -303
  31. package/docs/images/demo-channel-messages.png +0 -0
  32. package/docs/images/demo-channels.png +0 -0
  33. package/docs/images/demo-claude-mobile-360x800.png +0 -0
  34. package/docs/images/demo-claude-mobile-390x844.png +0 -0
  35. package/docs/images/demo-claude-mobile-poster.png +0 -0
  36. package/docs/images/demo-main-mobile-360x800.png +0 -0
  37. package/docs/images/demo-main-mobile-390x844.png +0 -0
  38. package/docs/images/demo-main.png +0 -0
  39. package/docs/images/demo-messages.png +0 -0
  40. package/docs/images/demo-poster.png +0 -0
  41. package/docs/images/demo-sidebar.png +0 -0
  42. package/docs/images/diagram-oauth-comparison.svg +0 -80
  43. package/docs/images/diagram-session-flow.svg +0 -105
  44. package/docs/images/social-preview-v3.png +0 -0
  45. package/docs/images/web-api-mobile-360x800.png +0 -0
  46. package/docs/images/web-api-mobile-390x844.png +0 -0
  47. package/public/demo-claude.html +0 -1974
  48. package/public/demo-video.html +0 -244
  49. package/public/demo.html +0 -1196
  50. package/scripts/build-mobile-demo.js +0 -168
  51. package/scripts/build-release-health-delta.js +0 -201
  52. package/scripts/build-social-preview.js +0 -189
  53. package/scripts/capture-screenshots.js +0 -152
  54. package/scripts/check-owner-attribution.sh +0 -131
  55. package/scripts/check-public-language.sh +0 -26
  56. package/scripts/check-version-parity.js +0 -218
  57. package/scripts/cloudflare-browser-tool.js +0 -237
  58. package/scripts/collect-release-health.js +0 -162
  59. package/scripts/impact-push-v3.js +0 -781
  60. package/scripts/record-demo.js +0 -163
  61. package/scripts/release-preflight.js +0 -247
  62. package/scripts/setup-git-hooks.sh +0 -15
  63. package/scripts/update-github-social-preview.js +0 -208
  64. package/scripts/verify-core.js +0 -159
  65. package/scripts/verify-install-flow.js +0 -193
  66. package/scripts/verify-web.js +0 -273
package/README.md CHANGED
@@ -1,239 +1,60 @@
1
1
  # Slack MCP Server
2
2
 
3
- Session-based Slack MCP for Claude and MCP clients. Local-first `stdio`/`web` with secure-default hosted HTTP in v3.
4
-
5
- ## Install + Verify
6
-
7
- ```bash
8
- npx -y @jtalk22/slack-mcp --setup
9
- npx -y @jtalk22/slack-mcp@latest --version
10
- npx -y @jtalk22/slack-mcp@latest --doctor
11
- npx -y @jtalk22/slack-mcp@latest --status
12
- ```
13
-
14
- [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)
15
-
16
- [![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)
17
-
18
- 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)
19
-
20
- Hosted migration note: `v3.0.0` keeps local `stdio`/`web` flows unchanged; hosted `/mcp` requires `SLACK_MCP_HTTP_AUTH_TOKEN` and `SLACK_MCP_HTTP_ALLOWED_ORIGINS`.
21
-
22
- Maintainer/operator: `jtalk22` (`james@revasser.nyc`)
23
- Release: [`v3.1.0`](https://github.com/jtalk22/slack-mcp-server/releases/tag/v3.1.0) · Notes: [v3.1.0 notes](https://github.com/jtalk22/slack-mcp-server/blob/main/.github/v3.1.0-release-notes.md) · Support: [deployment intake](https://github.com/jtalk22/slack-mcp-server/issues/new?template=deployment-intake.md)
24
-
25
- 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)
26
-
27
- ## v3.0.0 at a Glance
28
-
29
- - Hosted HTTP `/mcp` now requires bearer auth by default (`SLACK_MCP_HTTP_AUTH_TOKEN`).
30
- - Hosted HTTP CORS now uses explicit allowlisting (`SLACK_MCP_HTTP_ALLOWED_ORIGINS`).
31
- - Local-first paths (`stdio`, `web`) stay compatible.
32
- - MCP tool names stay stable (no renames/removals).
33
-
34
- ## Slack MCP Cloud
35
-
36
- Skip all setup. One URL, 13 tools, encrypted token storage, managed on Cloudflare edge.
3
+ [![npm version](https://img.shields.io/npm/v/@jtalk22/slack-mcp)](https://www.npmjs.com/package/@jtalk22/slack-mcp)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@jtalk22/slack-mcp)](https://www.npmjs.com/package/@jtalk22/slack-mcp)
5
+ [![MCP Registry](https://img.shields.io/badge/MCP_Registry-v3.2.0-blue)](https://registry.modelcontextprotocol.io)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
7
+
8
+ Give Claude your Slack. 16 tools — read channels, search messages, send replies, react, manage unreads. Self-host free or Cloud from $19/mo.
9
+
10
+ ## Tools
11
+
12
+ | Tool | Description | Safety |
13
+ |------|-------------|--------|
14
+ | `slack_health_check` | Verify token validity and workspace info | read-only |
15
+ | `slack_token_status` | Token age, health, and cache stats | read-only |
16
+ | `slack_refresh_tokens` | Auto-extract fresh tokens from Chrome | read-only* |
17
+ | `slack_list_conversations` | List DMs and channels | read-only |
18
+ | `slack_conversations_history` | Get messages from a channel or DM | read-only |
19
+ | `slack_get_full_conversation` | Export full history with threads | read-only |
20
+ | `slack_search_messages` | Search across workspace | read-only |
21
+ | `slack_get_thread` | Get thread replies | read-only |
22
+ | `slack_users_info` | Get user details | read-only |
23
+ | `slack_list_users` | List workspace users (paginated, 500+) | read-only |
24
+ | `slack_users_search` | Search users by name, display name, or email | read-only |
25
+ | `slack_conversations_unreads` | Get channels/DMs with unread messages | read-only |
26
+ | `slack_send_message` | Send a message to any conversation | **destructive** |
27
+ | `slack_add_reaction` | Add an emoji reaction to a message | **destructive** |
28
+ | `slack_remove_reaction` | Remove an emoji reaction from a message | **destructive** |
29
+ | `slack_conversations_mark` | Mark a conversation as read | **destructive** |
30
+
31
+ All tools carry [MCP safety annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations): 12 read-only (`readOnlyHint: true`), 4 write-path (`destructiveHint: true`). Only `slack_send_message` is non-idempotent.
32
+
33
+ \* `slack_refresh_tokens` modifies local token file only — no external Slack state.
34
+
35
+ ## Cloud (Recommended)
36
+
37
+ Skip all local setup. Paste one URL into Claude and get 16 Slack tools in 60 seconds. Encrypted token storage on Cloudflare's edge (300+ PoPs). OAuth 2.1 with PKCE S256.
37
38
 
38
39
  | Plan | Price | Includes |
39
40
  |------|-------|----------|
40
- | Solo | $19/mo | 10 standard tools, encrypted storage, 5K requests/mo |
41
- | Team | $49/mo | 13 tools (incl. compound intelligence), 3 workspaces, 25K requests/mo |
42
-
43
- [Get started](https://jtalk22.github.io/slack-mcp-server/cloud.html) — no Docker, no tokens, no admin approval.
44
-
45
- ## 60-Second Hosted Migration
46
-
47
- ```bash
48
- export SLACK_TOKEN=xoxc-...
49
- export SLACK_COOKIE=xoxd-...
50
- export SLACK_MCP_HTTP_AUTH_TOKEN=change-this
51
- export SLACK_MCP_HTTP_ALLOWED_ORIGINS=https://claude.ai
52
- node src/server-http.js
53
- ```
54
-
55
- Request with:
56
-
57
- ```bash
58
- Authorization: Bearer <SLACK_MCP_HTTP_AUTH_TOKEN>
59
- ```
60
-
61
- Emergency local fallback only:
62
-
63
- ```bash
64
- SLACK_MCP_HTTP_INSECURE=1 node src/server-http.js
65
- ```
66
-
67
- For guided hosted rollout requirements, open: [deployment intake](https://github.com/jtalk22/slack-mcp-server/issues/new?template=deployment-intake.md)
68
-
69
- ### Why This Exists
70
-
71
- I built this because I was working with someone to help me manage a complex workload, and we kept hitting walls. They needed context from my messages—"what did X say about Y?"—and standard app/OAuth flows were too constrained for that workflow.
72
-
73
- Screenshotting messages is not a workflow.
74
-
75
- This server bridges the gap. It creates a secure, local bridge between Claude and your Slack web session. It gives your MCP client the same access **you** already have in the browser—search history, summarize threads, and retrieve prior context—without fighting the platform.
76
-
77
- ![Slack MCP Server Web UI](https://jtalk22.github.io/slack-mcp-server/docs/images/demo-main.png)
78
-
79
- ---
80
-
81
- ## Architecture: Local Session Mirroring
82
-
83
- 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.
84
-
85
- ![Session Mirroring Flow](https://jtalk22.github.io/slack-mcp-server/docs/images/diagram-session-flow.svg)
86
-
87
- ### Why Not OAuth?
88
-
89
- ![OAuth vs Session Mirroring](https://jtalk22.github.io/slack-mcp-server/docs/images/diagram-oauth-comparison.svg)
41
+ | Solo | $19/mo | 16 standard tools, AES-256-GCM encrypted storage, 5K requests/mo |
42
+ | Team | $49/mo | 16 standard + 3 AI compound tools, 3 workspaces, 25K requests/mo |
90
43
 
91
- **Trade-off:** Session tokens expire every 1-2 weeks. Auto-refresh (macOS) or manual update keeps things running.
44
+ [Get Started](https://jtalk22.github.io/slack-mcp-server/cloud.html) · [Privacy Policy](https://jtalk22.github.io/slack-mcp-server/privacy.html)
92
45
 
93
- ---
94
-
95
- ## Features
96
-
97
- ### Core Capabilities
98
- - **Read Any Message** - DMs, private channels, public channels
99
- - **Full Export** - Conversations with threads and resolved usernames
100
- - **Search** - Query across your entire workspace
101
- - **Send Messages** - DMs or channels, with thread support
102
- - **User Directory** - List and search 500+ users with pagination
103
-
104
- ### Stability
105
- - **Auto Token Refresh** - Extracts fresh tokens from Chrome automatically *(macOS only)*
106
- - **Atomic Writes** - File operations use temp-file-then-rename to prevent corruption
107
- - **Zombie Protection** - Background timers use `unref()` for clean process exit
108
- - **Race Condition Safety** - Mutex locks prevent concurrent token extraction
109
- - **Rate Limit Handling** - Exponential backoff with jitter
110
-
111
- ### Tools
112
- | Tool | Description |
113
- |------|-------------|
114
- | `slack_health_check` | Verify token validity and workspace info |
115
- | `slack_token_status` | Detailed token age, health, and cache stats |
116
- | `slack_refresh_tokens` | Auto-extract fresh tokens from Chrome |
117
- | `slack_list_conversations` | List DMs/channels (with lazy discovery cache) |
118
- | `slack_conversations_history` | Get messages from a channel or DM |
119
- | `slack_get_full_conversation` | Export full history with threads |
120
- | `slack_search_messages` | Search across workspace |
121
- | `slack_send_message` | Send a message to any conversation |
122
- | `slack_get_thread` | Get thread replies |
123
- | `slack_users_info` | Get user details |
124
- | `slack_list_users` | List workspace users (paginated, 500+ supported) |
125
-
126
- ---
127
-
128
- ## Quick Start
46
+ ## Install (Self-Hosted)
129
47
 
130
48
  **Runtime:** Node.js 20+
131
49
 
132
- ### 30-Second Compatibility Check
133
-
134
- ```bash
135
- npx -y @jtalk22/slack-mcp --setup
136
- npx -y @jtalk22/slack-mcp --doctor
137
- npx -y @jtalk22/slack-mcp --status
138
- ```
139
-
140
- Expected:
141
- - `--setup` launches the interactive wizard
142
- - `--doctor` returns one clear next action with exit code:
143
- - `0` ready
144
- - `1` missing credentials
145
- - `2` invalid/expired credentials
146
- - `3` connectivity/runtime issue
147
- - `--status` is read-only and non-mutating
148
-
149
- Command reference: [HN launch kit](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/HN-LAUNCH.md)
150
-
151
- ### Known Working Clients
152
-
153
- - Claude Desktop (macOS/Windows/Linux)
154
- - Claude Code CLI
155
- - Local browser mode (`web`)
156
- - Hosted Node runtime (`http`)
157
- - Cloudflare Worker / Smithery transport
158
-
159
- Compatibility matrix: [compatibility matrix](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/COMPATIBILITY.md)
160
-
161
- ### Option A: npm (Recommended)
162
-
163
- ```bash
164
- npm install -g @jtalk22/slack-mcp
165
- ```
166
-
167
- ### Option B: Clone Repository
168
-
169
- ```bash
170
- git clone https://github.com/jtalk22/slack-mcp-server.git
171
- cd slack-mcp-server
172
- npm install
173
- ```
174
-
175
- ### Option C: Docker
176
-
177
- ```bash
178
- docker pull ghcr.io/jtalk22/slack-mcp-server:latest
179
- ```
180
-
181
- ### Install Sanity (Clean Temp Directory)
182
-
183
- ```bash
184
- tmpdir="$(mktemp -d)"
185
- cd "$tmpdir"
186
- npx -y @jtalk22/slack-mcp --version
187
- npx -y @jtalk22/slack-mcp --help
188
- npx -y @jtalk22/slack-mcp --status
189
- ```
190
-
191
- Expected:
192
- - `--version` and `--help` exit `0`
193
- - `--status` exits non-zero until credentials are configured
194
- - `--status` is read-only and never attempts Chrome extraction
195
-
196
- ---
197
-
198
- ## Configuration
199
-
200
- ### Step 1: Get Your Tokens
201
-
202
- #### Setup Wizard (Recommended)
203
-
204
- The interactive setup wizard handles token extraction and validation automatically:
205
-
206
50
  ```bash
207
51
  npx -y @jtalk22/slack-mcp --setup
208
52
  ```
209
53
 
210
- - **macOS**: Auto-extracts tokens from Chrome (have Slack open in a tab)
211
- - **Linux/Windows**: Guides you through manual extraction step-by-step
212
- - Validates tokens against Slack API before saving
213
- - Stores tokens securely at `~/.slack-mcp-tokens.json`
214
-
215
- #### Check Token Status
216
-
217
- ```bash
218
- npx -y @jtalk22/slack-mcp --status
219
- ```
220
-
221
- #### Alternative: Manual Token Scripts
222
-
223
- ```bash
224
- # macOS auto-extraction
225
- npm run tokens:auto
54
+ The setup wizard handles token extraction and validation automatically.
226
55
 
227
- # Manual entry (all platforms)
228
- npm run tokens:refresh
229
-
230
- # Check health
231
- npm run tokens:status
232
- ```
233
-
234
- ### Step 2: Configure Claude
235
-
236
- #### Claude Desktop (macOS)
56
+ <details>
57
+ <summary><strong>Claude Desktop (macOS)</strong></summary>
237
58
 
238
59
  Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
239
60
 
@@ -248,7 +69,10 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
248
69
  }
249
70
  ```
250
71
 
251
- #### Claude Desktop (Windows)
72
+ </details>
73
+
74
+ <details>
75
+ <summary><strong>Claude Desktop (Windows/Linux)</strong></summary>
252
76
 
253
77
  Edit `%APPDATA%\Claude\claude_desktop_config.json`:
254
78
 
@@ -267,9 +91,12 @@ Edit `%APPDATA%\Claude\claude_desktop_config.json`:
267
91
  }
268
92
  ```
269
93
 
270
- > **Note:** Windows/Linux users must provide tokens via `env` since auto-refresh is macOS-only.
94
+ > Windows/Linux users must provide tokens via `env` since auto-refresh is macOS-only.
95
+
96
+ </details>
271
97
 
272
- #### Claude Code (CLI)
98
+ <details>
99
+ <summary><strong>Claude Code CLI</strong></summary>
273
100
 
274
101
  Add to `~/.claude.json`:
275
102
 
@@ -285,9 +112,14 @@ Add to `~/.claude.json`:
285
112
  }
286
113
  ```
287
114
 
288
- Claude Code reads tokens from `~/.slack-mcp-tokens.json` automatically.
115
+ </details>
289
116
 
290
- #### Docker Configuration
117
+ <details>
118
+ <summary><strong>Docker</strong></summary>
119
+
120
+ ```bash
121
+ docker pull ghcr.io/jtalk22/slack-mcp-server:latest
122
+ ```
291
123
 
292
124
  ```json
293
125
  {
@@ -302,237 +134,61 @@ Claude Code reads tokens from `~/.slack-mcp-tokens.json` automatically.
302
134
  }
303
135
  ```
304
136
 
305
- ### Step 3: Restart Claude
306
-
307
- Fully quit and reopen Claude. The Slack tools will appear.
308
-
309
- ---
310
-
311
- ## Architecture
312
-
313
- ### Token Persistence (4 Layers)
314
-
315
- ```
316
- Priority 1: Environment Variables (SLACK_TOKEN, SLACK_COOKIE)
317
- ↓ fallback
318
- Priority 2: Token File (~/.slack-mcp-tokens.json)
319
- ↓ fallback
320
- Priority 3: macOS Keychain (encrypted)
321
- ↓ fallback
322
- Priority 4: Chrome Auto-Extraction (macOS only)
323
- ```
324
-
325
- ### Stability Features
326
-
327
- #### Atomic Writes
328
- All file operations (tokens, DM cache) use atomic writes:
329
- ```
330
- Write to temp file → chmod 600 → rename to target
331
- ```
332
- This prevents JSON corruption if the process is killed mid-write.
333
-
334
- #### Zombie Process Protection
335
- Background refresh timers use `unref()`:
336
- ```javascript
337
- const timer = setInterval(refreshTokens, 4 * 60 * 60 * 1000);
338
- timer.unref(); // Process can exit even if timer is pending
339
- ```
340
- When Claude closes the MCP connection, the server exits cleanly.
341
-
342
- #### Race Condition Prevention
343
- A mutex lock prevents concurrent Chrome extractions:
344
- ```javascript
345
- if (refreshInProgress) return null; // Skip if already refreshing
346
- refreshInProgress = true;
347
- try { return extractFromChromeInternal(); }
348
- finally { refreshInProgress = false; }
349
- ```
350
-
351
- ---
352
-
353
- ## Web UI (optional browser/local fallback)
354
-
355
- Claude now supports remote MCP connectors on paid plans. For claude.ai, the preferred path is adding a remote connector in Settings -> Connectors.
356
-
357
- Reference:
358
- - https://support.anthropic.com/en/articles/11995447-connectors-in-claude
359
- - https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp
360
-
361
- Use this Web UI when you want a local localhost dashboard, REST access, or a fallback workflow without remote connector hosting:
362
-
363
- ```bash
364
- npm run web
365
- # Or: npx -y @jtalk22/slack-mcp web
366
- ```
367
-
368
- **Magic Link:** The console prints a one-click URL with the API key embedded:
369
-
370
- ```
371
- ════════════════════════════════════════════════════════════
372
- Slack Web API Server v3.0.0
373
- ════════════════════════════════════════════════════════════
374
-
375
- Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx
376
- ```
377
-
378
- Just click the link - no copy-paste needed. The key is saved to your browser and stripped from the URL for security.
379
-
380
- <details>
381
- <summary><strong>Screenshots</strong></summary>
382
-
383
- | DMs View | Channels View |
384
- |----------|---------------|
385
- | ![DMs](https://jtalk22.github.io/slack-mcp-server/docs/images/demo-main.png) | ![Channels](https://jtalk22.github.io/slack-mcp-server/docs/images/demo-channels.png) |
386
-
387
137
  </details>
388
138
 
389
- ---
139
+ Restart Claude after configuration. Full setup guide: [docs/SETUP.md](docs/SETUP.md)
390
140
 
391
- ## Hosted HTTP Mode (Secure Defaults)
141
+ ## Hosted HTTP Mode
392
142
 
393
- Use this mode only when you need a remote MCP endpoint:
143
+ For remote MCP endpoints (Cloudflare Worker, VPS, etc.):
394
144
 
395
145
  ```bash
396
- SLACK_TOKEN=xoxc-...
397
- SLACK_COOKIE=xoxd-...
398
- SLACK_MCP_HTTP_AUTH_TOKEN=change-this
399
- SLACK_MCP_HTTP_ALLOWED_ORIGINS=https://claude.ai
146
+ SLACK_TOKEN=xoxc-... \
147
+ SLACK_COOKIE=xoxd-... \
148
+ SLACK_MCP_HTTP_AUTH_TOKEN=change-this \
149
+ SLACK_MCP_HTTP_ALLOWED_ORIGINS=https://claude.ai \
400
150
  node src/server-http.js
401
151
  ```
402
152
 
403
- Behavior:
404
- - `/mcp` requires `Authorization: Bearer <SLACK_MCP_HTTP_AUTH_TOKEN>` by default.
405
- - Cross-origin browser calls are denied unless origin is listed in `SLACK_MCP_HTTP_ALLOWED_ORIGINS`.
406
- - For local testing only, you can opt out with `SLACK_MCP_HTTP_INSECURE=1`.
407
-
408
- ---
409
-
410
- ## Operations Guides
411
-
412
- - [Docs Index](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/INDEX.md) - One-click index for setup, API, troubleshooting, deployment, and support docs
413
- - [Deployment Modes](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md) - Choose the right operating model (`stdio`, `web`, hosted HTTP, Smithery/Worker)
414
- - [Use Case Recipes](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/USE_CASE_RECIPES.md) - 12 copy/paste prompts mapped to current tool contracts
415
- - [Support Boundaries](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/SUPPORT-BOUNDARIES.md) - Scope, response targets, and solo-maintainer capacity limits
416
- - [Release Health](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/RELEASE-HEALTH.md) - Track setup reliability and support-load targets through this release cycle
417
-
418
- If you're evaluating team rollout, start with [Deployment Modes](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md) before exposing remote endpoints.
419
-
420
- ---
421
-
422
- ## Getting Help Fast
423
-
424
- 1. Run:
425
- ```bash
426
- npx -y @jtalk22/slack-mcp --version
427
- npx -y @jtalk22/slack-mcp --doctor
428
- ```
429
- 2. If setup fails, run:
430
- ```bash
431
- npx -y @jtalk22/slack-mcp --setup
432
- ```
433
- 3. Open an issue with full environment details:
434
- - [Bug Report Template](https://github.com/jtalk22/slack-mcp-server/issues/new?template=bug_report.md)
435
- - [Deployment Intake Template](https://github.com/jtalk22/slack-mcp-server/issues/new?template=deployment-intake.md)
436
- 4. For guided hosted rollout support:
437
- - [GitHub Discussions](https://github.com/jtalk22/slack-mcp-server/discussions)
438
- 5. Check scope and response targets:
439
- - [Support Boundaries](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/SUPPORT-BOUNDARIES.md)
440
- - [Troubleshooting Guide](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/TROUBLESHOOTING.md)
441
-
442
- ---
153
+ Details: [docs/DEPLOYMENT-MODES.md](docs/DEPLOYMENT-MODES.md)
443
154
 
444
155
  ## Troubleshooting
445
156
 
446
- ### Tokens Expired
447
- ```bash
448
- # macOS: Auto-refresh from Chrome
449
- slack_refresh_tokens # In Claude
450
- # Or: npm run tokens:auto
451
-
452
- # Package setup wizard
453
- npx -y @jtalk22/slack-mcp --setup
454
-
455
- # Linux/Windows: Manual update
456
- # Edit ~/.slack-mcp-tokens.json with fresh values
457
- ```
458
-
459
- ### DMs Not Showing
460
- Use `discover_dms: true` to force discovery:
461
- ```
462
- slack_list_conversations with discover_dms=true
463
- ```
464
- This caches DM channel IDs for 24 hours.
465
-
466
- ### Chrome Extraction Fails
467
- - Chrome must be **running** (not minimized to Dock)
468
- - Slack tab must be open at `app.slack.com`
469
- - You must be logged in
470
- - In Chrome menu, enable `View > Developer > Allow JavaScript from Apple Events`
157
+ **Tokens expired:** Run `npx -y @jtalk22/slack-mcp --setup` or use `slack_refresh_tokens` in Claude (macOS).
471
158
 
472
- ### Claude Desktop Not Seeing Tools
473
- 1. Verify JSON syntax in config file
474
- 2. Check logs: `~/Library/Logs/Claude/mcp*.log`
475
- 3. Fully restart Claude (Cmd+Q, then reopen)
159
+ **DMs not showing:** Use `slack_list_conversations` with `discover_dms=true` to force discovery.
476
160
 
477
- ---
161
+ **Claude not seeing tools:** Verify JSON syntax in config, check logs at `~/Library/Logs/Claude/mcp*.log`, fully restart Claude (Cmd+Q).
478
162
 
479
- ## Project Structure
163
+ More: [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
480
164
 
481
- ```
482
- slack-mcp-server/
483
- ├── src/
484
- │ ├── server.js # MCP server (stdio transport)
485
- │ └── web-server.js # REST API + Web UI
486
- ├── lib/
487
- │ ├── token-store.js # 4-layer persistence + atomic writes
488
- │ ├── slack-client.js # API client, LRU cache, retry logic
489
- │ ├── tools.js # MCP tool definitions
490
- │ └── handlers.js # Tool implementations
491
- ├── public/
492
- │ ├── index.html # Web UI
493
- │ └── demo.html # Interactive demo
494
- └── scripts/
495
- └── token-cli.js # Token management CLI
496
- ```
165
+ ## Docs
497
166
 
498
- ---
167
+ - [Setup Guide](docs/SETUP.md) — Token extraction and configuration
168
+ - [API Reference](docs/API.md) — All 16 tools with parameters and examples
169
+ - [Deployment Modes](docs/DEPLOYMENT-MODES.md) — stdio, web, hosted HTTP, Cloudflare Worker
170
+ - [Use Case Recipes](docs/USE_CASE_RECIPES.md) — 12 copy-paste prompts
171
+ - [Troubleshooting](docs/TROUBLESHOOTING.md) — Common issues and fixes
172
+ - [Compatibility](docs/COMPATIBILITY.md) — Client compatibility matrix
173
+ - [Support Boundaries](docs/SUPPORT-BOUNDARIES.md) — Scope and response targets
174
+ - [Docs Index](docs/INDEX.md) — Full documentation index
499
175
 
500
176
  ## Security
501
177
 
502
178
  - Token files stored with `chmod 600` (owner-only)
503
179
  - macOS Keychain provides encrypted backup
504
180
  - Web server binds to localhost only
505
- - Never commit tokens to version control
506
181
  - API keys are cryptographically random (`crypto.randomBytes`)
507
-
508
- ---
509
-
510
- ## Platform Support
511
-
512
- | Feature | macOS | Linux | Windows |
513
- |---------|-------|-------|---------|
514
- | MCP Server | Yes | Yes | Yes |
515
- | Token File | Yes | Yes | Yes |
516
- | Auto-Refresh from Chrome | Yes | No | No |
517
- | Keychain Storage | Yes | No | No |
518
- | Web UI | Yes | Yes | Yes |
519
-
520
- ---
182
+ - See [SECURITY.md](SECURITY.md) for vulnerability reporting
521
183
 
522
184
  ## Contributing
523
185
 
524
186
  PRs welcome. Run `node --check` on modified files before submitting.
525
187
 
526
- If this project saves you setup time, consider starring the repository.
527
-
528
- ---
529
-
530
188
  ## License
531
189
 
532
- MIT - See LICENSE
533
-
534
- ---
190
+ MIT See [LICENSE](LICENSE)
535
191
 
536
192
  ## Disclaimer
537
193
 
538
- This project uses unofficial Slack APIs. Use at your own risk. Not affiliated with or endorsed by Slack Technologies.
194
+ This project accesses Slack's Web API using browser session credentials. It is not affiliated with or endorsed by Slack Technologies, Inc. Slack workspace administrators should review their acceptable use policies.