slack-workspace-mcp-server 0.0.1

package/README.md

@@ -0,0 +1,122 @@
+# Slack MCP Server
+
+A Model Context Protocol (MCP) server for integrating with Slack workspaces. This server provides tools for reading and writing messages, managing threads, and reacting to messages in Slack.
+
+## Features
+
+- **List Channels** - View all accessible public and private channels
+- **Read Channel** - Get channel info and recent messages
+- **Read Threads** - Get full threaded conversations
+- **Post Messages** - Send new messages to channels
+- **Reply to Threads** - Continue threaded conversations
+- **Update Messages** - Edit previously posted messages
+- **React to Messages** - Add emoji reactions to messages
+
+## Installation
+
+```bash
+npm install slack-workspace-mcp-server
+```
+
+Or run directly with npx:
+
+```bash
+npx slack-workspace-mcp-server
+```
+
+## Configuration
+
+### Required Environment Variables
+
+| Variable          | Description                | Example        |
+| ----------------- | -------------------------- | -------------- |
+| `SLACK_BOT_TOKEN` | Slack Bot User OAuth Token | `xoxb-1234...` |
+
+### Optional Environment Variables
+
+| Variable             | Description                         | Default     |
+| -------------------- | ----------------------------------- | ----------- |
+| `ENABLED_TOOLGROUPS` | Comma-separated list of tool groups | All enabled |
+
+### Getting a Bot Token
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Create a new app or select an existing one
+3. Navigate to **OAuth & Permissions**
+4. Add the following **Bot Token Scopes**:
+   - `channels:read` - View basic channel information
+   - `channels:history` - View messages in public channels
+   - `groups:read` - View private channels
+   - `groups:history` - View messages in private channels
+   - `chat:write` - Send messages
+   - `reactions:write` - Add reactions
+5. Install the app to your workspace
+6. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
+
+### MCP Client Configuration
+
+For Claude Desktop, add to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "command": "npx",
+      "args": ["slack-workspace-mcp-server"],
+      "env": {
+        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Read-Only Tools
+
+| Tool                 | Description                           |
+| -------------------- | ------------------------------------- |
+| `slack_get_channels` | List all accessible channels          |
+| `slack_get_channel`  | Get channel info with recent messages |
+| `slack_get_thread`   | Get a thread with all replies         |
+
+### Write Tools
+
+| Tool                     | Description                        |
+| ------------------------ | ---------------------------------- |
+| `slack_post_message`     | Post a new message to a channel    |
+| `slack_reply_to_thread`  | Reply to an existing thread        |
+| `slack_update_message`   | Update a previously posted message |
+| `slack_react_to_message` | Add an emoji reaction to a message |
+
+## Tool Groups
+
+You can control which tools are available using the `ENABLED_TOOLGROUPS` environment variable:
+
+- `readonly` - Only read operations (get channels, messages, threads)
+- `write` - All operations including posting and reactions
+
+Example: `ENABLED_TOOLGROUPS=readonly` to disable all write operations.
+
+## Development
+
+```bash
+# Install dependencies
+npm run install-all
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test                  # Functional tests
+npm run test:integration  # Integration tests
+npm run test:manual       # Manual tests (requires real credentials)
+
+# Build
+npm run build
+```
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.integration-with-mock.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.integration-with-mock.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Integration Test Server Entry Point with Mock Client Factory
+ *
+ * This file is used for integration testing with a mocked SlackClient.
+ * It uses the real MCP server but injects a mock client factory.
+ *
+ * Mock data is passed via the SLACK_MOCK_DATA environment variable.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { createIntegrationMockSlackClient } from '../shared/slack-client/slack-client.integration-mock.js';
+async function main() {
+    const transport = new StdioServerTransport();
+    // Parse mock data from environment variable
+    let mockData = {};
+    if (process.env.SLACK_MOCK_DATA) {
+        try {
+            mockData = JSON.parse(process.env.SLACK_MOCK_DATA);
+        }
+        catch (e) {
+            console.error('Failed to parse SLACK_MOCK_DATA:', e);
+        }
+    }
+    // Create client factory that returns our mock
+    const clientFactory = () => createIntegrationMockSlackClient(mockData);
+    const { server, registerHandlers } = createMCPServer();
+    await registerHandlers(server, clientFactory);
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/build/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart, logError, logWarning } from '../shared/logging.js';
+// =============================================================================
+// ENVIRONMENT VALIDATION
+// =============================================================================
+function validateEnvironment() {
+    const required = [
+        {
+            name: 'SLACK_BOT_TOKEN',
+            description: 'Slack Bot User OAuth Token (starts with xoxb-)',
+            example: 'xoxb-YOUR-WORKSPACE-ID-YOUR-BOT-TOKEN-HERE',
+        },
+    ];
+    const optional = [
+        {
+            name: 'ENABLED_TOOLGROUPS',
+            description: 'Comma-separated list of tool groups to enable (readonly, write)',
+            defaultValue: 'all groups enabled',
+        },
+    ];
+    const missing = required.filter(({ name }) => !process.env[name]);
+    if (missing.length > 0) {
+        logError('validateEnvironment', 'Missing required environment variables:');
+        missing.forEach(({ name, description, example }) => {
+            console.error(`  - ${name}: ${description}`);
+            console.error(`    Example: ${example}`);
+        });
+        if (optional.length > 0) {
+            console.error('\nOptional environment variables:');
+            optional.forEach(({ name, description, defaultValue }) => {
+                const defaultStr = defaultValue ? ` (default: ${defaultValue})` : '';
+                console.error(`  - ${name}: ${description}${defaultStr}`);
+            });
+        }
+        console.error('\n----------------------------------------');
+        console.error('Please set the required environment variables and try again.');
+        console.error('\nTo get a bot token:');
+        console.error('1. Go to https://api.slack.com/apps');
+        console.error('2. Create or select your app');
+        console.error('3. Go to "OAuth & Permissions"');
+        console.error('4. Copy the "Bot User OAuth Token"');
+        console.error('----------------------------------------\n');
+        process.exit(1);
+    }
+    // Validate token format
+    const token = process.env.SLACK_BOT_TOKEN;
+    if (!token.startsWith('xoxb-')) {
+        logWarning('validateEnvironment', 'SLACK_BOT_TOKEN should start with "xoxb-"');
+    }
+    // Log active tool groups if configured
+    if (process.env.ENABLED_TOOLGROUPS) {
+        logWarning('config', `Tool groups filter active: ${process.env.ENABLED_TOOLGROUPS}`);
+    }
+}
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+async function main() {
+    // Step 1: Validate environment variables
+    validateEnvironment();
+    // Step 2: Create server using factory
+    const { server, registerHandlers } = createMCPServer();
+    // Step 3: Register all handlers (tools)
+    await registerHandlers(server);
+    // Step 4: Start server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('Slack');
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "slack-workspace-mcp-server",
+  "version": "0.0.1",
+  "description": "MCP server for Slack workspace integration",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "slack-workspace-mcp-server": "./build/index.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "shared/**/*.js",
+    "shared/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:integration",
+    "build:integration": "tsc -p tsconfig.integration.json",
+    "start": "node build/index.js",
+    "dev": "tsx src/index.ts",
+    "predev": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prebuild": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prepublishOnly": "node prepare-publish.js && node ../scripts/prepare-npm-readme.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "stage-publish": "npm version"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.6",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "mcp",
+    "slack",
+    "model-context-protocol"
+  ],
+  "author": "PulseMCP",
+  "license": "MIT"
+}

package/shared/index.d.ts

@@ -0,0 +1,4 @@
+export { createMCPServer, SlackClient, type ISlackClient, type ClientFactory } from './server.js';
+export { createRegisterTools, registerTools } from './tools.js';
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+export type { Channel, Message, Reaction, Attachment, Block, ThreadWithReplies, User, PaginatedResponse, } from './types.js';

package/shared/index.js

@@ -0,0 +1,7 @@
+// Main exports for Slack MCP Server
+// Server and client
+export { createMCPServer, SlackClient } from './server.js';
+// Tools
+export { createRegisterTools, registerTools } from './tools.js';
+// Logging utilities
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';

package/shared/logging.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Centralized logging utilities for Slack MCP Server
+ *
+ * IMPORTANT: All logging uses console.error() to write to stderr.
+ * The MCP protocol requires stdout to contain only JSON messages.
+ */
+export declare function logServerStart(serverName: string, transport?: string): void;
+export declare function logError(context: string, error: unknown): void;
+export declare function logWarning(context: string, message: string): void;
+export declare function logDebug(context: string, message: string): void;

package/shared/logging.js

@@ -0,0 +1,21 @@
+/**
+ * Centralized logging utilities for Slack MCP Server
+ *
+ * IMPORTANT: All logging uses console.error() to write to stderr.
+ * The MCP protocol requires stdout to contain only JSON messages.
+ */
+export function logServerStart(serverName, transport = 'stdio') {
+    console.error(`MCP server ${serverName} running on ${transport}`);
+}
+export function logError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[ERROR] ${context}: ${message}`);
+}
+export function logWarning(context, message) {
+    console.error(`[WARN] ${context}: ${message}`);
+}
+export function logDebug(context, message) {
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+        console.error(`[DEBUG] ${context}: ${message}`);
+    }
+}

package/shared/server.d.ts

@@ -0,0 +1,134 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Channel, Message } from './types.js';
+/**
+ * Slack API client interface
+ * Defines all methods for interacting with the Slack Web API
+ */
+export interface ISlackClient {
+    /**
+     * Get all channels the bot has access to
+     */
+    getChannels(options?: {
+        types?: string;
+        excludeArchived?: boolean;
+    }): Promise<Channel[]>;
+    /**
+     * Get information about a specific channel
+     */
+    getChannel(channelId: string): Promise<Channel>;
+    /**
+     * Get message history from a channel
+     */
+    getMessages(channelId: string, options?: {
+        limit?: number;
+        cursor?: string;
+        oldest?: string;
+        latest?: string;
+    }): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    /**
+     * Get all replies in a thread
+     */
+    getThread(channelId: string, threadTs: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    /**
+     * Post a new message to a channel
+     */
+    postMessage(channelId: string, text: string, options?: {
+        threadTs?: string;
+        replyBroadcast?: boolean;
+    }): Promise<Message>;
+    /**
+     * Update an existing message
+     */
+    updateMessage(channelId: string, ts: string, text: string): Promise<Message>;
+    /**
+     * Add a reaction to a message
+     */
+    addReaction(channelId: string, timestamp: string, emoji: string): Promise<void>;
+}
+/**
+ * Slack API client implementation
+ */
+export declare class SlackClient implements ISlackClient {
+    private botToken;
+    private baseUrl;
+    private headers;
+    constructor(botToken: string);
+    getChannels(options?: {
+        types?: string;
+        excludeArchived?: boolean;
+    }): Promise<Channel[]>;
+    getChannel(channelId: string): Promise<Channel>;
+    getMessages(channelId: string, options?: {
+        limit?: number;
+        cursor?: string;
+        oldest?: string;
+        latest?: string;
+    }): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    getThread(channelId: string, threadTs: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    postMessage(channelId: string, text: string, options?: {
+        threadTs?: string;
+        replyBroadcast?: boolean;
+    }): Promise<Message>;
+    updateMessage(channelId: string, ts: string, text: string): Promise<Message>;
+    addReaction(channelId: string, timestamp: string, emoji: string): Promise<void>;
+}
+export type ClientFactory = () => ISlackClient;
+export declare function createMCPServer(): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    registerHandlers: (server: Server, clientFactory?: ClientFactory) => Promise<void>;
+};

package/shared/server.js

@@ -0,0 +1,68 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { createRegisterTools } from './tools.js';
+/**
+ * Slack API client implementation
+ */
+export class SlackClient {
+    botToken;
+    baseUrl = 'https://slack.com/api';
+    headers;
+    constructor(botToken) {
+        this.botToken = botToken;
+        this.headers = {
+            Authorization: `Bearer ${botToken}`,
+        };
+    }
+    async getChannels(options) {
+        const { getChannels } = await import('./slack-client/lib/get-channels.js');
+        return getChannels(this.baseUrl, this.headers, options);
+    }
+    async getChannel(channelId) {
+        const { getChannel } = await import('./slack-client/lib/get-channel.js');
+        return getChannel(this.baseUrl, this.headers, channelId);
+    }
+    async getMessages(channelId, options) {
+        const { getMessages } = await import('./slack-client/lib/get-messages.js');
+        return getMessages(this.baseUrl, this.headers, channelId, options);
+    }
+    async getThread(channelId, threadTs, options) {
+        const { getThread } = await import('./slack-client/lib/get-thread.js');
+        return getThread(this.baseUrl, this.headers, channelId, threadTs, options);
+    }
+    async postMessage(channelId, text, options) {
+        const { postMessage } = await import('./slack-client/lib/post-message.js');
+        return postMessage(this.baseUrl, this.headers, channelId, text, options);
+    }
+    async updateMessage(channelId, ts, text) {
+        const { updateMessage } = await import('./slack-client/lib/update-message.js');
+        return updateMessage(this.baseUrl, this.headers, channelId, ts, text);
+    }
+    async addReaction(channelId, timestamp, emoji) {
+        const { addReaction } = await import('./slack-client/lib/add-reaction.js');
+        return addReaction(this.baseUrl, this.headers, channelId, timestamp, emoji);
+    }
+}
+export function createMCPServer() {
+    const server = new Server({
+        name: 'slack-workspace-mcp-server',
+        version: '0.0.1',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    const registerHandlers = async (server, clientFactory) => {
+        // Use provided factory or create default client
+        const factory = clientFactory ||
+            (() => {
+                const botToken = process.env.SLACK_BOT_TOKEN;
+                if (!botToken) {
+                    throw new Error('SLACK_BOT_TOKEN environment variable must be configured');
+                }
+                return new SlackClient(botToken);
+            });
+        const registerTools = createRegisterTools(factory);
+        registerTools(server);
+    };
+    return { server, registerHandlers };
+}

package/shared/slack-client/lib/add-reaction.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Adds a reaction (emoji) to a message
+ * @param name - The emoji name without colons (e.g., "thumbsup" not ":thumbsup:")
+ */
+export declare function addReaction(baseUrl: string, headers: Record<string, string>, channelId: string, timestamp: string, name: string): Promise<void>;

package/shared/slack-client/lib/add-reaction.js

@@ -0,0 +1,30 @@
+/**
+ * Adds a reaction (emoji) to a message
+ * @param name - The emoji name without colons (e.g., "thumbsup" not ":thumbsup:")
+ */
+export async function addReaction(baseUrl, headers, channelId, timestamp, name) {
+    const body = {
+        channel: channelId,
+        timestamp,
+        name,
+    };
+    const response = await fetch(`${baseUrl}/reactions.add`, {
+        method: 'POST',
+        headers: {
+            ...headers,
+            'Content-Type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to add reaction: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data.ok) {
+        // already_reacted is not really an error for our purposes
+        if (data.error === 'already_reacted') {
+            return;
+        }
+        throw new Error(`Slack API error: ${data.error}`);
+    }
+}

package/shared/slack-client/lib/get-channel.d.ts

@@ -0,0 +1,5 @@
+import type { Channel } from '../../types.js';
+/**
+ * Fetches information about a specific channel
+ */
+export declare function getChannel(baseUrl: string, headers: Record<string, string>, channelId: string): Promise<Channel>;

package/shared/slack-client/lib/get-channel.js

@@ -0,0 +1,24 @@
+/**
+ * Fetches information about a specific channel
+ */
+export async function getChannel(baseUrl, headers, channelId) {
+    const params = new URLSearchParams({
+        channel: channelId,
+        include_num_members: 'true',
+    });
+    const response = await fetch(`${baseUrl}/conversations.info?${params}`, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch channel: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data.ok) {
+        throw new Error(`Slack API error: ${data.error}`);
+    }
+    if (!data.channel) {
+        throw new Error('Channel not found in response');
+    }
+    return data.channel;
+}

package/shared/slack-client/lib/get-channels.d.ts

@@ -0,0 +1,10 @@
+import type { Channel } from '../../types.js';
+/**
+ * Fetches all channels the bot has access to
+ * Uses cursor-based pagination to get all results
+ */
+export declare function getChannels(baseUrl: string, headers: Record<string, string>, options?: {
+    types?: string;
+    excludeArchived?: boolean;
+    limit?: number;
+}): Promise<Channel[]>;

package/shared/slack-client/lib/get-channels.js

@@ -0,0 +1,37 @@
+/**
+ * Fetches all channels the bot has access to
+ * Uses cursor-based pagination to get all results
+ */
+export async function getChannels(baseUrl, headers, options) {
+    const allChannels = [];
+    let cursor;
+    const types = options?.types ?? 'public_channel,private_channel';
+    const excludeArchived = options?.excludeArchived ?? true;
+    const limit = options?.limit ?? 200;
+    do {
+        const params = new URLSearchParams({
+            types,
+            exclude_archived: excludeArchived.toString(),
+            limit: limit.toString(),
+        });
+        if (cursor) {
+            params.set('cursor', cursor);
+        }
+        const response = await fetch(`${baseUrl}/conversations.list?${params}`, {
+            method: 'GET',
+            headers,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch channels: ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        if (!data.ok) {
+            throw new Error(`Slack API error: ${data.error}`);
+        }
+        if (data.channels) {
+            allChannels.push(...data.channels);
+        }
+        cursor = data.response_metadata?.next_cursor;
+    } while (cursor);
+    return allChannels;
+}

package/shared/slack-client/lib/get-messages.d.ts

@@ -0,0 +1,16 @@
+import type { Message } from '../../types.js';
+/**
+ * Fetches message history from a channel
+ * Returns messages in reverse chronological order (newest first)
+ */
+export declare function getMessages(baseUrl: string, headers: Record<string, string>, channelId: string, options?: {
+    limit?: number;
+    cursor?: string;
+    oldest?: string;
+    latest?: string;
+    inclusive?: boolean;
+}): Promise<{
+    messages: Message[];
+    hasMore: boolean;
+    nextCursor?: string;
+}>;