@jtalk22/slack-mcp 1.2.2 → 1.2.3

package/README.md

@@ -37,6 +37,8 @@
 
 ---
 
+> Free local-first path: install with `npx -y @jtalk22/slack-mcp`, run on your own machine, and keep full control of session tokens.
+
 ### Why This Exists
 
 I built this because I was working with someone to help me manage a complex workload, and we kept hitting walls. They needed context from my messages—"what did X say about Y?"—and standard app/OAuth flows were too constrained for that workflow.
@@ -100,15 +102,24 @@ Instead of authenticating as a bot, this server leverages your existing Chrome s
 
 **Runtime:** Node.js 20+
 
-### 2-Minute Verify
+### 30-Second Proof
 
 ```bash
 npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --doctor
 npx -y @jtalk22/slack-mcp --setup
-npx -y @jtalk22/slack-mcp --status
 ```
 
-If `--status` returns valid workspace/user info, your install path is working.
+Expected:
+- `--version` prints `slack-mcp-server v1.2.x`
+- `--doctor` returns one clear next action with exit code:
+  - `0` ready
+  - `1` missing credentials
+  - `2` invalid/expired credentials
+  - `3` connectivity/runtime issue
+- `--setup` launches the interactive wizard
+
+Proof script for launch threads: [docs/HN-LAUNCH.md](docs/HN-LAUNCH.md)
 
 ### Option A: npm (Recommended)
 
@@ -130,6 +141,20 @@ npm install
 docker pull ghcr.io/jtalk22/slack-mcp-server:latest
 ```
 
+### Install Sanity (Clean Temp Directory)
+
+```bash
+tmpdir="$(mktemp -d)"
+cd "$tmpdir"
+npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --help
+npx -y @jtalk22/slack-mcp --status
+```
+
+Expected:
+- `--version` and `--help` exit `0`
+- `--status` exits non-zero until credentials are configured
+
 ---
 
 ## Configuration
@@ -300,7 +325,7 @@ npm run web
 
 ```
 ════════════════════════════════════════════════════════════
-  Slack Web API Server v1.2.2
+  Slack Web API Server v1.2.3
 ════════════════════════════════════════════════════════════
 
   Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx
@@ -321,6 +346,7 @@ Just click the link - no copy-paste needed. The key is saved to your browser and
 
 ## Operations Guides
 
+- [Docs Index](docs/INDEX.md) - One-click index for setup, API, troubleshooting, deployment, and support docs
 - [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
@@ -329,6 +355,26 @@ If you're evaluating team rollout, start with [Deployment Modes](docs/DEPLOYMENT
 
 ---
 
+## Getting Help Fast
+
+1. Run:
+   ```bash
+   npx -y @jtalk22/slack-mcp --version
+   npx -y @jtalk22/slack-mcp --doctor
+   ```
+2. If setup fails, run:
+   ```bash
+   npx -y @jtalk22/slack-mcp --setup
+   ```
+3. Open an issue with full environment details:
+   - [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md)
+   - [Deployment Intake Template](.github/ISSUE_TEMPLATE/deployment-intake.md)
+4. Check scope and response targets:
+   - [Support Boundaries](docs/SUPPORT-BOUNDARIES.md)
+   - [Troubleshooting Guide](docs/TROUBLESHOOTING.md)
+
+---
+
 ## Troubleshooting
 
 ### Tokens Expired
@@ -337,6 +383,9 @@ If you're evaluating team rollout, start with [Deployment Modes](docs/DEPLOYMENT
 slack_refresh_tokens  # In Claude
 # Or: npm run tokens:auto
 
+# Package setup wizard
+npx -y @jtalk22/slack-mcp --setup
+
 # Linux/Windows: Manual update
 # Edit ~/.slack-mcp-tokens.json with fresh values
 ```

package/docs/COMMUNICATION-STYLE.md

@@ -18,12 +18,18 @@ Thanks for reporting this.
 Status: fixed in `<version>`.
 
 Included:
-- `<change 1>`
-- `<change 2>`
+- `<fix 1>`
+- `<fix 2>`
+
+Verify:
+- `npx -y @jtalk22/slack-mcp --version`
+- `npx -y @jtalk22/slack-mcp --status`
 
 Install/update:
 - `npx -y @jtalk22/slack-mcp`
 - `npm i -g @jtalk22/slack-mcp@<version>`
+
+If it still reproduces, reply with OS, Node version, runtime mode (`stdio|web|http|worker`), and exact error output.
 ```
 
 ## Release Notes Template
@@ -31,17 +37,18 @@ Install/update:
 ````md
 ## <version> — <short title>
 
-### Fixed
+### Improved
 - <item>
 - <item>
 
-### Runtime / Security
-- <item>
+### Compatibility
+- No API/tool schema changes.
 
 ### Verify
 ```bash
-<command>
-<command>
+npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --setup
+npx -y @jtalk22/slack-mcp --status
 ```
 ````
 

package/docs/HN-LAUNCH.md

@@ -0,0 +1,61 @@
+# HN Launch Kit
+
+Use this file as copy/paste launch material with no extra edits.
+
+## Launch Post Draft
+
+Title idea: `Show HN: Slack MCP Server (local-first, session-based Slack access for Claude)`
+
+Post body:
+
+```md
+Built a local-first Slack MCP server so Claude can use the same Slack access already available in your browser session.
+
+What it does:
+- DMs/channels/thread reads
+- workspace search
+- message send + user lookups
+- local web mode when MCP is unavailable
+
+Quick proof:
+- `npx -y @jtalk22/slack-mcp --version`
+- `npx -y @jtalk22/slack-mcp --status`
+- `npx -y @jtalk22/slack-mcp --setup`
+
+Repo: https://github.com/jtalk22/slack-mcp-server
+npm: https://www.npmjs.com/package/@jtalk22/slack-mcp
+```
+
+## First Comment Draft
+
+```md
+Notes up front:
+- Local-first usage is fully supported.
+- Tokens are your 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
+
+### Is this bypassing Slack app scopes?
+It does not use Slack app OAuth scopes. It uses your 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 this safe for production teams?
+Treat as operator-managed infrastructure. Validate with your own risk/compliance controls before broader rollout.
+
+## Install Proof Block
+
+```bash
+npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --status
+npx -y @jtalk22/slack-mcp --setup
+```

package/docs/INDEX.md

@@ -0,0 +1,28 @@
+# Documentation Index
+
+Start here for setup, validation, operations, and support.
+
+## Core
+
+- [Setup Guide](SETUP.md)
+- [API Reference](API.md)
+- [Web API Reference](WEB-API.md)
+- [Troubleshooting](TROUBLESHOOTING.md)
+
+## Operations
+
+- [Deployment Modes](DEPLOYMENT-MODES.md)
+- [Use Case Recipes](USE_CASE_RECIPES.md)
+- [Support Boundaries](SUPPORT-BOUNDARIES.md)
+
+## Launch and Communication
+
+- [HN Launch Kit](HN-LAUNCH.md)
+- [Communication Style](COMMUNICATION-STYLE.md)
+- [Changelog](../CHANGELOG.md)
+
+## Issue Intake
+
+- [Bug Report Template](../.github/ISSUE_TEMPLATE/bug_report.md)
+- [Feature Request Template](../.github/ISSUE_TEMPLATE/feature_request.md)
+- [Deployment Intake Template](../.github/ISSUE_TEMPLATE/deployment-intake.md)

package/docs/SETUP.md

@@ -23,6 +23,24 @@ cd ~/slack-mcp-server
 npm install
 ```
 
+### 2.5 Verify Install Path in a Clean Directory
+
+```bash
+tmpdir="$(mktemp -d)"
+cd "$tmpdir"
+npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --help
+npx -y @jtalk22/slack-mcp --doctor
+```
+
+Expected:
+- `--version` and `--help` succeed.
+- `--doctor` exits with one clear status:
+  - `0` ready
+  - `1` missing credentials
+  - `2` invalid/expired credentials
+  - `3` connectivity/runtime issue
+
 ### 3. Get Slack Tokens
 
 **Option A: Setup Wizard (recommended)**
@@ -120,11 +138,11 @@ You should see your username and team name.
 
 ### "No credentials found"
 
-Run `npx -y @jtalk22/slack-mcp --setup` with Slack open in Chrome, or `npm run tokens:refresh` to enter manually.
+Run `npx -y @jtalk22/slack-mcp --doctor` to confirm diagnostic code, then `npx -y @jtalk22/slack-mcp --setup` with Slack open in Chrome.
 
 ### "invalid_auth" Error
 
-Tokens have expired. Open Slack in Chrome and use `slack_refresh_tokens` in Claude Code.
+Tokens have expired. Run `npx -y @jtalk22/slack-mcp --doctor` and follow the suggested next action.
 
 ### MCP Server Not Loading
 

package/docs/TROUBLESHOOTING.md

@@ -4,6 +4,30 @@ Common issues and their solutions.
 
 ---
 
+## Install Flow Sanity Check
+
+If first-run setup is failing, validate command resolution in a clean directory:
+
+```bash
+tmpdir="$(mktemp -d)"
+cd "$tmpdir"
+npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --help
+npx -y @jtalk22/slack-mcp --doctor
+```
+
+Expected:
+- `--version` and `--help` exit `0`
+- `--doctor` exits with one of:
+  - `0` ready
+  - `1` missing credentials
+  - `2` invalid/expired credentials
+  - `3` connectivity/runtime issue
+
+If `--version` fails here, the issue is install/runtime path, not Slack credentials.
+
+---
+
 ## DMs Not Showing Up
 
 **Symptom:** `slack_list_conversations` returns channels but no DMs.
@@ -57,6 +81,9 @@ slack_refresh_tokens
 # Option 2: Package setup wizard
 npx -y @jtalk22/slack-mcp --setup
 
+# Option 3: Doctor diagnostics
+npx -y @jtalk22/slack-mcp --doctor
+
 # Option 3: Repo CLI
 npm run tokens:auto
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jtalk22/slack-mcp",
   "mcpName": "io.github.jtalk22/slack-mcp-server",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Session-based Slack access for Claude - DMs, channels, search, and threads. Local-first with your existing Slack session.",
   "type": "module",
   "main": "src/server.js",

package/public/demo-claude.html

@@ -12,19 +12,19 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <meta name="author" content="@jtalk22">
   <title>Slack MCP Server - Claude Desktop Demo</title>
-  <meta name="description" content="Session-based Slack access demo showing Claude workflows for DMs, channels, search, and threads.">
+  <meta name="description" content="Session-based Slack access for Claude with your existing workspace permissions. Demo workflows for DMs, channels, search, and threads.">
 
   <!-- Open Graph -->
-  <meta property="og:title" content="Slack MCP Server - Session Access Demo">
-  <meta property="og:description" content="Interactive demo showing Claude using session-based Slack MCP tools for search, threads, and messaging workflows.">
+  <meta property="og:title" content="Slack MCP Server - Session-Based Slack Access Demo">
+  <meta property="og:description" content="Session-based Slack access for Claude with your existing workspace permissions. Search, thread, and messaging workflows.">
   <meta property="og:type" content="website">
   <meta property="og:url" content="https://jtalk22.github.io/slack-mcp-server/public/demo-claude.html">
   <meta property="og:image" content="https://assets-worker.james-20a.workers.dev/projects/slack-mcp-server/demo-claude.gif">
 
   <!-- Twitter Card -->
   <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Slack MCP Server - Session Access Demo">
-  <meta name="twitter:description" content="Interactive demo showing Claude using session-based Slack MCP tools for search, threads, and messaging workflows.">
+  <meta name="twitter:title" content="Slack MCP Server - Session-Based Slack Access Demo">
+  <meta name="twitter:description" content="Session-based Slack access for Claude with your existing workspace permissions. Search, thread, and messaging workflows.">
   <meta name="twitter:image" content="https://assets-worker.james-20a.workers.dev/projects/slack-mcp-server/demo-claude.gif">
 
   <!-- Theme -->
@@ -1151,17 +1151,17 @@
   <div class="cta-strip">
     <div class="links">
       <a href="https://www.npmjs.com/package/@jtalk22/slack-mcp" target="_blank" rel="noopener noreferrer">Install</a>
-      <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/API.md" target="_blank" rel="noopener noreferrer">API Docs</a>
-      <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/CHANGELOG.md" target="_blank" rel="noopener noreferrer">Changelog</a>
+      <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/SETUP.md" target="_blank" rel="noopener noreferrer">Setup Guide</a>
+      <a href="https://github.com/jtalk22/slack-mcp-server#30-second-proof" target="_blank" rel="noopener noreferrer">30-Second Proof</a>
     </div>
     <div class="note">
-      Team rollout? Review <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md" target="_blank" rel="noopener noreferrer">Deployment Modes</a>.
+      Free local-first path with optional team rollout guidance in <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md" target="_blank" rel="noopener noreferrer">Deployment Modes</a>.
     </div>
   </div>
   <header class="page-header">
     <h1>
       <span>Slack MCP Server</span>
-      <span class="badge">🔧 MCP Demo v1.2.2</span>
+      <span class="badge">🔧 MCP Demo v1.2.3</span>
     </h1>
     <p>See how Claude uses MCP tools to access your Slack workspace</p>
   </header>
@@ -1233,7 +1233,7 @@
       <div class="title-logo">💬</div>
       <h1>Slack MCP Server</h1>
       <p class="title-tagline">Full Slack access for Claude Desktop</p>
-      <p class="title-version">v1.2.2 • @jtalk22</p>
+      <p class="title-version">v1.2.3 • @jtalk22</p>
     </div>
 
     <!-- Scenario Caption Overlay -->

package/public/demo-video.html

@@ -4,15 +4,15 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Slack MCP Server Demo</title>
-  <meta name="description" content="Video demo of session-based Slack access for Claude with DMs, channels, search, and threads.">
+  <meta name="description" content="Session-based Slack access for Claude with your existing workspace permissions. Video demo for DMs, channels, search, and threads.">
   <meta property="og:type" content="website">
-  <meta property="og:title" content="Slack MCP Server - Session Access Demo">
-  <meta property="og:description" content="Video walkthrough of session-based Slack workflows in Claude.">
+  <meta property="og:title" content="Slack MCP Server - Session-Based Slack Access Demo">
+  <meta property="og:description" content="Session-based Slack access for Claude with your existing workspace permissions. Video walkthrough for Slack workflows.">
   <meta property="og:url" content="https://jtalk22.github.io/slack-mcp-server/public/demo-video.html">
   <meta property="og:image" content="https://raw.githubusercontent.com/jtalk22/slack-mcp-server/main/docs/images/demo-poster.png">
   <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Slack MCP Server - Session Access Demo">
-  <meta name="twitter:description" content="Video walkthrough of session-based Slack workflows in Claude.">
+  <meta name="twitter:title" content="Slack MCP Server - Session-Based Slack Access Demo">
+  <meta name="twitter:description" content="Session-based Slack access for Claude with your existing workspace permissions. Video walkthrough for Slack workflows.">
   <meta name="twitter:image" content="https://raw.githubusercontent.com/jtalk22/slack-mcp-server/main/docs/images/demo-poster.png">
   <style>
     * {
@@ -142,15 +142,15 @@
 <body>
   <div class="container">
     <h1>Slack MCP Server</h1>
-    <p class="subtitle">Full workspace access via local session mirroring</p>
+    <p class="subtitle">Free local-first Slack access using your existing session permissions</p>
     <div class="cta-strip">
       <div class="links">
         <a href="https://www.npmjs.com/package/@jtalk22/slack-mcp" target="_blank" rel="noopener noreferrer">Install</a>
-        <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/API.md" target="_blank" rel="noopener noreferrer">API Docs</a>
-        <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/CHANGELOG.md" target="_blank" rel="noopener noreferrer">Changelog</a>
+        <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/SETUP.md" target="_blank" rel="noopener noreferrer">Setup Guide</a>
+        <a href="https://github.com/jtalk22/slack-mcp-server#30-second-proof" target="_blank" rel="noopener noreferrer">30-Second Proof</a>
       </div>
       <div class="note">
-        Team rollout? Review <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md" target="_blank" rel="noopener noreferrer">Deployment Modes</a>.
+        Free local-first path with optional team rollout guidance in <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md" target="_blank" rel="noopener noreferrer">Deployment Modes</a>.
       </div>
     </div>
 

package/public/demo.html

@@ -8,18 +8,18 @@
   <!-- Open Graph / Social Sharing -->
   <meta property="og:type" content="website">
   <meta property="og:url" content="https://jtalk22.github.io/slack-mcp-server/public/demo.html">
-  <meta property="og:title" content="Slack MCP Server - Session Access Demo">
-  <meta property="og:description" content="Interactive demo for session-based Slack access in Claude: DMs, channels, search, and threads.">
+  <meta property="og:title" content="Slack MCP Server - Session-Based Slack Access Demo">
+  <meta property="og:description" content="Session-based Slack access for Claude with your existing workspace permissions. DMs, channels, search, and threads.">
   <meta property="og:image" content="https://raw.githubusercontent.com/jtalk22/slack-mcp-server/main/docs/images/demo-main.png">
 
   <!-- Twitter Card -->
   <meta name="twitter:card" content="summary_large_image">
-  <meta name="twitter:title" content="Slack MCP Server - Session Access Demo">
-  <meta name="twitter:description" content="Interactive demo for session-based Slack access in Claude: DMs, channels, search, and threads.">
+  <meta name="twitter:title" content="Slack MCP Server - Session-Based Slack Access Demo">
+  <meta name="twitter:description" content="Session-based Slack access for Claude with your existing workspace permissions. DMs, channels, search, and threads.">
   <meta name="twitter:image" content="https://raw.githubusercontent.com/jtalk22/slack-mcp-server/main/docs/images/demo-main.png">
 
   <!-- SEO -->
-  <meta name="description" content="Session-based Slack access for Claude. Interactive demo for DMs, channels, search, and thread workflows.">
+  <meta name="description" content="Session-based Slack access for Claude with your existing workspace permissions. Interactive demo for DMs, channels, search, and thread workflows.">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
@@ -636,11 +636,11 @@
   <div class="cta-strip">
     <div class="cta-links">
       <a href="https://www.npmjs.com/package/@jtalk22/slack-mcp" target="_blank" rel="noopener noreferrer">Install</a>
-      <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/API.md" target="_blank" rel="noopener noreferrer">API Docs</a>
-      <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/CHANGELOG.md" target="_blank" rel="noopener noreferrer">Changelog</a>
+      <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/SETUP.md" target="_blank" rel="noopener noreferrer">Setup Guide</a>
+      <a href="https://github.com/jtalk22/slack-mcp-server#30-second-proof" target="_blank" rel="noopener noreferrer">30-Second Proof</a>
     </div>
     <div class="cta-note">
-      Team rollout? Review <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md" target="_blank" rel="noopener noreferrer">Deployment Modes</a>.
+      Free local-first path with optional team rollout guidance in <a href="https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md" target="_blank" rel="noopener noreferrer">Deployment Modes</a>.
     </div>
   </div>
 

package/scripts/setup-wizard.js

@@ -12,11 +12,19 @@
 
 import { platform } from "os";
 import * as readline from "readline";
-import { loadTokens, saveTokens, extractFromChrome, isAutoRefreshAvailable, TOKEN_FILE } from "../lib/token-store.js";
-import { slackAPI } from "../lib/slack-client.js";
+import {
+  loadTokens,
+  saveTokens,
+  extractFromChrome,
+  isAutoRefreshAvailable,
+  TOKEN_FILE,
+  getFromFile,
+  getFromKeychain,
+} from "../lib/token-store.js";
 
 const IS_MACOS = platform() === 'darwin';
-const VERSION = "1.2.2";
+const VERSION = "1.2.3";
+const MIN_NODE_MAJOR = 20;
 
 // ANSI colors
 const colors = {
@@ -69,27 +77,25 @@ async function pressEnterToContinue(rl) {
 }
 
 async function validateTokens(token, cookie) {
-  const hadOldToken = Object.prototype.hasOwnProperty.call(process.env, "SLACK_TOKEN");
-  const hadOldCookie = Object.prototype.hasOwnProperty.call(process.env, "SLACK_COOKIE");
-  const oldToken = process.env.SLACK_TOKEN;
-  const oldCookie = process.env.SLACK_COOKIE;
-
-  // Temporarily set env vars for validation
-  process.env.SLACK_TOKEN = token;
-  process.env.SLACK_COOKIE = cookie;
-
   try {
-    const result = await slackAPI("auth.test", {});
-    return { valid: true, user: result.user, team: result.team };
+    const response = await fetch("https://slack.com/api/auth.test", {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${token}`,
+        "Cookie": `d=${cookie}`,
+        "Content-Type": "application/json; charset=utf-8",
+      },
+      body: JSON.stringify({}),
+    });
+
+    const result = await response.json();
+    if (!result.ok) {
+      return { valid: false, error: result.error || "auth.test_failed" };
+    }
+
+    return { valid: true, user: result.user, team: result.team, userId: result.user_id };
   } catch (e) {
     return { valid: false, error: e.message };
-  } finally {
-    // Always restore prior process env state
-    if (hadOldToken) process.env.SLACK_TOKEN = oldToken;
-    else delete process.env.SLACK_TOKEN;
-
-    if (hadOldCookie) process.env.SLACK_COOKIE = oldCookie;
-    else delete process.env.SLACK_COOKIE;
   }
 }
 
@@ -243,23 +249,118 @@ async function showStatus() {
   }
   print();
 
-  try {
-    // Need to set env vars for slackAPI to work
-    process.env.SLACK_TOKEN = creds.token;
-    process.env.SLACK_COOKIE = creds.cookie;
-
-    const result = await slackAPI("auth.test", {});
-    success("Status: VALID");
-    print(`User: ${result.user}`);
-    print(`Team: ${result.team}`);
-    print(`User ID: ${result.user_id}`);
-  } catch (e) {
+  const result = await validateTokens(creds.token, creds.cookie);
+  if (!result.valid) {
     error("Status: INVALID");
-    print(`Error: ${e.message}`);
+    print(`Error: ${result.error}`);
     print();
     print("Run setup wizard to refresh: npx -y @jtalk22/slack-mcp --setup");
     process.exit(1);
   }
+
+  success("Status: VALID");
+  print(`User: ${result.user}`);
+  print(`Team: ${result.team}`);
+  print(`User ID: ${result.userId}`);
+}
+
+function getDoctorCredentials() {
+  if (process.env.SLACK_TOKEN && process.env.SLACK_COOKIE) {
+    return { token: process.env.SLACK_TOKEN, cookie: process.env.SLACK_COOKIE, source: "environment" };
+  }
+
+  const fileTokens = getFromFile();
+  if (fileTokens?.token && fileTokens?.cookie) {
+    return {
+      token: fileTokens.token,
+      cookie: fileTokens.cookie,
+      source: "file",
+      path: TOKEN_FILE,
+      updatedAt: fileTokens.updatedAt,
+    };
+  }
+
+  if (IS_MACOS) {
+    const keychainToken = getFromKeychain("token");
+    const keychainCookie = getFromKeychain("cookie");
+    if (keychainToken && keychainCookie) {
+      return { token: keychainToken, cookie: keychainCookie, source: "keychain" };
+    }
+  }
+
+  return null;
+}
+
+function classifyAuthError(rawError) {
+  const msg = String(rawError || "").toLowerCase();
+  if (
+    msg.includes("invalid_auth") ||
+    msg.includes("token_expired") ||
+    msg.includes("not_authed") ||
+    msg.includes("account_inactive")
+  ) {
+    return 2;
+  }
+  return 3;
+}
+
+function parseNodeMajor() {
+  return Number.parseInt(process.versions.node.split(".")[0], 10);
+}
+
+async function runDoctor() {
+  print(`${colors.bold}slack-mcp-server doctor${colors.reset}`);
+  print();
+
+  const nodeMajor = parseNodeMajor();
+  if (Number.isNaN(nodeMajor) || nodeMajor < MIN_NODE_MAJOR) {
+    error(`Node.js ${process.versions.node} detected (requires Node ${MIN_NODE_MAJOR}+)`);
+    print();
+    print("Next action:");
+    print(`  npx -y @jtalk22/slack-mcp --doctor  # rerun after upgrading Node ${MIN_NODE_MAJOR}+`);
+    process.exit(3);
+  }
+  success(`Node.js ${process.versions.node} (supported)`);
+
+  const creds = getDoctorCredentials();
+  if (!creds) {
+    error("Credentials: not found");
+    print();
+    print("Next action:");
+    print("  npx -y @jtalk22/slack-mcp --setup");
+    process.exit(1);
+  }
+
+  success(`Credentials loaded from: ${creds.source}`);
+  if (creds.path) {
+    print(`Path: ${creds.path}`);
+  }
+  if (creds.updatedAt) {
+    print(`Last updated: ${creds.updatedAt}`);
+  }
+
+  print();
+  print("Validating Slack auth...");
+  const validation = await validateTokens(creds.token, creds.cookie);
+  if (!validation.valid) {
+    const exitCode = classifyAuthError(validation.error);
+    error(`Slack auth failed: ${validation.error}`);
+    print();
+    print("Next action:");
+    if (exitCode === 2) {
+      print("  npx -y @jtalk22/slack-mcp --setup");
+    } else {
+      print("  Check network connectivity and retry:");
+      print("  npx -y @jtalk22/slack-mcp --doctor");
+    }
+    process.exit(exitCode);
+  }
+
+  success(`Slack auth valid for ${validation.user} @ ${validation.team}`);
+  print();
+  print("Ready. Next command:");
+  print("  npx -y @jtalk22/slack-mcp");
+  process.exit(0);
 }
 
 async function showHelp() {
@@ -271,6 +372,7 @@ async function showHelp() {
   print("  npx -y @jtalk22/slack-mcp             Start MCP server (stdio)");
   print("  npx -y @jtalk22/slack-mcp --setup     Interactive token setup wizard");
   print("  npx -y @jtalk22/slack-mcp --status    Check token health");
+  print("  npx -y @jtalk22/slack-mcp --doctor    Run runtime and auth diagnostics");
   print("  npx -y @jtalk22/slack-mcp --version   Print version");
   print("  npx -y @jtalk22/slack-mcp --help      Show this help");
   print();
@@ -296,6 +398,10 @@ async function main() {
     case 'status':
       await showStatus();
       return;
+    case '--doctor':
+    case 'doctor':
+      await runDoctor();
+      return;
     case '--version':
     case '-v':
       print(`slack-mcp-server v${VERSION}`);

package/scripts/verify-install-flow.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PKG = "@jtalk22/slack-mcp";
+
+function runNpx(args, options = {}) {
+  const cmdArgs = ["-y", PKG, ...args];
+  const result = spawnSync("npx", cmdArgs, {
+    cwd: options.cwd,
+    env: options.env,
+    encoding: "utf8",
+    timeout: 120000,
+  });
+
+  return {
+    args: cmdArgs.join(" "),
+    status: result.status,
+    stdout: (result.stdout || "").trim(),
+    stderr: (result.stderr || "").trim(),
+    error: result.error,
+  };
+}
+
+function assert(condition, message, details = "") {
+  if (!condition) {
+    const suffix = details ? `\n${details}` : "";
+    throw new Error(`${message}${suffix}`);
+  }
+}
+
+function printResult(label, result) {
+  console.log(`\n[${label}] npx ${result.args}`);
+  console.log(`exit=${result.status}`);
+  if (result.stdout) {
+    console.log("stdout:");
+    console.log(result.stdout);
+  }
+  if (result.stderr) {
+    console.log("stderr:");
+    console.log(result.stderr);
+  }
+}
+
+function main() {
+  const testHome = mkdtempSync(join(tmpdir(), "slack-mcp-install-check-"));
+
+  // Force a clean environment so --status reflects missing credentials.
+  const env = { ...process.env, HOME: testHome, USERPROFILE: testHome };
+  delete env.SLACK_TOKEN;
+  delete env.SLACK_COOKIE;
+
+  try {
+    const versionResult = runNpx(["--version"], { cwd: testHome, env });
+    printResult("version", versionResult);
+    assert(
+      versionResult.status === 0,
+      "Expected --version to exit 0",
+      versionResult.stderr || versionResult.stdout,
+    );
+
+    const helpResult = runNpx(["--help"], { cwd: testHome, env });
+    printResult("help", helpResult);
+    assert(
+      helpResult.status === 0,
+      "Expected --help to exit 0",
+      helpResult.stderr || helpResult.stdout,
+    );
+
+    const statusResult = runNpx(["--status"], { cwd: testHome, env });
+    printResult("status", statusResult);
+    assert(
+      statusResult.status !== 0,
+      "Expected --status to exit non-zero when credentials are missing",
+      statusResult.stderr || statusResult.stdout,
+    );
+
+    console.log("\nInstall flow verification passed.");
+  } finally {
+    rmSync(testHome, { recursive: true, force: true });
+  }
+}
+
+main();

package/src/cli.js

@@ -20,6 +20,7 @@ const firstArg = args[0];
 const WIZARD_ARGS = new Set([
   "--setup", "setup",
   "--status", "status",
+  "--doctor", "doctor",
   "--version", "-v",
   "--help", "-h", "help",
 ]);

package/src/server-http.js

@@ -30,7 +30,7 @@ import {
 } from "../lib/handlers.js";
 
 const SERVER_NAME = "slack-mcp-server";
-const SERVER_VERSION = "1.2.2";
+const SERVER_VERSION = "1.2.3";
 const PORT = process.env.PORT || 3000;
 
 // Create MCP server

package/src/server.js

@@ -11,7 +11,7 @@
  * - Network error retry with exponential backoff
  * - Background token health monitoring
  *
- * @version 1.2.2
+ * @version 1.2.3
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -47,7 +47,7 @@ const BACKGROUND_REFRESH_INTERVAL = 4 * 60 * 60 * 1000;
 
 // Package info
 const SERVER_NAME = "slack-mcp-server";
-const SERVER_VERSION = "1.2.2";
+const SERVER_VERSION = "1.2.3";
 
 // MCP Prompts - predefined prompt templates for common Slack operations
 const PROMPTS = [

package/src/web-server.js

@@ -5,7 +5,7 @@
  * Exposes Slack MCP tools as REST endpoints for browser access.
  * Run alongside or instead of the MCP server for web-based access.
  *
- * @version 1.2.2
+ * @version 1.2.3
  */
 
 import express from "express";
@@ -116,7 +116,7 @@ function extractContent(result) {
 app.get("/", (req, res) => {
   res.json({
     name: "Slack Web API Server",
-    version: "1.2.2",
+    version: "1.2.3",
     status: "running",
     endpoints: [
       "GET  /health",
@@ -295,7 +295,7 @@ async function main() {
   app.listen(PORT, '127.0.0.1', () => {
     // Print to stderr to keep logs clean (stdout reserved for JSON in some setups)
     console.error(`\n${"═".repeat(60)}`);
-    console.error(`  Slack Web API Server v1.2.2`);
+    console.error(`  Slack Web API Server v1.2.3`);
     console.error(`${"═".repeat(60)}`);
     console.error(`\n  Dashboard: http://localhost:${PORT}/?key=${API_KEY}`);
     console.error(`\n  API Key:   ${API_KEY}`);