slack-workspace-mcp-server 0.0.2 → 0.0.4

package/README.md

@@ -11,6 +11,7 @@ A Model Context Protocol (MCP) server for integrating with Slack workspaces. Thi
 - **Reply to Threads** - Continue threaded conversations
 - **Update Messages** - Edit previously posted messages
 - **React to Messages** - Add emoji reactions to messages
+- **Upload Snippets** - Upload text content as file snippets (for long content that exceeds message limits)
 
 ## Setup
 
@@ -38,6 +39,7 @@ A Model Context Protocol (MCP) server for integrating with Slack workspaces. Thi
    - `groups:history` - View messages in private channels
    - `chat:write` - Send messages
    - `reactions:write` - Add reactions
+   - `files:write` - Upload files and snippets
 5. Install the app to your workspace
 6. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
 
@@ -85,12 +87,13 @@ Restart Claude Desktop and you should be ready to go!
 
 ### 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                     | 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                 |
+| `slack_upload_snippet`   | Upload text content as a file snippet to a channel |
 
 ## Tool Groups
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slack-workspace-mcp-server",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "MCP server for Slack workspace integration",
   "main": "build/index.js",
   "type": "module",

package/shared/server.d.ts

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { Channel, Message } from './types.js';
+import type { Channel, Message, SlackFile } from './types.js';
 /**
  * Slack API client interface
  * Defines all methods for interacting with the Slack Web API
@@ -55,6 +55,23 @@ export interface ISlackClient {
      * Add a reaction to a message
      */
     addReaction(channelId: string, timestamp: string, emoji: string): Promise<void>;
+    /**
+     * Get file metadata from Slack
+     */
+    getFileInfo(fileId: string): Promise<SlackFile>;
+    /**
+     * Download a file from Slack (requires authenticated URL)
+     */
+    downloadFile(fileUrl: string): Promise<Buffer>;
+    /**
+     * Upload text content as a snippet/file to a channel
+     */
+    uploadSnippet(content: string, options: {
+        channelId: string;
+        filename?: string;
+        title?: string;
+        threadTs?: string;
+    }): Promise<SlackFile>;
 }
 /**
  * Slack API client implementation
@@ -93,6 +110,14 @@ export declare class SlackClient implements ISlackClient {
     }): Promise<Message>;
     updateMessage(channelId: string, ts: string, text: string): Promise<Message>;
     addReaction(channelId: string, timestamp: string, emoji: string): Promise<void>;
+    getFileInfo(fileId: string): Promise<SlackFile>;
+    downloadFile(fileUrl: string): Promise<Buffer>;
+    uploadSnippet(content: string, options: {
+        channelId: string;
+        filename?: string;
+        title?: string;
+        threadTs?: string;
+    }): Promise<SlackFile>;
 }
 export type ClientFactory = () => ISlackClient;
 export interface CreateMCPServerOptions {

package/shared/server.js

@@ -41,6 +41,18 @@ export class SlackClient {
         const { addReaction } = await import('./slack-client/lib/add-reaction.js');
         return addReaction(this.baseUrl, this.headers, channelId, timestamp, emoji);
     }
+    async getFileInfo(fileId) {
+        const { getFileInfo } = await import('./slack-client/lib/get-file-info.js');
+        return getFileInfo(this.baseUrl, this.headers, fileId);
+    }
+    async downloadFile(fileUrl) {
+        const { downloadFile } = await import('./slack-client/lib/download-file.js');
+        return downloadFile(this.headers, fileUrl);
+    }
+    async uploadSnippet(content, options) {
+        const { uploadSnippet } = await import('./slack-client/lib/upload-snippet.js');
+        return uploadSnippet(this.baseUrl, this.headers, content, options);
+    }
 }
 export function createMCPServer(options) {
     const server = new Server({

package/shared/slack-client/lib/download-file.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Downloads a file from Slack using an authenticated URL.
+ * Slack's url_private requires the bot token in the Authorization header.
+ */
+export declare function downloadFile(headers: Record<string, string>, fileUrl: string): Promise<Buffer>;

package/shared/slack-client/lib/download-file.js

@@ -0,0 +1,15 @@
+/**
+ * Downloads a file from Slack using an authenticated URL.
+ * Slack's url_private requires the bot token in the Authorization header.
+ */
+export async function downloadFile(headers, fileUrl) {
+    const response = await fetch(fileUrl, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to download file: ${response.status} ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}

package/shared/slack-client/lib/get-file-info.d.ts

@@ -0,0 +1,5 @@
+import type { SlackFile } from '../../types.js';
+/**
+ * Fetches information about a specific file using Slack's files.info API
+ */
+export declare function getFileInfo(baseUrl: string, headers: Record<string, string>, fileId: string): Promise<SlackFile>;

package/shared/slack-client/lib/get-file-info.js

@@ -0,0 +1,23 @@
+/**
+ * Fetches information about a specific file using Slack's files.info API
+ */
+export async function getFileInfo(baseUrl, headers, fileId) {
+    const params = new URLSearchParams({
+        file: fileId,
+    });
+    const response = await fetch(`${baseUrl}/files.info?${params}`, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch file info: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data.ok) {
+        throw new Error(`Slack API error: ${data.error}`);
+    }
+    if (!data.file) {
+        throw new Error('File not found in response');
+    }
+    return data.file;
+}

package/shared/slack-client/lib/upload-snippet.d.ts

@@ -0,0 +1,14 @@
+import type { SlackFile } from '../../types.js';
+/**
+ * Uploads text content as a snippet/file to Slack using the modern
+ * files.getUploadURLExternal + files.completeUploadExternal flow.
+ *
+ * The deprecated files.upload API stopped working for new apps in May 2024
+ * and was fully retired in November 2025.
+ */
+export declare function uploadSnippet(baseUrl: string, headers: Record<string, string>, content: string, options: {
+    channelId: string;
+    filename?: string;
+    title?: string;
+    threadTs?: string;
+}): Promise<SlackFile>;

package/shared/slack-client/lib/upload-snippet.js

@@ -0,0 +1,80 @@
+/**
+ * Uploads text content as a snippet/file to Slack using the modern
+ * files.getUploadURLExternal + files.completeUploadExternal flow.
+ *
+ * The deprecated files.upload API stopped working for new apps in May 2024
+ * and was fully retired in November 2025.
+ */
+export async function uploadSnippet(baseUrl, headers, content, options) {
+    const filename = options.filename ?? 'snippet.txt';
+    const contentBuffer = Buffer.from(content, 'utf-8');
+    const length = contentBuffer.length;
+    // Step 1: Get an upload URL from Slack
+    const params = new URLSearchParams({
+        filename,
+        length: length.toString(),
+    });
+    const uploadUrlResponse = await fetch(`${baseUrl}/files.getUploadURLExternal?${params}`, {
+        method: 'GET',
+        headers,
+    });
+    if (!uploadUrlResponse.ok) {
+        throw new Error(`Failed to get upload URL: ${uploadUrlResponse.status} ${uploadUrlResponse.statusText}`);
+    }
+    const uploadUrlData = (await uploadUrlResponse.json());
+    if (!uploadUrlData.ok) {
+        throw new Error(`Slack API error (getUploadURLExternal): ${uploadUrlData.error}`);
+    }
+    if (!uploadUrlData.upload_url || !uploadUrlData.file_id) {
+        throw new Error('Missing upload_url or file_id in response');
+    }
+    // Step 2: Upload the file content to the presigned URL (no auth headers needed)
+    const uploadResponse = await fetch(uploadUrlData.upload_url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/octet-stream',
+        },
+        body: contentBuffer,
+    });
+    if (!uploadResponse.ok) {
+        throw new Error(`Failed to upload file content: ${uploadResponse.status} ${uploadResponse.statusText}`);
+    }
+    // Step 3: Complete the upload and share in channel
+    const completeBody = {
+        files: [
+            {
+                id: uploadUrlData.file_id,
+                title: options.title,
+            },
+        ],
+        channel_id: options.channelId,
+    };
+    if (options.threadTs) {
+        completeBody.thread_ts = options.threadTs;
+    }
+    const completeResponse = await fetch(`${baseUrl}/files.completeUploadExternal`, {
+        method: 'POST',
+        headers: {
+            ...headers,
+            'Content-Type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify(completeBody),
+    });
+    if (!completeResponse.ok) {
+        throw new Error(`Failed to complete upload: ${completeResponse.status} ${completeResponse.statusText}`);
+    }
+    const completeData = (await completeResponse.json());
+    if (!completeData.ok) {
+        throw new Error(`Slack API error (completeUploadExternal): ${completeData.error}`);
+    }
+    const file = completeData.files?.[0];
+    if (!file) {
+        // Return a minimal file object using the file_id we already know
+        return {
+            id: uploadUrlData.file_id,
+            name: filename,
+            title: options.title,
+        };
+    }
+    return file;
+}

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

@@ -101,6 +101,29 @@ export function createIntegrationMockSlackClient(mockData = {}) {
         async addReaction() {
             // No-op for mock
         },
+        async getFileInfo(fileId) {
+            return {
+                id: fileId,
+                name: `mock-file-${fileId}.txt`,
+                mimetype: 'text/plain',
+                size: 1024,
+                url_private: `https://files.slack.com/files-pri/mock/${fileId}`,
+                url_private_download: `https://files.slack.com/files-pri/mock/${fileId}/download`,
+            };
+        },
+        async downloadFile() {
+            return Buffer.from('mock-file-content');
+        },
+        async uploadSnippet(content, options) {
+            return {
+                id: `F${Date.now()}`,
+                name: options.filename ?? 'snippet.txt',
+                title: options.title,
+                mimetype: 'text/plain',
+                size: content.length,
+                permalink: `https://slack.com/files/mock/${options.filename ?? 'snippet.txt'}`,
+            };
+        },
     };
     return client;
 }

package/shared/tools/download-file.d.ts

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

package/shared/tools/download-file.js

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import { writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+const PARAM_DESCRIPTIONS = {
+    file_id: 'The Slack file ID (e.g., "F1234567890"). ' +
+        'File IDs are shown in message outputs next to uploaded files.',
+};
+export const DownloadFileSchema = z.object({
+    file_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.file_id),
+});
+const TOOL_DESCRIPTION = `Download a file from Slack to a local temporary path.
+
+Slack files require authentication to access, so this tool handles the download using the bot token. It saves the file to a temporary directory and returns the local file path.
+
+**Returns:**
+- Local file path (file:// URI) where the downloaded file was saved
+- File metadata: name, type, size
+
+**Use cases:**
+- Download images shared in Slack to view them
+- Download documents, PDFs, or other files shared in channels
+- Access any file attachment from a Slack message
+
+**Note:** File IDs (e.g., "F1234567890") are shown in message outputs from slack_get_channel and slack_get_thread.`;
+export function downloadFileTool(server, clientFactory) {
+    return {
+        name: 'slack_download_file',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                file_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.file_id,
+                },
+            },
+            required: ['file_id'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = DownloadFileSchema.parse(args);
+                const client = clientFactory();
+                // Get file metadata
+                const fileInfo = await client.getFileInfo(parsed.file_id);
+                const downloadUrl = fileInfo.url_private_download || fileInfo.url_private;
+                if (!downloadUrl) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `File ${parsed.file_id} has no downloadable URL. It may have been deleted or is not accessible.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Download the file
+                const fileBuffer = await client.downloadFile(downloadUrl);
+                // Write to temp directory
+                const slackTmpDir = join(tmpdir(), 'slack-files');
+                await mkdir(slackTmpDir, { recursive: true });
+                const fileName = fileInfo.name || fileInfo.title || parsed.file_id;
+                const safeName = fileName.replace(/[^a-zA-Z0-9._-]/g, '_');
+                const localPath = join(slackTmpDir, `${parsed.file_id}-${safeName}`);
+                await writeFile(localPath, fileBuffer);
+                const sizeParts = [];
+                if (fileInfo.mimetype)
+                    sizeParts.push(fileInfo.mimetype);
+                if (fileInfo.size)
+                    sizeParts.push(formatFileSize(fileInfo.size));
+                let output = `File downloaded successfully.\n`;
+                output += `Name: ${fileName}\n`;
+                if (sizeParts.length > 0)
+                    output += `Type: ${sizeParts.join(', ')}\n`;
+                output += `Path: file://${localPath}\n`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: output,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error downloading file: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/shared/tools/format-message-extras.js

@@ -51,13 +51,8 @@ export function formatMessageExtras(msg) {
             if (file.size) {
                 parts.push(formatFileSize(file.size));
             }
-            if (file.permalink) {
-                parts.push(`Link: ${file.permalink}`);
-            }
-            else if (file.url_private) {
-                parts.push(`Link: ${file.url_private}`);
-            }
-            output += `  📄 File: ${parts.join(' | ')}\n`;
+            parts.push(`id: ${file.id}`);
+            output += `  📄 File: ${parts.join(' | ')} — use slack_download_file to download\n`;
         }
     }
     return output;

package/shared/tools/upload-snippet.d.ts

@@ -0,0 +1,65 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const UploadSnippetSchema: z.ZodObject<{
+    channel_id: z.ZodString;
+    content: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    thread_ts: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    channel_id: string;
+    content: string;
+    thread_ts?: string | undefined;
+    filename?: string | undefined;
+    title?: string | undefined;
+}, {
+    channel_id: string;
+    content: string;
+    thread_ts?: string | undefined;
+    filename?: string | undefined;
+    title?: string | undefined;
+}>;
+export declare function uploadSnippetTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            channel_id: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            filename: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: "Title displayed in Slack above the snippet.";
+            };
+            thread_ts: {
+                type: string;
+                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/upload-snippet.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    channel_id: 'The channel ID to share the snippet in (e.g., "C1234567890"). ' +
+        'Get channel IDs using the slack_get_channels tool.',
+    content: 'The text content to upload as a snippet. Can be arbitrarily long — ' +
+        'use this instead of slack_post_message when content exceeds message length limits.',
+    filename: 'Filename for the snippet (e.g., "output.txt", "error.log", "code.py"). ' +
+        'Slack uses the file extension for syntax highlighting. Default: "snippet.txt".',
+    title: 'Title displayed in Slack above the snippet.',
+    thread_ts: 'Post the snippet as a thread reply to this message timestamp. ' +
+        'If omitted, the snippet is posted as a new message in the channel.',
+};
+export const UploadSnippetSchema = z.object({
+    channel_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.channel_id),
+    content: z.string().min(1).describe(PARAM_DESCRIPTIONS.content),
+    filename: z.string().optional().describe(PARAM_DESCRIPTIONS.filename),
+    title: z.string().optional().describe(PARAM_DESCRIPTIONS.title),
+    thread_ts: z.string().optional().describe(PARAM_DESCRIPTIONS.thread_ts),
+});
+const TOOL_DESCRIPTION = `Upload text content as a file snippet to a Slack channel.
+
+Uploads content as a text file/snippet, bypassing Slack's message length limits. Use this when content is too long for slack_post_message (e.g., long URLs, logs, code, JSON payloads).
+
+**Returns:**
+- Confirmation of the uploaded snippet
+- The file ID for reference
+
+**Use cases:**
+- Share very long URLs that exceed message length limits
+- Post error logs, stack traces, or debug output
+- Share code snippets or configuration files
+- Upload large JSON or text payloads
+
+**Note:** For short messages that fit within Slack's limits, use slack_post_message instead. Use the filename extension to control syntax highlighting (e.g., "code.py" for Python).`;
+export function uploadSnippetTool(server, clientFactory) {
+    return {
+        name: 'slack_upload_snippet',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                channel_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.channel_id,
+                },
+                content: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.content,
+                },
+                filename: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.filename,
+                },
+                title: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.title,
+                },
+                thread_ts: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.thread_ts,
+                },
+            },
+            required: ['channel_id', 'content'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = UploadSnippetSchema.parse(args);
+                const client = clientFactory();
+                const file = await client.uploadSnippet(parsed.content, {
+                    channelId: parsed.channel_id,
+                    filename: parsed.filename,
+                    title: parsed.title,
+                    threadTs: parsed.thread_ts,
+                });
+                const parts = [
+                    `Snippet uploaded successfully!\n`,
+                    `Channel: ${parsed.channel_id}`,
+                    `File ID: ${file.id}`,
+                ];
+                if (file.name) {
+                    parts.push(`Filename: ${file.name}`);
+                }
+                if (file.title) {
+                    parts.push(`Title: ${file.title}`);
+                }
+                if (parsed.thread_ts) {
+                    parts.push(`Thread: ${parsed.thread_ts}`);
+                }
+                if (file.permalink) {
+                    parts.push(`Permalink: ${file.permalink}`);
+                }
+                const byteLength = Buffer.from(parsed.content, 'utf-8').length;
+                parts.push(`\nContent length: ${byteLength} bytes`);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: parts.join('\n'),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error uploading snippet: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.js

@@ -7,6 +7,8 @@ import { postMessageTool } from './tools/post-message.js';
 import { replyToThreadTool } from './tools/reply-to-thread.js';
 import { updateMessageTool } from './tools/update-message.js';
 import { reactToMessageTool } from './tools/react-to-message.js';
+import { downloadFileTool } from './tools/download-file.js';
+import { uploadSnippetTool } from './tools/upload-snippet.js';
 const ALL_TOOL_GROUPS = ['readonly', 'write'];
 /**
  * Parse enabled tool groups from environment variable
@@ -31,11 +33,13 @@ const ALL_TOOLS = [
     { factory: getChannelsTool, groups: ['readonly', 'write'] },
     { factory: getChannelTool, groups: ['readonly', 'write'] },
     { factory: getThreadTool, groups: ['readonly', 'write'] },
+    { factory: downloadFileTool, groups: ['readonly', 'write'] },
     // Write tools
     { factory: postMessageTool, groups: ['write'] },
     { factory: replyToThreadTool, groups: ['write'] },
     { factory: updateMessageTool, groups: ['write'] },
     { factory: reactToMessageTool, groups: ['write'] },
+    { factory: uploadSnippetTool, groups: ['write'] },
 ];
 /**
  * Creates a function to register all tools with the server