@jtalk22/slack-mcp 1.2.4 → 2.0.0

package/README.md

@@ -36,6 +36,10 @@
 
 ---
 
+> **Release:** `v2.0.0` is live with deterministic diagnostics and no MCP tool renames/removals.  
+> Release notes: [.github/v2.0.0-release-notes.md](.github/v2.0.0-release-notes.md)  
+> Install proof: [docs/INSTALL-PROOF.md](docs/INSTALL-PROOF.md)
+
 > 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
@@ -110,7 +114,7 @@ npx -y @jtalk22/slack-mcp --setup
 ```
 
 Expected:
-- `--version` prints `slack-mcp-server v1.2.x`
+- `--version` prints `slack-mcp-server v2.0.x`
 - `--doctor` returns one clear next action with exit code:
   - `0` ready
   - `1` missing credentials
@@ -335,7 +339,7 @@ npm run web
 
 ```
 ════════════════════════════════════════════════════════════
-  Slack Web API Server v1.2.4
+  Slack Web API Server v2.0.0
 ════════════════════════════════════════════════════════════
 
   Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx

package/docs/HN-LAUNCH.md

@@ -1,28 +1,29 @@
-# HN Launch Kit
+# HN Launch Kit (v2.0.0)
 
-Use this file as copy/paste launch material with minimal edits.
+Use this file for Show HN posting and first-comment follow-up.
 
 ## Title Options
 
-- `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)`
+- `Show HN: Slack MCP Server v2.0.0 (deterministic Slack MCP diagnostics)`
+- `Show HN: Slack MCP Server v2.0.0 (session-based Slack access, stable contracts)`
+- `Show HN: Slack MCP Server v2.0.0 (local-first Slack context for Claude)`
 
 ## Launch Post Template
 
 ```md
-Built a session-based Slack MCP server so Claude can use the same access already available in your Slack web session.
+Released `@jtalk22/slack-mcp@2.0.0` today.
 
-Current scope:
-- DM/channel/thread reads
-- workspace search
-- message sends and user lookups
-- local web mode when MCP is unavailable
+This release focuses on install reliability and deterministic diagnostics:
+- read-only `--status` behavior enforced in install-path verification
+- deterministic `--doctor` exits (`0/1/2/3`)
+- structured MCP/web error payloads for triage consistency
+- token health handles missing timestamp as unknown age, not false critical
+- no MCP tool renames or removals
 
 Verify:
 - `npx -y @jtalk22/slack-mcp --version`
+- `npx -y @jtalk22/slack-mcp --doctor`
 - `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
@@ -31,33 +32,30 @@ npm: https://www.npmjs.com/package/@jtalk22/slack-mcp
 ## First Comment Draft
 
 ```md
-Notes up front:
-- Local-first usage is fully supported.
-- 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.
+Quick notes:
+- Default path is local-first (`stdio`) and remains fully supported.
+- `--status` is read-only by design in this release.
+- `--doctor` has deterministic exit codes for automation and triage.
+- If registry pages lag, metadata is propagating; npm and GitHub release are authoritative first.
 
-If install fails, include OS, Node version, runtime mode (`stdio|web|http|worker`), and exact error output.
+If anything fails, include OS, Node version, runtime mode (`stdio|web|http|worker`), and exact output.
 ```
 
-## FAQ
+## FAQ Macro
 
-### 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.
+### Why session-based instead of OAuth app scopes?
+Session mirroring provides the same access visible in the signed-in Slack web session.
 
 ### Is hosted deployment required?
-No. The default path is local/self-hosted first. Deployment docs describe hosted tradeoffs.
-
-### Is this suitable for production teams?
-Treat as operator-managed infrastructure and validate against your own security and compliance requirements.
+No. Local operator path is primary. Hosted paths are optional.
 
-## Install Check Block
+### Are tool contracts changed in v2.0.0?
+No. This release keeps existing MCP tool names.
 
+### What should I run first?
+Use:
 ```bash
 npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --doctor
 npx -y @jtalk22/slack-mcp --status
-npx -y @jtalk22/slack-mcp --setup
 ```

package/docs/INDEX.md

@@ -19,9 +19,15 @@ Start here for setup, compatibility checks, operations, and support.
 ## Launch and Communication
 
 - [HN Launch Kit](HN-LAUNCH.md)
+- [Launch Copy (v2.0.0)](LAUNCH-COPY-v2.0.0.md)
+- [Launch Ops Runbook](LAUNCH-OPS.md)
+- [Capability Matrix](LAUNCH-MATRIX.md)
+- [Install Proof Block](INSTALL-PROOF.md)
 - [Communication Style](COMMUNICATION-STYLE.md)
 - [Release Health Guide](RELEASE-HEALTH.md)
 - [Latest Release Health Snapshot](release-health/latest.md)
+- [Version Parity Report](release-health/version-parity.md)
+- [Launch Log Template](release-health/launch-log-template.md)
 - [Changelog](../CHANGELOG.md)
 
 ## Issue Intake

package/docs/INSTALL-PROOF.md

@@ -0,0 +1,18 @@
+# Install Proof Block (v2.0.0)
+
+Use this command block in release notes, HN/X/Reddit follow-ups, and issue replies.
+
+```bash
+npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --doctor
+npx -y @jtalk22/slack-mcp --status
+```
+
+Expected:
+- `--version` prints `slack-mcp-server v2.0.0`
+- `--doctor` exits with:
+  - `0` ready
+  - `1` missing credentials
+  - `2` invalid or expired credentials
+  - `3` runtime or connectivity issue
+- `--status` is read-only and does not trigger Chrome extraction.

package/docs/LAUNCH-COPY-v2.0.0.md

@@ -0,0 +1,59 @@
+# Launch Copy (v2.0.0)
+
+Use this file for channel-specific copy with consistent technical claims.
+
+## Short Release Summary (150 words)
+
+`@jtalk22/slack-mcp v2.0.0` is out with a focus on deterministic diagnostics and clean operator workflows. This release enforces read-only `--status` behavior in install-path verification, expands `--doctor` coverage to a strict `0/1/2/3` exit matrix, and standardizes structured error envelopes across MCP tool failures and web API validation/runtime paths. Token health handling now reports explicit unknown-age semantics when timestamps are missing, so operators do not get false critical warnings. Metadata is aligned for distribution parity with updated registry-facing server metadata and a new parity checker (`npm run verify:version-parity`) that reports local/npm/registry alignment. MCP tool contracts stay compatible: no renames, no removals. If you use Claude Desktop, Claude Code, or local web mode, this is a drop-in upgrade focused on faster triage and fewer install surprises.
+
+## X Thread (7 posts)
+
+1. `Slack MCP Server v2.0.0 is live.`
+   `Focus: deterministic diagnostics + install reliability.`
+2. `No MCP tool renames/removals in this release.`
+   `Compatibility stays stable.`
+3. `Install-path checks now enforce read-only --status behavior.`
+   `No token extraction side effects during status checks.`
+4. `--doctor now enforces deterministic exits:`
+   `0 ready / 1 missing creds / 2 invalid creds / 3 runtime issue.`
+5. `Token health now reports unknown-age semantics when timestamp is missing.`
+   `No false critical warning from missing metadata.`
+6. `Parity checker added: npm/local/registry view in one report.`
+   `npm run verify:version-parity`
+7. `Try it:`
+   `npx -y @jtalk22/slack-mcp --version`
+   `npx -y @jtalk22/slack-mcp --doctor`
+   `Repo: https://github.com/jtalk22/slack-mcp-server`
+
+## Reddit Post (Technical Variant)
+
+Title:
+- `Slack MCP Server v2.0.0: deterministic install diagnostics, stable tool contracts`
+
+Body:
+```md
+Released `@jtalk22/slack-mcp@2.0.0` today.
+
+Main changes are reliability-focused:
+- install-path verification enforces read-only `--status`
+- `--doctor` exit matrix enforced (`0/1/2/3`)
+- standardized structured error payloads for MCP tool failures and web API errors
+- token health handles missing timestamp as unknown age (no false critical)
+- new version parity report script for npm/local/registry checks
+
+No MCP tool renames or removals in this release.
+
+Verify:
+`npx -y @jtalk22/slack-mcp --version`
+`npx -y @jtalk22/slack-mcp --doctor`
+`npx -y @jtalk22/slack-mcp --status`
+
+Repo: https://github.com/jtalk22/slack-mcp-server
+npm: https://www.npmjs.com/package/@jtalk22/slack-mcp
+```
+
+## Registry Propagation Note
+
+If registry versions are still syncing right after publish, use this sentence:
+
+`Release is published; registry metadata is propagating. Timestamp: <UTC timestamp>.`

package/docs/LAUNCH-MATRIX.md

@@ -0,0 +1,20 @@
+# Capability Matrix (v2.0.0)
+
+Comparison matrix for release notes and channel posts. Keep competitor references unnamed.
+
+| Capability | This Release (`v2.0.0`) | Typical Session-Based Alternatives |
+|---|---|---|
+| Read-only status checks | Enforced and verified in install flow | Often undocumented or mixed with refresh side effects |
+| Deterministic doctor exits | Enforced (`0/1/2/3`) with install-path coverage | Often ad-hoc or text-only |
+| Structured diagnostics | Shared fields in MCP/web error payloads | Mixed payload shapes |
+| Unknown token age handling | Explicit `unknown_age` semantics | Missing timestamp may appear as stale/failing |
+| Tool contract stability | No MCP tool rename/removal | Varies by release |
+| Local-first operator path | First-class (`stdio`, `web`) | Varies by runtime emphasis |
+| Version parity check | Scripted local/npm/registry report | Often manual |
+| Smithery/registry alignment | Metadata prepared in release wave | Often delayed post-release |
+
+## Usage Guidance
+
+1. Use this table in release notes and social threads.
+2. Do not name external projects.
+3. Keep claims tied to verifiable commands and docs.

package/docs/LAUNCH-OPS.md

@@ -0,0 +1,70 @@
+# Launch Ops Runbook (v2.0.0)
+
+This runbook defines launch-day monitoring, response rules, and reinforcement loops.
+
+## Same-Day Fanout Order
+
+1. GitHub release publish (`v2.0.0`)
+2. npm publish confirm (`@jtalk22/slack-mcp@2.0.0`)
+3. MCP registry metadata update
+4. Smithery listing metadata parity update
+5. `awesome-mcp-servers` version update PR
+6. Glama listing refresh/update
+7. HN post + first comment
+8. X thread
+9. Reddit technical post
+
+## Monitoring Cadence
+
+- First 4 hours: every 30 minutes
+- Up to 24 hours: every 60 minutes
+
+Track:
+- install reports and blocker count
+- npm version/install confirmation
+- registry parity status
+- inbound issue volume and severity
+
+## 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 template
+- provide timeline as best effort
+
+## Escalation Triggers
+
+1. If install failures exceed 3 unique reports in 24h:
+- pause outbound posting
+- prioritize hotfix
+
+2. If support load exceeds 2 hours/day for 2 days:
+- move to stability-only mode
+- defer non-critical requests
+
+## 24h / 48h / 72h Follow-Up
+
+24h:
+- publish release-health delta and short technical update
+
+48h:
+- answer top 5 recurring questions in docs
+
+72h:
+- publish `v2.0.1` only if launch defects are confirmed
+
+## Evidence Log
+
+Use:
+- `docs/release-health/launch-log-template.md`
+
+Capture:
+- channel
+- UTC timestamp
+- URL
+- action taken
+- observed result

package/docs/RELEASE-HEALTH.md

@@ -13,6 +13,21 @@ Outputs:
 - `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
+```
+
 24-hour loop artifacts:
 - `docs/release-health/24h-start.md`
 - `docs/release-health/24h-end.md`

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

@@ -1,6 +1,6 @@
 # Release Health Snapshot
 
-- Generated: 2026-02-26T09:32:53.328Z
+- Generated: 2026-02-26T12:46:11.970Z
 - Repo: `jtalk22/slack-mcp-server`
 - Package: `@jtalk22/slack-mcp`
 
@@ -8,7 +8,7 @@
 
 - npm downloads (last week): 532
 - npm downloads (last month): 1011
-- npm latest version: 1.2.3
+- npm latest version: 1.2.4
 
 ## GitHub Reach
 
@@ -21,7 +21,7 @@
 - 14d unique cloners: 113
 - deployment-intake submissions (all-time): 1
 
-## 14-Day Reliability Targets (v1.2.3 Cycle)
+## 14-Day Reliability Targets (v2.0.0 Cycle)
 
 - weekly downloads: >= 180
 - qualified deployment-intake submissions: >= 2

package/docs/release-health/latest.md

@@ -1,6 +1,6 @@
 # Release Health Snapshot
 
-- Generated: 2026-02-26T09:32:53.328Z
+- Generated: 2026-02-26T12:46:11.970Z
 - Repo: `jtalk22/slack-mcp-server`
 - Package: `@jtalk22/slack-mcp`
 
@@ -8,7 +8,7 @@
 
 - npm downloads (last week): 532
 - npm downloads (last month): 1011
-- npm latest version: 1.2.3
+- npm latest version: 1.2.4
 
 ## GitHub Reach
 
@@ -21,7 +21,7 @@
 - 14d unique cloners: 113
 - deployment-intake submissions (all-time): 1
 
-## 14-Day Reliability Targets (v1.2.3 Cycle)
+## 14-Day Reliability Targets (v2.0.0 Cycle)
 
 - weekly downloads: >= 180
 - qualified deployment-intake submissions: >= 2

package/docs/release-health/launch-log-template.md

@@ -0,0 +1,21 @@
+# Launch Log Template
+
+Use this template to record public distribution actions and outcomes.
+
+## Entry Format
+
+| UTC Timestamp | Channel | Action | URL | Outcome | Notes |
+|---|---|---|---|---|---|
+| 2026-02-26T00:00:00Z | GitHub | Published release | <url> | success/pending/fail | <note> |
+
+## Recommended Channels
+
+- GitHub release
+- npm publish
+- MCP registry update
+- Smithery update
+- awesome-mcp-servers PR
+- Glama listing update
+- HN post/comment
+- X thread
+- Reddit post

package/docs/release-health/version-parity.md

@@ -0,0 +1,21 @@
+# Version Parity Report
+
+- Generated: 2026-02-26T12:45:39.684Z
+- Local target version: 2.0.0
+
+## Surface Matrix
+
+| Surface | Version | Status | Notes |
+|---|---|---|---|
+| package.json | 2.0.0 | ok |  |
+| server.json (root) | 2.0.0 | ok |  |
+| server.json (package entry) | 2.0.0 | ok |  |
+| npm dist-tag latest | 1.2.4 | mismatch |  |
+| MCP Registry latest | 1.1.8 | mismatch |  |
+| Smithery endpoint | n/a | unreachable | check_error: HTTP 401 for https://server.smithery.ai/jtalk22/slack-mcp-server |
+
+## Interpretation
+
+- Local metadata parity: pass.
+- External parity mismatch: npm latest, MCP registry latest.
+- Propagation mode enabled: external mismatch accepted temporarily.

package/lib/handlers.js

@@ -95,17 +95,25 @@ export async function handleTokenStatus() {
   const dmCache = loadDMCache();
   const tokenStatus = health.reason === 'no_tokens'
     ? "missing"
-    : health.critical
-      ? "critical"
-      : health.warning
-        ? "warning"
-        : "healthy";
+    : health.age_state === "unknown"
+      ? "unknown_age"
+      : health.critical
+        ? "critical"
+        : health.warning
+          ? "warning"
+          : "healthy";
 
   return asMcpJson({
     status: tokenStatus,
-    code: health.reason || (health.critical ? "token_critical" : health.warning ? "token_warning" : "ok"),
+    code: health.reason
+      || (health.age_state === "unknown" ? "unknown_age" : null)
+      || (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,
+    details: {
+      age_known: health.age_known,
+      age_state: health.age_state
+    },
     token: {
       status: tokenStatus,
       age_hours: health.age_hours,

package/lib/slack-client.js

@@ -97,7 +97,13 @@ export async function checkTokenHealth(logger = console) {
   const creds = loadTokens(false, silentLogger, { autoExtract: false });
 
   if (!creds) {
-    return { healthy: false, reason: 'no_tokens', message: 'No credentials found' };
+    return {
+      healthy: false,
+      reason: 'no_tokens',
+      age_known: false,
+      age_state: 'missing',
+      message: 'No credentials found'
+    };
   }
 
   const updatedAtMs = creds.updatedAt ? new Date(creds.updatedAt).getTime() : Number.NaN;
@@ -120,6 +126,8 @@ export async function checkTokenHealth(logger = console) {
         healthy: true,
         refreshed: true,
         age_hours: 0,
+        age_known: true,
+        age_state: 'fresh',
         source: 'chrome-auto',
         message: 'Tokens refreshed successfully'
       };
@@ -131,6 +139,14 @@ export async function checkTokenHealth(logger = console) {
   return {
     healthy: !hasKnownAge || tokenAge < TOKEN_CRITICAL_AGE,
     age_hours: ageHours,
+    age_known: hasKnownAge,
+    age_state: !hasKnownAge
+      ? 'unknown'
+      : tokenAge > TOKEN_CRITICAL_AGE
+        ? 'critical'
+        : tokenAge > TOKEN_WARNING_AGE
+          ? 'warning'
+          : 'healthy',
     warning: hasKnownAge && tokenAge > TOKEN_WARNING_AGE,
     critical: hasKnownAge && tokenAge > TOKEN_CRITICAL_AGE,
     source: creds.source,

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@jtalk22/slack-mcp",
   "mcpName": "io.github.jtalk22/slack-mcp-server",
-  "version": "1.2.4",
+  "version": "2.0.0",
   "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",
   "bin": {
-    "slack-mcp": "./src/cli.js",
-    "slack-mcp-server": "./src/server.js",
-    "slack-mcp-http": "./src/server-http.js",
-    "slack-mcp-web": "./src/web-server.js",
-    "slack-mcp-setup": "./scripts/setup-wizard.js"
+    "slack-mcp": "src/cli.js",
+    "slack-mcp-server": "src/server.js",
+    "slack-mcp-http": "src/server-http.js",
+    "slack-mcp-web": "src/web-server.js",
+    "slack-mcp-setup": "scripts/setup-wizard.js"
   },
   "scripts": {
     "start": "node src/server.js",
@@ -26,7 +26,8 @@
     "screenshot": "node scripts/capture-screenshots.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"
+    "metrics:release-health:delta": "node scripts/build-release-health-delta.js",
+    "verify:version-parity": "node scripts/check-version-parity.js"
   },
   "keywords": [
     "mcp",
@@ -54,13 +55,20 @@
     "channels",
     "workspace",
     "session-based",
+    "session-mirroring",
+    "slack-dm",
+    "slack-threads",
+    "workspace-search",
+    "mcp-tools",
+    "mcp-stdio",
+    "mcp-http",
     "open-source"
   ],
   "author": "jtalk22",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jtalk22/slack-mcp-server.git"
+    "url": "git+https://github.com/jtalk22/slack-mcp-server.git"
   },
   "homepage": "https://jtalk22.github.io/slack-mcp-server/public/demo.html",
   "bugs": {

package/public/demo-claude.html

@@ -1161,7 +1161,7 @@
   <header class="page-header">
     <h1>
       <span>Slack MCP Server</span>
-      <span class="badge">🔧 MCP Demo v1.2.4</span>
+      <span class="badge">🔧 MCP Demo v2.0.0</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.4 • @jtalk22</p>
+      <p class="title-version">v2.0.0 • @jtalk22</p>
     </div>
 
     <!-- Scenario Caption Overlay -->

package/scripts/check-version-parity.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+
+const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"));
+const serverMeta = JSON.parse(readFileSync(join(repoRoot, "server.json"), "utf8"));
+
+const outputArg = process.argv.includes("--out")
+  ? process.argv[process.argv.indexOf("--out") + 1]
+  : "docs/release-health/version-parity.md";
+const allowPropagation = process.argv.includes("--allow-propagation");
+
+const mcpServerName = serverMeta.name;
+const smitheryEndpoint = "https://server.smithery.ai/jtalk22/slack-mcp-server";
+
+async function fetchJson(url) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} for ${url}`);
+  }
+  return res.json();
+}
+
+async function fetchText(url) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} for ${url}`);
+  }
+  return res.text();
+}
+
+function row(surface, version, status, note = "") {
+  return `| ${surface} | ${version || "n/a"} | ${status} | ${note} |`;
+}
+
+async function main() {
+  const localVersion = pkg.version;
+  const localServerVersion = serverMeta.version;
+  const localServerPkgVersion = serverMeta.packages?.[0]?.version || null;
+
+  let npmVersion = null;
+  let mcpRegistryVersion = null;
+  let smitheryReachable = null;
+  let npmError = null;
+  let mcpError = null;
+  let smitheryError = null;
+
+  try {
+    const npmMeta = await fetchJson(`https://registry.npmjs.org/${encodeURIComponent(pkg.name)}`);
+    npmVersion = npmMeta?.["dist-tags"]?.latest || null;
+  } catch (error) {
+    npmError = String(error?.message || error);
+  }
+
+  try {
+    const registry = await fetchJson(
+      `https://registry.modelcontextprotocol.io/v0/servers/${encodeURIComponent(mcpServerName)}/versions/latest`
+    );
+    mcpRegistryVersion = registry?.server?.version || null;
+  } catch (error) {
+    mcpError = String(error?.message || error);
+  }
+
+  try {
+    const html = await fetchText(smitheryEndpoint);
+    smitheryReachable = html.length > 0;
+  } catch (error) {
+    smitheryError = String(error?.message || error);
+  }
+
+  const parityChecks = [
+    { name: "package.json vs server.json", ok: localVersion === localServerVersion },
+    { name: "package.json vs server.json package", ok: localVersion === localServerPkgVersion },
+    { name: "npm latest", ok: npmVersion === localVersion },
+    { name: "MCP registry latest", ok: mcpRegistryVersion === localVersion },
+  ];
+
+  const externalMismatches = parityChecks
+    .filter((check) => !check.ok && (check.name === "npm latest" || check.name === "MCP registry latest"));
+  const hardFailures = parityChecks
+    .filter((check) => !check.ok && check.name !== "npm latest" && check.name !== "MCP registry latest");
+
+  const now = new Date().toISOString();
+  const lines = [
+    "# Version Parity Report",
+    "",
+    `- Generated: ${now}`,
+    `- Local target version: ${localVersion}`,
+    "",
+    "## Surface Matrix",
+    "",
+    "| Surface | Version | Status | Notes |",
+    "|---|---|---|---|",
+    row(
+      "package.json",
+      localVersion,
+      "ok"
+    ),
+    row(
+      "server.json (root)",
+      localServerVersion,
+      localServerVersion === localVersion ? "ok" : "mismatch"
+    ),
+    row(
+      "server.json (package entry)",
+      localServerPkgVersion,
+      localServerPkgVersion === localVersion ? "ok" : "mismatch"
+    ),
+    row(
+      "npm dist-tag latest",
+      npmVersion,
+      npmVersion === localVersion ? "ok" : "mismatch",
+      npmError ? `fetch_error: ${npmError}` : ""
+    ),
+    row(
+      "MCP Registry latest",
+      mcpRegistryVersion,
+      mcpRegistryVersion === localVersion ? "ok" : "mismatch",
+      mcpError ? `fetch_error: ${mcpError}` : ""
+    ),
+    row(
+      "Smithery endpoint",
+      "n/a",
+      smitheryReachable ? "reachable" : "unreachable",
+      smitheryError ? `check_error: ${smitheryError}` : "Version check is manual."
+    ),
+    "",
+    "## Interpretation",
+    "",
+    hardFailures.length === 0
+      ? "- Local metadata parity: pass."
+      : `- Local metadata parity: fail (${hardFailures.map((f) => f.name).join(", ")}).`,
+    externalMismatches.length === 0
+      ? "- External parity: pass."
+      : `- External parity mismatch: ${externalMismatches.map((f) => f.name).join(", ")}.`,
+    allowPropagation && externalMismatches.length > 0
+      ? "- Propagation mode enabled: external mismatch accepted temporarily."
+      : "- Propagation mode disabled: external mismatch is a release gate failure.",
+  ];
+
+  const outPath = join(repoRoot, outputArg);
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, `${lines.join("\n")}\n`, "utf8");
+  console.log(`Wrote ${outputArg}`);
+
+  if (hardFailures.length > 0) {
+    process.exit(1);
+  }
+  if (!allowPropagation && externalMismatches.length > 0) {
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/scripts/collect-release-health.js

@@ -70,7 +70,7 @@ function buildMarkdown(data) {
   lines.push(`- deployment-intake submissions (all-time): ${data.github.deploymentIntakeCount ?? "n/a"}`);
   lines.push("");
 
-  lines.push("## 14-Day Reliability Targets (v1.2.4 Cycle)");
+  lines.push("## 14-Day Reliability Targets (v2.0.0 Cycle)");
   lines.push("");
   lines.push("- weekly downloads: >= 180");
   lines.push("- qualified deployment-intake submissions: >= 2");

package/scripts/setup-wizard.js

@@ -23,8 +23,9 @@ import {
 } from "../lib/token-store.js";
 
 const IS_MACOS = platform() === 'darwin';
-const VERSION = "1.2.4";
+const VERSION = "2.0.0";
 const MIN_NODE_MAJOR = 20;
+const AUTH_TEST_URL = process.env.SLACK_MCP_AUTH_TEST_URL || "https://slack.com/api/auth.test";
 
 // ANSI colors
 const colors = {
@@ -78,7 +79,7 @@ async function pressEnterToContinue(rl) {
 
 async function validateTokens(token, cookie) {
   try {
-    const response = await fetch("https://slack.com/api/auth.test", {
+    const response = await fetch(AUTH_TEST_URL, {
       method: "POST",
       headers: {
         "Authorization": `Bearer ${token}`,
@@ -251,6 +252,8 @@ async function showStatus() {
 
   if (!creds) {
     error("No tokens found");
+    print("Code: missing_credentials");
+    print("Message: No credentials available from environment, file, or keychain.");
     print();
     print("Run setup wizard: npx -y @jtalk22/slack-mcp --setup");
     process.exit(1);
@@ -268,6 +271,7 @@ async function showStatus() {
   const result = await validateTokens(creds.token, creds.cookie);
   if (!result.valid) {
     error("Status: INVALID");
+    print("Code: auth_failed");
     print(`Error: ${result.error}`);
     print();
     print("Run setup wizard to refresh: npx -y @jtalk22/slack-mcp --setup");
@@ -275,6 +279,8 @@ async function showStatus() {
   }
 
   success("Status: VALID");
+  print("Code: ok");
+  print("Message: Slack auth valid.");
   print(`User: ${result.user}`);
   print(`Team: ${result.team}`);
   print(`User ID: ${result.userId}`);
@@ -331,6 +337,7 @@ async function runDoctor() {
   const nodeMajor = parseNodeMajor();
   if (Number.isNaN(nodeMajor) || nodeMajor < MIN_NODE_MAJOR) {
     error(`Node.js ${process.versions.node} detected (requires Node ${MIN_NODE_MAJOR}+)`);
+    print("Code: runtime_node_unsupported");
     print();
     print("Next action:");
     print(`  npx -y @jtalk22/slack-mcp --doctor  # rerun after upgrading Node ${MIN_NODE_MAJOR}+`);
@@ -341,6 +348,7 @@ async function runDoctor() {
   const creds = getDoctorCredentials();
   if (!creds) {
     error("Credentials: not found");
+    print("Code: missing_credentials");
     print();
     print("Next action:");
     print("  npx -y @jtalk22/slack-mcp --setup");
@@ -361,6 +369,7 @@ async function runDoctor() {
   if (!validation.valid) {
     const exitCode = classifyAuthError(validation.error);
     error(`Slack auth failed: ${validation.error}`);
+    print(`Code: ${exitCode === 2 ? "auth_invalid" : "runtime_auth_check_failed"}`);
     print();
     print("Next action:");
     if (exitCode === 2) {
@@ -373,6 +382,7 @@ async function runDoctor() {
   }
 
   success(`Slack auth valid for ${validation.user} @ ${validation.team}`);
+  print("Code: ok");
   print();
   print("Ready. Next command:");
   print("  npx -y @jtalk22/slack-mcp");

package/scripts/verify-install-flow.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG = "@jtalk22/slack-mcp";
 const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const strictPublished = process.argv.includes("--strict-published");
+const localVersion = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).version;
 
 function runNpx(args, options = {}) {
   const cmdArgs = ["-y", PKG, ...args];
@@ -97,6 +99,18 @@ function main() {
       "Expected --version to exit 0",
       versionResult.stderr || versionResult.stdout,
     );
+    const publishedMatchesLocal = versionResult.stdout.includes(localVersion);
+    if (strictPublished) {
+      assert(
+        publishedMatchesLocal,
+        `Expected published npx version to match local ${localVersion}`,
+        versionResult.stdout,
+      );
+    } else if (!publishedMatchesLocal) {
+      console.log(
+        `warning: npx resolved ${versionResult.stdout || "unknown"} while local version is ${localVersion}; strict published checks are deferred until publish.`
+      );
+    }
 
     const helpResult = runNpx(["--help"], { cwd: testHome, env });
     printResult("help", helpResult);
@@ -113,6 +127,15 @@ function main() {
       "Expected --status to exit non-zero when credentials are missing",
       statusResult.stderr || statusResult.stdout,
     );
+    if (strictPublished) {
+      assert(
+        !statusResult.stderr.includes("Attempting Chrome auto-extraction"),
+        "Expected npx --status to be read-only without auto-extraction side effects",
+        statusResult.stderr,
+      );
+    } else if (statusResult.stderr.includes("Attempting Chrome auto-extraction")) {
+      console.log("warning: published npx --status still has extraction side effects; re-run with --strict-published after publish.");
+    }
 
     const localStatusResult = runLocalSetupStatus({ env });
     printResult("local-status", localStatusResult);
@@ -148,6 +171,18 @@ function main() {
       localDoctorInvalidResult.stderr || localDoctorInvalidResult.stdout,
     );
 
+    const runtimeEnv = {
+      ...invalidEnv,
+      SLACK_MCP_AUTH_TEST_URL: "http://127.0.0.1:9/auth.test"
+    };
+    const localDoctorRuntimeResult = runLocalDoctor({ env: runtimeEnv });
+    printResult("local-doctor-runtime", localDoctorRuntimeResult);
+    assert(
+      localDoctorRuntimeResult.status === 3,
+      "Expected local --doctor to exit 3 when runtime connectivity fails",
+      localDoctorRuntimeResult.stderr || localDoctorRuntimeResult.stdout,
+    );
+
     console.log("\nInstall flow verification passed.");
   } finally {
     rmSync(testHome, { recursive: true, force: true });

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.4";
+const SERVER_VERSION = "2.0.0";
 const PORT = process.env.PORT || 3000;
 
 // Create MCP server
@@ -74,13 +74,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return await handleListUsers(args);
       default:
         return {
-          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: "error",
+              code: "unknown_tool",
+              message: `Unknown tool: ${name}`,
+              next_action: "Call tools/list to inspect available tool names."
+            }, null, 2)
+          }],
           isError: true
         };
     }
   } catch (error) {
     return {
-      content: [{ type: "text", text: `Error: ${error.message}` }],
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          status: "error",
+          code: "tool_call_failed",
+          message: String(error?.message || error),
+          next_action: "Retry with validated input payload."
+        }, null, 2)
+      }],
       isError: true
     };
   }
@@ -110,7 +126,13 @@ const httpServer = http.createServer(async (req, res) => {
   // Health check endpoint
   if (req.url === '/health') {
     res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ status: 'ok', server: SERVER_NAME, version: SERVER_VERSION }));
+    res.end(JSON.stringify({
+      status: 'ok',
+      code: 'ok',
+      message: 'HTTP transport healthy',
+      server: SERVER_NAME,
+      version: SERVER_VERSION
+    }));
     return;
   }
 

package/src/server.js

@@ -11,7 +11,7 @@
  * - Network error retry with exponential backoff
  * - Background token health monitoring
  *
- * @version 1.2.4
+ * @version 2.0.0
  */
 
 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.4";
+const SERVER_VERSION = "2.0.0";
 
 // MCP Prompts - predefined prompt templates for common Slack operations
 const PROMPTS = [
@@ -256,13 +256,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       default:
         return {
-          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: "error",
+              code: "unknown_tool",
+              message: `Unknown tool: ${name}`,
+              next_action: "Use tools/list to discover available tools."
+            }, null, 2)
+          }],
           isError: true
         };
     }
   } catch (error) {
     return {
-      content: [{ type: "text", text: `Error: ${error.message}` }],
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          status: "error",
+          code: "tool_call_failed",
+          message: String(error?.message || error),
+          next_action: "Retry the call and include full arguments."
+        }, null, 2)
+      }],
       isError: true
     };
   }

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.4
+ * @version 2.0.0
  */
 
 import express from "express";
@@ -95,11 +95,27 @@ function authenticate(req, res, next) {
   const providedKey = authHeader?.replace("Bearer ", "");
 
   if (providedKey !== API_KEY) {
-    return res.status(401).json({ error: "Invalid API key" });
+    return res.status(401).json({
+      status: "error",
+      code: "unauthorized",
+      message: "Invalid API key",
+      next_action: "Provide Authorization: Bearer <api-key>."
+    });
   }
   next();
 }
 
+function sendStructuredError(res, statusCode, code, message, nextAction = null, details = null) {
+  const payload = {
+    status: "error",
+    code,
+    message,
+    next_action: nextAction,
+  };
+  if (details) payload.details = details;
+  return res.status(statusCode).json(payload);
+}
+
 // Helper to extract response content
 function extractContent(result) {
   if (result.content && result.content[0] && result.content[0].text) {
@@ -116,8 +132,10 @@ function extractContent(result) {
 app.get("/", (req, res) => {
   res.json({
     name: "Slack Web API Server",
-    version: "1.2.4",
-    status: "running",
+    version: "2.0.0",
+    status: "ok",
+    code: "ok",
+    message: "Web API server is running.",
     endpoints: [
       "GET  /health",
       "POST /refresh",
@@ -140,7 +158,7 @@ app.get("/token-status", authenticate, async (req, res) => {
     const result = await handleTokenStatus();
     res.json(extractContent(result));
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "token_status_failed", String(e?.message || e));
   }
 });
 
@@ -148,9 +166,13 @@ app.get("/token-status", authenticate, async (req, res) => {
 app.get("/health", authenticate, async (req, res) => {
   try {
     const result = await handleHealthCheck();
-    res.json(extractContent(result));
+    const payload = extractContent(result);
+    if (result.isError) {
+      return res.status(400).json(payload);
+    }
+    res.json(payload);
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "health_check_failed", String(e?.message || e));
   }
 });
 
@@ -158,9 +180,13 @@ app.get("/health", authenticate, async (req, res) => {
 app.post("/refresh", authenticate, async (req, res) => {
   try {
     const result = await handleRefreshTokens();
-    res.json(extractContent(result));
+    const payload = extractContent(result);
+    if (result.isError) {
+      return res.status(400).json(payload);
+    }
+    res.json(payload);
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "refresh_failed", String(e?.message || e));
   }
 });
 
@@ -173,7 +199,7 @@ app.get("/conversations", authenticate, async (req, res) => {
     });
     res.json(extractContent(result));
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "list_conversations_failed", String(e?.message || e));
   }
 });
 
@@ -189,7 +215,7 @@ app.get("/conversations/:id/history", authenticate, async (req, res) => {
     });
     res.json(extractContent(result));
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "history_failed", String(e?.message || e));
   }
 });
 
@@ -206,7 +232,7 @@ app.get("/conversations/:id/full", authenticate, async (req, res) => {
     });
     res.json(extractContent(result));
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "full_export_failed", String(e?.message || e));
   }
 });
 
@@ -219,7 +245,7 @@ app.get("/conversations/:id/thread/:ts", authenticate, async (req, res) => {
     });
     res.json(extractContent(result));
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "thread_fetch_failed", String(e?.message || e));
   }
 });
 
@@ -227,7 +253,13 @@ app.get("/conversations/:id/thread/:ts", authenticate, async (req, res) => {
 app.get("/search", authenticate, async (req, res) => {
   try {
     if (!req.query.q) {
-      return res.status(400).json({ error: "Query parameter 'q' is required" });
+      return sendStructuredError(
+        res,
+        400,
+        "invalid_request",
+        "Query parameter 'q' is required",
+        "Set the q query string and retry."
+      );
     }
     const result = await handleSearchMessages({
       query: req.query.q,
@@ -235,7 +267,7 @@ app.get("/search", authenticate, async (req, res) => {
     });
     res.json(extractContent(result));
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "search_failed", String(e?.message || e));
   }
 });
 
@@ -243,7 +275,13 @@ app.get("/search", authenticate, async (req, res) => {
 app.post("/messages", authenticate, async (req, res) => {
   try {
     if (!req.body.channel_id || !req.body.text) {
-      return res.status(400).json({ error: "channel_id and text are required" });
+      return sendStructuredError(
+        res,
+        400,
+        "invalid_request",
+        "channel_id and text are required",
+        "Include channel_id and text in request JSON."
+      );
     }
     const result = await handleSendMessage({
       channel_id: req.body.channel_id,
@@ -252,7 +290,7 @@ app.post("/messages", authenticate, async (req, res) => {
     });
     res.json(extractContent(result));
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "send_message_failed", String(e?.message || e));
   }
 });
 
@@ -264,7 +302,7 @@ app.get("/users", authenticate, async (req, res) => {
     });
     res.json(extractContent(result));
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "list_users_failed", String(e?.message || e));
   }
 });
 
@@ -276,7 +314,7 @@ app.get("/users/:id", authenticate, async (req, res) => {
     });
     res.json(extractContent(result));
   } catch (e) {
-    res.status(500).json({ error: e.message });
+    sendStructuredError(res, 500, "user_info_failed", String(e?.message || e));
   }
 });
 
@@ -295,7 +333,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.4`);
+    console.error(`  Slack Web API Server v2.0.0`);
     console.error(`${"═".repeat(60)}`);
     console.error(`\n  Dashboard: http://localhost:${PORT}/?key=${API_KEY}`);
     console.error(`\n  API Key:   ${API_KEY}`);