@jtalk22/slack-mcp 3.0.0 → 3.2.0

package/docs/LAUNCH-OPS.md

@@ -1,71 +0,0 @@
-# Launch Ops Runbook (v3.0.0)
-
-This runbook defines launch-day monitoring and distribution for technical/operator channels (no X/Reddit dependency).
-
-## Same-Day Fanout Order (9 Channels)
-
-1. GitHub release page refresh (`v3.0.0` copy + install-proof block)
-2. npm parity confirm (`@jtalk22/slack-mcp@3.0.0`)
-3. MCP registry parity confirm (`3.0.0`)
-4. Smithery listing metadata/parity update (or timestamped propagation note)
-5. `awesome-mcp-servers` listing PR refresh
-6. Glama metadata sync and canonical link verification
-7. HN thread update comment (high-signal install proof + support path)
-8. GitHub Discussions announcement/support threads update
-9. GitHub Pages/docs surface publish + link verification
-
-## Monitoring Cadence
-
-- First 4 hours: every 30 minutes
-- Up to 24 hours: every 60 minutes
-
-Track:
-- install reports and blocker count
-- npm/MCP parity state
-- listing propagation status (Smithery/Glama)
-- inbound issue and discussion severity
-- hosted migration questions (`SLACK_MCP_HTTP_AUTH_TOKEN`, CORS allowlist)
-
-## Triage Rules
-
-P1 install blocker:
-- acknowledge within 30-60 minutes
-- provide immediate workaround
-- add fix to patch queue
-
-Non-blocking request:
-- acknowledge and route to issue/discussion template
-- provide timeline as best effort
-
-## Escalation Triggers
-
-1. If install failures exceed 3 unique reports in 24h:
-- pause outbound promotion
-- prioritize hotfix
-
-2. If support load exceeds 2 hours/day for 2 days:
-- switch to stability-only mode
-- defer non-critical requests
-
-## 24h / 48h / 72h Follow-Up
-
-24h:
-- publish release-health delta and short technical summary
-
-48h:
-- patch docs for top recurring setup questions
-
-72h:
-- ship `v3.0.1` only if launch defects are confirmed
-
-## Evidence Log
-
-Use:
-- `docs/release-health/launch-log-template.md`
-
-Capture:
-- channel
-- UTC timestamp
-- URL or command evidence
-- action taken
-- observed result (`success|partial|blocked`)

package/docs/RELEASE-HEALTH.md

@@ -1,90 +0,0 @@
-# Release Health Tracking
-
-Use this to track installation reliability and operational load during the current release cycle.
-
-## One-command snapshot
-
-```bash
-node scripts/collect-release-health.js
-```
-
-Outputs:
-- `docs/release-health/latest.md`
-- `docs/release-health/YYYY-MM-DD.md`
-- `docs/release-health/automation-delta.md` (when delta script is run)
-
-## Version parity report
-
-```bash
-npm run verify:version-parity
-```
-
-Output:
-- `docs/release-health/version-parity.md`
-
-If external registries are still propagating immediately after publish:
-
-```bash
-npm run verify:version-parity -- --allow-propagation
-```
-
-## Prepublish dry run
-
-```bash
-npm run verify:release-dry-run
-```
-
-Output:
-- `docs/release-health/prepublish-dry-run.md`
-
-24-hour loop artifacts:
-- `docs/release-health/24h-start.md`
-- `docs/release-health/24h-end.md`
-- `docs/release-health/24h-delta.md`
-
-## What it captures automatically
-
-- npm downloads (last week, last month)
-- npm latest version
-- GitHub stars, forks, open issues
-- GitHub 14-day traffic views/clones (owner token required via `gh auth`)
-- Count of `deployment-intake` issues
-
-## 14-day targets
-
-- weekly downloads: `>= 180`
-- qualified deployment-intake submissions: `>= 2`
-- support load: `<= 2 hours/week`
-
-## Manual fields to track alongside snapshots
-
-- Weekly support minutes spent.
-- Deployment-intake quality (clear use case, owner, timeline).
-- Traffic source notes (search, referrals, docs traffic).
-- External \"first run succeeded\" confirmations (issues/discussions).
-
-## Recommended cadence
-
-- Days 1-7: daily snapshot
-- Days 8-14: every 2-3 days
-
-## Automated cadence (low-touch)
-
-- Workflow: `.github/workflows/release-health.yml`
-- Triggers:
-  - scheduled at `07:15` and `19:15` UTC
-  - manual `workflow_dispatch`
-- Outputs per run:
-  - workflow summary with current snapshot and baseline delta
-  - artifacts: `docs/release-health/latest.md`, `docs/release-health/automation-delta.md`
-
-## Local delta command
-
-If you want to compare two explicit snapshots locally:
-
-```bash
-node scripts/build-release-health-delta.js \
-  --before docs/release-health/24h-start.md \
-  --after docs/release-health/24h-end.md \
-  --out docs/release-health/24h-delta.md
-```

package/docs/SUPPORT-BOUNDARIES.md

@@ -1,49 +0,0 @@
-# Support Boundaries
-
-This document sets expectations for issue triage, support scope, and rollout safety.
-
-## In Scope
-
-- Reproducible bugs in published release behavior.
-- Install and setup blockers for supported Node/runtime paths.
-- Regressions in existing tools (`slack_get_thread`, `slack_search_messages`, etc.).
-- Documentation corrections with clear technical evidence.
-
-## Out of Scope
-
-- Custom Slack policy/legal interpretation for a specific organization.
-- Workspace-specific data migrations or bespoke integrations.
-- Real-time operational support for third-party hosting providers.
-- Urgent production incident ownership for self-hosted external deployments.
-
-## Intake Requirements
-
-Include the following in every issue:
-
-1. Version (`npm view @jtalk22/slack-mcp version` output).
-2. Runtime mode (`stdio`, `web`, `http`, or Worker/Smithery).
-3. OS and Node version.
-4. Minimal reproduction steps and exact error text.
-5. Whether this blocks individual use or team rollout.
-
-## Response Windows (Best Effort)
-
-- Installation/blocker bugs: initial response target within 2 business days.
-- Non-blocking bugs: initial response target within 5 business days.
-- Feature requests: triaged in backlog batches.
-
-## Solo Maintainer Capacity Guardrail
-
-- Weekly support budget target: <= 2 hours/week.
-- If inbound support exceeds this cap, new feature work may be paused.
-- High-context requests may be deferred until reproducible artifacts are provided.
-
-## Security and Data Handling
-
-- Do not post raw tokens/cookies in issues.
-- Use redacted logs.
-- If credentials are exposed, rotate immediately and update issue with redaction.
-
-## Deployment Escalation Rule
-
-For team/hosted usage, open a deployment intake issue before broad rollout.

package/docs/USE_CASE_RECIPES.md

@@ -1,69 +0,0 @@
-# Use Case Recipes
-
-Copy and paste any prompt into your MCP client. Each recipe maps to existing tools and parameters.
-
-## 1) Fast Health Check
-
-Prompt:
-`Run slack_health_check and tell me if my workspace connection is valid.`
-
-## 2) Token Age and Cache Snapshot
-
-Prompt:
-`Run slack_token_status and summarize token age, health, and cache stats.`
-
-## 3) List Recent DMs
-
-Prompt:
-`Use slack_list_conversations with types="im,mpim" and limit=50. Return names and IDs.`
-
-## 4) Summarize a Channel for the Last 3 Days
-
-Prompt:
-`Use slack_conversations_history with channel_id="<CHANNEL_ID>", oldest="<UNIX_TS_3_DAYS_AGO>", limit=100, resolve_users=true, then summarize decisions and action items.`
-
-## 5) Pull a Full Thread
-
-Prompt:
-`Use slack_get_thread with channel_id="<CHANNEL_ID>" and thread_ts="<THREAD_TS>". Summarize timeline and owners.`
-
-## 6) Search for Decisions
-
-Prompt:
-`Use slack_search_messages with query="decision OR approved after:2026-01-01" and count=50. Group results by channel.`
-
-## 7) Find Messages from One Person
-
-Prompt:
-`Use slack_search_messages with query="from:@<USERNAME> after:2026-01-01" and count=30. Return top themes.`
-
-## 8) Export Conversation History
-
-Prompt:
-`Use slack_get_full_conversation with channel_id="<CHANNEL_ID>", max_messages=2000, include_threads=true, output_file="q1-export.json".`
-
-## 9) Lookup a User Profile
-
-Prompt:
-`Use slack_users_info with user_id="<USER_ID>" and return role, timezone, and status fields.`
-
-## 10) Send a Channel Update
-
-Prompt:
-`Use slack_send_message with channel_id="<CHANNEL_ID>" and text="Daily update: build passed, deploy at 4 PM ET."`
-
-## 11) Reply in a Thread
-
-Prompt:
-`Use slack_send_message with channel_id="<CHANNEL_ID>", thread_ts="<THREAD_TS>", text="Acknowledged. I will post follow-up logs in 30 minutes."`
-
-## 12) Directory Snapshot
-
-Prompt:
-`Use slack_list_users with limit=500. Return a compact list of users with admin/bot flags.`
-
-## Notes
-
-- Replace placeholders before running (`<CHANNEL_ID>`, `<THREAD_TS>`, `<USER_ID>`, `<USERNAME>`, timestamps).
-- Timestamp parameters are Unix seconds in string form.
-- For large workspaces, start with smaller limits, then expand.

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>