slack-workspace-mcp-server 0.0.1 → 0.0.2

package/README.md

@@ -12,31 +12,19 @@ A Model Context Protocol (MCP) server for integrating with Slack workspaces. Thi
 - **Update Messages** - Edit previously posted messages
 - **React to Messages** - Add emoji reactions to messages
 
-## Installation
+## Setup
 
-```bash
-npm install slack-workspace-mcp-server
-```
-
-Or run directly with npx:
-
-```bash
-npx slack-workspace-mcp-server
-```
-
-## Configuration
-
-### Required Environment Variables
+### Prerequisites
 
-| Variable          | Description                | Example        |
-| ----------------- | -------------------------- | -------------- |
-| `SLACK_BOT_TOKEN` | Slack Bot User OAuth Token | `xoxb-1234...` |
+- A Slack workspace with admin permissions to create apps
+- A Slack Bot Token (see instructions below)
 
-### Optional Environment Variables
+### Environment Variables
 
-| Variable             | Description                         | Default     |
-| -------------------- | ----------------------------------- | ----------- |
-| `ENABLED_TOOLGROUPS` | Comma-separated list of tool groups | All enabled |
+| Variable             | Required | Description                         | Default     |
+| -------------------- | -------- | ----------------------------------- | ----------- |
+| `SLACK_BOT_TOKEN`    | Yes      | Slack Bot User OAuth Token          | -           |
+| `ENABLED_TOOLGROUPS` | No       | Comma-separated list of tool groups | All enabled |
 
 ### Getting a Bot Token
 
@@ -53,16 +41,28 @@ npx slack-workspace-mcp-server
 5. Install the app to your workspace
 6. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
 
-### MCP Client Configuration
+### Claude Desktop
 
-For Claude Desktop, add to your configuration:
+Make sure you have your Slack Bot Token ready.
+
+Then proceed to the setup instructions below. If this is your first time using MCP Servers, you'll want to make sure you have the [Claude Desktop application](https://claude.ai/download) and follow the [official MCP setup instructions](https://modelcontextprotocol.io/quickstart/user).
+
+#### Manual Setup
+
+You're going to need Node working on your machine so you can run `npx` commands in your terminal. If you don't have Node, you can install it from [nodejs.org](https://nodejs.org/en/download).
+
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Modify your `claude_desktop_config.json` file to add the following:
 
 ```json
 {
   "mcpServers": {
     "slack": {
       "command": "npx",
-      "args": ["slack-workspace-mcp-server"],
+      "args": ["-y", "slack-workspace-mcp-server"],
       "env": {
         "SLACK_BOT_TOKEN": "xoxb-your-token-here"
       }
@@ -71,6 +71,8 @@ For Claude Desktop, add to your configuration:
 }
 ```
 
+Restart Claude Desktop and you should be ready to go!
+
 ## Available Tools
 
 ### Read-Only Tools

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

@@ -8,8 +8,16 @@
  * Mock data is passed via the SLACK_MOCK_DATA environment variable.
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { createMCPServer } from '../shared/index.js';
 import { createIntegrationMockSlackClient } from '../shared/slack-client/slack-client.integration-mock.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
 async function main() {
     const transport = new StdioServerTransport();
     // Parse mock data from environment variable
@@ -24,7 +32,7 @@ async function main() {
     }
     // Create client factory that returns our mock
     const clientFactory = () => createIntegrationMockSlackClient(mockData);
-    const { server, registerHandlers } = createMCPServer();
+    const { server, registerHandlers } = createMCPServer({ version: VERSION });
     await registerHandlers(server, clientFactory);
     await server.connect(transport);
 }

package/build/index.js

@@ -1,7 +1,15 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { createMCPServer } from '../shared/index.js';
 import { logServerStart, logError, logWarning } from '../shared/logging.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
 // =============================================================================
 // ENVIRONMENT VALIDATION
 // =============================================================================
@@ -61,7 +69,7 @@ async function main() {
     // Step 1: Validate environment variables
     validateEnvironment();
     // Step 2: Create server using factory
-    const { server, registerHandlers } = createMCPServer();
+    const { server, registerHandlers } = createMCPServer({ version: VERSION });
     // Step 3: Register all handlers (tools)
     await registerHandlers(server);
     // Step 4: Start server with stdio transport

package/package.json

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

package/shared/index.d.ts

@@ -1,4 +1,4 @@
-export { createMCPServer, SlackClient, type ISlackClient, type ClientFactory } from './server.js';
+export { createMCPServer, SlackClient, type ISlackClient, type ClientFactory, type CreateMCPServerOptions, } 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

@@ -1,6 +1,6 @@
 // Main exports for Slack MCP Server
 // Server and client
-export { createMCPServer, SlackClient } from './server.js';
+export { createMCPServer, SlackClient, } from './server.js';
 // Tools
 export { createRegisterTools, registerTools } from './tools.js';
 // Logging utilities

package/shared/server.d.ts

@@ -95,7 +95,10 @@ export declare class SlackClient implements ISlackClient {
     addReaction(channelId: string, timestamp: string, emoji: string): Promise<void>;
 }
 export type ClientFactory = () => ISlackClient;
-export declare function createMCPServer(): {
+export interface CreateMCPServerOptions {
+    version: string;
+}
+export declare function createMCPServer(options: CreateMCPServerOptions): {
     server: Server<{
         method: string;
         params?: {

package/shared/server.js

@@ -42,10 +42,10 @@ export class SlackClient {
         return addReaction(this.baseUrl, this.headers, channelId, timestamp, emoji);
     }
 }
-export function createMCPServer() {
+export function createMCPServer(options) {
     const server = new Server({
         name: 'slack-workspace-mcp-server',
-        version: '0.0.1',
+        version: options.version,
     }, {
         capabilities: {
             tools: {},

package/shared/tools/format-message-extras.d.ts

@@ -0,0 +1,6 @@
+import type { Message } from '../types.js';
+/**
+ * Formats attachment and file information from a Slack message into markdown text.
+ * Returns an empty string if the message has no attachments or files.
+ */
+export declare function formatMessageExtras(msg: Message): string;

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

@@ -0,0 +1,71 @@
+/**
+ * Formats attachment and file information from a Slack message into markdown text.
+ * Returns an empty string if the message has no attachments or files.
+ */
+export function formatMessageExtras(msg) {
+    let output = '';
+    if (msg.attachments && msg.attachments.length > 0) {
+        for (const att of msg.attachments) {
+            const parts = [];
+            if (att.pretext) {
+                parts.push(att.pretext);
+            }
+            // Title with optional link
+            if (att.title) {
+                parts.push(att.title_link ? `[${att.title}](${att.title_link})` : att.title);
+            }
+            // Service/source info for unfurled links
+            if (att.service_name) {
+                parts.push(`(${att.service_name})`);
+            }
+            if (att.author_name) {
+                parts.push(`By: ${att.author_name}`);
+            }
+            if (att.text) {
+                parts.push(att.text);
+            }
+            // Image URL (unfurled preview or inline image)
+            if (att.image_url) {
+                parts.push(`Image: ${att.image_url}`);
+            }
+            else if (att.thumb_url) {
+                parts.push(`Thumbnail: ${att.thumb_url}`);
+            }
+            // Original URL for unfurled links
+            if (att.from_url) {
+                parts.push(`URL: ${att.from_url}`);
+            }
+            if (parts.length > 0) {
+                output += `  📎 Attachment: ${parts.join(' | ')}\n`;
+            }
+        }
+    }
+    if (msg.files && msg.files.length > 0) {
+        for (const file of msg.files) {
+            const parts = [];
+            const name = file.name || file.title || 'Untitled file';
+            parts.push(name);
+            if (file.mimetype) {
+                parts.push(`(${file.mimetype})`);
+            }
+            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`;
+        }
+    }
+    return output;
+}
+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/get-channel.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { formatMessageExtras } from './format-message-extras.js';
 const PARAM_DESCRIPTIONS = {
     channel_id: 'The unique identifier of the channel (e.g., "C1234567890"). ' +
         'Get channel IDs using the slack_get_channels tool.',
@@ -98,6 +99,7 @@ export function getChannelTool(server, clientFactory) {
                                 : '';
                             output += `**${sender}** (${time})${threadInfo}${reactions}\n`;
                             output += `${msg.text}\n`;
+                            output += formatMessageExtras(msg);
                             if (msg.thread_ts && msg.thread_ts !== msg.ts) {
                                 output += `↳ Reply to thread: ${msg.thread_ts}\n`;
                             }

package/shared/tools/get-thread.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { formatMessageExtras } from './format-message-extras.js';
 const PARAM_DESCRIPTIONS = {
     channel_id: 'The channel ID where the thread exists (e.g., "C1234567890"). ' +
         'Get channel IDs using the slack_get_channels tool.',
@@ -84,6 +85,7 @@ export function getThreadTool(server, clientFactory) {
                 output += `## Parent Message\n`;
                 output += `**${parentSender}** (${parentTime})\n`;
                 output += `${parent.text}${parentReactions}\n`;
+                output += formatMessageExtras(parent);
                 output += `ts: ${parent.ts}\n\n`;
                 // Format replies
                 if (replies.length > 0) {
@@ -96,6 +98,7 @@ export function getThreadTool(server, clientFactory) {
                             : '';
                         output += `**${sender}** (${time})\n`;
                         output += `${reply.text}${reactions}\n`;
+                        output += formatMessageExtras(reply);
                         output += `ts: ${reply.ts}\n\n`;
                     }
                     if (hasMore) {

package/shared/types.d.ts

@@ -41,6 +41,7 @@ export interface Message {
     reply_users?: string[];
     reactions?: Reaction[];
     attachments?: Attachment[];
+    files?: SlackFile[];
     blocks?: Block[];
     edited?: {
         user: string;
@@ -73,6 +74,27 @@ export interface Attachment {
     footer?: string;
     footer_icon?: string;
     ts?: number;
+    from_url?: string;
+    original_url?: string;
+    service_name?: string;
+    service_icon?: string;
+}
+export interface SlackFile {
+    id: string;
+    name?: string;
+    title?: string;
+    mimetype?: string;
+    filetype?: string;
+    size?: number;
+    url_private?: string;
+    url_private_download?: string;
+    permalink?: string;
+    permalink_public?: string;
+    thumb_360?: string;
+    thumb_480?: string;
+    thumb_720?: string;
+    thumb_800?: string;
+    thumb_1024?: string;
 }
 export interface Block {
     type: string;