@jtalk22/slack-mcp 1.2.1 → 1.2.3

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <em>Give Claude the same Slack access you have.<br>
-  DMs, threads, history—no admin approval.</em>
+  DMs, threads, history—using your existing Slack session.</em>
 </p>
 
 <p align="center">
@@ -37,9 +37,11 @@
 
 ---
 
+> 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?"—but Slack's API blocks access to DMs without admin approval.
+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.
 
 Screenshotting messages is not a workflow.
 
@@ -100,6 +102,25 @@ Instead of authenticating as a bot, this server leverages your existing Chrome s
 
 **Runtime:** Node.js 20+
 
+### 30-Second Proof
+
+```bash
+npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --doctor
+npx -y @jtalk22/slack-mcp --setup
+```
+
+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)
 
 ```bash
@@ -120,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
@@ -131,7 +166,7 @@ docker pull ghcr.io/jtalk22/slack-mcp-server:latest
 The interactive setup wizard handles token extraction and validation automatically:
 
 ```bash
-npx @jtalk22/slack-mcp --setup
+npx -y @jtalk22/slack-mcp --setup
 ```
 
 - **macOS**: Auto-extracts tokens from Chrome (have Slack open in a tab)
@@ -142,7 +177,7 @@ npx @jtalk22/slack-mcp --setup
 #### Check Token Status
 
 ```bash
-npx @jtalk22/slack-mcp --status
+npx -y @jtalk22/slack-mcp --status
 ```
 
 #### Alternative: Manual Token Scripts
@@ -283,14 +318,14 @@ If you're using claude.ai in a browser (which doesn't support MCP), you can use
 
 ```bash
 npm run web
-# Or: npx @jtalk22/slack-mcp web
+# Or: npx -y @jtalk22/slack-mcp web
 ```
 
 **Magic Link:** The console prints a one-click URL with the API key embedded:
 
 ```
 ════════════════════════════════════════════════════════════
-  Slack Web API Server v1.2.1
+  Slack Web API Server v1.2.3
 ════════════════════════════════════════════════════════════
 
   Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx
@@ -309,6 +344,37 @@ 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
+
+If you're evaluating team rollout, start with [Deployment Modes](docs/DEPLOYMENT-MODES.md) before exposing remote endpoints.
+
+---
+
+## 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
@@ -317,6 +383,9 @@ Just click the link - no copy-paste needed. The key is saved to your browser and
 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

@@ -0,0 +1,65 @@
+# Communication Style Guide
+
+Use this guide for release notes, issue replies, and changelog entries.
+
+## Rules
+
+1. Keep text technical, concise, and factual.
+2. Do not include model/tool credit lines.
+3. Do not include co-author trailers from tooling.
+4. State exact versions and commands when relevant.
+5. Avoid speculative claims.
+
+## Issue Reply Template
+
+```md
+Thanks for reporting this.
+
+Status: fixed in `<version>`.
+
+Included:
+- `<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
+
+````md
+## <version> — <short title>
+
+### Improved
+- <item>
+- <item>
+
+### Compatibility
+- No API/tool schema changes.
+
+### Verify
+```bash
+npx -y @jtalk22/slack-mcp --version
+npx -y @jtalk22/slack-mcp --setup
+npx -y @jtalk22/slack-mcp --status
+```
+````
+
+## Changelog Entry Template
+
+```md
+## [<version>] - YYYY-MM-DD
+
+### Fixed
+- <item>
+
+### Changed
+- <item>
+```

package/docs/DEPLOYMENT-MODES.md

@@ -0,0 +1,48 @@
+# Deployment Modes
+
+Use this guide to choose the right operating mode before rollout.
+
+## Quick Chooser
+
+- Choose `stdio` for personal use in Claude Desktop/Claude Code.
+- Choose local `web` for browser workflows and manual Slack browsing.
+- Choose hosted HTTP only when you need remote execution and can handle token operations.
+- Choose Smithery/Worker only when your consumers require registry-hosted MCP transport.
+
+## Mode Matrix
+
+| Mode | Start Command | Best For | Auth Material | Exposure | Notes |
+|------|---------------|----------|---------------|----------|-------|
+| Local MCP (`stdio`) | `npx -y @jtalk22/slack-mcp` | Individual daily usage in Claude | `SLACK_TOKEN` + `SLACK_COOKIE` via token file/env | Local process | Lowest ops burden |
+| Local Web UI (`web`) | `npx -y @jtalk22/slack-mcp web` | Browser-first usage, manual search/send | Same as above + generated API key | `localhost` by default | Useful when MCP is not available |
+| Hosted MCP (`http`) | `node src/server-http.js` | Controlled hosted integration | Env-injected Slack token/cookie | Remote endpoint | Requires runtime hardening and monitoring |
+| Smithery/Worker | `wrangler deploy` + Smithery publish flow | Registry distribution for hosted consumers | Query/env token handoff | Remote endpoint | Keep worker version parity with npm release |
+
+## Team Deployment Guidance
+
+If you are deploying for more than one operator:
+
+1. Start with one maintainer on local `stdio`.
+2. Document token lifecycle and rotation ownership.
+3. Define support window and incident contact before enabling hosted mode.
+4. Validate `/health` and MCP initialize responses on every release.
+
+## Release Checklist by Mode
+
+### Local `stdio`
+
+1. `npx -y @jtalk22/slack-mcp --status`
+2. `npx -y @jtalk22/slack-mcp --help`
+3. Confirm tool list in Claude client.
+
+### Local `web`
+
+1. `npx -y @jtalk22/slack-mcp web`
+2. Verify API key generation at `~/.slack-mcp-api-key`.
+3. Verify `/health`, `/conversations`, and `/search` endpoints.
+
+### Hosted (`http` or Worker)
+
+1. Verify `version` parity across `package.json`, server metadata, and health responses.
+2. Confirm `slack_get_thread`, `slack_search_messages`, and `slack_users_info` behavior.
+3. Confirm token handling mode (ephemeral vs env persistence) is documented.

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,18 +23,42 @@ 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: Automatic Extraction**
+**Option A: Setup Wizard (recommended)**
 
 1. Open Chrome
 2. Navigate to https://app.slack.com and log in
 3. Run:
    ```bash
-   npm run tokens:auto
+   npx -y @jtalk22/slack-mcp --setup
    ```
 
-**Option B: Manual Extraction**
+**Option B: Automatic Extraction (repo clone workflow)**
+
+```bash
+npm run tokens:auto
+```
+
+**Option C: Manual Extraction**
 
 1. Open https://app.slack.com in Chrome
 2. Press F12 to open DevTools
@@ -114,11 +138,11 @@ You should see your username and team name.
 
 ### "No credentials found"
 
-Run `npm run tokens:auto` 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/SUPPORT-BOUNDARIES.md

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

package/docs/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.
@@ -54,10 +78,16 @@ slack_list_conversations limit=50
 # Option 1: In Claude Code/Desktop
 slack_refresh_tokens
 
-# Option 2: CLI
+# 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
 
-# Option 3: Manual
+# Option 4: Manual
 npm run tokens:refresh
 ```
 

package/docs/USE_CASE_RECIPES.md

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

package/docs/WEB-API.md

@@ -7,6 +7,8 @@ The Slack Web Server exposes all MCP tools as REST endpoints, accessible from an
 ```bash
 cd ~/slack-mcp-server
 npm run web
+# Or run directly from npm:
+npx -y @jtalk22/slack-mcp web
 ```
 
 The server will:

package/lib/handlers.js

@@ -116,7 +116,7 @@ export async function handleHealthCheck() {
     return {
       content: [{
         type: "text",
-        text: "NO CREDENTIALS\n\nOptions:\n1. Open Slack in Chrome, then use slack_refresh_tokens\n2. Run: npm run tokens:auto (or npx @jtalk22/slack-mcp tokens:auto)"
+        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
     };

package/lib/slack-client.js

@@ -150,7 +150,7 @@ export async function slackAPI(method, params = {}, options = {}) {
 
   const creds = loadTokens(false, logger);
   if (!creds) {
-    throw new Error("No credentials available. Run refresh-tokens.sh or open Slack in Chrome.");
+    throw new Error("No credentials available. Run npx -y @jtalk22/slack-mcp --setup or open Slack in Chrome.");
   }
 
   // Proactive token health check (non-blocking, only on first attempt)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jtalk22/slack-mcp",
   "mcpName": "io.github.jtalk22/slack-mcp-server",
-  "version": "1.2.1",
-  "description": "Full Slack access for Claude - DMs, channels, search. No OAuth. No admin approval. Just works.",
+  "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",
   "bin": {
@@ -17,6 +17,8 @@
     "http": "node src/server-http.js",
     "web": "node src/web-server.js",
     "setup": "node scripts/setup-wizard.js --setup",
+    "hooks:setup": "bash scripts/setup-git-hooks.sh",
+    "verify:owner-attribution": "bash scripts/check-owner-attribution.sh",
     "tokens:status": "node scripts/token-cli.js status",
     "tokens:refresh": "node scripts/token-cli.js refresh",
     "tokens:auto": "node scripts/token-cli.js auto",