@jtalk22/slack-mcp 1.2.3 → 1.2.4

package/README.md

@@ -32,7 +32,6 @@
   <a href="https://github.com/jtalk22/slack-mcp-server/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/jtalk22/slack-mcp-server/ci.yml?label=build" alt="Build Status"></a>
   <a href="https://smithery.ai/server/jtalk22/slack-mcp-server"><img src="https://img.shields.io/badge/Smithery-Registry-4A154B" alt="Smithery"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
-  <a href="https://github.com/sponsors/jtalk22"><img src="https://img.shields.io/badge/Sponsor-♡-ea4aaa?logo=github" alt="Sponsor"></a>
 </p>
 
 ---
@@ -45,7 +44,7 @@ I built this because I was working with someone to help me manage a complex work
 
 Screenshotting messages is not a workflow.
 
-This server bridges the gap. It creates a secure, local bridge between Claude and your Slack web session. It gives your AI the same access **you** already have in the browser—search history, summarize threads, find that thing someone sent you three weeks ago—without fighting the platform.
+This server bridges the gap. It creates a secure, local bridge between Claude and your Slack web session. It gives your MCP client the same access **you** already have in the browser—search history, summarize threads, and retrieve prior context—without fighting the platform.
 
 ![Slack MCP Server Web UI](docs/images/demo-main.png)
 
@@ -102,7 +101,7 @@ Instead of authenticating as a bot, this server leverages your existing Chrome s
 
 **Runtime:** Node.js 20+
 
-### 30-Second Proof
+### 30-Second Compatibility Check
 
 ```bash
 npx -y @jtalk22/slack-mcp --version
@@ -119,7 +118,17 @@ Expected:
   - `3` connectivity/runtime issue
 - `--setup` launches the interactive wizard
 
-Proof script for launch threads: [docs/HN-LAUNCH.md](docs/HN-LAUNCH.md)
+Command reference: [docs/HN-LAUNCH.md](docs/HN-LAUNCH.md)
+
+### Known Working Clients
+
+- Claude Desktop (macOS/Windows/Linux)
+- Claude Code CLI
+- Local browser mode (`web`)
+- Hosted Node runtime (`http`)
+- Cloudflare Worker / Smithery transport
+
+Compatibility matrix: [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)
 
 ### Option A: npm (Recommended)
 
@@ -154,6 +163,7 @@ npx -y @jtalk22/slack-mcp --status
 Expected:
 - `--version` and `--help` exit `0`
 - `--status` exits non-zero until credentials are configured
+- `--status` is read-only and never attempts Chrome extraction
 
 ---
 
@@ -325,7 +335,7 @@ npm run web
 
 ```
 ════════════════════════════════════════════════════════════
-  Slack Web API Server v1.2.3
+  Slack Web API Server v1.2.4
 ════════════════════════════════════════════════════════════
 
   Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx
@@ -350,6 +360,7 @@ Just click the link - no copy-paste needed. The key is saved to your browser and
 - [Deployment Modes](docs/DEPLOYMENT-MODES.md) - Choose the right operating model (`stdio`, `web`, hosted HTTP, Smithery/Worker)
 - [Use Case Recipes](docs/USE_CASE_RECIPES.md) - 12 copy/paste prompts mapped to current tool contracts
 - [Support Boundaries](docs/SUPPORT-BOUNDARIES.md) - Scope, response targets, and solo-maintainer capacity limits
+- [Release Health](docs/RELEASE-HEALTH.md) - Track setup reliability and support-load targets through this release cycle
 
 If you're evaluating team rollout, start with [Deployment Modes](docs/DEPLOYMENT-MODES.md) before exposing remote endpoints.
 
@@ -401,6 +412,7 @@ This caches DM channel IDs for 24 hours.
 - Chrome must be **running** (not minimized to Dock)
 - Slack tab must be open at `app.slack.com`
 - You must be logged in
+- In Chrome menu, enable `View > Developer > Allow JavaScript from Apple Events`
 
 ### Claude Desktop Not Seeing Tools
 1. Verify JSON syntax in config file
@@ -456,7 +468,7 @@ slack-mcp-server/
 
 PRs welcome. Run `node --check` on modified files before submitting.
 
-If you find this project useful, consider [sponsoring](https://github.com/sponsors/jtalk22) or starring the repo.
+If you find this project useful, consider starring the repo.
 
 ---
 

package/docs/API.md

@@ -11,7 +11,9 @@ Check if Slack tokens are valid.
 **Returns:**
 ```json
 {
-  "status": "OK",
+  "status": "ok",
+  "code": "ok",
+  "message": "Slack auth valid",
   "user": "james",
   "team": "Rêvasser",
   "token_source": "environment",
@@ -30,12 +32,15 @@ Get detailed token health, age, and cache statistics.
 **Returns:**
 ```json
 {
+  "status": "healthy",
+  "code": "ok",
+  "message": "Token is healthy",
+  "next_action": null,
   "token": {
     "status": "healthy",
     "age_hours": 2.5,
     "source": "file",
-    "updated_at": "2026-01-08T12:00:00Z",
-    "message": "Token is healthy"
+    "updated_at": "2026-01-08T12:00:00Z"
   },
   "auto_refresh": {
     "enabled": true,
@@ -62,7 +67,9 @@ Force refresh tokens from Chrome.
 **Returns:**
 ```json
 {
-  "status": "SUCCESS",
+  "status": "ok",
+  "code": "refreshed",
+  "message": "Tokens refreshed from Chrome.",
   "user": "james",
   "team": "Rêvasser"
 }

package/docs/COMMUNICATION-STYLE.md

@@ -9,6 +9,7 @@ Use this guide for release notes, issue replies, and changelog entries.
 3. Do not include co-author trailers from tooling.
 4. State exact versions and commands when relevant.
 5. Avoid speculative claims.
+6. Release titles use `vX.Y.Z — <concrete operational outcome>`.
 
 ## Issue Reply Template
 

package/docs/COMPATIBILITY.md

@@ -0,0 +1,19 @@
+# Compatibility Matrix
+
+Use this matrix to choose a known working client/runtime path before rollout.
+
+| Client | Mode | Token path | Status | Quick verify command |
+|---|---|---|---|---|
+| Claude Desktop (macOS) | `stdio` | `~/.slack-mcp-tokens.json` via `--setup` auto-extract | Supported | `npx -y @jtalk22/slack-mcp --setup && npx -y @jtalk22/slack-mcp --status` |
+| Claude Desktop (Windows) | `stdio` | `env` (`SLACK_TOKEN`, `SLACK_COOKIE`) in config | Supported | `npx -y @jtalk22/slack-mcp --status` |
+| Claude Desktop (Linux) | `stdio` | `env` or token file via guided setup | Supported | `npx -y @jtalk22/slack-mcp --status` |
+| Claude Code CLI | `stdio` | `~/.slack-mcp-tokens.json` or `env` | Supported | `npx -y @jtalk22/slack-mcp --version && npx -y @jtalk22/slack-mcp --status` |
+| Local Browser UI | `web` | token file or `env` | Supported | `npx -y @jtalk22/slack-mcp web` |
+| Hosted Node Runtime | `http` | `env` in host runtime | Supported with operator controls | `node src/server-http.js` then `curl -s http://localhost:8080/health` |
+| Cloudflare Worker / Smithery transport | `worker` | runtime env/query handoff per deployment config | Supported with deployment validation | `wrangler deploy --config workers/wrangler.toml` and verify `/health` |
+
+## Notes
+
+1. Runtime baseline is Node 20+.
+2. `--doctor` is the fastest first check when setup status is unknown.
+3. For hosted/team deployment, use [DEPLOYMENT-MODES.md](DEPLOYMENT-MODES.md) before production rollout.

package/docs/HN-LAUNCH.md

@@ -1,23 +1,25 @@
 # HN Launch Kit
 
-Use this file as copy/paste launch material with no extra edits.
+Use this file as copy/paste launch material with minimal edits.
 
-## Launch Post Draft
+## Title Options
 
-Title idea: `Show HN: Slack MCP Server (local-first, session-based Slack access for Claude)`
+- `Show HN: Slack MCP Server (session-based Slack access for Claude)`
+- `Show HN: Slack MCP Server (local-first Slack context for Claude)`
+- `Show HN: Slack MCP Server (Slack MCP for local and hosted runtimes)`
 
-Post body:
+## Launch Post Template
 
 ```md
-Built a local-first Slack MCP server so Claude can use the same Slack access already available in your browser session.
+Built a session-based Slack MCP server so Claude can use the same access already available in your Slack web session.
 
-What it does:
-- DMs/channels/thread reads
+Current scope:
+- DM/channel/thread reads
 - workspace search
-- message send + user lookups
+- message sends and user lookups
 - local web mode when MCP is unavailable
 
-Quick proof:
+Verify:
 - `npx -y @jtalk22/slack-mcp --version`
 - `npx -y @jtalk22/slack-mcp --status`
 - `npx -y @jtalk22/slack-mcp --setup`
@@ -31,28 +33,28 @@ npm: https://www.npmjs.com/package/@jtalk22/slack-mcp
 ```md
 Notes up front:
 - Local-first usage is fully supported.
-- Tokens are your Slack session credentials and are stored locally by default.
+- Tokens are Slack session credentials and are stored locally by default.
 - macOS supports automatic Chrome extraction; Linux/Windows use guided manual setup.
 - Current docs include deployment modes, support boundaries, and troubleshooting.
 
 If install fails, include OS, Node version, runtime mode (`stdio|web|http|worker`), and exact error output.
 ```
 
-## Rebuttal Mini-FAQ
+## FAQ
 
-### Is this bypassing Slack app scopes?
-It does not use Slack app OAuth scopes. It uses your existing signed-in session permissions.
+### Is this using Slack app OAuth scopes?
+No. It uses existing signed-in session permissions.
 
 ### What about token expiry?
 Session tokens expire. `--setup` refreshes credentials, and macOS supports automatic extraction from Chrome.
 
-### Is this intended as a stealth hosted proxy?
-No. The free path is local/self-hosted first. Deployment docs describe tradeoffs and support boundaries before team rollout.
+### Is hosted deployment required?
+No. The default path is local/self-hosted first. Deployment docs describe hosted tradeoffs.
 
-### Is this safe for production teams?
-Treat as operator-managed infrastructure. Validate with your own risk/compliance controls before broader rollout.
+### Is this suitable for production teams?
+Treat as operator-managed infrastructure and validate against your own security and compliance requirements.
 
-## Install Proof Block
+## Install Check Block
 
 ```bash
 npx -y @jtalk22/slack-mcp --version

package/docs/INDEX.md

@@ -1,10 +1,11 @@
 # Documentation Index
 
-Start here for setup, validation, operations, and support.
+Start here for setup, compatibility checks, operations, and support.
 
 ## Core
 
 - [Setup Guide](SETUP.md)
+- [Compatibility Matrix](COMPATIBILITY.md)
 - [API Reference](API.md)
 - [Web API Reference](WEB-API.md)
 - [Troubleshooting](TROUBLESHOOTING.md)
@@ -19,6 +20,8 @@ Start here for setup, validation, operations, and support.
 
 - [HN Launch Kit](HN-LAUNCH.md)
 - [Communication Style](COMMUNICATION-STYLE.md)
+- [Release Health Guide](RELEASE-HEALTH.md)
+- [Latest Release Health Snapshot](release-health/latest.md)
 - [Changelog](../CHANGELOG.md)
 
 ## Issue Intake

package/docs/RELEASE-HEALTH.md

@@ -0,0 +1,66 @@
+# 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)
+
+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/SETUP.md

@@ -40,6 +40,7 @@ Expected:
   - `1` missing credentials
   - `2` invalid/expired credentials
   - `3` connectivity/runtime issue
+- `--status` is read-only and never performs Chrome extraction.
 
 ### 3. Get Slack Tokens
 
@@ -156,3 +157,4 @@ 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
+- In Chrome menu, enable `View > Developer > Allow JavaScript from Apple Events`

package/docs/TROUBLESHOOTING.md

@@ -23,6 +23,7 @@ Expected:
   - `1` missing credentials
   - `2` invalid/expired credentials
   - `3` connectivity/runtime issue
+- `--status` is read-only and never attempts Chrome extraction.
 
 If `--version` fails here, the issue is install/runtime path, not Slack credentials.
 
@@ -81,13 +82,13 @@ slack_refresh_tokens
 # Option 2: Package setup wizard
 npx -y @jtalk22/slack-mcp --setup
 
-# Option 3: Doctor diagnostics
+# Option 3: Diagnostics check
 npx -y @jtalk22/slack-mcp --doctor
 
-# Option 3: Repo CLI
+# Option 4: Repo CLI
 npm run tokens:auto
 
-# Option 4: Manual
+# Option 5: Manual
 npm run tokens:refresh
 ```
 
@@ -212,7 +213,8 @@ tail -50 ~/Library/Logs/Claude/mcp-server-slack.log
 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
+4. In Chrome menu, enable `View > Developer > Allow JavaScript from Apple Events`
+5. Grant accessibility permissions to Terminal/Claude
 
 **Check permissions:**
 System Preferences → Privacy & Security → Accessibility → Ensure Terminal is enabled

package/docs/WEB-API.md

@@ -99,7 +99,9 @@ curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/health
 **Response:**
 ```json
 {
-  "status": "OK",
+  "status": "ok",
+  "code": "ok",
+  "message": "Slack auth valid",
   "user": "james",
   "team": "Rêvasser"
 }
@@ -107,6 +109,15 @@ curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/health
 
 ---
 
+### 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.
 

package/docs/release-health/2026-02-25.md

@@ -0,0 +1,33 @@
+# Release Health Snapshot
+
+- Generated: 2026-02-25T06:14:12.948Z
+- Repo: `jtalk22/slack-mcp-server`
+- Package: `@jtalk22/slack-mcp`
+
+## Install Signals
+
+- npm downloads (last week): 139
+- npm downloads (last month): 632
+- npm latest version: 1.2.3
+
+## GitHub Reach
+
+- stars: 13
+- forks: 8
+- open issues: 0
+- 14d views: 497
+- 14d unique visitors: 259
+- 14d clones: 118
+- 14d unique cloners: 67
+- deployment-intake submissions (all-time): 1
+
+## 14-Day Reliability Targets (v1.2.3 Cycle)
+
+- weekly downloads: >= 180
+- qualified deployment-intake submissions: >= 2
+- maintainer support load: <= 2 hours/week
+
+## Notes
+
+- Update this snapshot daily during the first week, then every 2-3 days.
+- Track deployment-intake quality and support load manually in issue notes.

package/docs/release-health/2026-02-26.md

@@ -0,0 +1,33 @@
+# Release Health Snapshot
+
+- Generated: 2026-02-26T09:32:53.328Z
+- Repo: `jtalk22/slack-mcp-server`
+- Package: `@jtalk22/slack-mcp`
+
+## Install Signals
+
+- npm downloads (last week): 532
+- npm downloads (last month): 1011
+- npm latest version: 1.2.3
+
+## GitHub Reach
+
+- stars: 13
+- forks: 8
+- open issues: 0
+- 14d views: 498
+- 14d unique visitors: 263
+- 14d clones: 338
+- 14d unique cloners: 113
+- deployment-intake submissions (all-time): 1
+
+## 14-Day Reliability Targets (v1.2.3 Cycle)
+
+- weekly downloads: >= 180
+- qualified deployment-intake submissions: >= 2
+- maintainer support load: <= 2 hours/week
+
+## Notes
+
+- Update this snapshot daily during active release windows, then weekly.
+- Track deployment-intake quality and support load manually in issue notes.

package/docs/release-health/24h-delta.md

@@ -0,0 +1,21 @@
+# 24-Hour Release Health Delta
+
+- Window start snapshot: docs/release-health/24h-start.md
+- Window end snapshot: docs/release-health/24h-end.md
+
+| Metric | Start | End | Delta |
+|---|---:|---:|---:|
+| npm downloads (last week) | 532 | 532 | 0 |
+| npm downloads (last month) | 1011 | 1011 | 0 |
+| stars | 13 | 13 | 0 |
+| forks | 8 | 8 | 0 |
+| open issues | 0 | 0 | 0 |
+| 14d views | 498 | 498 | 0 |
+| 14d unique visitors | 263 | 263 | 0 |
+| 14d clones | 338 | 338 | 0 |
+| 14d unique cloners | 113 | 113 | 0 |
+| deployment-intake submissions (all-time) | 1 | 1 | 0 |
+
+## Qualitative Signal
+
+- External "first run succeeded" confirmations (issues/discussions): track manually in cycle notes.

package/docs/release-health/24h-end.md

@@ -0,0 +1,33 @@
+# Release Health Snapshot
+
+- Generated: 2026-02-26T09:32:53.328Z
+- Repo: `jtalk22/slack-mcp-server`
+- Package: `@jtalk22/slack-mcp`
+
+## Install Signals
+
+- npm downloads (last week): 532
+- npm downloads (last month): 1011
+- npm latest version: 1.2.3
+
+## GitHub Reach
+
+- stars: 13
+- forks: 8
+- open issues: 0
+- 14d views: 498
+- 14d unique visitors: 263
+- 14d clones: 338
+- 14d unique cloners: 113
+- deployment-intake submissions (all-time): 1
+
+## 14-Day Reliability Targets (v1.2.3 Cycle)
+
+- weekly downloads: >= 180
+- qualified deployment-intake submissions: >= 2
+- maintainer support load: <= 2 hours/week
+
+## Notes
+
+- Update this snapshot daily during active release windows, then weekly.
+- Track deployment-intake quality and support load manually in issue notes.

package/docs/release-health/24h-start.md

@@ -0,0 +1,33 @@
+# Release Health Snapshot
+
+- Generated: 2026-02-26T09:32:04.228Z
+- Repo: `jtalk22/slack-mcp-server`
+- Package: `@jtalk22/slack-mcp`
+
+## Install Signals
+
+- npm downloads (last week): 532
+- npm downloads (last month): 1011
+- npm latest version: 1.2.3
+
+## GitHub Reach
+
+- stars: 13
+- forks: 8
+- open issues: 0
+- 14d views: 498
+- 14d unique visitors: 263
+- 14d clones: 338
+- 14d unique cloners: 113
+- deployment-intake submissions (all-time): 1
+
+## 14-Day Reliability Targets (v1.2.3 Cycle)
+
+- weekly downloads: >= 180
+- qualified deployment-intake submissions: >= 2
+- maintainer support load: <= 2 hours/week
+
+## Notes
+
+- Update this snapshot daily during active release windows, then weekly.
+- Track deployment-intake quality and support load manually in issue notes.

package/docs/release-health/latest.md

@@ -0,0 +1,33 @@
+# Release Health Snapshot
+
+- Generated: 2026-02-26T09:32:53.328Z
+- Repo: `jtalk22/slack-mcp-server`
+- Package: `@jtalk22/slack-mcp`
+
+## Install Signals
+
+- npm downloads (last week): 532
+- npm downloads (last month): 1011
+- npm latest version: 1.2.3
+
+## GitHub Reach
+
+- stars: 13
+- forks: 8
+- open issues: 0
+- 14d views: 498
+- 14d unique visitors: 263
+- 14d clones: 338
+- 14d unique cloners: 113
+- deployment-intake submissions (all-time): 1
+
+## 14-Day Reliability Targets (v1.2.3 Cycle)
+
+- weekly downloads: >= 180
+- qualified deployment-intake submissions: >= 2
+- maintainer support load: <= 2 hours/week
+
+## Notes
+
+- Update this snapshot daily during active release windows, then weekly.
+- Track deployment-intake quality and support load manually in issue notes.