feat: add attachment support tools

- Add messages_with_attachments tool to search for file attachments in channels
- Add get_attachment_details tool to get file metadata (thumbnails, dimensions, etc.)
- Add get_attachment_content tool to retrieve text file content for RAG/AI
- Add files:read scope to documentation
- Add SlackToken() and ProvideHTTPClient() methods to ApiProvider

Based on work started in korotovsky#130 by @FlorianOtel
Closes korotovsky#88

Author: cacapouh

docs/01-authentication-setup.md

@@ -56,7 +56,8 @@ Instead of using browser-based tokens (`xoxc`/`xoxd`), you can use a User OAuth
     - `mpim:write` - Start group direct messages with people on a user’s behalf (new since `v1.1.18`)
     - `users:read` - View people in a workspace.
     - `chat:write` - Send messages on a user’s behalf. (new since `v1.1.18`)
-    - `search:read` - Search a workspace’s content. (new since `v1.1.18`)
+    - `search:read` - Search a workspace's content. (new since `v1.1.18`)
+    - `files:read` - View files shared in channels and conversations.
 
 3. Install the app to your workspace
 4. Copy the "User OAuth Token" (starts with `xoxp-`)
@@ -84,7 +85,8 @@ To create the app from a manifest with permissions preconfigured, use the follow
                 "mpim:write",
                 "users:read",
                 "chat:write",
-                "search:read"
+                "search:read",
+                "files:read"
             ]
         }
     },

pkg/handler/attachments.go

@@ -5,6 +5,8 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
+	"net/http"
 	"strings"
 
 	"github.com/gocarina/gocsv"
@@ -246,3 +248,121 @@ func (ah *AttachmentsHandler) GetAttachmentDetailsHandler(ctx context.Context, r
 
 	return mcp.NewToolResultText(string(jsonBytes)), nil
 }
+
+// textMimeTypes are MIME types considered as text for content retrieval
+var textMimeTypes = map[string]bool {
+	"text/plain":             true,
+	"text/html":              true,
+	"text/css":               true,
+	"text/csv":               true,
+	"text/markdown":          true,
+	"text/xml":               true,
+	"application/json":       true,
+	"application/xml":        true,
+	"application/javascript": true,
+	"application/x-yaml":     true,
+	"application/x-sh":       true,
+}
+
+// isTextFile checks if the file is a text file based on MIME type or file extension
+func isTextFile(mimeType, fileType string) bool {
+	if textMimeTypes[mimeType] {
+		return true
+	}
+	// Check common text file extensions
+	textExtensions := []string{"txt", "md", "json", "xml", "yaml", "yml", "csv", "log", "sh", "py", "go", "js", "ts", "html", "css", "sql"}
+	for _, ext := range textExtensions {
+		if fileType == ext {
+			return true
+		}
+	}
+	return false
+}
+
+// GetAttachmentContentHandler retrieves the content of a text file attachment
+func (ah *AttachmentsHandler) GetAttachmentContentHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	ah.logger.Debug("GetAttachmentContentHandler called", zap.Any("params", request.Params))
+
+	if authenticated, err := auth.IsAuthenticated(ctx, ah.apiProvider.ServerTransport(), ah.logger); !authenticated {
+		ah.logger.Error("Authentication failed", zap.Error(err))
+		return nil, err
+	}
+
+	fileID := request.GetString("file_id", "")
+	if fileID == "" {
+		return nil, errors.New("file_id is required")
+	}
+
+	// Get file info first
+	file, _, _, err := ah.apiProvider.Slack().GetFileInfoContext(ctx, fileID, 1, 1)
+	if err != nil {
+		ah.logger.Error("Failed to get file info", zap.String("file_id", fileID), zap.Error(err))
+		return nil, err
+	}
+
+	// Check if it's a text file
+	if !isTextFile(file.Mimetype, file.Filetype) {
+		return nil, fmt.Errorf("file %q is not a text file (type: %s). Use get_attachment_details for binary files", file.Name, file.Mimetype)
+	}
+
+	// Download the file content
+	content, err := ah.downloadFileContent(ctx, file.URLPrivate)
+	if err != nil {
+		ah.logger.Error("Failed to download file content", zap.String("file_id", fileID), zap.Error(err))
+		return nil, err
+	}
+
+	// Build response with metadata and content
+	response := map[string]interface{}{
+		"id":       file.ID,
+		"name":     file.Name,
+		"title":    file.Title,
+		"mimeType": file.Mimetype,
+		"fileType": file.Filetype,
+		"size":     file.Size,
+		"content":  content,
+	}
+
+	jsonBytes, err := json.MarshalIndent(response, "", "  ")
+	if err != nil {
+		ah.logger.Error("Failed to marshal response to JSON", zap.Error(err))
+		return nil, err
+	}
+
+	return mcp.NewToolResultText(string(jsonBytes)), nil
+}
+
+// downloadFileContent downloads the content of a file from Slack
+func (ah *AttachmentsHandler) downloadFileContent(ctx context.Context, url string) (string, error) {
+	// Get HTTP client from provider
+	httpClient := ah.apiProvider.ProvideHTTPClient()
+
+	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	// Add Authorization header for authenticated file download
+	// This is required for bot tokens (xoxb-) and user tokens (xoxp-)
+	token := ah.apiProvider.SlackToken()
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("failed to download file: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("failed to download file: HTTP %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read file content: %w", err)
+	}
+
+	return string(body), nil
+}

pkg/provider/api.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"io/ioutil"
+	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
@@ -774,6 +775,24 @@ func (ap *ApiProvider) IsBotToken() bool {
 	return ok && client != nil && client.IsBotToken()
 }
 
+// ProvideHTTPClient returns the HTTP client used for Slack API requests
+func (ap *ApiProvider) ProvideHTTPClient() *http.Client {
+	client, ok := ap.client.(*MCPSlackClient)
+	if !ok || client == nil || client.authProvider == nil {
+		return http.DefaultClient
+	}
+	return transport.ProvideHTTPClient(client.authProvider.Cookies(), ap.logger)
+}
+
+// SlackToken returns the Slack API token for authenticated requests
+func (ap *ApiProvider) SlackToken() string {
+	client, ok := ap.client.(*MCPSlackClient)
+	if !ok || client == nil || client.authProvider == nil {
+		return ""
+	}
+	return client.authProvider.SlackToken()
+}
+
 func mapChannel(
 	id, name, nameNormalized, topic, purpose, user string,
 	members []string,

pkg/server/server.go

@@ -177,6 +177,16 @@ func NewMCPServer(provider *provider.ApiProvider, logger *zap.Logger) *MCPServer
 		),
 	), attachmentsHandler.GetAttachmentDetailsHandler)
 
+	s.AddTool(mcp.NewTool("get_attachment_content",
+		mcp.WithDescription("Get the content of a text file attachment. Only works for text files (txt, json, md, yaml, csv, etc.). Returns the file content directly for RAG/AI processing."),
+		mcp.WithTitleAnnotation("Get Attachment Content"),
+		mcp.WithReadOnlyHintAnnotation(true),
+		mcp.WithString("file_id",
+			mcp.Required(),
+			mcp.Description("The ID of the file attachment to get content for (format: Fxxxxxxxxxx)."),
+		),
+	), attachmentsHandler.GetAttachmentContentHandler)
+
 	s.AddTool(mcp.NewTool("channels_list",
 		mcp.WithDescription("Get list of channels"),
 		mcp.WithTitleAnnotation("List Channels"),