Files

aakash 06505c069e Update Slack setup guide with bot invitation requirements

- Add important section about inviting bot to channels before RAG queries
- Explain the 'not_in_channel' errors and their meaning
- Provide clear steps for bot invitation process
- Document realistic scenario where bot needs explicit channel access
- Update documentation to be more professional and less cursor-style

2025-10-12 16:17:47 -07:00

15 KiB

Raw Blame History

Slack Integration Setup Guide

This guide provides step-by-step instructions for setting up Slack integration with LEANN.

Overview

LEANN's Slack integration uses MCP (Model Context Protocol) servers to fetch and index your Slack messages for RAG (Retrieval-Augmented Generation). This allows you to search through your Slack conversations using natural language queries.

Prerequisites

Slack Workspace Access: You need admin or owner permissions in your Slack workspace to create apps and configure OAuth tokens.
Slack MCP Server: Install a Slack MCP server (e.g., slack-mcp-server via npm)
LEANN: Ensure you have LEANN installed and working

Step 1: Create a Slack App

1.1 Go to Slack API Dashboard

Visit https://api.slack.com/apps
Click "Create New App"
Choose "From scratch"
Enter your app name (e.g., "LEANN Slack Integration")
Select your workspace
Click "Create App"

1.2 Configure App Permissions

Bot Token Scopes

In your app dashboard, go to "OAuth & Permissions" in the left sidebar
Scroll down to "Scopes" section
Under "Bot Token Scopes", click "Add an OAuth Scope"
Add the following scopes:
- channels:read - Read public channel information
- channels:history - Read messages in public channels
- groups:read - Read private channel information
- groups:history - Read messages in private channels
- im:read - Read direct message information
- im:history - Read direct messages
- mpim:read - Read group direct message information
- mpim:history - Read group direct messages
- users:read - Read user information
- team:read - Read workspace information

App-Level Tokens (Optional)

Some MCP servers may require app-level tokens:

Go to "Basic Information" in the left sidebar
Scroll down to "App-Level Tokens"
Click "Generate Token and Scopes"
Enter a name (e.g., "LEANN Integration")
Add the connections:write scope
Click "Generate"
Copy the token (starts with xapp-)

1.3 Install App to Workspace

Go to "OAuth & Permissions" in the left sidebar
Click "Install to Workspace"
Review the permissions and click "Allow"
Copy the "Bot User OAuth Token" (starts with xoxb-)

Step 2: Install Slack MCP Server

Option A: Using npm (Recommended)

# Install globally
npm install -g slack-mcp-server

# Or install locally
npm install slack-mcp-server

Option B: Using npx (No installation required)

# Use directly without installation
npx slack-mcp-server

Step 3: Configure Environment Variables

Create a .env file or set environment variables:

# Required: Bot User OAuth Token
SLACK_BOT_TOKEN=xoxb-your-bot-token-here

# Optional: App-Level Token (if your MCP server requires it)
SLACK_APP_TOKEN=xapp-your-app-token-here

# Optional: Workspace-specific settings
SLACK_WORKSPACE_ID=T1234567890  # Your workspace ID (optional)

Step 4: Test the Setup

4.1 Test MCP Server Connection

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --test-connection \
  --workspace-name "Your Workspace Name"

This will test the connection and list available tools without indexing any data.

4.2 Index a Specific Channel

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --workspace-name "Your Workspace Name" \
  --channels general \
  --query "What did we discuss about the project?"

4.3 Real RAG Query Example

To ask intelligent questions about your Slack conversations:

# Ask about a specific topic discussed in your channels
python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --workspace-name "Sky Lab Computing" \
  --channels random general \
  --query "What is LEANN about?"

This will:

Retrieve relevant messages from the specified channels
Index the content for semantic search
Generate an intelligent answer based on the retrieved context
Provide citations showing which messages were used

Success Example: Working Integration

Here's what a successful Slack integration looks like in practice:

Terminal Output

When you run the connection test, you should see output similar to this:

Testing Slack MCP Connection...
Environment: SLACK_MCP_XOXP_TOKEN = xoxb-16753592806-967...

Connected to Slack MCP server!
Authenticated with Slack.

Listing available MCP tools...
Found 5 available tools:
  1. channels_list - Get list of channels
  2. conversations_add_message - Add messages to channels
  3. conversations_history - Get messages from channels
  4. conversations_replies - Get thread messages
  5. conversations_search_messages - Search messages with filters

Testing message fetch from 'random' channel...
Successfully fetched messages from channel random.

Visual Example

The following screenshot shows a successful integration with VS Code displaying the retrieved Slack channel data:

Key Success Indicators

Authentication Success: Connected to your Slack workspace
Tool Availability: 5 MCP tools ready for interaction
Data Access: Retrieved channel directory with member counts and purposes
Comprehensive Coverage: Access to multiple channels including specialized research groups

This demonstrates that your Slack integration is fully functional and ready for RAG queries across your entire workspace.

Important: Invite Your Bot to Channels

Before running RAG queries, you need to invite your Slack bot to the channels you want to access. This is a security feature in Slack.

To invite your bot to a channel:

Go to the channel in Slack (e.g., #general or #random)
Type: /invite @YourBotName (replace with your actual bot name)
Or click the channel name → "Settings" → "Integrations" → "Add apps"

RAG Example: Querying Slack Messages

Here's what happens when you run a real RAG query on your Slack conversations:

Command:

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --workspace-name "Sky Lab Computing" \
  --channels general random ps2 \
  --query "What is LEANN about?"

Actual Terminal Output:

Getting Conversation Messages
============================================================
Connected to Slack MCP server!

⏳ Waiting for users cache to be ready...

📋 Getting channel list...
✅ Got channels data!

📊 Found 107 channels

🎯 Trying to get messages from 5 channels:

🔍 Getting messages from #ps2 (183 members)...
❌ No messages in #ps2: {'jsonrpc': '2.0', 'id': 2, 'error': {'code': -32603, 'message': 'not_in_channel'}}

🔍 Getting messages from #systems-reading-group (174 members)...
❌ No messages in #systems-reading-group: {'jsonrpc': '2.0', 'id': 2, 'error': {'code': -32603, 'message': 'not_in_channel'}}

🔍 Getting messages from #dsf-fac-and-grad-students (140 members)...
❌ No messages in #dsf-fac-and-grad-students: {'jsonrpc': '2.0', 'id': 2, 'error': {'code': -32603, 'message': 'not_in_channel'}}

🔍 Getting messages from #ps-social (87 members)...
❌ No messages in #ps-social: {'jsonrpc': '2.0', 'id': 2, 'error': {'code': -32603, 'message': 'not_in_channel'}}

🔍 Getting messages from #llm-reading (84 members)...
❌ No messages in #llm-reading: {'jsonrpc': '2.0', 'id': 2, 'error': {'code': -32603, 'message': 'not_in_channel'}}

============================================================
📊 SUMMARY:
- Retrieved data from 5 channels
- Found channel directory with 107 total channels
- Channels include: #ps2, #systems-reading-group, #dsf-fac-and-grad-students, etc.
- This demonstrates successful Slack workspace access and data retrieval

============================================================
RAG RESPONSE:
============================================================
Query: 'What is LEANN about?'

Based on the retrieved Slack workspace data, here's what I found:

The "Sky Lab Computing" workspace is a large academic research environment with **107 channels**:

**Major Research Channels:**
- **#ps2** - Progressive Systems Seminar (183 members) - Systems/berkeley/life discussions
- **#systems-reading-group** - Sky Systems Reading Group (174 members)
- **#dsf-fac-and-grad-students** - DSF faculty and grad students (140 members)
- **#ps-social** - Social channel (87 members)
- **#llm-reading** - Generative Models reading group (84 members)

**Research Focus Areas:**
- Systems and distributed computing
- Machine learning and generative models
- Graduate education and fellowships
- Academic collaboration and reading groups

**Integration Status:**
The Slack integration successfully:
1. **Connected to the workspace** and authenticated
2. **Retrieved comprehensive channel directory** (107 channels)
3. **Identified channel permissions** - bot needs to be invited to specific channels
4. **Demonstrated proper error handling** for access restrictions

**Next Steps for Full RAG:**
To access actual conversation messages, the bot needs to be invited to specific channels. Once invited, the system would be able to:
- Retrieve actual conversation messages
- Index them for semantic search
- Answer questions based on real discussions

**Sources:** Channel directory from Sky Lab Computing workspace (107 channels analyzed)

============================================================
✅ RAG Query Complete!

After Inviting Your Bot

Once you've invited your bot to a channel, you'll see actual conversation messages instead of "not_in_channel" errors. The RAG system will then be able to:

Retrieve real messages from the channels your bot has access to
Index them for semantic search using LEANN's vector database
Answer questions based on actual conversation content
Provide context-aware responses about your team's discussions

This demonstrates that the integration is working correctly - it's just a matter of proper channel permissions!

Common Issues and Solutions

Issue 1: "users cache is not ready yet" Error

Problem: You see this warning:

WARNING - Failed to fetch messages from channel random: Failed to fetch messages: {'code': -32603, 'message': 'users cache is not ready yet, sync process is still running... please wait'}

Solution: This is a common timing issue. The LEANN integration now includes automatic retry logic:

Wait and Retry: The system will automatically retry with exponential backoff (2s, 4s, 8s, etc.)

Increase Retry Parameters: If needed, you can customize retry behavior:

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --max-retries 10 \
  --retry-delay 3.0 \
  --channels general \
  --query "Your query here"

Keep MCP Server Running: Start the MCP server separately and keep it running:

# Terminal 1: Start MCP server
slack-mcp-server

# Terminal 2: Run LEANN (it will connect to the running server)
python -m apps.slack_rag --mcp-server "slack-mcp-server" --channels general --query "test"

Issue 2: "No message fetching tool found"

Problem: The MCP server doesn't have the expected tools.

Solution:

Check if your MCP server is properly installed and configured
Verify your Slack tokens are correct
Try a different MCP server implementation
Check the MCP server documentation for required configuration

Issue 3: Permission Denied Errors

Problem: You get permission errors when trying to access channels.

Solutions:

Check Bot Permissions: Ensure your bot has been added to the channels you want to access
Verify Token Scopes: Make sure you have all required scopes configured
Channel Access: For private channels, the bot needs to be explicitly invited
Workspace Permissions: Ensure your Slack app has the necessary workspace permissions

Issue 4: Empty Results

Problem: No messages are returned even though the channel has messages.