@jtalk22/slack-mcp 3.1.0 → 3.2.0

package/docs/WEB-API.md

@@ -1,303 +0,0 @@
-# Web API Reference
-
-The Slack Web Server exposes all MCP tools as REST endpoints, accessible from any browser or HTTP client.
-
-Claude web now supports remote MCP connectors on paid plans, so this Web API mode is best used for:
-- local localhost dashboard workflows
-- REST/API integrations
-- fallback operation when you do not want to host a remote MCP endpoint
-
-References:
-- https://support.anthropic.com/en/articles/11995447-connectors-in-claude
-- https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp
-
-## Starting the Server
-
-```bash
-cd ~/slack-mcp-server
-npm run web
-# Or run directly from npm:
-npx -y @jtalk22/slack-mcp web
-```
-
-The server will:
-1. Start on port 3000
-2. Serve the web UI at http://localhost:3000
-3. Generate a secure API key (saved to `~/.slack-mcp-api-key`)
-
-## 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>
-```
-
-The server generates a cryptographically secure API key on first run, saved to `~/.slack-mcp-api-key`. The key is printed to the console:
-
-```
-Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx
-```
-
-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",
-  "code": "ok",
-  "message": "Slack auth valid",
-  "user": "james",
-  "team": "Rêvasser"
-}
-```
-
----
-
-### GET /token-status
-Read-only token diagnostics (age/health/cache stats). This endpoint does not trigger Chrome extraction.
-
-```bash
-curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/token-status
-```
-
----
-
-### 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. Preferred: add a remote MCP connector in Claude settings if you run a remote endpoint.
-2. Fallback: open the web UI alongside claude.ai for local browsing/search.
-3. Copy-paste relevant message content 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.

package/docs/images/diagram-oauth-comparison.svg

@@ -1,80 +0,0 @@
-<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

@@ -1,105 +0,0 @@
-<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>