slack-workspace-mcp-server 0.0.1

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

@@ -0,0 +1,38 @@
+/**
+ * Fetches message history from a channel
+ * Returns messages in reverse chronological order (newest first)
+ */
+export async function getMessages(baseUrl, headers, channelId, options) {
+    const params = new URLSearchParams({
+        channel: channelId,
+        limit: (options?.limit ?? 20).toString(),
+    });
+    if (options?.cursor) {
+        params.set('cursor', options.cursor);
+    }
+    if (options?.oldest) {
+        params.set('oldest', options.oldest);
+    }
+    if (options?.latest) {
+        params.set('latest', options.latest);
+    }
+    if (options?.inclusive !== undefined) {
+        params.set('inclusive', options.inclusive.toString());
+    }
+    const response = await fetch(`${baseUrl}/conversations.history?${params}`, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch messages: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data.ok) {
+        throw new Error(`Slack API error: ${data.error}`);
+    }
+    return {
+        messages: data.messages ?? [],
+        hasMore: data.has_more ?? false,
+        nextCursor: data.response_metadata?.next_cursor,
+    };
+}

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

@@ -0,0 +1,16 @@
+import type { Message } from '../../types.js';
+/**
+ * Fetches all replies in a thread
+ * The first message is the parent message, followed by replies
+ */
+export declare function getThread(baseUrl: string, headers: Record<string, string>, channelId: string, threadTs: string, options?: {
+    limit?: number;
+    cursor?: string;
+    oldest?: string;
+    latest?: string;
+    inclusive?: boolean;
+}): Promise<{
+    messages: Message[];
+    hasMore: boolean;
+    nextCursor?: string;
+}>;

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

@@ -0,0 +1,39 @@
+/**
+ * Fetches all replies in a thread
+ * The first message is the parent message, followed by replies
+ */
+export async function getThread(baseUrl, headers, channelId, threadTs, options) {
+    const params = new URLSearchParams({
+        channel: channelId,
+        ts: threadTs,
+        limit: (options?.limit ?? 100).toString(),
+    });
+    if (options?.cursor) {
+        params.set('cursor', options.cursor);
+    }
+    if (options?.oldest) {
+        params.set('oldest', options.oldest);
+    }
+    if (options?.latest) {
+        params.set('latest', options.latest);
+    }
+    if (options?.inclusive !== undefined) {
+        params.set('inclusive', options.inclusive.toString());
+    }
+    const response = await fetch(`${baseUrl}/conversations.replies?${params}`, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch thread: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data.ok) {
+        throw new Error(`Slack API error: ${data.error}`);
+    }
+    return {
+        messages: data.messages ?? [],
+        hasMore: data.has_more ?? false,
+        nextCursor: data.response_metadata?.next_cursor,
+    };
+}

package/shared/slack-client/lib/post-message.d.ts

@@ -0,0 +1,10 @@
+import type { Message } from '../../types.js';
+/**
+ * Posts a new message to a channel
+ */
+export declare function postMessage(baseUrl: string, headers: Record<string, string>, channelId: string, text: string, options?: {
+    threadTs?: string;
+    replyBroadcast?: boolean;
+    unfurlLinks?: boolean;
+    unfurlMedia?: boolean;
+}): Promise<Message>;

package/shared/slack-client/lib/post-message.js

@@ -0,0 +1,44 @@
+/**
+ * Posts a new message to a channel
+ */
+export async function postMessage(baseUrl, headers, channelId, text, options) {
+    const body = {
+        channel: channelId,
+        text,
+    };
+    if (options?.threadTs) {
+        body.thread_ts = options.threadTs;
+    }
+    if (options?.replyBroadcast !== undefined) {
+        body.reply_broadcast = options.replyBroadcast;
+    }
+    if (options?.unfurlLinks !== undefined) {
+        body.unfurl_links = options.unfurlLinks;
+    }
+    if (options?.unfurlMedia !== undefined) {
+        body.unfurl_media = options.unfurlMedia;
+    }
+    const response = await fetch(`${baseUrl}/chat.postMessage`, {
+        method: 'POST',
+        headers: {
+            ...headers,
+            'Content-Type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to post message: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data.ok) {
+        throw new Error(`Slack API error: ${data.error}`);
+    }
+    if (!data.message) {
+        throw new Error('Message not found in response');
+    }
+    // Ensure ts is set on the message
+    return {
+        ...data.message,
+        ts: data.ts ?? data.message.ts,
+    };
+}

package/shared/slack-client/lib/update-message.d.ts

@@ -0,0 +1,5 @@
+import type { Message } from '../../types.js';
+/**
+ * Updates an existing message
+ */
+export declare function updateMessage(baseUrl: string, headers: Record<string, string>, channelId: string, ts: string, text: string): Promise<Message>;

package/shared/slack-client/lib/update-message.js

@@ -0,0 +1,32 @@
+/**
+ * Updates an existing message
+ */
+export async function updateMessage(baseUrl, headers, channelId, ts, text) {
+    const body = {
+        channel: channelId,
+        ts,
+        text,
+    };
+    const response = await fetch(`${baseUrl}/chat.update`, {
+        method: 'POST',
+        headers: {
+            ...headers,
+            'Content-Type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to update message: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data.ok) {
+        throw new Error(`Slack API error: ${data.error}`);
+    }
+    // Return the updated message
+    return {
+        type: 'message',
+        ts: data.ts ?? ts,
+        text: data.text ?? text,
+        ...data.message,
+    };
+}

package/shared/slack-client/slack-client.integration-mock.d.ts

@@ -0,0 +1,16 @@
+import type { ISlackClient } from '../server.js';
+import type { Channel, Message } from '../types.js';
+interface MockData {
+    channels?: Channel[];
+    messages?: Record<string, Message[]>;
+    threads?: Record<string, Message[]>;
+    [key: string]: unknown;
+}
+/**
+ * Creates a mock implementation of ISlackClient for integration tests.
+ * This mocks the EXTERNAL Slack API, NOT the MCP client.
+ */
+export declare function createIntegrationMockSlackClient(mockData?: MockData): ISlackClient & {
+    mockData: MockData;
+};
+export {};

package/shared/slack-client/slack-client.integration-mock.js

@@ -0,0 +1,106 @@
+/**
+ * Creates a mock implementation of ISlackClient for integration tests.
+ * This mocks the EXTERNAL Slack API, NOT the MCP client.
+ */
+export function createIntegrationMockSlackClient(mockData = {}) {
+    // Track posted messages for testing
+    const postedMessages = [];
+    const client = {
+        mockData,
+        async getChannels() {
+            return (mockData.channels ?? [
+                {
+                    id: 'C123456789',
+                    name: 'general',
+                    is_channel: true,
+                    is_group: false,
+                    is_im: false,
+                    is_mpim: false,
+                    is_private: false,
+                    is_archived: false,
+                    is_general: true,
+                    is_member: true,
+                    num_members: 10,
+                    created: 1234567890,
+                },
+            ]);
+        },
+        async getChannel(channelId) {
+            const channel = mockData.channels?.find((c) => c.id === channelId);
+            if (channel) {
+                return channel;
+            }
+            return {
+                id: channelId,
+                name: 'mock-channel',
+                is_channel: true,
+                is_group: false,
+                is_im: false,
+                is_mpim: false,
+                is_private: false,
+                is_archived: false,
+                is_general: false,
+                is_member: true,
+                created: 1234567890,
+            };
+        },
+        async getMessages(channelId, options) {
+            const messages = mockData.messages?.[channelId] ?? [
+                {
+                    type: 'message',
+                    user: 'U123456789',
+                    text: 'Mock message',
+                    ts: '1234567890.123456',
+                },
+            ];
+            const limit = options?.limit ?? 20;
+            return {
+                messages: messages.slice(0, limit),
+                hasMore: messages.length > limit,
+            };
+        },
+        async getThread(channelId, threadTs, options) {
+            const key = `${channelId}:${threadTs}`;
+            const messages = mockData.threads?.[key] ?? [
+                {
+                    type: 'message',
+                    user: 'U123456789',
+                    text: 'Mock parent message',
+                    ts: threadTs,
+                    thread_ts: threadTs,
+                },
+            ];
+            const limit = options?.limit ?? 50;
+            return {
+                messages: messages.slice(0, limit),
+                hasMore: messages.length > limit,
+            };
+        },
+        async postMessage(channelId, text, options) {
+            const ts = `${Date.now() / 1000}.123456`;
+            const message = {
+                type: 'message',
+                text,
+                ts,
+                thread_ts: options?.threadTs,
+            };
+            postedMessages.push(message);
+            return message;
+        },
+        async updateMessage(channelId, ts, text) {
+            return {
+                type: 'message',
+                text,
+                ts,
+                edited: {
+                    user: 'U123456789',
+                    ts: `${Date.now() / 1000}`,
+                },
+            };
+        },
+        async addReaction() {
+            // No-op for mock
+        },
+    };
+    return client;
+}

package/shared/tools/get-channel.d.ts

@@ -0,0 +1,55 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const GetChannelSchema: z.ZodObject<{
+    channel_id: z.ZodString;
+    include_messages: z.ZodDefault<z.ZodBoolean>;
+    message_limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    channel_id: string;
+    include_messages: boolean;
+    message_limit: number;
+}, {
+    channel_id: string;
+    include_messages?: boolean | undefined;
+    message_limit?: number | undefined;
+}>;
+export declare function getChannelTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            channel_id: {
+                type: string;
+                description: string;
+            };
+            include_messages: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            message_limit: {
+                type: string;
+                default: number;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/get-channel.js

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    channel_id: 'The unique identifier of the channel (e.g., "C1234567890"). ' +
+        'Get channel IDs using the slack_get_channels tool.',
+    include_messages: 'Whether to include recent messages from the channel. Default: true. ' +
+        'Set to false to only get channel metadata.',
+    message_limit: 'Maximum number of messages to return when include_messages is true. ' +
+        'Default: 20. Maximum: 100.',
+};
+export const GetChannelSchema = z.object({
+    channel_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.channel_id),
+    include_messages: z.boolean().default(true).describe(PARAM_DESCRIPTIONS.include_messages),
+    message_limit: z.number().min(1).max(100).default(20).describe(PARAM_DESCRIPTIONS.message_limit),
+});
+const TOOL_DESCRIPTION = `Get detailed information about a Slack channel, optionally including recent messages.
+
+Returns channel metadata (name, topic, purpose, member count) and optionally the most recent messages. This is equivalent to opening a channel in Slack.
+
+**Returns:**
+- Channel details: name, topic, purpose, member count, creation date
+- Recent messages (if include_messages is true): sender, content, timestamp, reactions, thread info
+
+**Use cases:**
+- Get context about a channel before posting
+- Read recent messages to understand current discussions
+- Check if a channel is active or archived
+- Find threads that may need responses
+
+**Note:** Messages are returned newest first. Thread parent messages include reply counts.`;
+export function getChannelTool(server, clientFactory) {
+    return {
+        name: 'slack_get_channel',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                channel_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.channel_id,
+                },
+                include_messages: {
+                    type: 'boolean',
+                    default: true,
+                    description: PARAM_DESCRIPTIONS.include_messages,
+                },
+                message_limit: {
+                    type: 'number',
+                    default: 20,
+                    minimum: 1,
+                    maximum: 100,
+                    description: PARAM_DESCRIPTIONS.message_limit,
+                },
+            },
+            required: ['channel_id'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = GetChannelSchema.parse(args);
+                const client = clientFactory();
+                // Get channel info
+                const channel = await client.getChannel(parsed.channel_id);
+                // Build channel info section
+                const flags = [];
+                if (channel.is_private)
+                    flags.push('private');
+                if (channel.is_archived)
+                    flags.push('archived');
+                if (channel.is_general)
+                    flags.push('general');
+                let output = `# Channel: #${channel.name}\n`;
+                if (flags.length > 0) {
+                    output += `Status: ${flags.join(', ')}\n`;
+                }
+                output += `ID: ${channel.id}\n`;
+                if (channel.topic?.value) {
+                    output += `Topic: ${channel.topic.value}\n`;
+                }
+                if (channel.purpose?.value) {
+                    output += `Purpose: ${channel.purpose.value}\n`;
+                }
+                if (channel.num_members !== undefined) {
+                    output += `Members: ${channel.num_members}\n`;
+                }
+                output += `Created: ${new Date(channel.created * 1000).toISOString()}\n`;
+                // Get messages if requested
+                if (parsed.include_messages) {
+                    const { messages, hasMore } = await client.getMessages(parsed.channel_id, {
+                        limit: parsed.message_limit,
+                    });
+                    if (messages.length > 0) {
+                        output += `\n## Recent Messages (${messages.length}${hasMore ? '+' : ''}):\n\n`;
+                        for (const msg of messages) {
+                            const time = new Date(parseFloat(msg.ts) * 1000).toISOString();
+                            const sender = msg.user || msg.bot_id || 'unknown';
+                            const threadInfo = msg.reply_count ? ` [${msg.reply_count} replies]` : '';
+                            const reactions = msg.reactions
+                                ? ` | Reactions: ${msg.reactions.map((r) => `:${r.name}: ${r.count}`).join(' ')}`
+                                : '';
+                            output += `**${sender}** (${time})${threadInfo}${reactions}\n`;
+                            output += `${msg.text}\n`;
+                            if (msg.thread_ts && msg.thread_ts !== msg.ts) {
+                                output += `↳ Reply to thread: ${msg.thread_ts}\n`;
+                            }
+                            output += `ts: ${msg.ts}\n\n`;
+                        }
+                        if (hasMore) {
+                            output += `_More messages available. Increase message_limit to see more._\n`;
+                        }
+                    }
+                    else {
+                        output += '\n_No messages in this channel yet._\n';
+                    }
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: output,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error fetching channel: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/get-channels.d.ts

@@ -0,0 +1,46 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const GetChannelsSchema: z.ZodObject<{
+    include_private: z.ZodDefault<z.ZodBoolean>;
+    include_archived: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    include_private: boolean;
+    include_archived: boolean;
+}, {
+    include_private?: boolean | undefined;
+    include_archived?: boolean | undefined;
+}>;
+export declare function getChannelsTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            include_private: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+            include_archived: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/get-channels.js

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    include_private: 'Include private channels the bot is a member of. Default: true. ' +
+        'Set to false to only list public channels.',
+    include_archived: 'Include archived channels. Default: false. ' +
+        'Archived channels are read-only and cannot receive new messages.',
+};
+export const GetChannelsSchema = z.object({
+    include_private: z.boolean().default(true).describe(PARAM_DESCRIPTIONS.include_private),
+    include_archived: z.boolean().default(false).describe(PARAM_DESCRIPTIONS.include_archived),
+});
+const TOOL_DESCRIPTION = `List all Slack channels the bot has access to.
+
+Returns a list of public and private channels in the workspace that the bot can see. Each channel includes its ID, name, topic, purpose, and member count.
+
+**Returns:**
+A formatted list of channels with their key details including:
+- Channel ID (needed for other operations)
+- Channel name
+- Topic and purpose
+- Whether the channel is private or archived
+- Number of members
+
+**Use cases:**
+- Discover available channels to read or post to
+- Find a specific channel's ID for subsequent operations
+- Get an overview of the workspace's channel structure
+
+**Note:** The bot can only see channels it has been invited to (for private channels) or all public channels.`;
+export function getChannelsTool(server, clientFactory) {
+    return {
+        name: 'slack_get_channels',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                include_private: {
+                    type: 'boolean',
+                    default: true,
+                    description: PARAM_DESCRIPTIONS.include_private,
+                },
+                include_archived: {
+                    type: 'boolean',
+                    default: false,
+                    description: PARAM_DESCRIPTIONS.include_archived,
+                },
+            },
+            required: [],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = GetChannelsSchema.parse(args ?? {});
+                const client = clientFactory();
+                const types = parsed.include_private ? 'public_channel,private_channel' : 'public_channel';
+                const channels = await client.getChannels({
+                    types,
+                    excludeArchived: !parsed.include_archived,
+                });
+                if (channels.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'No channels found. The bot may not have access to any channels yet.',
+                            },
+                        ],
+                    };
+                }
+                const channelList = channels
+                    .map((ch) => {
+                    const flags = [];
+                    if (ch.is_private)
+                        flags.push('private');
+                    if (ch.is_archived)
+                        flags.push('archived');
+                    if (ch.is_general)
+                        flags.push('general');
+                    const flagStr = flags.length > 0 ? ` [${flags.join(', ')}]` : '';
+                    const topic = ch.topic?.value ? `\n   Topic: ${ch.topic.value}` : '';
+                    const purpose = ch.purpose?.value ? `\n   Purpose: ${ch.purpose.value}` : '';
+                    const members = ch.num_members !== undefined ? `\n   Members: ${ch.num_members}` : '';
+                    return `• #${ch.name}${flagStr}\n   ID: ${ch.id}${topic}${purpose}${members}`;
+                })
+                    .join('\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${channels.length} channel(s):\n\n${channelList}`,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error fetching channels: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}