@uniquedivine/mcp-slack 0.0.0-stage → 4.4.3

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.
package/docs/SETUP.md ADDED
@@ -0,0 +1,211 @@
1
+ # Setup Guide
2
+
3
+ ## Hosted (Coming Soon)
4
+
5
+ A hosted version with permanent OAuth tokens, semantic search, and AI summaries is in development at [mcp.revasserlabs.com](https://mcp.revasserlabs.com). The current release is self-hosted only — continue below.
6
+
7
+ ---
8
+
9
+ ## Self-Hosted Setup
10
+
11
+ ### Prerequisites
12
+
13
+ - Bun 1.4.3 or newer
14
+ - Google Chrome (for token extraction on macOS)
15
+ - macOS (for Keychain storage - other platforms use file storage only)
16
+
17
+ ### 1. Install with Bun
18
+
19
+ ```bash
20
+ bun add -g @uniquedivine/mcp-slack@4.4.3
21
+ # or run it without a global install:
22
+ bunx @uniquedivine/mcp-slack@4.4.3 --version
23
+ ```
24
+
25
+ ### 1b. Or Clone the Repository
26
+
27
+ ```bash
28
+ git clone https://github.com/Unique-Divine/jiyuu.git
29
+ cd jiyuu/mcp/slack
30
+ bun install --frozen-lockfile
31
+ ```
32
+
33
+ ### 2. Verify Installation
34
+
35
+ ```bash
36
+ tmpdir="$(mktemp -d)"
37
+ cd "$tmpdir"
38
+ bunx @uniquedivine/mcp-slack@4.4.3 --version
39
+ bunx @uniquedivine/mcp-slack@4.4.3 --help
40
+ bunx @uniquedivine/mcp-slack@4.4.3 --doctor
41
+ ```
42
+
43
+ Expected:
44
+ - `--version` and `--help` succeed.
45
+ - `--doctor` exits with one clear status:
46
+ - `0` ready
47
+ - `1` missing credentials
48
+ - `2` invalid/expired credentials
49
+ - `3` connectivity/runtime issue
50
+ - `--status` is read-only and never performs Chrome extraction.
51
+
52
+ ### 3. Get Slack Tokens
53
+
54
+ **Option A: Setup Wizard**
55
+
56
+ 1. Open Chrome
57
+ 2. Navigate to https://app.slack.com and log in
58
+ 3. Run:
59
+ ```bash
60
+ bunx @uniquedivine/mcp-slack@4.4.3 --setup
61
+ ```
62
+
63
+ **Option B: Automatic Extraction (repo clone workflow)**
64
+
65
+ ```bash
66
+ npm run tokens:auto
67
+ ```
68
+
69
+ **Option C: Manual Extraction**
70
+
71
+ 1. Open https://app.slack.com in Chrome
72
+ 2. Press F12 to open DevTools
73
+ 3. Go to **Application** → **Cookies** → **https://app.slack.com**
74
+ 4. Find the cookie named `d` and copy its value (starts with `xoxd-`)
75
+ 5. Go to **Console** and paste:
76
+ ```javascript
77
+ JSON.parse(localStorage.localConfig_v2).teams[Object.keys(JSON.parse(localStorage.localConfig_v2).teams)[0]].token
78
+ ```
79
+ 6. Copy the result (starts with `xoxc-`)
80
+ 7. Run:
81
+ ```bash
82
+ npm run tokens:refresh
83
+ ```
84
+ And paste both values when prompted.
85
+
86
+ ### 4. Configure Claude Desktop
87
+
88
+ **macOS:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
89
+ **Windows:** Edit `%APPDATA%\Claude\claude_desktop_config.json`
90
+
91
+ ```json
92
+ {
93
+ "mcpServers": {
94
+ "slack": {
95
+ "command": "bunx",
96
+ "args": ["@uniquedivine/mcp-slack@4.4.3"]
97
+ }
98
+ }
99
+ }
100
+ ```
101
+
102
+ Fully restart Claude Desktop (Cmd+Q on macOS, then reopen).
103
+
104
+ **Verify it's working:** Check `~/Library/Logs/Claude/mcp-server-slack.log` (macOS)
105
+
106
+ ### 5. Configure Claude Code (CLI)
107
+
108
+ ```bash
109
+ claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.4.3
110
+ ```
111
+
112
+ Or manually edit `~/.claude.json`:
113
+
114
+ ```json
115
+ {
116
+ "mcpServers": {
117
+ "slack": {
118
+ "type": "stdio",
119
+ "command": "bunx",
120
+ "args": ["@uniquedivine/mcp-slack@4.4.3"]
121
+ }
122
+ }
123
+ }
124
+ ```
125
+
126
+ Claude Code reads tokens from `~/.slack-mcp-tokens.json` automatically.
127
+
128
+ ### 6. Restart Claude
129
+
130
+ The Slack tools will now be available in both Claude Desktop and Claude Code.
131
+
132
+ ## Verification
133
+
134
+ In Claude Code, try:
135
+ ```
136
+ slack_health_check
137
+ ```
138
+
139
+ You should see your username and team name.
140
+
141
+ ## Keep Tokens Fresh While Claude Is Closed (macOS, Optional)
142
+
143
+ The MCP server auto-refreshes tokens every 4 hours while Claude is running. But if you keep Claude closed for a couple weeks, tokens expire silently — your next session opens with `invalid_auth`.
144
+
145
+ A LaunchAgent fixes this. It runs token refresh twice a day regardless of whether Claude is open, as long as Chrome is running with a Slack tab somewhere.
146
+
147
+ Create `~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist`:
148
+
149
+ ```xml
150
+ <?xml version="1.0" encoding="UTF-8"?>
151
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
152
+ <plist version="1.0">
153
+ <dict>
154
+ <key>Label</key>
155
+ <string>com.yourname.slack-token-refresh</string>
156
+ <key>ProgramArguments</key>
157
+ <array>
158
+ <string>/bin/bash</string>
159
+ <string>-c</string>
160
+ <string>exec "$HOME/.bun/bin/bunx" @uniquedivine/mcp-slack@4.4.3 --refresh-tokens</string>
161
+ </array>
162
+ <key>StartCalendarInterval</key>
163
+ <array>
164
+ <dict><key>Hour</key><integer>6</integer><key>Minute</key><integer>17</integer></dict>
165
+ <dict><key>Hour</key><integer>18</integer><key>Minute</key><integer>17</integer></dict>
166
+ </array>
167
+ <key>RunAtLoad</key><true/>
168
+ <key>StandardErrorPath</key><string>/tmp/slack-token-refresh.log</string>
169
+ </dict>
170
+ </plist>
171
+ ```
172
+
173
+ Load it:
174
+
175
+ ```bash
176
+ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist
177
+ ```
178
+
179
+ Check it ran:
180
+
181
+ ```bash
182
+ tail /tmp/slack-token-refresh.log
183
+ ```
184
+
185
+ **Why the absolute `bunx` path:** LaunchAgents start without your shell profile, so `bunx` is not on `PATH`. The `bash -c` wrapper expands `$HOME` to the default Bun install path, `~/.bun/bin/bunx`. If you installed Bun with Homebrew, use `/opt/homebrew/bin/bunx` instead. Run `bunx` directly, not through `node`. Command `bunx` is a native Bun binary, not a JavaScript file. Keep the version pin equal to the one in your MCP client config.
186
+
187
+ **Trade-off:** Chrome must be running for extraction to succeed. If it's not, the LaunchAgent logs "Failed to extract" and tokens stay where they are — which is fine for another 12 hours.
188
+
189
+ ## Troubleshooting
190
+
191
+ ### "No credentials found"
192
+
193
+ Run `bunx @uniquedivine/mcp-slack@4.4.3 --doctor` to confirm diagnostic code, then `bunx @uniquedivine/mcp-slack@4.4.3 --setup` with Slack open in Chrome.
194
+
195
+ ### "invalid_auth" Error
196
+
197
+ Tokens have expired. Run `bunx @uniquedivine/mcp-slack@4.4.3 --doctor` and follow the suggested next action.
198
+
199
+ ### MCP Server Not Loading
200
+
201
+ 1. Check `~/.claude.json` syntax
202
+ 2. Verify JSON syntax in your client's MCP config
203
+ 3. Restart Claude Code
204
+
205
+ ### Chrome Extraction Fails
206
+
207
+ Make sure:
208
+ - Chrome is running (not just in dock)
209
+ - You have a Slack tab open (not the desktop app)
210
+ - You're logged into Slack in that tab
211
+ - In Chrome menu, enable `View > Developer > Allow JavaScript from Apple Events`
@@ -0,0 +1,289 @@
1
+ # Troubleshooting Guide
2
+
3
+ Common issues and their solutions.
4
+
5
+ ---
6
+
7
+ ## Install Flow Sanity Check
8
+
9
+ If first-run setup is failing, validate command resolution in a clean directory:
10
+
11
+ ```bash
12
+ tmpdir="$(mktemp -d)"
13
+ cd "$tmpdir"
14
+ bunx @uniquedivine/mcp-slack --version
15
+ bunx @uniquedivine/mcp-slack --help
16
+ bunx @uniquedivine/mcp-slack --doctor
17
+ ```
18
+
19
+ Expected:
20
+ - `--version` and `--help` exit `0`
21
+ - `--doctor` exits with one of:
22
+ - `0` ready
23
+ - `1` missing credentials
24
+ - `2` invalid/expired credentials
25
+ - `3` connectivity/runtime issue
26
+ - `--status` is read-only and never attempts Chrome extraction.
27
+
28
+ If `--version` fails here, the issue is install/runtime path, not Slack credentials.
29
+
30
+ ---
31
+
32
+ ## Hosted Version
33
+
34
+ The hosted version is live at [mcp.revasserlabs.com](https://mcp.revasserlabs.com). Free tier (no card) ships 2,000 requests/mo + 25 AI tool calls/mo + all 5 workflow profile types. Pro at $19/mo (or $190/yr) unlocks unlimited requests and AI tool calls, permanent OAuth (no 2-week token rotation), email support, and 2 workspaces. Team at $49/mo flat (or $490/yr) covers 5 workspaces with shared workflow profiles and 24h support. Safeguard at $199/mo (waitlist only) adds agent approval gates, the scheduled morning catch-up DM at 8am workspace time, and workspace memory — all *(in development)*.
35
+
36
+ The OSS package keeps the local-machine path. The hosted version adds the AI brain (smart_search, catch_me_up, triage) — these tools also appear in the OSS package as discoverable upgrade stubs that point at the hosted signup.
37
+
38
+ ---
39
+
40
+ ## DMs Not Showing Up
41
+
42
+ **Symptom:** `slack_list_conversations` returns channels but no DMs.
43
+
44
+ **Cause:** Slack's `conversations.list` API doesn't return IMs when using xoxc browser tokens.
45
+
46
+ **Solution:** This is handled automatically. The server discovers DMs by calling `conversations.open` for each user in your workspace. This happens in `lib/handlers.js`.
47
+
48
+ If DMs still don't appear:
49
+ 1. Check you're requesting the right types: `slack_list_conversations types=im,mpim`
50
+ 2. Verify the user exists: `slack_list_users`
51
+
52
+ ---
53
+
54
+ ## Rate Limiting Errors
55
+
56
+ **Symptom:** `{"error":"ratelimited"}` in API responses.
57
+
58
+ **Cause:** Slack limits API calls, especially when listing many users/DMs.
59
+
60
+ **Solution:** The client (`lib/slack-client.js`) implements automatic retry with exponential backoff:
61
+ - First retry: Wait 5 seconds
62
+ - Second retry: Wait 10 seconds
63
+ - Third retry: Wait 15 seconds
64
+
65
+ If you still hit limits, reduce batch sizes:
66
+ ```
67
+ slack_list_conversations limit=50
68
+ ```
69
+
70
+ ---
71
+
72
+ ## Token Expiration
73
+
74
+ **Symptom:** `invalid_auth` or `token_expired` errors.
75
+
76
+ **Cause:** Browser tokens (xoxc/xoxd) expire after 1-2 weeks.
77
+
78
+ **Solution:** The server has 4 layers of token recovery:
79
+
80
+ 1. **Environment variables** - From MCP config (Claude Desktop)
81
+ 2. **Token file** - `~/.slack-mcp-tokens.json`
82
+ 3. **macOS Keychain** - Encrypted persistent storage
83
+ 4. **Chrome auto-extraction** - Fallback when all else fails
84
+
85
+ **To refresh tokens:**
86
+ ```bash
87
+ # Option 1: In Claude Code/Desktop
88
+ slack_refresh_tokens
89
+
90
+ # Option 2: Package setup wizard
91
+ bunx @uniquedivine/mcp-slack --setup
92
+
93
+ # Option 3: Diagnostics check
94
+ bunx @uniquedivine/mcp-slack --doctor
95
+
96
+ # Option 4: Repo CLI
97
+ npm run tokens:auto
98
+
99
+ # Option 5: Manual
100
+ npm run tokens:refresh
101
+ ```
102
+
103
+ ---
104
+
105
+ ## Web Server Issues
106
+
107
+ ### Server Stops When Terminal Closes
108
+
109
+ **Solution:** Use LaunchAgent for persistence:
110
+
111
+ ```bash
112
+ # Create LaunchAgent
113
+ cat > ~/Library/LaunchAgents/com.slack-web-api.plist << 'EOF'
114
+ <?xml version="1.0" encoding="UTF-8"?>
115
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
116
+ <plist version="1.0">
117
+ <dict>
118
+ <key>Label</key>
119
+ <string>com.slack-web-api</string>
120
+ <key>ProgramArguments</key>
121
+ <array>
122
+ <string>/Users/YOUR_USERNAME/.bun/bin/bunx</string>
123
+ <string>@uniquedivine/mcp-slack@4.4.3</string>
124
+ <string>web</string>
125
+ </array>
126
+ <key>RunAtLoad</key>
127
+ <true/>
128
+ <key>KeepAlive</key>
129
+ <true/>
130
+ </dict>
131
+ </plist>
132
+ EOF
133
+
134
+ launchctl load ~/Library/LaunchAgents/com.slack-web-api.plist
135
+ ```
136
+
137
+ ### API Key Invalid
138
+
139
+ The web server generates a unique API key on first run, stored in `~/.slack-mcp-api-key`.
140
+
141
+ The key is printed to the console when you start the server:
142
+ ```
143
+ Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx
144
+ API Key: smcp_xxxxxxxxxxxx
145
+ ```
146
+
147
+ You can also set a custom key:
148
+ ```bash
149
+ SLACK_API_KEY=your-custom-key npm run web
150
+ ```
151
+
152
+ ### Can't Connect to localhost:3000
153
+
154
+ Check if the server is running:
155
+ ```bash
156
+ # Get your API key from ~/.slack-mcp-api-key
157
+ curl http://localhost:3000/health -H "Authorization: Bearer $(cat ~/.slack-mcp-api-key)"
158
+ ```
159
+
160
+ Check LaunchAgent status:
161
+ ```bash
162
+ launchctl list | grep slack-web-api
163
+ ```
164
+
165
+ Check logs:
166
+ ```bash
167
+ cat /tmp/slack-web-api.log
168
+ cat /tmp/slack-web-api.error.log
169
+ ```
170
+
171
+ ### Hosted HTTP `/mcp` Returns 503 or 401
172
+
173
+ If you run `bun src/server-http.js`, `/mcp` is protected by default.
174
+
175
+ `503 http_auth_token_missing` means you did not set:
176
+
177
+ ```bash
178
+ SLACK_MCP_HTTP_AUTH_TOKEN=change-this
179
+ ```
180
+
181
+ `401 unauthorized` means your request is missing or using the wrong bearer token.
182
+
183
+ Example request:
184
+
185
+ ```bash
186
+ curl http://localhost:3000/mcp \
187
+ -H "Authorization: Bearer $SLACK_MCP_HTTP_AUTH_TOKEN" \
188
+ -H "Content-Type: application/json" \
189
+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
190
+ ```
191
+
192
+ For local-only testing (not remote exposure), you can opt out:
193
+
194
+ ```bash
195
+ SLACK_MCP_HTTP_INSECURE=1 bun src/server-http.js
196
+ ```
197
+
198
+ ---
199
+
200
+ ## Claude Desktop Issues
201
+
202
+ ### Slack Tools Not Appearing
203
+
204
+ **Symptom:** Claude Desktop doesn't show Slack tools after adding config.
205
+
206
+ **Solutions:**
207
+
208
+ 1. **Fully restart Claude Desktop:**
209
+ - Cmd+Q (don't just close window)
210
+ - Reopen the app
211
+
212
+ 2. **Check config syntax:**
213
+ ```bash
214
+ cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
215
+ ```
216
+
217
+ 3. **Check MCP logs:**
218
+ ```bash
219
+ cat ~/Library/Logs/Claude/mcp-server-slack.log
220
+ ```
221
+
222
+ 4. **Verify the Bun path:**
223
+ ```bash
224
+ which bunx
225
+ # Use this full path in config
226
+ ```
227
+
228
+ ### MCP Server Crashes on Start
229
+
230
+ **Check the log:**
231
+ ```bash
232
+ tail -50 ~/Library/Logs/Claude/mcp-server-slack.log
233
+ ```
234
+
235
+ **Common causes:**
236
+ - Bun not found (use the full path, such as `~/.bun/bin/bunx` or `/opt/homebrew/bin/bunx`)
237
+ - Missing tokens in env section
238
+ - Invalid JSON syntax in config
239
+
240
+ ---
241
+
242
+ ## Chrome Extraction Fails
243
+
244
+ **Symptom:** `slack_refresh_tokens` returns "Could not extract from Chrome"
245
+
246
+ **Requirements:**
247
+ 1. Google Chrome must be running (not just in Dock)
248
+ 2. Have a Slack tab open at `app.slack.com` (not desktop app)
249
+ 3. Be logged into Slack in that tab
250
+ 4. In Chrome menu, enable `View > Developer > Allow JavaScript from Apple Events`
251
+ 5. Grant accessibility permissions to Terminal/Claude
252
+
253
+ **Check permissions:**
254
+ System Preferences → Privacy & Security → Accessibility → Ensure Terminal is enabled
255
+
256
+ ---
257
+
258
+ ## Why Browser Tokens Instead of Slack App?
259
+
260
+ **Question:** Why not just create a Slack app with proper OAuth?
261
+
262
+ **Answer:** Slack apps cannot access DMs without explicit OAuth authorization for each conversation. This is by design for privacy.
263
+
264
+ Browser tokens (xoxc/xoxd) provide the same access you have in Slack's web interface - everything you can see, Claude can see.
265
+
266
+ **Trade-offs:**
267
+ - ✅ Full access to all your conversations
268
+ - ✅ No per-conversation authorization needed
269
+ - ❌ Tokens expire every 1-2 weeks
270
+ - ❌ Requires Chrome for token extraction
271
+
272
+ ---
273
+
274
+ ## Getting Help
275
+
276
+ 1. Check logs:
277
+ - MCP: `~/Library/Logs/Claude/mcp-server-slack.log`
278
+ - Web: `/tmp/slack-web-api.log`
279
+
280
+ 2. Test manually:
281
+ ```bash
282
+ cd jiyuu/mcp/slack
283
+ bun src/server.js # Should say "running"
284
+ ```
285
+
286
+ 3. Verify tokens:
287
+ ```bash
288
+ npm run tokens:status
289
+ ```
Binary file
@@ -0,0 +1,27 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
2
+ <defs>
3
+ <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
4
+ <stop offset="0%" style="stop-color:#4A154B"/>
5
+ <stop offset="100%" style="stop-color:#3D1140"/>
6
+ </linearGradient>
7
+ </defs>
8
+
9
+ <!-- Background rounded square -->
10
+ <rect x="0" y="0" width="512" height="512" rx="96" ry="96" fill="url(#bg)"/>
11
+
12
+ <!-- Stylized hashtag/channel symbol -->
13
+ <g fill="none" stroke="#FFFFFF" stroke-width="36" stroke-linecap="round">
14
+ <!-- Vertical lines -->
15
+ <line x1="180" y1="140" x2="160" y2="372"/>
16
+ <line x1="352" y1="140" x2="332" y2="372"/>
17
+ <!-- Horizontal lines -->
18
+ <line x1="120" y1="200" x2="392" y2="200"/>
19
+ <line x1="120" y1="312" x2="392" y2="312"/>
20
+ </g>
21
+
22
+ <!-- Slack-colored connection dots (representing MCP bridge) -->
23
+ <circle cx="420" cy="92" r="28" fill="#36C5F0"/>
24
+ <circle cx="92" cy="420" r="28" fill="#2EB67D"/>
25
+ <circle cx="420" cy="420" r="28" fill="#ECB22E"/>
26
+ <circle cx="92" cy="92" r="28" fill="#E01E5A"/>
27
+ </svg>