@jtalk22/slack-mcp 1.2.2 → 1.2.4

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.

package/lib/handlers.js

@@ -8,7 +8,13 @@ import { writeFileSync, readFileSync, existsSync, renameSync, unlinkSync, mkdirS
 import { execSync } from "child_process";
 import { homedir, platform } from "os";
 import { join } from "path";
-import { loadTokens, saveTokens, extractFromChrome, isAutoRefreshAvailable } from "./token-store.js";
+import {
+  loadTokensReadOnly,
+  saveTokens,
+  extractFromChrome,
+  isAutoRefreshAvailable,
+  getLastExtractionError
+} from "./token-store.js";
 import { slackAPI, resolveUser, formatTimestamp, sleep, checkTokenHealth, getUserCacheStats } from "./slack-client.js";
 
 // ============ Utilities ============
@@ -26,6 +32,16 @@ function parseBool(val) {
   return false;
 }
 
+function asMcpJson(payload, isError = false) {
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify(payload, null, 2)
+    }],
+    ...(isError ? { isError: true } : {})
+  };
+}
+
 /**
  * Atomic write to prevent file corruption from concurrent writes
  */
@@ -77,72 +93,75 @@ export async function handleTokenStatus() {
   const health = await checkTokenHealth({ error: () => {} });
   const cacheStats = getUserCacheStats();
   const dmCache = loadDMCache();
-
-  return {
-    content: [{
-      type: "text",
-      text: JSON.stringify({
-        token: {
-          status: health.healthy ? "healthy" : health.reason === 'no_tokens' ? "missing" : "warning",
-          age_hours: health.age_hours,
-          source: health.source,
-          updated_at: health.updated_at,
-          message: health.message
-        },
-        auto_refresh: {
-          enabled: true,
-          interval: "4 hours",
-          last_attempt: health.refreshed ? "just now" : "on-demand",
-          requires: "Slack tab open in Chrome"
-        },
-        cache: {
-          users: cacheStats,
-          dms: {
-            count: Object.keys(dmCache.dms || {}).length,
-            age_hours: dmCache.updated ? Math.round((Date.now() - dmCache.updated) / (60 * 60 * 1000) * 10) / 10 : null
-          }
-        }
-      }, null, 2)
-    }]
-  };
+  const tokenStatus = health.reason === 'no_tokens'
+    ? "missing"
+    : health.critical
+      ? "critical"
+      : health.warning
+        ? "warning"
+        : "healthy";
+
+  return asMcpJson({
+    status: tokenStatus,
+    code: health.reason || (health.critical ? "token_critical" : health.warning ? "token_warning" : "ok"),
+    message: health.message,
+    next_action: health.reason === 'no_tokens' ? "Run npx -y @jtalk22/slack-mcp --setup" : null,
+    token: {
+      status: tokenStatus,
+      age_hours: health.age_hours,
+      source: health.source,
+      updated_at: health.updated_at
+    },
+    auto_refresh: {
+      enabled: isAutoRefreshAvailable(),
+      interval: "4 hours",
+      last_attempt: health.refreshed ? "just_now" : null,
+      requires: isAutoRefreshAvailable() ? "Slack tab open in Chrome" : "Not supported on this platform"
+    },
+    cache: {
+      users: cacheStats,
+      dms: {
+        count: Object.keys(dmCache.dms || {}).length,
+        age_hours: dmCache.updated ? Math.round((Date.now() - dmCache.updated) / (60 * 60 * 1000) * 10) / 10 : null
+      }
+    }
+  });
 }
 
 /**
  * Health check handler
  */
 export async function handleHealthCheck() {
-  const creds = loadTokens();
+  const creds = loadTokensReadOnly();
   if (!creds) {
-    return {
-      content: [{
-        type: "text",
-        text: "NO CREDENTIALS\n\nOptions:\n1. Open Slack in Chrome, then use slack_refresh_tokens\n2. Run: npx -y @jtalk22/slack-mcp --setup"
-      }],
-      isError: true
-    };
+    return asMcpJson({
+      status: "error",
+      code: "missing_credentials",
+      message: "No credentials found",
+      next_action: "Run npx -y @jtalk22/slack-mcp --setup"
+    }, true);
   }
 
   try {
-    const result = await slackAPI("auth.test", {});
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          status: "OK",
-          user: result.user,
-          user_id: result.user_id,
-          team: result.team,
-          team_id: result.team_id,
-          token_source: creds.source,
-          token_updated: creds.updatedAt || "unknown"
-        }, null, 2)
-      }]
-    };
+    const result = await slackAPI("auth.test", {}, { retryOnAuthFail: false });
+    return asMcpJson({
+      status: "ok",
+      code: "ok",
+      message: "Slack auth valid",
+      user: result.user,
+      user_id: result.user_id,
+      team: result.team,
+      team_id: result.team_id,
+      token_source: creds.source,
+      token_updated: creds.updatedAt || null
+    });
   } catch (e) {
-    return {
-      content: [{ type: "text", text: `AUTH FAILED: ${e.message}` }],
-      isError: true
-    };
+    return asMcpJson({
+      status: "error",
+      code: "auth_failed",
+      message: e.message,
+      next_action: "Run npx -y @jtalk22/slack-mcp --setup"
+    }, true);
   }
 }
 
@@ -152,13 +171,12 @@ export async function handleHealthCheck() {
 export async function handleRefreshTokens() {
   // Check platform support
   if (!isAutoRefreshAvailable()) {
-    return {
-      content: [{
-        type: "text",
-        text: "Auto-refresh is only available on macOS.\n\nOn other platforms, manually update ~/.slack-mcp-tokens.json with:\n{\n  \"SLACK_TOKEN\": \"xoxc-...\",\n  \"SLACK_COOKIE\": \"xoxd-...\"\n}"
-      }],
-      isError: true
-    };
+    return asMcpJson({
+      status: "error",
+      code: "unsupported_platform",
+      message: "Auto-refresh is only available on macOS.",
+      next_action: "Manually update ~/.slack-mcp-tokens.json with SLACK_TOKEN and SLACK_COOKIE."
+    }, true);
   }
 
   const chromeTokens = extractFromChrome();
@@ -166,31 +184,41 @@ export async function handleRefreshTokens() {
     saveTokens(chromeTokens.token, chromeTokens.cookie);
     try {
       const result = await slackAPI("auth.test", {}, { retryOnAuthFail: false });
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            status: "SUCCESS",
-            message: "Tokens refreshed from Chrome!",
-            user: result.user,
-            team: result.team
-          }, null, 2)
-        }]
-      };
+      return asMcpJson({
+        status: "ok",
+        code: "refreshed",
+        message: "Tokens refreshed from Chrome.",
+        user: result.user,
+        team: result.team
+      });
     } catch (e) {
-      return {
-        content: [{ type: "text", text: `Extracted but invalid: ${e.message}` }],
-        isError: true
-      };
+      return asMcpJson({
+        status: "error",
+        code: "auth_failed_after_refresh",
+        message: e.message,
+        next_action: "Refresh Slack in Chrome and rerun slack_refresh_tokens."
+      }, true);
     }
   }
-  return {
-    content: [{
-      type: "text",
-      text: "Could not extract from Chrome.\n\nMake sure:\n1. Chrome is running\n2. Slack tab is open (app.slack.com)\n3. You're logged into Slack"
-    }],
-    isError: true
-  };
+
+  const extractionError = getLastExtractionError();
+  if (extractionError?.code === "apple_events_javascript_disabled") {
+    return asMcpJson({
+      status: "error",
+      code: extractionError.code,
+      message: extractionError.message,
+      detail: extractionError.detail,
+      next_action: "In Chrome: View > Developer > Allow JavaScript from Apple Events, then retry."
+    }, true);
+  }
+
+  return asMcpJson({
+    status: "error",
+    code: extractionError?.code || "chrome_extraction_failed",
+    message: extractionError?.message || "Could not extract tokens from Chrome.",
+    detail: extractionError?.detail || "Ensure Chrome is running with a logged-in Slack tab at app.slack.com.",
+    next_action: "Open Slack in Chrome and run slack_refresh_tokens again."
+  }, true);
 }
 
 /**

package/lib/slack-client.js

@@ -13,8 +13,8 @@ import { loadTokens, saveTokens, extractFromChrome } from "./token-store.js";
 
 // ============ Configuration ============
 
-const TOKEN_WARNING_AGE = 6 * 60 * 60 * 1000;  // 6 hours
-const TOKEN_CRITICAL_AGE = 10 * 60 * 60 * 1000; // 10 hours
+const TOKEN_WARNING_AGE = 10 * 24 * 60 * 60 * 1000;   // 10 days
+const TOKEN_CRITICAL_AGE = 13 * 24 * 60 * 60 * 1000;  // 13 days
 const REFRESH_COOLDOWN = 60 * 60 * 1000;        // 1 hour between refresh attempts
 const USER_CACHE_MAX_SIZE = 500;
 const USER_CACHE_TTL = 60 * 60 * 1000;          // 1 hour
@@ -94,19 +94,21 @@ const userCache = new LRUCache(USER_CACHE_MAX_SIZE, USER_CACHE_TTL);
  */
 export async function checkTokenHealth(logger = console) {
   const silentLogger = { error: () => {}, warn: () => {}, log: () => {} };
-  const creds = loadTokens(false, silentLogger);
+  const creds = loadTokens(false, silentLogger, { autoExtract: false });
 
   if (!creds) {
     return { healthy: false, reason: 'no_tokens', message: 'No credentials found' };
   }
 
-  const tokenAge = creds.updatedAt
-    ? Date.now() - new Date(creds.updatedAt).getTime()
-    : Infinity;
-  const ageHours = Math.round(tokenAge / (60 * 60 * 1000) * 10) / 10;
+  const updatedAtMs = creds.updatedAt ? new Date(creds.updatedAt).getTime() : Number.NaN;
+  const hasKnownAge = Number.isFinite(updatedAtMs);
+  const tokenAge = hasKnownAge ? Date.now() - updatedAtMs : null;
+  const ageHours = hasKnownAge
+    ? Math.round(tokenAge / (60 * 60 * 1000) * 10) / 10
+    : null;
 
   // Attempt proactive refresh if token is getting old
-  if (tokenAge > TOKEN_WARNING_AGE && Date.now() - lastRefreshAttempt > REFRESH_COOLDOWN) {
+  if (hasKnownAge && tokenAge > TOKEN_WARNING_AGE && Date.now() - lastRefreshAttempt > REFRESH_COOLDOWN) {
     lastRefreshAttempt = Date.now();
     logger.error?.(`Token is ${ageHours}h old, attempting proactive refresh...`);
 
@@ -127,17 +129,19 @@ export async function checkTokenHealth(logger = console) {
   }
 
   return {
-    healthy: tokenAge < TOKEN_CRITICAL_AGE,
+    healthy: !hasKnownAge || tokenAge < TOKEN_CRITICAL_AGE,
     age_hours: ageHours,
-    warning: tokenAge > TOKEN_WARNING_AGE,
-    critical: tokenAge > TOKEN_CRITICAL_AGE,
+    warning: hasKnownAge && tokenAge > TOKEN_WARNING_AGE,
+    critical: hasKnownAge && tokenAge > TOKEN_CRITICAL_AGE,
     source: creds.source,
     updated_at: creds.updatedAt,
-    message: tokenAge > TOKEN_CRITICAL_AGE
-      ? 'Token may expire soon - open Slack in Chrome'
-      : tokenAge > TOKEN_WARNING_AGE
-        ? 'Token is getting old - will auto-refresh if Slack tab is open'
-        : 'Token is healthy'
+    message: !hasKnownAge
+      ? 'Token age unknown (missing timestamp) - auth can still be valid'
+      : tokenAge > TOKEN_CRITICAL_AGE
+        ? 'Token may expire soon - open Slack in Chrome'
+        : tokenAge > TOKEN_WARNING_AGE
+          ? 'Token is getting old - will auto-refresh if Slack tab is open'
+          : 'Token is healthy'
   };
 }
 

package/lib/token-store.js

@@ -21,6 +21,7 @@ const IS_MACOS = platform() === 'darwin';
 
 // Refresh lock to prevent concurrent extraction attempts
 let refreshInProgress = null;
+let lastExtractionError = null;
 
 // ============ Keychain Storage (macOS only) ============
 
@@ -62,7 +63,7 @@ export function getFromFile() {
     return {
       token: data.SLACK_TOKEN,
       cookie: data.SLACK_COOKIE,
-      updatedAt: data.updated_at
+      updatedAt: data.updated_at || data.UPDATED_AT || null
     };
   } catch (e) {
     return null;
@@ -110,13 +111,53 @@ const SLACK_TOKEN_PATHS = [
   `window.boot_data?.api_token`,
 ];
 
+function normalizeExtractionError(error) {
+  const raw = String(error?.message || error || "");
+
+  if (raw.includes("Executing JavaScript through AppleScript is turned off")) {
+    return {
+      code: "apple_events_javascript_disabled",
+      message: "Chrome blocked JavaScript execution from Apple Events.",
+      detail: "Enable it in Chrome: View > Developer > Allow JavaScript from Apple Events."
+    };
+  }
+
+  if (raw.includes("Application isn't running") || raw.includes("Google Chrome got an error")) {
+    return {
+      code: "chrome_not_ready",
+      message: "Chrome is not ready for token extraction.",
+      detail: "Open Google Chrome with an active Slack tab at app.slack.com."
+    };
+  }
+
+  if (raw.toLowerCase().includes("timed out")) {
+    return {
+      code: "chrome_extraction_timeout",
+      message: "Chrome token extraction timed out.",
+      detail: "Ensure Slack is open in Chrome and retry."
+    };
+  }
+
+  return {
+    code: "chrome_extraction_failed",
+    message: "Chrome token extraction failed.",
+    detail: raw || "Unknown extraction error."
+  };
+}
+
 /**
  * Extract tokens from Chrome (macOS only, uses AppleScript)
  * Returns null on non-macOS platforms
  */
 function extractFromChromeInternal() {
+  lastExtractionError = null;
   if (!IS_MACOS) {
     // AppleScript/osascript is macOS-only
+    lastExtractionError = {
+      code: "unsupported_platform",
+      message: "Chrome auto-extraction is only available on macOS.",
+      detail: "Use manual token setup on this platform."
+    };
     return null;
   }
 
@@ -138,7 +179,14 @@ function extractFromChromeInternal() {
       encoding: 'utf-8', timeout: 5000
     }).trim();
 
-    if (!cookie || !cookie.startsWith('xoxd-')) return null;
+    if (!cookie || !cookie.startsWith('xoxd-')) {
+      lastExtractionError = {
+        code: "cookie_not_found",
+        message: "Could not extract Slack cookie from Chrome.",
+        detail: "Ensure a logged-in Slack tab is open at app.slack.com."
+      };
+      return null;
+    }
 
     // Try multiple token extraction paths
     const tokenPathsJS = SLACK_TOKEN_PATHS.map((path, i) =>
@@ -161,10 +209,18 @@ function extractFromChromeInternal() {
       encoding: 'utf-8', timeout: 5000
     }).trim();
 
-    if (!token || !token.startsWith('xoxc-')) return null;
+    if (!token || !token.startsWith('xoxc-')) {
+      lastExtractionError = {
+        code: "token_not_found",
+        message: "Could not extract Slack token from Chrome.",
+        detail: "Refresh Slack in Chrome and retry extraction."
+      };
+      return null;
+    }
 
     return { token, cookie };
   } catch (e) {
+    lastExtractionError = normalizeExtractionError(e);
     return null;
   }
 }
@@ -188,6 +244,10 @@ export function extractFromChrome() {
   }
 }
 
+export function getLastExtractionError() {
+  return lastExtractionError;
+}
+
 /**
  * Check if auto-refresh is available on this platform
  */
@@ -197,9 +257,8 @@ export function isAutoRefreshAvailable() {
 
 // ============ Main Token Loader ============
 
-export function loadTokens(forceRefresh = false, logger = console) {
-  // Priority 1: Environment variables
-  if (!forceRefresh && process.env.SLACK_TOKEN && process.env.SLACK_COOKIE) {
+function getStoredTokens() {
+  if (process.env.SLACK_TOKEN && process.env.SLACK_COOKIE) {
     return {
       token: process.env.SLACK_TOKEN,
       cookie: process.env.SLACK_COOKIE,
@@ -207,37 +266,46 @@ export function loadTokens(forceRefresh = false, logger = console) {
     };
   }
 
-  // Priority 2: Token file
-  if (!forceRefresh) {
-    const fileTokens = getFromFile();
-    if (fileTokens?.token && fileTokens?.cookie) {
-      return {
-        token: fileTokens.token,
-        cookie: fileTokens.cookie,
-        source: "file",
-        updatedAt: fileTokens.updatedAt
-      };
-    }
+  const fileTokens = getFromFile();
+  if (fileTokens?.token && fileTokens?.cookie) {
+    return {
+      token: fileTokens.token,
+      cookie: fileTokens.cookie,
+      source: "file",
+      updatedAt: fileTokens.updatedAt
+    };
+  }
+
+  const keychainToken = getFromKeychain("token");
+  const keychainCookie = getFromKeychain("cookie");
+  if (keychainToken && keychainCookie) {
+    return {
+      token: keychainToken,
+      cookie: keychainCookie,
+      source: "keychain"
+    };
   }
 
-  // Priority 3: Keychain
+  return null;
+}
+
+export function loadTokensReadOnly() {
+  return getStoredTokens();
+}
+
+export function loadTokens(forceRefresh = false, logger = console, options = {}) {
+  const { autoExtract = true } = options;
   if (!forceRefresh) {
-    const keychainToken = getFromKeychain("token");
-    const keychainCookie = getFromKeychain("cookie");
-    if (keychainToken && keychainCookie) {
-      return {
-        token: keychainToken,
-        cookie: keychainCookie,
-        source: "keychain"
-      };
-    }
+    const storedTokens = getStoredTokens();
+    if (storedTokens) return storedTokens;
   }
 
-  // Priority 4: Chrome auto-extract
-  logger.error("Attempting Chrome auto-extraction...");
+  if (!autoExtract) return null;
+
+  logger.error?.("Attempting Chrome auto-extraction...");
   const chromeTokens = extractFromChrome();
   if (chromeTokens) {
-    logger.error("Successfully extracted tokens from Chrome!");
+    logger.error?.("Successfully extracted tokens from Chrome!");
     saveTokens(chromeTokens.token, chromeTokens.cookie);
     return {
       token: chromeTokens.token,
@@ -246,6 +314,11 @@ export function loadTokens(forceRefresh = false, logger = console) {
     };
   }
 
+  if (lastExtractionError?.code === "apple_events_javascript_disabled") {
+    logger.error?.(lastExtractionError.message);
+    logger.error?.(lastExtractionError.detail);
+  }
+
   return null;
 }
 

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.4",
   "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",
@@ -24,7 +24,9 @@
     "tokens:auto": "node scripts/token-cli.js auto",
     "tokens:clear": "node scripts/token-cli.js clear",
     "screenshot": "node scripts/capture-screenshots.js",
-    "record-demo": "node scripts/record-demo.js"
+    "record-demo": "node scripts/record-demo.js",
+    "metrics:release-health": "node scripts/collect-release-health.js",
+    "metrics:release-health:delta": "node scripts/build-release-health-delta.js"
   },
   "keywords": [
     "mcp",
@@ -33,50 +35,27 @@
     "slack",
     "slack-api",
     "slack-mcp",
-    "slack-bot",
     "slack-integration",
     "claude",
     "claude-desktop",
     "claude-code",
-    "anthropic",
+    "cursor",
+    "llm",
     "ai",
     "ai-assistant",
-    "ai-agent",
-    "llm",
-    "llm-tools",
-    "chatbot",
-    "dm",
-    "direct-messages",
-    "channels",
-    "workspace",
     "automation",
     "workflow-automation",
-    "browser-tokens",
-    "no-oauth",
-    "cli",
     "developer-tools",
-    "devtools",
+    "cli",
     "productivity",
     "messaging",
-    "chat",
-    "model-context-protocol",
-    "chatgpt",
-    "cursor",
-    "open-source",
-    "openai",
-    "gpt",
-    "gemini",
-    "copilot",
-    "ai-tools",
-    "personal-assistant",
     "message-search",
-    "slack-integration",
-    "workspace-automation"
+    "direct-messages",
+    "channels",
+    "workspace",
+    "session-based",
+    "open-source"
   ],
-  "funding": {
-    "type": "individual",
-    "url": "https://github.com/sponsors/jtalk22"
-  },
   "author": "jtalk22",
   "license": "MIT",
   "repository": {