@jtalk22/slack-mcp 1.0.0

package/docs/SETUP.md

@@ -0,0 +1,134 @@
+# Setup Guide
+
+## Prerequisites
+
+- Node.js 18+
+- Google Chrome (for token extraction)
+- macOS (for Keychain storage - other platforms use file storage only)
+
+## Installation
+
+### 1. Clone or Copy the Project
+
+```bash
+cd ~
+git clone https://github.com/yourusername/slack-mcp-server.git
+# or if already exists:
+cd ~/slack-mcp-server
+```
+
+### 2. Install Dependencies
+
+```bash
+npm install
+```
+
+### 3. Get Slack Tokens
+
+**Option A: Automatic Extraction**
+
+1. Open Chrome
+2. Navigate to https://app.slack.com and log in
+3. Run:
+   ```bash
+   npm run tokens:auto
+   ```
+
+**Option B: Manual Extraction**
+
+1. Open https://app.slack.com in Chrome
+2. Press F12 to open DevTools
+3. Go to **Application** → **Cookies** → **https://app.slack.com**
+4. Find the cookie named `d` and copy its value (starts with `xoxd-`)
+5. Go to **Console** and paste:
+   ```javascript
+   JSON.parse(localStorage.localConfig_v2).teams[Object.keys(JSON.parse(localStorage.localConfig_v2).teams)[0]].token
+   ```
+6. Copy the result (starts with `xoxc-`)
+7. Run:
+   ```bash
+   npm run tokens:refresh
+   ```
+   And paste both values when prompted.
+
+### 4. Configure Claude Desktop (GUI App)
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "command": "/opt/homebrew/bin/node",
+      "args": ["/Users/YOUR_USERNAME/slack-mcp-server/src/server.js"],
+      "env": {
+        "SLACK_TOKEN": "xoxc-your-token-here",
+        "SLACK_COOKIE": "xoxd-your-cookie-here",
+        "PATH": "/opt/homebrew/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+**Important:**
+- Replace `YOUR_USERNAME` with your actual username
+- Copy tokens from `~/.slack-mcp-tokens.json` into the env section
+- Fully restart Claude Desktop (Cmd+Q, then reopen)
+
+**Verify it's working:** Check `~/Library/Logs/Claude/mcp-server-slack.log`
+
+### 5. Configure Claude Code (CLI)
+
+Edit `~/.claude.json` and add under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/Users/YOUR_USERNAME/slack-mcp-server/src/server.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+Claude Code reads tokens from `~/.slack-mcp-tokens.json` automatically.
+
+### 6. Restart Claude
+
+The Slack tools will now be available in both Claude Desktop and Claude Code.
+
+## Verification
+
+In Claude Code, try:
+```
+slack_health_check
+```
+
+You should see your username and team name.
+
+## Troubleshooting
+
+### "No credentials found"
+
+Run `npm run tokens:auto` with Slack open in Chrome, or `npm run tokens:refresh` to enter manually.
+
+### "invalid_auth" Error
+
+Tokens have expired. Open Slack in Chrome and use `slack_refresh_tokens` in Claude Code.
+
+### MCP Server Not Loading
+
+1. Check `~/.claude.json` syntax
+2. Verify the path to server.js is correct
+3. Restart Claude Code
+
+### Chrome Extraction Fails
+
+Make sure:
+- Chrome is running (not just in dock)
+- You have a Slack tab open (not the desktop app)
+- You're logged into Slack in that tab

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,216 @@
+# Troubleshooting Guide
+
+Common issues and their solutions.
+
+---
+
+## DMs Not Showing Up
+
+**Symptom:** `slack_list_conversations` returns channels but no DMs.
+
+**Cause:** Slack's `conversations.list` API doesn't return IMs when using xoxc browser tokens.
+
+**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`.
+
+If DMs still don't appear:
+1. Check you're requesting the right types: `slack_list_conversations types=im,mpim`
+2. Verify the user exists: `slack_list_users`
+
+---
+
+## Rate Limiting Errors
+
+**Symptom:** `{"error":"ratelimited"}` in API responses.
+
+**Cause:** Slack limits API calls, especially when listing many users/DMs.
+
+**Solution:** The client (`lib/slack-client.js`) implements automatic retry with exponential backoff:
+- First retry: Wait 5 seconds
+- Second retry: Wait 10 seconds
+- Third retry: Wait 15 seconds
+
+If you still hit limits, reduce batch sizes:
+```
+slack_list_conversations limit=50
+```
+
+---
+
+## Token Expiration
+
+**Symptom:** `invalid_auth` or `token_expired` errors.
+
+**Cause:** Browser tokens (xoxc/xoxd) expire after 1-2 weeks.
+
+**Solution:** The server has 4 layers of token recovery:
+
+1. **Environment variables** - From MCP config (Claude Desktop)
+2. **Token file** - `~/.slack-mcp-tokens.json`
+3. **macOS Keychain** - Encrypted persistent storage
+4. **Chrome auto-extraction** - Fallback when all else fails
+
+**To refresh tokens:**
+```bash
+# Option 1: In Claude Code/Desktop
+slack_refresh_tokens
+
+# Option 2: CLI
+npm run tokens:auto
+
+# Option 3: Manual
+npm run tokens:refresh
+```
+
+---
+
+## Web Server Issues
+
+### Server Stops When Terminal Closes
+
+**Solution:** Use LaunchAgent for persistence:
+
+```bash
+# Create LaunchAgent
+cat > ~/Library/LaunchAgents/com.slack-web-api.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.slack-web-api</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/homebrew/bin/node</string>
+        <string>/Users/YOUR_USERNAME/slack-mcp-server/src/web-server.js</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/Users/YOUR_USERNAME/slack-mcp-server</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+</dict>
+</plist>
+EOF
+
+launchctl load ~/Library/LaunchAgents/com.slack-web-api.plist
+```
+
+### API Key Invalid
+
+**Default API Key:** `slack-mcp-local`
+
+If you set a custom key, make sure it matches:
+```bash
+SLACK_API_KEY=your-custom-key npm run web
+```
+
+### Can't Connect to localhost:3000
+
+Check if the server is running:
+```bash
+curl http://localhost:3000/health -H "Authorization: Bearer slack-mcp-local"
+```
+
+Check LaunchAgent status:
+```bash
+launchctl list | grep slack-web-api
+```
+
+Check logs:
+```bash
+cat /tmp/slack-web-api.log
+cat /tmp/slack-web-api.error.log
+```
+
+---
+
+## Claude Desktop Issues
+
+### Slack Tools Not Appearing
+
+**Symptom:** Claude Desktop doesn't show Slack tools after adding config.
+
+**Solutions:**
+
+1. **Fully restart Claude Desktop:**
+   - Cmd+Q (don't just close window)
+   - Reopen the app
+
+2. **Check config syntax:**
+   ```bash
+   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
+   ```
+
+3. **Check MCP logs:**
+   ```bash
+   cat ~/Library/Logs/Claude/mcp-server-slack.log
+   ```
+
+4. **Verify node path:**
+   ```bash
+   which node
+   # Use this full path in config
+   ```
+
+### MCP Server Crashes on Start
+
+**Check the log:**
+```bash
+tail -50 ~/Library/Logs/Claude/mcp-server-slack.log
+```
+
+**Common causes:**
+- Node.js not found (use full path like `/opt/homebrew/bin/node`)
+- Missing tokens in env section
+- Invalid JSON syntax in config
+
+---
+
+## Chrome Extraction Fails
+
+**Symptom:** `slack_refresh_tokens` returns "Could not extract from Chrome"
+
+**Requirements:**
+1. Google Chrome must be running (not just in Dock)
+2. Have a Slack tab open at `app.slack.com` (not desktop app)
+3. Be logged into Slack in that tab
+4. Grant accessibility permissions to Terminal/Claude
+
+**Check permissions:**
+System Preferences → Privacy & Security → Accessibility → Ensure Terminal is enabled
+
+---
+
+## Why Browser Tokens Instead of Slack App?
+
+**Question:** Why not just create a Slack app with proper OAuth?
+
+**Answer:** Slack apps cannot access DMs without explicit OAuth authorization for each conversation. This is by design for privacy.
+
+Browser tokens (xoxc/xoxd) provide the same access you have in Slack's web interface - everything you can see, Claude can see.
+
+**Trade-offs:**
+- ✅ Full access to all your conversations
+- ✅ No per-conversation authorization needed
+- ❌ Tokens expire every 1-2 weeks
+- ❌ Requires Chrome for token extraction
+
+---
+
+## Getting Help
+
+1. Check logs:
+   - MCP: `~/Library/Logs/Claude/mcp-server-slack.log`
+   - Web: `/tmp/slack-web-api.log`
+
+2. Test manually:
+   ```bash
+   cd ~/slack-mcp-server
+   node src/server.js  # Should say "running"
+   ```
+
+3. Verify tokens:
+   ```bash
+   npm run tokens:status
+   ```

package/docs/WEB-API.md

@@ -0,0 +1,277 @@
+# Web API Reference
+
+The Slack Web Server exposes all MCP tools as REST endpoints, accessible from any browser or HTTP client. This is useful for accessing Slack from claude.ai (which doesn't support MCP).
+
+## Starting the Server
+
+```bash
+cd ~/slack-mcp-server
+npm run web
+```
+
+The server will:
+1. Start on port 3000
+2. Serve the web UI at http://localhost:3000
+3. Use default API key `slack-mcp-local` (or set `SLACK_API_KEY` env var)
+
+## Auto-Start on Login (Recommended)
+
+Create a LaunchAgent to auto-start the web server on login:
+
+```bash
+cat > ~/Library/LaunchAgents/com.slack-web-api.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.slack-web-api</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/homebrew/bin/node</string>
+        <string>/Users/YOUR_USERNAME/slack-mcp-server/src/web-server.js</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/Users/YOUR_USERNAME/slack-mcp-server</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/tmp/slack-web-api.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/slack-web-api.error.log</string>
+</dict>
+</plist>
+EOF
+
+# Load it
+launchctl load ~/Library/LaunchAgents/com.slack-web-api.plist
+```
+
+**Manage the service:**
+```bash
+# Check status
+launchctl list | grep slack-web-api
+
+# Restart
+launchctl kickstart -k gui/$(id -u)/com.slack-web-api
+
+# Stop
+launchctl unload ~/Library/LaunchAgents/com.slack-web-api.plist
+```
+
+## Authentication
+
+All API requests require the API key in the Authorization header:
+
+```
+Authorization: Bearer <your-api-key>
+```
+
+**Default API Key:** `slack-mcp-local`
+
+To use a custom key:
+```bash
+SLACK_API_KEY=your-custom-key npm run web
+```
+
+---
+
+## Endpoints
+
+### GET /
+Server info and available endpoints (no auth required).
+
+### GET /health
+Check Slack connection status.
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/health
+```
+
+**Response:**
+```json
+{
+  "status": "OK",
+  "user": "james",
+  "team": "Rêvasser"
+}
+```
+
+---
+
+### POST /refresh
+Force token refresh from Chrome.
+
+```bash
+curl -X POST -H "Authorization: Bearer $API_KEY" http://localhost:3000/refresh
+```
+
+---
+
+### GET /conversations
+List conversations (DMs/channels).
+
+**Query Parameters:**
+| Param | Default | Description |
+|-------|---------|-------------|
+| types | im,mpim | Conversation types |
+| limit | 100 | Max results |
+
+**Types:** `im`, `mpim`, `public_channel`, `private_channel`
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" "http://localhost:3000/conversations?types=im"
+```
+
+**Response:**
+```json
+{
+  "count": 5,
+  "conversations": [
+    { "id": "D063M4403MW", "name": "Gwen Santos", "type": "dm" }
+  ]
+}
+```
+
+---
+
+### GET /conversations/:id/history
+Get messages from a conversation.
+
+**Query Parameters:**
+| Param | Default | Description |
+|-------|---------|-------------|
+| limit | 50 | Messages to fetch |
+| oldest | - | Unix timestamp start |
+| latest | - | Unix timestamp end |
+| resolve_users | true | Convert user IDs to names |
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" "http://localhost:3000/conversations/D063M4403MW/history?limit=10"
+```
+
+---
+
+### GET /conversations/:id/full
+Export full conversation with threads.
+
+**Query Parameters:**
+| Param | Default | Description |
+|-------|---------|-------------|
+| max_messages | 2000 | Max messages |
+| include_threads | true | Fetch replies |
+| oldest | - | Unix timestamp start |
+| latest | - | Unix timestamp end |
+| output_file | - | Save to file path |
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" "http://localhost:3000/conversations/D063M4403MW/full?max_messages=500"
+```
+
+---
+
+### GET /conversations/:id/thread/:ts
+Get thread replies.
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" "http://localhost:3000/conversations/D063M4403MW/thread/1767368030.607599"
+```
+
+---
+
+### GET /search
+Search messages across workspace.
+
+**Query Parameters:**
+| Param | Default | Description |
+|-------|---------|-------------|
+| q | *required* | Search query |
+| count | 20 | Max results |
+
+**Query Syntax:**
+- `from:@username` - From specific user
+- `in:#channel` - In specific channel
+- `before:2026-01-01` - Before date
+- `after:2025-12-01` - After date
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" "http://localhost:3000/search?q=from:@gwen%20meeting"
+```
+
+---
+
+### POST /messages
+Send a message.
+
+**Body:**
+```json
+{
+  "channel_id": "D063M4403MW",
+  "text": "Hello!",
+  "thread_ts": "1767368030.607599"  // optional, for replies
+}
+```
+
+```bash
+curl -X POST -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"channel_id":"D063M4403MW","text":"Hello!"}' \
+  http://localhost:3000/messages
+```
+
+---
+
+### GET /users
+List all workspace users.
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" "http://localhost:3000/users?limit=50"
+```
+
+---
+
+### GET /users/:id
+Get user details.
+
+```bash
+curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/users/U05GPEVH7J9
+```
+
+---
+
+## Web UI
+
+Open http://localhost:3000 in your browser for a visual interface.
+
+The UI auto-connects with the default API key:
+1. Select a conversation from the sidebar
+2. View messages, threads, and user info
+3. Search messages across the workspace
+4. Send messages directly from the browser
+
+**Using with claude.ai:**
+1. Open the web UI alongside claude.ai
+2. Browse/search for relevant conversations
+3. Copy-paste message content into claude.ai as needed
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| PORT | 3000 | Server port |
+| SLACK_API_KEY | (generated) | API key for authentication |
+| SLACK_TOKEN | - | Slack xoxc token |
+| SLACK_COOKIE | - | Slack xoxd cookie |
+
+---
+
+## Security Notes
+
+1. **API Key**: Keep it secret. Anyone with the key can access your Slack.
+2. **Local Only**: By default, only accessible from localhost.
+3. **HTTPS**: For remote access, put behind a reverse proxy with HTTPS.
+4. **Token Storage**: Slack tokens are stored in keychain and token file.