* feat: add slack-cli, a no-daemon CLI over the slack-mcp-server engine
Turn the forked slack-mcp-server into a CLI so running many agents no
longer means one resident MCP process each. Every command is a
short-lived process that reads the shared on-disk cache.
- rename module to github.com/paymog/slack-cli (go install/homebrew/ldflags)
- internal/toolcall: invoke the upstream tool handlers in-process; the only
mcp-go coupling lives here, so pkg/handler and pkg/provider are reused
byte-for-byte (clean upstream merges, fork-and-extend)
- internal/{cli,cmds,config,credstore,runtime,output}: cobra command tree,
keyring-backed credential profiles, provider bootstrap, result printing
- 21 tools as subcommands (channels, conversations, users, usergroups,
saved, reactions, attachments, cache); write tools keep their env gating
- goreleaser + homebrew release workflow; ships a skills/slack-cli skill
- unit tests for config/credstore/toolcall; MCP server still builds
The MCP server (cmd/slack-mcp-server) is kept intact.
* chore(napkin): record real-workspace verification
* docs: explain how the CLI works (in-process handler invocation, shared cache)
The sort=popularity option forced fetching every channel the user belongs
to before sorting client-side — hundreds of API calls on large workspaces.
The Slack API doesn't support server-side sorting, so this was inherently
expensive. Remove it and always stop fetching once we have enough results,
using the Slack API's native cursor for pagination.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a new MCP tool to list channels the calling user is a member of,
using the users.conversations API. Follows the same pattern as
usergroups_me vs usergroups_list.
Unlike channels_list which returns all workspace channels, channels_me
returns only channels the user has joined — useful on large workspaces
where channels_list returns thousands of results.
Supports channel_types, sort (by popularity), limit, and cursor
parameters.
Add optional `blocks` parameter to conversations_add_message for raw
Slack Block Kit JSON support (rich_text lists, code blocks, etc.).
When blocks is provided it takes precedence over text/content_type for
message rendering. The text parameter serves as notification fallback.
The blocks argument accepts both a JSON string and a raw JSON array to
accommodate different MCP client serialization behaviors.
Also bumps takara2314/slack-go-util from v0.3.0 to v0.4.0 which adds
nested list support to the existing text/markdown conversion path.
Previously, the AttachmentIDs field only contained raw file IDs
(e.g. "F08ABC1234"), making it impossible to identify which file
an ID corresponds to without calling attachment_get_data first.
Now the field includes filenames: "F08ABC1234 (contract.pdf)".
This makes it practical to use AttachmentIDs to selectively
download relevant attachments.
Fixes#260
When the query matches a Slack user ID pattern (e.g., U07VCEPP4N5),
use the users.info API for direct lookup instead of searching by
name/email/display name. This is useful when you already have a
user ID (from message metadata, mentions, etc.) and need to resolve
it to user details.
Falls back to existing search behavior for non-ID queries.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Closes#251. Adds keyword filtering to channels_list so users can find
channels without paginating through the entire list. Matches are
case-insensitive substrings; query_targets controls which fields to
search (name by default, optionally topic and purpose).
Add three new tools for managing Slack's "Save for Later" panel,
replacing the deprecated stars.* API (March 2023). Uses internal
saved.list, saved.update, and saved.clearCompleted endpoints.
- saved_list: List saved items with filter (saved/completed/archived),
auto-pagination, and optional message content fetching
- saved_update: Mark items as completed and/or set due dates
- saved_clear_completed: Bulk-clear all completed items
All tools require browser session tokens (xoxc/xoxd) and are guarded
at registration time for bot/OAuth tokens.
Includes unit tests for CSV format, field extraction, timestamp
formatting, parameter validation, and response parsing.
Made-with: Cursor
Add two new MCP tools for channel membership management:
- conversations_join: Join public channels via conversations.join API.
Idempotent — joining a channel you're already in is a no-op.
Requires channels:join (xoxb) or channels:write (xoxp) scope.
- conversations_leave: Leave channels, group conversations, or DMs
via conversations.leave API. Marked as destructive.
Requires channels:manage (xoxb) or channels:write (xoxp) scope.
On Enterprise Grid with session tokens (xoxc/xoxd), routes through
the edge API to bypass enterprise_is_restricted errors.
Both tools accept channel IDs (Cxxxxxxxxxx) or names (#channel-name)
using the existing resolveChannelID helper.
Updated docs/01-authentication-setup.md with new OAuth scopes
(channels:join, channels:manage) and docs/03-configuration-and-usage.md
with the new tool names in the available tools list.
* fix: pre-check token type to avoid faulty ClientCounts call
client.counts only works with browser session tokens (xoxc/xoxd). OAuth
tokens (xoxp) get 'not_allowed_token_type' and bot tokens (xoxb) have no
concept of user-level unreads.
Instead of calling ClientCounts and catching the error after the fact,
pre-check the token type using the existing IsOAuth()/IsBotToken()
infrastructure and route directly to the appropriate path:
- xoxc/xoxd: fast path via client.counts (unchanged)
- xoxp: conversations.info fallback (no wasted API call)
- xoxb: clear error message
Follows the same pattern used by SearchUsers and GetConversationsContext
which already branch on token type.
Addresses review comments on korotovsky/slack-mcp-server#171.
* fix: exclude conversations_unreads tool for bot tokens
Bot tokens (xoxb) don't support unread tracking — it's a user-level
concept. Don't register the tool at all for bot token users, matching
the same pattern used for conversations_search_messages.
This gives a clean UX: bot users simply don't see the tool, rather
than getting a runtime error.
* fix: cap xoxp fallback scan depth and document limitations
The xoxp path previously scanned ALL channels (~2000+ API calls on large
workspaces). Slack's API has no bulk unread endpoint for xoxp tokens —
every other open-source implementation (agent-kit, NextNotifier, wee-slack)
uses the same per-channel scanning approach.
Changes:
- Cap scan depth to budget*2 per type group (~300 API calls max with
default max_channels=50, down from ~2000+)
- Return scan metadata (channels scanned, API calls) from each type group
- Prepend an xoxp limitation note to response text so the LLM knows
results may be partial
- Update tool description to explain xoxc vs xoxp behavior
- Fix inaccurate comment about conversations.list sort order
* fix: validate GetMutedChannels response to surface xoxp failures
Add validate() call after ParseResponse in GetMutedChannels (prefs.go),
matching the pattern used in ClientCounts. Without this, xoxp tokens
receive {ok:false, error:missing_scope} but ParseResponse only checks
HTTP status — the error was silently swallowed, returning nil/nil.
This caused muted channels to leak into xoxp results (17/28 channels
were muted in testing). Now the error propagates to the handler's
existing warn-and-proceed logic.
Also surface the limitation in the xoxp response note so the LLM
knows muted filtering is unavailable.
* fix: add shouldAddTool gating for conversations_unreads and conversations_mark
Both tools were missing Tool* constants, ValidToolNames entries, and
shouldAddTool() wrapping — breaking the established pattern used by
every other tool in the server. This prevented selective enable/disable
via the enabledTools config.
Also fixes indentation on conversations_mark registration block.
* fix: use index-based range loop so unread counts persist
The message-fetch loop uses 'for _, uc := range unreadChannels', so
writes to uc.UnreadCount go to a copy — the original slice element
stays at 0. Messages are fetched correctly (appended to a separate
slice), but the unread count column is silently wrong.
Switch to 'for i := range' and index into the slice directly.
Also aligns struct field formatting (gofmt).
* feat: backfill unread counts via conversations.history
client.counts returns HasUnreads (bool) and MentionCount per channel,
but MentionCount is only non-zero for @mentions. Regular channel
activity shows as 'has unreads' with count 0.
For channels where HasUnreads=true and MentionCount=0, call
conversations.history(oldest=lastRead, limit=20) to count actual
unread messages. DMs don't need this since every message counts
as a mention.
* feat: filter muted channels from unreads by default
Fetches muted channel set from users.prefs.get (all_notifications_prefs)
and excludes them from both ClientCounts and conversations.info fallback
paths. Adds include_muted opt-in parameter to show muted channels when
explicitly requested.
Muted status is only available in users.prefs.get as a nested JSON
string — it is not exposed by client.counts, conversations.info, or
conversations.list.
- Add mentions_only parameter to conversations_unreads to filter
channels to only those with @mentions (priority inbox)
- Add conversations_mark tool to mark channels/DMs as read
- Supports channel IDs, #channel names, and @username
- If no timestamp provided, marks all messages as read
- Uses ClientUserBoot to get all channels with LastRead/Latest in one API call
- Filters channels where Latest > LastRead to find unreads
- Prioritizes: DMs > group DMs > partner channels (ext-*) > internal
- Only fetches message history for channels with actual unreads
- Supports filtering by channel type and configurable limits
Addresses issue #114
Verifies that the error recovery middleware correctly converts handler
errors into isError tool results instead of JSON-RPC protocol errors.
Uses mcp-go client/server wired via stdio pipes to test the full
middleware chain without external dependencies.
Per the MCP specification, tool execution errors should be returned as
tool results with isError=true, not as JSON-RPC protocol errors (-32603).
This allows LLMs to see the error message and self-correct by retrying
with different parameters.
Previously, all handler errors were returned as Go errors which mcp-go
converted into JSON-RPC -32603 responses. MCP clients either crash or
silently discard these, so the LLM never sees what went wrong.
This adds a middleware that catches handler errors and converts them to
mcp.NewToolResultError() responses. The middleware is registered before
the logger and auth middlewares, so it catches all tool handler errors
regardless of which tool triggered them.
Resolve conflict in README.md by keeping updated env var descriptions
that document the SLACK_MCP_ENABLED_TOOLS interaction.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Merge shouldAddTool and shouldAddWriteTool into single function
- Remove redundant comments
- Add envVarName parameter for write tools requiring explicit enablement
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Write tools (conversations_add_message, reactions_add, reactions_remove,
attachment_get_data) now require explicit enablement:
- If ENABLED_TOOLS explicitly includes the tool, register it
- If ENABLED_TOOLS is empty, only register if tool-specific env var is set
- If ENABLED_TOOLS excludes the tool, don't register
This resolves the conflict where ENABLED_TOOLS="" would register all tools
but SLACK_MCP_ADD_MESSAGE_TOOL="" would fail at runtime with an error.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add five new tools for managing Slack user groups (subteams):
- usergroups_list: List all user groups in the workspace
- usergroups_me: Manage your own membership (list/join/leave)
- usergroups_create: Create a new user group
- usergroups_update: Update group metadata (name, handle, description)
- usergroups_users_update: Replace all members of a group
The usergroups_me tool provides a convenient way to join or leave
groups without needing to know the full member list. It handles
fetching current members and updating the list automatically.
Required OAuth scopes:
- usergroups:read (for list operations)
- usergroups:write (for create/update/join/leave operations)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The parameter name was inconsistent with the error message which said
"text must be a string". Changed to use "text" as the primary parameter
name with backward compatibility for "payload".
Fixes#181
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds a new users_search tool that searches for Slack users by name,
email, or display name using the Edge API. Returns user details
including UserID, username, real name, display name, email, title,
and DM channel ID (if available in cache).
Note: This feature requires browser session tokens (xoxc/xoxd),
not OAuth tokens (xoxp/xoxb), similar to conversations_unreads.
- Add Tool* constants to avoid magic strings in tool registration
- Add ValidToolNames slice and ValidateEnabledTools function
- Validate tool names at startup, fail with helpful error message
- Update tests to use constants
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Simplify the logic so that:
- ENABLED_TOOLS only controls which tools are registered/exposed via MCP
- Empty ENABLED_TOOLS = all tools registered (no filtering)
- Runtime permissions (ADD_MESSAGE_TOOL, REACTION_TOOL, ATTACHMENT_TOOL)
are always enforced in handlers regardless of ENABLED_TOOLS
This keeps the two concerns separate:
1. Registration/visibility (ENABLED_TOOLS)
2. Runtime permissions (individual tool env vars)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add a new CLI flag `--enabled-tools` (alias `-e`) and environment variable
`SLACK_MCP_ENABLED_TOOLS` to allow users to specify which MCP tools should
be loaded. This provides flexibility to limit tool exposure based on
security requirements or use case.
- If not set, all tools are enabled (backward compatible)
- Accepts comma-separated tool names
- CLI flag takes precedence over environment variable
Available tools: conversations_history, conversations_replies,
conversations_add_message, reactions_add, reactions_remove,
attachment_get_data, conversations_search_messages, channels_list
Example usage:
slack-mcp-server --enabled-tools=conversations_history,channels_list
SLACK_MCP_ENABLED_TOOLS=channels_list slack-mcp-server
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Tool: files_get → attachment_get_data
- Field: FileIDs → AttachmentIDs
- Env var: SLACK_MCP_FILES_TOOL → SLACK_MCP_ATTACHMENT_TOOL
Per maintainer feedback - aligns with Slack's 'attachment' terminology
and may improve LLM performance due to training data prevalence.
Adds ability to download file content by file ID, addressing maintainer
request on PR #170.
- New files_get tool gated by SLACK_MCP_FILES_TOOL env var
- Text files (text/*, application/json, etc.) returned as plain text
- Binary files returned as base64-encoded content
- 5MB size limit to keep responses reasonable for LLM context
- Returns structured JSON: file_id, filename, mimetype, size, encoding, content
Companion to reactions_add (merged in #141). Allows removing emoji
reactions from messages using the same channel/timestamp/emoji params.
Tested with xoxb, xoxc/xoxd token types.
Add readOnlyHint and destructiveHint annotations to all tools
to help LLMs better understand tool behavior and make safer decisions.
Changes:
- Added readOnlyHint: true to read-only tools (conversations_history,
conversations_replies, conversations_search_messages, channels_list)
- Added destructiveHint: true to conversations_add_message tool
- Added title annotations for human-readable display
This improves tool safety metadata for MCP clients by providing
semantic hints about whether tools modify data or just read it.
Co-Authored-By: Claude <noreply@anthropic.com>
- Add support for bot tokens as an alternative authentication method
- Conditionally register search tool only for non-bot tokens (bots cannot use search.messages API)
- Update isOAuth definition to include both xoxp and xoxb tokens for cleaner implementation
- Add bot token configuration to manifest-dxt.json for DXT extension
- Document bot token limitations in README and authentication setup guide
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Paymahn Moghadasian