Slack MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview A TypeScript-based Model Context Protocol (MCP) server for Slack workspace integration. This server exposes Slack's Web API through the MCP protocol, allowing AI assistants to interact with channels, users, messages, files, and reactions. Ported from: https://github.com/piekstra/slack-mcp-server ## Build and Development Commands ```bash # Build the project (compiles TypeScript to build/) npm run build # Development mode with hot reload npm run dev # Start the compiled server npm start # Test with MCP Inspector npx @modelcontextprotocol/inspector node build/index.js ``` ## Architecture ### MCP Server Structure The server follows a modular architecture with three layers: 1. **Entry Point** (`src/index.ts`): MCP server initialization and tool registration - Defines all 17 tool schemas inline (channels, users, messages, files, reactions, workspace) - Maps tool names to handler functions via `toolHandlers` record - Handles tool invocation through CallToolRequestSchema 2. **Tool Handlers** (`src/tools/`): Business logic for each API category - Each file exports async functions that accept `SlackClientWrapper` + validated args - Uses Zod schemas from validators for input validation - Returns structured JSON responses 3. **Core Utilities**: - `SlackClientWrapper` (`src/utils/slack-client.ts`): Wraps Slack WebClient with error handling - Validators (`src/utils/validators.ts` & `src/utils/block-validators.ts`): Zod schemas for all inputs - Config (`src/config/credentials.ts`): Environment variable loader with token validation ### Data Flow ``` MCP Client Request → index.ts (CallToolRequestSchema handler) → toolHandlers[toolName](args) → Tool handler validates with Zod → SlackClientWrapper.safeCall() → Slack Web API call → Error handling / response formatting → JSON response to MCP client ``` ### Key Design Patterns - **Error Handling**: All Slack API calls wrapped in `SlackClientWrapper.safeCall()` which translates Slack error codes to human-readable messages - **Validation**: Zod schemas validate all inputs before API calls, catching format errors early - **Type Safety**: TypeScript interfaces in `src/types/slack.ts` define contracts - **Separation of Concerns**: Tool definitions (index.ts), validation (validators.ts), and API calls (tools/*.ts) are decoupled ## Configuration The server requires `SLACK_BOT_TOKEN` environment variable (format: `xoxb-*`). Token validation happens at startup in `getSlackConfig()` (src/config/credentials.ts:7-28). Required OAuth scopes: `channels:read`, `channels:write`, `channels:manage`, `users:read`, `chat:write`, `files:write`, `reactions:write`, `team:read`, `search:read` ## Tool Categories - **Channels**: list_channels, get_channel_info, create_channel, archive_channel - **Users**: list_users, get_user_info, invite_to_channel - **Messages**: send_message, update_message, delete_message, get_channel_history, search_messages, send_formatted_message - **Files**: upload_file - **Reactions**: add_reaction, remove_reaction - **Workspace**: get_team_info ## Common Patterns ### Adding a New Tool 1. Add tool definition object to `tools` array in `src/index.ts` (with name, description, inputSchema) 2. Create handler function in appropriate `src/tools/*.ts` file 3. Add Zod validator schema to `src/utils/validators.ts` 4. Map tool name to handler in `toolHandlers` record (src/index.ts:413-442) ### Slack ID Formats - Channels: `C[A-Z0-9]+` (public) or `G[A-Z0-9]+` (private/group) or `D[A-Z0-9]+` (DM) - Users: `U[A-Z0-9]+` - Message timestamps: `\d+\.\d+` format (e.g., `1234567890.123456`) Validation regexes are in `src/utils/validators.ts:5-8`. ### Block Kit Messages The `send_formatted_message` tool accepts Block Kit blocks. Block validation is handled by `blocksArraySchema` in `src/utils/block-validators.ts`. See Slack's Block Kit documentation for structure.