@uniquedivine/mcp-slack 4.5.1 → 4.5.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 CHANGED
@@ -1,28 +1,24 @@
1
1
  # Setup Guide
2
2
 
3
- ## Hosted (Coming Soon)
3
+ This guide covers `@uniquedivine/mcp-slack`, maintained by
4
+ [Unique Divine](https://uniquedivine.com). The [README](../README.md) has the
5
+ short version.
4
6
 
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.
7
+ ## Prerequisites
6
8
 
7
- ---
9
+ - Bun 1.4.3 or newer.
10
+ - A Slack account signed in at `app.slack.com` in a browser.
11
+ - On macOS only: Google Chrome, for automatic token extraction and refresh.
12
+ The server also stores tokens in the macOS Keychain. Other platforms use the
13
+ token file.
8
14
 
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
15
+ ## 1. Install
18
16
 
19
17
  ```bash
20
- bun add -g @uniquedivine/mcp-slack@4.5.1
21
- # or run it without a global install:
22
- bunx @uniquedivine/mcp-slack@4.5.1 --version
18
+ bunx @uniquedivine/mcp-slack@4.5.3 --version
23
19
  ```
24
20
 
25
- ### 1b. Or Clone the Repository
21
+ To work from source instead:
26
22
 
27
23
  ```bash
28
24
  git clone https://github.com/Unique-Divine/jiyuu.git
@@ -30,121 +26,104 @@ cd jiyuu/mcp/slack
30
26
  bun install --frozen-lockfile
31
27
  ```
32
28
 
33
- ### 2. Verify Installation
29
+ ## 2. Verify the Install
30
+
31
+ Run these in an empty directory so that a local checkout can't shadow the
32
+ package:
34
33
 
35
34
  ```bash
36
- tmpdir="$(mktemp -d)"
37
- cd "$tmpdir"
38
- bunx @uniquedivine/mcp-slack@4.5.1 --version
39
- bunx @uniquedivine/mcp-slack@4.5.1 --help
40
- bunx @uniquedivine/mcp-slack@4.5.1 --doctor
35
+ cd "$(mktemp -d)"
36
+ bunx @uniquedivine/mcp-slack@4.5.3 --version
37
+ bunx @uniquedivine/mcp-slack@4.5.3 --help
38
+ bunx @uniquedivine/mcp-slack@4.5.3 --doctor
41
39
  ```
42
40
 
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.
41
+ Flags `--version` and `--help` exit `0`. Flag `--doctor` exits with one code:
51
42
 
52
- ### 3. Get Slack Tokens
43
+ | Code | Meaning |
44
+ |------|---------|
45
+ | `0` | Ready |
46
+ | `1` | Missing credentials |
47
+ | `2` | Invalid or expired credentials |
48
+ | `3` | Connectivity or runtime issue |
53
49
 
54
- **Option A: Setup Wizard**
50
+ Flag `--status` is read-only and never runs Chrome extraction.
55
51
 
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.5.1 --setup
61
- ```
52
+ ## 3. Get Slack Tokens
62
53
 
63
- **Option B: Automatic Extraction (repo clone workflow)**
54
+ Run the setup wizard:
64
55
 
65
56
  ```bash
66
- npm run tokens:auto
57
+ bunx @uniquedivine/mcp-slack@4.5.3 --setup
67
58
  ```
68
59
 
69
- **Option C: Manual Extraction**
60
+ On macOS, the wizard reads the tokens from Chrome when Slack is open in a
61
+ Chrome tab. On other platforms, it asks you to paste them. From a source
62
+ checkout, `bun run tokens:auto` runs the macOS extraction and
63
+ `bun run tokens:refresh` prompts for manual values.
64
+
65
+ ### Manual Extraction
66
+
67
+ 1. Open <https://app.slack.com> in a browser and sign in.
68
+ 2. Open DevTools with F12.
69
+ 3. Under **Application** > **Cookies** > `https://app.slack.com`, copy the
70
+ value of cookie `d`. It starts with `xoxd-`.
71
+ 4. In the **Console** tab, run:
70
72
 
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
73
  ```javascript
77
74
  JSON.parse(localStorage.localConfig_v2).teams[Object.keys(JSON.parse(localStorage.localConfig_v2).teams)[0]].token
78
75
  ```
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
76
 
91
- ```json
92
- {
93
- "mcpServers": {
94
- "slack": {
95
- "command": "bunx",
96
- "args": ["@uniquedivine/mcp-slack@4.5.1"]
97
- }
98
- }
99
- }
100
- ```
77
+ 5. Copy the result. It starts with `xoxc-`.
78
+ 6. Paste both values into `--setup`, or set environment variables
79
+ `SLACK_TOKEN` and `SLACK_COOKIE`.
101
80
 
102
- Fully restart Claude Desktop (Cmd+Q on macOS, then reopen).
81
+ Slack rotates these tokens every one to two weeks. Off macOS, repeat these
82
+ steps when a tool returns `invalid_auth` or `slack_auth_expired`.
103
83
 
104
- **Verify it's working:** Check `~/Library/Logs/Claude/mcp-server-slack.log` (macOS)
84
+ ## 4. Configure a Client
105
85
 
106
- ### 5. Configure Claude Code (CLI)
86
+ Claude Code:
107
87
 
108
88
  ```bash
109
- claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.1
89
+ claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.3
110
90
  ```
111
91
 
112
- Or manually edit `~/.claude.json`:
92
+ Claude Desktop reads file
93
+ `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and
94
+ `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
113
95
 
114
96
  ```json
115
97
  {
116
98
  "mcpServers": {
117
99
  "slack": {
118
- "type": "stdio",
119
100
  "command": "bunx",
120
- "args": ["@uniquedivine/mcp-slack@4.5.1"]
101
+ "args": ["@uniquedivine/mcp-slack@4.5.3"]
121
102
  }
122
103
  }
123
104
  }
124
105
  ```
125
106
 
126
- Claude Code reads tokens from `~/.slack-mcp-tokens.json` automatically.
107
+ Quit Claude Desktop fully and reopen it. On macOS, its log is file
108
+ `~/Library/Logs/Claude/mcp-server-slack.log`. The [README](../README.md#install)
109
+ lists the Codex and Cursor entries.
127
110
 
128
- ### 6. Restart Claude
111
+ ## 5. Verify the Connection
129
112
 
130
- The Slack tools will now be available in both Claude Desktop and Claude Code.
113
+ Call tool `slack_health_check`. It returns your user and team names.
131
114
 
132
- ## Verification
115
+ ## Keep Tokens Fresh While the Client Is Closed (macOS)
133
116
 
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`.
117
+ While it runs on macOS, the server checks token health every 4 hours. It reads
118
+ new tokens from Chrome only when the token file is more than 10 days old, or
119
+ when a read or send fails with `invalid_auth` or `token_expired`; edit and
120
+ delete tools don't retry. Neither path helps when `SLACK_TOKEN` and
121
+ `SLACK_COOKIE` are set, because those win over the token file. If no client
122
+ runs the server for a week or two, the tokens can expire before either case
123
+ happens. A LaunchAgent can run the refresh twice a day
124
+ whenever Chrome is open with a Slack tab.
144
125
 
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`:
126
+ Create file `~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist`:
148
127
 
149
128
  ```xml
150
129
  <?xml version="1.0" encoding="UTF-8"?>
@@ -157,7 +136,7 @@ Create `~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist`:
157
136
  <array>
158
137
  <string>/bin/bash</string>
159
138
  <string>-c</string>
160
- <string>exec "$HOME/.bun/bin/bunx" @uniquedivine/mcp-slack@4.5.1 --refresh-tokens</string>
139
+ <string>exec "$HOME/.bun/bin/bunx" @uniquedivine/mcp-slack@4.5.3 --refresh-tokens</string>
161
140
  </array>
162
141
  <key>StartCalendarInterval</key>
163
142
  <array>
@@ -170,42 +149,17 @@ Create `~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist`:
170
149
  </plist>
171
150
  ```
172
151
 
173
- Load it:
152
+ Load it and check the log:
174
153
 
175
154
  ```bash
176
155
  launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist
177
- ```
178
-
179
- Check it ran:
180
-
181
- ```bash
182
156
  tail /tmp/slack-token-refresh.log
183
157
  ```
184
158
 
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.5.1 --doctor` to confirm diagnostic code, then `bunx @uniquedivine/mcp-slack@4.5.1 --setup` with Slack open in Chrome.
194
-
195
- ### "invalid_auth" Error
196
-
197
- Tokens have expired. Run `bunx @uniquedivine/mcp-slack@4.5.1 --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
159
+ LaunchAgents start without your shell profile, so the plist calls `bunx` by
160
+ its absolute path. With a Homebrew Bun install, use `/opt/homebrew/bin/bunx`.
161
+ Keep the version pin equal to the one in your client configuration. If Chrome
162
+ isn't running, the log shows "Failed to extract" and the tokens stay as they
163
+ were.
206
164
 
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`
165
+ For problems, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
@@ -1,186 +1,103 @@
1
1
  # Troubleshooting Guide
2
2
 
3
- Common issues and their solutions.
3
+ Fixes for common problems with `@uniquedivine/mcp-slack`. If none of these
4
+ help, open an issue in
5
+ [Unique-Divine/jiyuu](https://github.com/Unique-Divine/jiyuu/issues) with
6
+ `mcp/slack` in the title.
4
7
 
5
- ---
8
+ ## Install Check
6
9
 
7
- ## Install Flow Sanity Check
8
-
9
- If first-run setup is failing, validate command resolution in a clean directory:
10
+ If first-run setup fails, check command resolution in an empty directory:
10
11
 
11
12
  ```bash
12
- tmpdir="$(mktemp -d)"
13
- cd "$tmpdir"
13
+ cd "$(mktemp -d)"
14
14
  bunx @uniquedivine/mcp-slack --version
15
15
  bunx @uniquedivine/mcp-slack --help
16
16
  bunx @uniquedivine/mcp-slack --doctor
17
17
  ```
18
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
- ---
19
+ Flag `--doctor` exits `0` when ready, `1` for missing credentials, `2` for
20
+ invalid or expired credentials, and `3` for a connectivity or runtime issue.
21
+ If `--version` fails, the problem is the Bun install or `PATH`, not Slack
22
+ credentials.
31
23
 
32
- ## Hosted Version
24
+ ## Expired Tokens
33
25
 
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)*.
26
+ **Symptom:** Tools return `invalid_auth`, `token_expired`, or
27
+ `slack_auth_expired`.
35
28
 
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.
29
+ **Cause:** Slack rotates browser session tokens (`xoxc-` and `xoxd-`) every
30
+ one to two weeks.
37
31
 
38
- ---
32
+ The server looks for tokens in this order:
39
33
 
40
- ## DMs Not Showing Up
41
-
42
- **Symptom:** `slack_list_conversations` returns channels but no DMs.
34
+ 1. Environment variables `SLACK_TOKEN` and `SLACK_COOKIE`.
35
+ 2. File `~/.slack-mcp-tokens.json`.
36
+ 3. The macOS Keychain.
37
+ 4. Chrome extraction, on macOS only.
43
38
 
44
- **Cause:** Slack's `conversations.list` API doesn't return IMs when using xoxc browser tokens.
39
+ **Fix on macOS:** With Slack open in a Chrome tab, call tool
40
+ `slack_refresh_tokens`, or run
41
+ `bunx @uniquedivine/mcp-slack --refresh-tokens`.
45
42
 
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`.
43
+ **Fix everywhere else:** Chrome auto-refresh runs only on macOS. Sign in to
44
+ Slack in a browser, run `bunx @uniquedivine/mcp-slack --setup`, and paste
45
+ fresh values. [Manual Extraction](SETUP.md#manual-extraction) shows where to
46
+ find them. Then reconnect the MCP server.
47
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`
48
+ If `SLACK_TOKEN` and `SLACK_COOKIE` are set, they win over the token file.
49
+ Update both or unset both; `--setup` alone has no effect while they are set.
51
50
 
52
- ---
51
+ ## Edit or Delete Refused
53
52
 
54
- ## Rate Limiting Errors
53
+ **`message_too_old`:** Tools `slack_update_message` and
54
+ `slack_delete_message` refuse messages older than 7 days. Set
55
+ `SLACK_MCP_EDIT_DELETE_MAX_AGE_HOURS` on the server to change the window, or
56
+ ask for `slack_update_message_unsafe` or `slack_delete_message_unsafe`, which
57
+ skip only the age check.
55
58
 
56
- **Symptom:** `{"error":"ratelimited"}` in API responses.
59
+ **`unknown_tool` for an `_unsafe` tool over HTTP:** The HTTP server hides
60
+ the `_unsafe` tools unless `SLACK_MCP_ENABLE_UNSAFE_TOOLS=true`.
57
61
 
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
62
+ **`not_own_message` or `text_mismatch`:** The tools act only on your own
63
+ messages, and argument `expected_text` must match the message's current text.
64
+ Re-read the message with `slack_conversations_history` or `slack_get_thread`
65
+ and pass its text.
89
66
 
90
- # Option 2: Package setup wizard
91
- bunx @uniquedivine/mcp-slack --setup
67
+ [API.md](API.md#slack_delete_message) lists every error code.
92
68
 
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.5.1</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
- ```
69
+ ## DMs Missing
146
70
 
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
- ```
71
+ **Symptom:** `slack_list_conversations` returns channels but no DMs.
159
72
 
160
- Check LaunchAgent status:
161
- ```bash
162
- launchctl list | grep slack-web-api
163
- ```
73
+ Slack's `conversations.list` method doesn't return DMs for `xoxc-` tokens. By
74
+ default, `slack_list_conversations` adds DMs only from its cache in file
75
+ `~/.slack-mcp-dm-cache.json`, and the server ignores that cache once it is
76
+ more than 24 hours old. To rebuild it, call the tool with
77
+ `discover_dms: true` and `types: "im,mpim"`. The server then reads the first
78
+ 200 users from `users.list`, calls `conversations.open` for each one, 50 ms
79
+ apart, and saves the DMs it finds.
164
80
 
165
- Check logs:
166
- ```bash
167
- cat /tmp/slack-web-api.log
168
- cat /tmp/slack-web-api.error.log
169
- ```
81
+ Discovery is slow and can hit rate limits. It also calls `conversations.open`
82
+ for users you have never messaged, which can add empty DMs to your Slack
83
+ sidebar.
170
84
 
171
- ### Hosted HTTP `/mcp` Returns 503 or 401
85
+ ## Rate Limits
172
86
 
173
- If you run `bun src/server-http.js`, `/mcp` is protected by default.
87
+ **Symptom:** `ratelimited` errors.
174
88
 
175
- `503 http_auth_token_missing` means you did not set:
89
+ The Slack client in file `lib/slack-client.js` waits for Slack's
90
+ `Retry-After` header, or 5 seconds without one, and retries up to 3 times
91
+ with a longer wait each time. If you still hit limits, lower `limit` on list
92
+ calls.
176
93
 
177
- ```bash
178
- SLACK_MCP_HTTP_AUTH_TOKEN=change-this
179
- ```
94
+ ## HTTP Server Returns 503 or 401
180
95
 
181
- `401 unauthorized` means your request is missing or using the wrong bearer token.
96
+ Endpoint `/mcp` on the HTTP server (`bun src/cli.js http`) requires a bearer
97
+ token.
182
98
 
183
- Example request:
99
+ - `503 http_auth_token_missing`: set `SLACK_MCP_HTTP_AUTH_TOKEN`.
100
+ - `401 unauthorized`: the request has no bearer token or the wrong one.
184
101
 
185
102
  ```bash
186
103
  curl http://localhost:3000/mcp \
@@ -189,101 +106,47 @@ curl http://localhost:3000/mcp \
189
106
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
190
107
  ```
191
108
 
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
- ```
109
+ For local testing only, `SLACK_MCP_HTTP_INSECURE=1` turns the check off.
221
110
 
222
- 4. **Verify the Bun path:**
223
- ```bash
224
- which bunx
225
- # Use this full path in config
226
- ```
111
+ ## Web Server Problems
227
112
 
228
- ### MCP Server Crashes on Start
113
+ The web server writes its API key to file `~/.slack-mcp-api-key`, and the
114
+ startup log masks all but the first 8 characters. If `SLACK_API_KEY` is set,
115
+ the server uses it instead of the file. This check picks the same key:
229
116
 
230
- **Check the log:**
231
117
  ```bash
232
- tail -50 ~/Library/Logs/Claude/mcp-server-slack.log
118
+ API_KEY="${SLACK_API_KEY:-$(cat ~/.slack-mcp-api-key)}"
119
+ curl http://localhost:3000/health -H "Authorization: Bearer $API_KEY"
233
120
  ```
234
121
 
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?
122
+ To keep it running after the terminal closes on macOS, use the LaunchAgent
123
+ in [WEB-API.md](WEB-API.md#auto-start-on-login).
261
124
 
262
- **Answer:** Slack apps cannot access DMs without explicit OAuth authorization for each conversation. This is by design for privacy.
125
+ ## Tools Missing in Claude Desktop
263
126
 
264
- Browser tokens (xoxc/xoxd) provide the same access you have in Slack's web interface - everything you can see, Claude can see.
127
+ 1. Quit Claude Desktop fully and reopen it.
128
+ 2. Check the config syntax:
129
+ `python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json`.
130
+ 3. Read file `~/Library/Logs/Claude/mcp-server-slack.log`.
131
+ 4. If the log says Bun wasn't found, put the absolute path from
132
+ `which bunx` in `command`.
265
133
 
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
134
+ ## Chrome Extraction Fails (macOS)
271
135
 
272
- ---
136
+ **Symptom:** `slack_refresh_tokens` can't extract tokens from Chrome.
273
137
 
274
- ## Getting Help
138
+ Check that:
275
139
 
276
- 1. Check logs:
277
- - MCP: `~/Library/Logs/Claude/mcp-server-slack.log`
278
- - Web: `/tmp/slack-web-api.log`
140
+ 1. Chrome is running with a Slack tab at `app.slack.com`, not the desktop
141
+ app, and you are signed in.
142
+ 2. **View** > **Developer** > **Allow JavaScript from Apple Events** is on.
143
+ Or set `SLACK_MCP_EXTRACTION_MODE=leveldb` to skip AppleScript.
144
+ 3. If Chrome uses a non-default profile or location, set
145
+ `SLACK_MCP_CHROME_PROFILE` or `SLACK_MCP_CHROME_USER_DATA_DIR`.
279
146
 
280
- 2. Test manually:
281
- ```bash
282
- cd jiyuu/mcp/slack
283
- bun src/server.js # Should say "running"
284
- ```
147
+ ## Why Browser Tokens Instead of a Slack App?
285
148
 
286
- 3. Verify tokens:
287
- ```bash
288
- npm run tokens:status
289
- ```
149
+ A Slack app needs workspace approval and OAuth scopes, and it can't read your
150
+ DMs the way you see them. Session tokens give the server the same access you
151
+ have in Slack's web client. The cost is token rotation every one to two
152
+ weeks, which you refresh by hand off macOS.