@uniquedivine/mcp-slack 4.5.1 → 4.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,11 @@
1
1
  # Slack MCP
2
2
 
3
- Read Slack channels, threads and search results, and perform explicitly
4
- authorized writes through your user session. This server is maintained as
5
- part of Jiyuu. It preserves the imported stdio, HTTP and web entrypoints.
3
+ Read Slack channels, DMs, threads, and search results through your own
4
+ browser session, and send, edit, or delete your messages when you ask. The
5
+ server needs no Slack app and no admin approval.
6
+
7
+ Maintained by [Unique Divine](https://uniquedivine.com) in
8
+ [Unique-Divine/jiyuu](https://github.com/Unique-Divine/jiyuu).
6
9
 
7
10
  ## Install
8
11
 
@@ -11,8 +14,8 @@ in through a browser. Store credentials once, then run the published package
11
14
  with an exact version pin:
12
15
 
13
16
  ```sh
14
- bunx @uniquedivine/mcp-slack@4.5.1 --setup
15
- bunx @uniquedivine/mcp-slack@4.5.1
17
+ bunx @uniquedivine/mcp-slack@4.5.3 --setup
18
+ bunx @uniquedivine/mcp-slack@4.5.3
16
19
  ```
17
20
 
18
21
  Flag `--setup` writes file `~/.slack-mcp-tokens.json`. To pass environment
@@ -25,7 +28,7 @@ changes on `main`. The version pin selects the exact reviewed release that runs.
25
28
  ### Claude Code
26
29
 
27
30
  ```sh
28
- claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.1
31
+ claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.3
29
32
  ```
30
33
 
31
34
  ### Codex
@@ -35,7 +38,7 @@ Add this entry to file `~/.codex/config.toml`:
35
38
  ```toml
36
39
  [mcp_servers.slack]
37
40
  command = "bunx"
38
- args = ["@uniquedivine/mcp-slack@4.5.1"]
41
+ args = ["@uniquedivine/mcp-slack@4.5.3"]
39
42
  ```
40
43
 
41
44
  ### Cursor
@@ -48,7 +51,7 @@ a project:
48
51
  "mcpServers": {
49
52
  "slack": {
50
53
  "command": "bunx",
51
- "args": ["@uniquedivine/mcp-slack@4.5.1"]
54
+ "args": ["@uniquedivine/mcp-slack@4.5.3"]
52
55
  }
53
56
  }
54
57
  }
@@ -58,47 +61,113 @@ a project:
58
61
 
59
62
  1. Find the newest version with command
60
63
  `npm view @uniquedivine/mcp-slack version`.
61
- 2. Change the `@4.5.1` pin in the client configuration to that version.
64
+ 2. Change the `@4.5.3` pin in the client configuration to that version.
62
65
  3. Restart the MCP server in the client, or restart the client. In Claude
63
66
  Code, run `/mcp` and reconnect the server. Command `bunx` downloads the new
64
67
  version on the next launch.
65
68
 
66
69
  The token store and workflow files live in your home directory, so an update
67
- needs no new credentials.
70
+ needs no new credentials. Tool `mcp_info` reports the running version and
71
+ whether a newer release exists.
68
72
 
69
- ## Install From Source
73
+ ## Tools
70
74
 
71
- Requirements: Git and Bun 1.4.3 or newer. Linked executables, package scripts,
72
- tests and CI use Bun directly; no Node installation or `node` shim is needed.
75
+ The server has 25 Slack tools. The stdio server also lists tool `mcp_info`.
76
+ [docs/API.md](docs/API.md) documents parameters, results, and errors.
73
77
 
74
- ```sh
75
- git clone https://github.com/Unique-Divine/jiyuu.git
76
- cd jiyuu
77
- just --justfile mcp/slack/justfile install
78
- ```
78
+ | Group | Tools |
79
+ |-------|-------|
80
+ | Session | `slack_health_check`, `slack_token_status`, `slack_refresh_tokens` |
81
+ | Read | `slack_list_conversations`, `slack_conversations_history`, `slack_get_full_conversation`, `slack_get_thread`, `slack_search_messages`, `slack_conversations_unreads`, `slack_users_info`, `slack_list_users`, `slack_users_search` |
82
+ | Write | `slack_send_message`, `slack_update_message`, `slack_update_message_unsafe`, `slack_delete_message`, `slack_delete_message_unsafe`, `slack_add_reaction`, `slack_remove_reaction`, `slack_conversations_mark` |
83
+ | Workflow profiles | `slack_workflow_save`, `slack_workflows` |
84
+ | Hosted only | `slack_smart_search`, `slack_catch_me_up`, `slack_triage` |
85
+
86
+ The three hosted-only tools call nothing locally and return error
87
+ `tool_requires_hosted`.
88
+
89
+ ### Edit and Delete
90
+
91
+ Tools `slack_update_message` and `slack_delete_message` act only on your own
92
+ messages. Before each write, the tool checks that:
93
+
94
+ - the signed-in user wrote the message;
95
+ - argument `expected_text` matches the message's current text;
96
+ - the message is no older than 7 days.
79
97
 
80
- Without Just, run `bun install --frozen-lockfile` inside `mcp/slack`.
81
- To make the existing command names available, run `just link` in that directory.
82
- This uses `bun link` and points them at this source checkout. The executable
83
- shebangs launch Bun directly.
98
+ Environment variable `SLACK_MCP_EDIT_DELETE_MAX_AGE_HOURS` changes the window
99
+ from its default of 168 hours. Tools `slack_update_message_unsafe` and
100
+ `slack_delete_message_unsafe` skip only the age check, for cleanup of older
101
+ messages that you ask for by name. Keep both off your client's auto-allow list
102
+ so that you confirm each call.
103
+
104
+ The stdio server lists the `_unsafe` tools. The HTTP server
105
+ (`bun src/cli.js http`) hides them unless environment variable
106
+ `SLACK_MCP_ENABLE_UNSAFE_TOOLS` is `true`, because HTTP clients may not prompt
107
+ before a call.
108
+
109
+ Each edit or delete attempt writes one `slack-mcp write` JSON line to stderr
110
+ with the tool, channel, timestamp, status, error code, and message age. The
111
+ line never holds tokens, cookies, or message text.
112
+ [Write Log](docs/API.md#write-log) lists the fields.
84
113
 
85
114
  ## Authenticate
86
115
 
87
- Use the setup helper, which stores credentials outside the source tree:
116
+ The server uses your browser session tokens: an `xoxc-` token and the `xoxd-`
117
+ value of cookie `d`. Run the setup helper, which stores them outside the
118
+ source tree:
88
119
 
89
120
  ```sh
90
- cd mcp/slack
91
- bun src/cli.js --setup
121
+ bunx @uniquedivine/mcp-slack@4.5.3 --setup
92
122
  ```
93
123
 
94
- The server accepts `SLACK_TOKEN` and `SLACK_COOKIE`, or uses the existing
95
- `~/.slack-mcp-tokens.json` store. Existing local token, workflow and cache
96
- locations are retained. No new credentials are needed for a checkout move.
97
- Do not commit tokens, cookies, browser profiles or local exports.
124
+ Environment variables `SLACK_TOKEN` and `SLACK_COOKIE` take precedence over
125
+ file `~/.slack-mcp-tokens.json`. Do not commit tokens, cookies, browser
126
+ profiles, or local exports.
127
+
128
+ Slack rotates session tokens every one to two weeks. On macOS, the server
129
+ reads fresh tokens from Chrome in three cases:
130
+
131
+ - A Slack call fails with `invalid_auth` or `token_expired`. The server
132
+ extracts new tokens and retries the call once. Edit and delete tools skip
133
+ this retry on purpose, so that a write never runs under a different
134
+ session. Refresh the tokens, then call the tool again.
135
+ - A health check, which runs every 4 hours, finds that the tokens in file
136
+ `~/.slack-mcp-tokens.json` are more than 10 days old. The server tries at
137
+ most once an hour. Tokens from environment variables have no recorded age,
138
+ so this check never refreshes them.
139
+ - You call tool `slack_refresh_tokens` or run `--refresh-tokens`.
140
+
141
+ Each case needs Chrome running with a signed-in Slack tab at `app.slack.com`.
142
+ Extraction writes file `~/.slack-mcp-tokens.json`. If you set `SLACK_TOKEN`
143
+ and `SLACK_COOKIE`, the server keeps using them, so none of these cases
144
+ helps. Update both variables or unset both.
145
+
146
+ Chrome auto-refresh runs only on macOS. On Linux, Windows, and WSL, refresh by
147
+ hand when a tool returns `invalid_auth` or `slack_auth_expired`:
148
+
149
+ 1. Sign in to Slack at <https://app.slack.com> in a browser.
150
+ 2. Run `bunx @uniquedivine/mcp-slack@4.5.3 --setup` and paste the token and
151
+ cookie when it asks. [Manual Extraction](docs/SETUP.md#manual-extraction)
152
+ shows where to find them.
153
+ 3. If you set `SLACK_TOKEN` and `SLACK_COOKIE`, update both or unset both.
154
+ Setup alone has no effect while they are set.
155
+ 4. Reconnect the MCP server.
156
+
157
+ ## Install From Source
158
+
159
+ Requirements: Git and Bun 1.4.3 or newer. Linked executables, package scripts,
160
+ tests, and CI use Bun directly; no Node installation is needed.
98
161
 
99
- ## Configure an MCP Client From Source
162
+ ```sh
163
+ git clone https://github.com/Unique-Divine/jiyuu.git
164
+ cd jiyuu
165
+ just --justfile mcp/slack/justfile install
166
+ ```
100
167
 
101
- After `just link`, the existing configuration remains valid:
168
+ Without Just, run `bun install --frozen-lockfile` inside `mcp/slack`. Command
169
+ `just link` runs `bun link`, which points command `slack-mcp` and the other
170
+ package executables at this checkout. Then configure the client:
102
171
 
103
172
  ```json
104
173
  {
@@ -108,9 +177,9 @@ After `just link`, the existing configuration remains valid:
108
177
  }
109
178
  ```
110
179
 
111
- For a direct source launch, use `bun` with the absolute path to `src/cli.js`.
112
- Restart the MCP connection after relinking or changing code. Verify the
113
- connected Slack identity before performing writes.
180
+ For a direct source launch, run `bun` with the absolute path to `src/cli.js`.
181
+ Restart the MCP connection after you relink or change code. Check the
182
+ connected Slack identity with `slack_health_check` before you write.
114
183
 
115
184
  ## Develop
116
185
 
@@ -121,27 +190,18 @@ just check
121
190
  just run
122
191
  ```
123
192
 
124
- Run these commands from `mcp/slack`. The native `bun:test` suite uses `expect`
125
- matchers and covers tool/handler parity, rich
126
- message fields and authentication-error handling without sending Slack messages.
127
- `check` builds the entrypoints to an ignored cache to catch import and syntax
128
- errors. TypeScript conversion and native `bun check` coverage are follow-ups.
129
-
130
- The inherited Dockerfile still describes the upstream Node image and is not
131
- the supported Jiyuu installation. Its conversion is tracked separately.
193
+ Run these commands from `mcp/slack`. The `bun:test` suite covers tool and
194
+ handler parity, rich message fields, edit and delete guards, the write log,
195
+ and authentication errors without sending Slack messages. Recipe `check`
196
+ builds the entrypoints to an ignored cache to catch import and syntax errors.
132
197
 
133
- HTTP and web modes remain available through `bun src/cli.js http` and
134
- `bun src/cli.js web`. The inherited hosted-service, pricing and marketing code
135
- has not been removed in this compatibility import. Keeping it is not a
136
- recommendation to deploy or purchase the original hosted service.
198
+ HTTP and web modes run through `bun src/cli.js http` and
199
+ `bun src/cli.js web`. [docs/WEB-API.md](docs/WEB-API.md) covers the web mode.
200
+ The Dockerfile targets a Node image and is not a supported install path.
137
201
 
138
202
  Report issues in [Unique-Divine/jiyuu](https://github.com/Unique-Divine/jiyuu/issues)
139
- with `mcp/slack` in the title. The version continues from the imported
140
- `@jtalk22/slack-mcp` 4.4.3. Package metadata `jiyuu.upstream` in file
141
- `package.json` records that baseline.
203
+ with `mcp/slack` in the title.
142
204
 
143
- ## Origin and License
205
+ ## License
144
206
 
145
- Imported from `Unique-Divine/slack-mcp-server`, originally forked from
146
- `jtalk22/slack-mcp-server`. [IMPORT.json](IMPORT.json) pins the source commit.
147
- The original [MIT license and copyright notice](LICENSE) are retained.
207
+ MIT. See [LICENSE](LICENSE).
package/docs/API.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # API Reference
2
2
 
3
+ Parameters, results, and errors for the 25 Slack tools in
4
+ `@uniquedivine/mcp-slack`, plus tool `mcp_info`. Over HTTP, the `_unsafe`
5
+ tools need `SLACK_MCP_ENABLE_UNSAFE_TOOLS=true`.
6
+
3
7
  ## Tools
4
8
 
5
9
  ### slack_health_check
@@ -14,8 +18,8 @@ Check if Slack tokens are valid.
14
18
  "status": "ok",
15
19
  "code": "ok",
16
20
  "message": "Slack auth valid",
17
- "user": "james",
18
- "team": "Rêvasser",
21
+ "user": "unique",
22
+ "team": "Example Workspace",
19
23
  "token_source": "environment",
20
24
  "token_updated": "2026-01-03T00:00:00Z"
21
25
  }
@@ -70,8 +74,8 @@ Force refresh tokens from Chrome.
70
74
  "status": "ok",
71
75
  "code": "refreshed",
72
76
  "message": "Tokens refreshed from Chrome.",
73
- "user": "james",
74
- "team": "Rêvasser"
77
+ "user": "unique",
78
+ "team": "Example Workspace"
75
79
  }
76
80
  ```
77
81
 
@@ -149,20 +153,20 @@ Get messages from a channel or DM.
149
153
  }
150
154
  ```
151
155
 
152
- `include_rich_message_fields` changes this tool's **output shape only** — it surfaces fields Slack
153
- already returns on the message object: `attachments`, `blocks`, `files`, `reactions`, `metadata`,
154
- plus `subtype`, `bot_id`, `app_id` (markers that flag automated / bot / app messages) and `team`
155
- (the workspace id, present on all messages). Especially `blocks` can be large, so it's opt-in per
156
- call to keep MCP client context lean.
156
+ Parameter `include_rich_message_fields` changes only the output shape. It
157
+ adds fields Slack already returns on each message: `attachments`, `blocks`,
158
+ `files`, `reactions`, `metadata`, `subtype`, `bot_id`, `app_id`, and `team`.
159
+ Fields `subtype`, `bot_id`, and `app_id` mark bot and app messages. Field
160
+ `blocks` can be large, so the parameter is off by default.
157
161
 
158
- `include_all_metadata` is a **separate, independent** Slack request flag: its only effect is to add
159
- the full `event_payload` inside a message's developer `metadata` (without it you still get
160
- `metadata.event_type`). The two are orthogonal — set `include_rich_message_fields` to see `metadata`
161
- in the output at all; additionally set `include_all_metadata` for the full payload.
162
+ Parameter `include_all_metadata` is a separate Slack request flag. It adds the
163
+ full `event_payload` inside a message's `metadata`; without it, you get only
164
+ `metadata.event_type`. Set `include_rich_message_fields` to see `metadata` at
165
+ all, and add `include_all_metadata` for the full payload.
162
166
 
163
- Note: `slack_search_messages` matches are thin — Slack's search API does not return these rich
164
- fields on matches (only `team`). To read rich content for a search hit, call
165
- `slack_conversations_history` or `slack_get_thread` on the match's channel/ts.
167
+ Slack's search API doesn't return these rich fields on matches, only `team`.
168
+ To read rich content for a search hit, call `slack_conversations_history` or
169
+ `slack_get_thread` with the match's channel and timestamp.
166
170
 
167
171
  ---
168
172
 
@@ -196,7 +200,7 @@ Export full conversation with threads.
196
200
  "oldest": "2025-12-01T00:00:00Z",
197
201
  "latest": "now"
198
202
  },
199
- "saved_to": "/Users/james/export.json",
203
+ "saved_to": "/Users/you/export.json",
200
204
  "messages": [...]
201
205
  }
202
206
  ```
@@ -319,6 +323,7 @@ Before it calls `chat.delete`, the tool checks the target:
319
323
  | `invalid_argument` | An argument is missing or malformed; `field` names it |
320
324
  | `message_too_old` | The message is older than the age window |
321
325
  | `message_not_found` | No message with that timestamp in the channel |
326
+ | `message_deleted` | Only a deleted thread parent's placeholder remains at that timestamp |
322
327
  | `lookup_incomplete` | The thread search hit its page cap before finding the message |
323
328
  | `not_own_message` | Someone else, or a bot, sent the message |
324
329
  | `text_mismatch` | `expected_text` doesn't match the message's text |
@@ -411,6 +416,7 @@ string of at most 4,000 characters.
411
416
  | `invalid_argument` | An argument is missing or malformed; `field` names it |
412
417
  | `message_too_old` | The message is older than the age window |
413
418
  | `message_not_found` | No message with that timestamp in the channel |
419
+ | `message_deleted` | Only a deleted thread parent's placeholder remains at that timestamp |
414
420
  | `lookup_incomplete` | The thread search hit its page cap before finding the message |
415
421
  | `not_own_message` | Someone else, or a bot, sent the message |
416
422
  | `text_mismatch` | `expected_text` doesn't match the message's text |
@@ -655,3 +661,77 @@ Search workspace users by name, display name, or email. Case-insensitive partial
655
661
  ]
656
662
  }
657
663
  ```
664
+
665
+ ---
666
+
667
+ ### slack_workflow_save
668
+
669
+ Save or update a workflow profile in file `~/.slack-mcp-workflows.json`. A
670
+ profile binds a `workflow_kind` to channels and people. Only the hosted-only
671
+ tools below read profiles.
672
+
673
+ **Parameters:**
674
+ | Name | Type | Default | Description |
675
+ |------|------|---------|-------------|
676
+ | profile_name | string | *required* | Profile name |
677
+ | workflow_kind | string | *required* | `support_inbox`, `incident_room`, `exec_brief`, `product_launch_watch`, or `custom` |
678
+ | channels | string[] | - | Channel IDs |
679
+ | priority_people | string[] | - | User IDs to weight higher |
680
+ | retention_mode | string | `ephemeral` | `ephemeral` or `persistent` |
681
+ | summary_cadence | string | - | `on_demand`, `daily_8am`, or `weekly_monday` |
682
+
683
+ ---
684
+
685
+ ### slack_workflows
686
+
687
+ List saved workflow profiles. Optional parameter `workflow_kind` filters them.
688
+
689
+ ---
690
+
691
+ ### slack_smart_search, slack_catch_me_up, slack_triage
692
+
693
+ Upstream's hosted-only AI tools. This package lists them for parity with
694
+ upstream, but locally each returns error `tool_requires_hosted` without
695
+ calling Slack. The error carries upstream's signup and pricing links.
696
+
697
+ ---
698
+
699
+ ### mcp_info
700
+
701
+ Report the server version, install source, and whether a newer release
702
+ exists. The stdio server lists it; the HTTP server doesn't. It takes no
703
+ parameters.
704
+
705
+ Each call reads the npm registry. If npm can't be reached, the `update`
706
+ object holds the last cached answer and `update.source` is `cache` instead
707
+ of `live`. `update.pinCommand` is set only when npm has a newer version. See
708
+ the [MCP servers README](../../README.md#version-and-update-notices).
709
+
710
+ ## Write Log
711
+
712
+ Each call to `slack_delete_message`, `slack_delete_message_unsafe`,
713
+ `slack_update_message`, or `slack_update_message_unsafe` writes one line to
714
+ stderr, whether it succeeds, is refused, or throws:
715
+
716
+ ```text
717
+ slack-mcp write {"tool":"slack_delete_message","channel":"D063M4403MW","timestamp":"1767368030.607599","status":"deleted","code":null,"age_hours":0.2}
718
+ ```
719
+
720
+ | Field | Meaning |
721
+ |-------|---------|
722
+ | `tool` | The tool called |
723
+ | `channel` | `channel_id`, once Slack has answered `conversations.history` for it; otherwise `null` |
724
+ | `timestamp` | `timestamp`, once Slack has returned that message; otherwise `null` |
725
+ | `status` | `deleted`, `updated`, `probably_deleted`, `outcome_unknown`, `error`, or `thrown` |
726
+ | `code` | The error code, such as `text_mismatch`, or `null` on success |
727
+ | `age_hours` | The message's age in hours, once Slack has returned that message; otherwise `null` |
728
+
729
+ The line never includes tokens, cookies, or message text. `channel_id` and
730
+ `timestamp` come from the caller, and an ID shape proves nothing:
731
+ `C0NF1DENT1AL` looks like a channel ID. So the log writes the channel only
732
+ after Slack confirms the conversation exists, and the timestamp only after
733
+ Slack returns the message. A refusal before any Slack call, such as
734
+ `invalid_argument` or `message_too_old`, and a Slack error such as
735
+ `channel_not_found` or `not_in_channel` log both as `null`, along with
736
+ `age_hours`. A `message_too_old` result still reports the age to the caller. For
737
+ `message_not_found`, the channel is logged and the timestamp and age are `null`.
@@ -8,15 +8,14 @@ Use this guide to choose the right operating mode before rollout.
8
8
  - Choose local `web` for browser workflows and manual Slack browsing.
9
9
  - Choose hosted HTTP only when you need remote execution and can handle token operations.
10
10
  - Choose Smithery/Worker only when your consumers require registry-hosted MCP transport.
11
- - A managed **Hosted** version is live at [mcp.revasserlabs.com](https://mcp.revasserlabs.com) — Free tier (no card), Pro $19/mo, Team $49/mo flat, Safeguard $199/mo (waitlist). See [pricing](https://mcp.revasserlabs.com/pricing).
12
11
 
13
12
  ## Mode Matrix
14
13
 
15
14
  | Mode | Start Command | Best For | Auth Material | Exposure | Notes |
16
15
  |------|---------------|----------|---------------|----------|-------|
17
- | Local MCP (`stdio`) | `bunx @uniquedivine/mcp-slack` | Individual daily usage in Claude | `SLACK_TOKEN` + `SLACK_COOKIE` via token file/env | Local process | Lowest ops burden. Free. 21 tools (16 read/write + 2 workflow profile primitives + 3 discoverable upgrade stubs to hosted). |
16
+ | Local MCP (`stdio`) | `bunx @uniquedivine/mcp-slack` | Individual daily usage in Claude | `SLACK_TOKEN` + `SLACK_COOKIE` via token file/env | Local process | 26 tools: 25 Slack tools plus `mcp_info`. |
18
17
  | Local Web UI (`web`) | `bunx @uniquedivine/mcp-slack web` | Browser-first usage, manual search/send | Same as above + generated API key | `localhost` by default | Useful when MCP is not available |
19
- | Hosted MCP (`http`) | `bun src/server-http.js` | Controlled hosted integration | Env-injected Slack token/cookie + HTTP bearer token | Remote endpoint | `/mcp` is bearer-protected by default; configure CORS allowlist |
18
+ | Hosted MCP (`http`) | `bun src/server-http.js` | Controlled hosted integration | Env-injected Slack token/cookie + HTTP bearer token | Remote endpoint | `/mcp` requires a bearer token. The `_unsafe` tools need `SLACK_MCP_ENABLE_UNSAFE_TOOLS=true`. |
20
19
  | 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 |
21
20
 
22
21
  ## Team Deployment Guidance