Project 21: Slack Integration Agent (Team Communication)

Project 21: Slack Integration Agent (Team Communication)

Build an MCP integration that connects Kiro CLI to Slack - reading messages, posting updates, and searching channel history with AI assistance.

---

Learning Objectives

By completing this project, you will:

1. Understand MCP server architecture and how to expose external APIs to AI agents
2. Master Slack API fundamentals including OAuth 2.0, Bot tokens, and app scopes
3. Implement rate limiting and backoff strategies for production API integrations
4. Design conversational AI workflows that bridge team communication with development tasks
5. Apply Block Kit formatting to create rich, interactive Slack messages

---

Deep Theoretical Foundation

The Communication Integration Problem

Modern development teams live in chat platforms. Slack has become the de facto operating system for team communication, yet developers constantly context-switch between their IDE, terminal, and Slack. This creates friction:

Traditional Workflow:
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Terminal  │───►│   Browser   │───►│    Slack    │
│  (coding)   │    │ (tab switch)│    │ (reading)   │
└─────────────┘    └─────────────┘    └─────────────┘
       │                                     │
       └────────── Context Lost ─────────────┘

Integrated Workflow:
┌─────────────────────────────────────────────────────┐
│                    Kiro CLI                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │  File Ops   │  │    MCP      │  │   Slack     │ │
│  │   Agent     │◄─┤   Router    ├─►│   Server    │ │
│  └─────────────┘  └─────────────┘  └─────────────┘ │
│         │               ▲                │          │
│         └───────────────┴────────────────┘          │
│              Unified Context                         │
└─────────────────────────────────────────────────────┘

Model Context Protocol (MCP) Architecture

MCP provides a standardized way for AI agents to interact with external systems. Think of it as “USB for AI” - a universal connector that lets any AI system plug into any data source:

MCP Communication Flow:

┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│   AI Agent   │◄───────►│  MCP Client  │◄───────►│  MCP Server  │
│  (Kiro CLI)  │  JSON   │  (in Kiro)   │  stdio  │   (Slack)    │
└──────────────┘   RPC   └──────────────┘   or    └──────────────┘
                                          HTTP          │
                                                        │
                                                        ▼
                                                 ┌──────────────┐
                                                 │  Slack API   │
                                                 │  (External)  │
                                                 └──────────────┘

Key MCP Concepts:

Concept	Description	Slack Mapping
Tools	Actions the AI can invoke	post_message, search_messages
Resources	Data the AI can read	Channel lists, user profiles
Prompts	Pre-built conversation starters	“Summarize #engineering today”

Slack API Architecture

Slack’s API follows a layered architecture with three main access patterns:

Slack API Layers:

┌─────────────────────────────────────────────────────────────┐
│                     Your Application                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Web API                                 │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐   │
│  │ conversations │  │    users      │  │    chat       │   │
│  │   .history    │  │   .list       │  │   .postMsg    │   │
│  └───────────────┘  └───────────────┘  └───────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Authentication                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Bot Token: xoxb-...                                    │  │
│  │ Scopes: channels:read, chat:write, users:read         │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Rate Limiting Strategy

Slack enforces rate limits per method tier. Understanding this is crucial for production integrations:

Rate Limit Tiers:

Tier 1 (Generous):          Tier 2 (Moderate):       Tier 3 (Restrictive):
  ~1+ req/sec                 ~20 req/min              ~1 req/min
  ┌─────────────┐             ┌─────────────┐          ┌─────────────┐
  │conversations│             │  chat.post  │          │ admin.*     │
  │   .list     │             │  Message    │          │ methods     │
  └─────────────┘             └─────────────┘          └─────────────┘

Backoff Strategy:
┌────────┐    429    ┌────────┐  Retry-After  ┌────────┐
│ Request│─────────►│  Wait  │──────────────►│ Retry  │
└────────┘          │ Header │               └────────┘
                    └────────┘
                         │
              Exponential backoff:
              1s → 2s → 4s → 8s → max 60s

Block Kit: Rich Message Formatting

Slack’s Block Kit provides structured, interactive message layouts. Understanding this transforms your AI from text-only to richly formatted:

Block Kit Structure:

┌─────────────────────────────────────────────────────────┐
│ Message                                                  │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Section Block                                        │ │
│ │ ┌───────────────────────┬───────────────────────┐  │ │
│ │ │ Text                   │ Accessory (optional)  │  │ │
│ │ │ "Summary of today..."  │ [image/button/menu]   │  │ │
│ │ └───────────────────────┴───────────────────────┘  │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Divider Block                                        │ │
│ │ ──────────────────────────────────────────────────  │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Actions Block                                        │ │
│ │ [Button 1] [Button 2] [Dropdown ▼]                  │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Real-World Analogy: The AI Team Assistant

Think of this integration like hiring a team assistant who sits in every Slack channel:

1. They can listen - Read messages and understand context
2. They can speak - Post updates on your behalf
3. They can search - Find past conversations instantly
4. They can summarize - Condense hours of chatter into key points

But unlike a human assistant, this one:

• Never forgets a conversation
• Can search thousands of messages in seconds
• Works 24/7 without breaks
• Can format information beautifully

Historical Context

The evolution of team chat integration follows a clear trajectory:

1990s: IRC Bots           2010s: Slack Apps        2024+: AI Agents
  │                           │                        │
  │ Simple commands           │ Interactive buttons    │ Natural language
  │ !weather NYC              │ Click to approve       │ "What did we discuss?"
  │                           │                        │
  │ Pattern matching          │ Webhooks/OAuth         │ MCP Protocol
  │ Regex triggers            │ App Directory          │ Context-aware
  └───────────────────────────┴────────────────────────┴─────────────

Book References

For deeper understanding, consult:

• “Building Bots with Node.js” by Eduardo Freitas - Chapters 4-6 cover Slack bot architecture
• “OAuth 2.0 in Action” by Justin Richer - Essential for understanding bot authentication
• “API Design Patterns” by JJ Geewax - Chapters on rate limiting and pagination
• “Designing Distributed Systems” by Brendan Burns - Sidecar patterns for API integration

---

Complete Project Specification

What You Are Building

An MCP server that exposes Slack functionality to Kiro CLI, enabling:

1. Message Reading: Fetch messages from any accessible channel
2. Message Posting: Send messages with rich formatting
3. Channel Search: Search across channel history
4. User Resolution: Convert user IDs to names and vice versa
5. Conversation Summarization: AI-powered summaries of channel activity

Functional Requirements

Feature	Input	Output
List channels	Workspace scope	Channel names + IDs
Read messages	Channel ID + time range	Message array with metadata
Post message	Channel ID + content	Message confirmation
Search messages	Query string + filters	Matching messages
Summarize channel	Channel ID + time range	AI-generated summary

Non-Functional Requirements

• Latency: < 2 seconds for single channel operations
• Rate Limiting: Automatic backoff on 429 responses
• Token Security: Secure storage of Slack bot tokens
• Error Handling: Graceful degradation with helpful messages

---

Solution Architecture

High-Level Component Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                           Kiro CLI                                   │
│  ┌─────────────────────────────────────────────────────────────────┐│
│  │                    Agent Runtime                                 ││
│  │                         │                                        ││
│  │                         ▼                                        ││
│  │              ┌─────────────────────┐                            ││
│  │              │    MCP Router       │                            ││
│  │              │  (Tool Dispatcher)  │                            ││
│  │              └─────────────────────┘                            ││
│  │                         │                                        ││
│  └─────────────────────────┼────────────────────────────────────────┘│
└────────────────────────────┼────────────────────────────────────────┘
                             │ stdio/HTTP
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     Slack MCP Server                                 │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐           │
│  │  Tool Handler │  │ Rate Limiter  │  │ Token Manager │           │
│  │  - list_chans │  │ - Bucket alg  │  │ - Env vars    │           │
│  │  - read_msgs  │  │ - Backoff     │  │ - Validation  │           │
│  │  - post_msg   │  │ - Queue       │  │               │           │
│  └───────────────┘  └───────────────┘  └───────────────┘           │
│          │                  │                  │                    │
│          └──────────────────┼──────────────────┘                    │
│                             ▼                                        │
│                   ┌─────────────────────┐                           │
│                   │   Slack Web API     │                           │
│                   │      Client         │                           │
│                   └─────────────────────┘                           │
└─────────────────────────────────────────────────────────────────────┘
                             │
                             ▼ HTTPS
┌─────────────────────────────────────────────────────────────────────┐
│                    Slack Platform                                    │
│                   api.slack.com                                      │
└─────────────────────────────────────────────────────────────────────┘

Data Flow: Reading Channel Messages

User Request: "Show me the last 10 messages in #engineering"

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  User   │────►│  Kiro   │────►│  MCP    │────►│  Slack  │
│ Prompt  │     │  Agent  │     │ Server  │     │   API   │
└─────────┘     └─────────┘     └─────────┘     └─────────┘
                    │               │               │
                    │ Parse intent  │               │
                    │ Map to tool   │               │
                    │◄──────────────┘               │
                    │                               │
                    │      conversations.history    │
                    │              ──────────────────►
                    │                               │
                    │      Message Array (JSON)     │
                    │◄──────────────────────────────
                    │                               │
                    │ Format for display            │
                    ▼                               │
              ┌───────────────────────────────┐    │
              │ Last 10 messages in #eng:     │    │
              │ 1. @alice: "PR is ready..."   │    │
              │ 2. @bob: "LGTM, merging..."   │    │
              │ ...                           │    │
              └───────────────────────────────┘    │

Key Interfaces

// MCP Tool Definitions
interface SlackTools {
  // List accessible channels
  list_channels: () => Promise<Channel[]>;

  // Read channel history
  read_messages: (params: {
    channel: string;
    limit?: number;
    oldest?: string;  // Unix timestamp
    latest?: string;  // Unix timestamp
  }) => Promise<Message[]>;

  // Post a message
  post_message: (params: {
    channel: string;
    text: string;
    blocks?: Block[];  // Block Kit formatting
  }) => Promise<MessageResponse>;

  // Search across workspace
  search_messages: (params: {
    query: string;
    channel?: string;
    from?: string;  // User ID
  }) => Promise<SearchResult[]>;
}

// Data Types
interface Message {
  user: string;
  text: string;
  ts: string;
  thread_ts?: string;
  reactions?: Reaction[];
}

interface Channel {
  id: string;
  name: string;
  is_private: boolean;
  num_members: number;
}

Technology Choices

Component	Technology	Rationale
MCP Server	TypeScript + Bun	Fast startup, native TypeScript
Slack Client	@slack/web-api	Official SDK, well-maintained
Token Storage	Environment variables	Simple, secure, standard
Transport	stdio	Local integration, no network overhead
Rate Limiting	Token bucket	Industry standard, configurable

---

Phased Implementation Guide

Phase 1: Foundation - Slack App Setup (Days 1-2)

Goal: Create a Slack app and establish basic API connectivity.

Tasks:

1. Create a Slack app at api.slack.com/apps
2. Configure required OAuth scopes
3. Install app to your workspace
4. Store bot token securely
5. Test basic API calls with curl

Required Scopes:

channels:read      - View basic channel info
channels:history   - Read channel messages
chat:write         - Send messages
users:read         - Get user profiles
search:read        - Search messages (if using search)

Hints:

• Start with a test workspace to avoid disrupting real channels
• The bot token starts with xoxb-
• Use auth.test API method to verify your token works

Verification:

# Test your token
curl -X POST 'https://slack.com/api/auth.test' \
  -H 'Authorization: Bearer xoxb-your-token' \
  -H 'Content-Type: application/json'

Phase 2: MCP Server Skeleton (Days 3-4)

Goal: Create a minimal MCP server that Kiro can discover.

Tasks:

1. Initialize a TypeScript/Bun project
2. Implement MCP protocol handlers
3. Define tool schemas (without implementation)
4. Configure Kiro to connect to your server
5. Verify tools appear in Kiro’s tool list

Hints:

• MCP servers communicate via stdin/stdout (stdio transport)
• Use the official MCP SDK: @modelcontextprotocol/sdk
• Tool schemas define what parameters the AI can pass

Kiro Configuration (.kiro/settings.json):

{
  "mcpServers": {
    "slack": {
      "command": "bun",
      "args": ["run", "/path/to/your/server/index.ts"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-..."
      }
    }
  }
}

Verification:

# In Kiro chat
> /mcp
# Should list "slack" as an available server

Phase 3: Core Functionality (Days 5-8)

Goal: Implement the main Slack operations.

Tasks:

1. Implement list_channels tool
2. Implement read_messages tool
3. Implement post_message tool
4. Add error handling for API failures
5. Implement basic rate limiting

Hints:

• Use the @slack/web-api client for API calls
• Slack returns timestamps as strings (Unix epoch with decimals)
• Implement pagination for channels with many messages
• The conversations.history API returns messages newest-first

Rate Limiting Pattern:

if response.status == 429:
    wait_time = response.headers['Retry-After']
    sleep(wait_time)
    retry()

Phase 4: Polish and Advanced Features (Days 9-14)

Goal: Add rich formatting, search, and summarization.

Tasks:

1. Implement Block Kit message formatting
2. Add search_messages tool
3. Add user ID to name resolution
4. Create helper prompts for common operations
5. Add channel summarization capability

Hints:

• Block Kit has a visual builder at app.slack.com/block-kit-builder
• User IDs look like U1234567890 - resolve to names for readability
• Summarization can use Kiro’s AI directly on fetched messages
• Consider caching user profiles to reduce API calls

Block Kit Example:

{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Channel Summary*\n• 47 messages today\n• 3 action items"
      }
    },
    {
      "type": "divider"
    }
  ]
}

---

Testing Strategy

Unit Tests

Test individual components in isolation:

// Test rate limiter
describe('RateLimiter', () => {
  it('should delay requests when limit exceeded', async () => {
    const limiter = new RateLimiter({ maxRequests: 1, window: 1000 });
    const start = Date.now();
    await limiter.acquire();
    await limiter.acquire();
    expect(Date.now() - start).toBeGreaterThan(1000);
  });
});

// Test message formatting
describe('MessageFormatter', () => {
  it('should convert Block Kit to text', () => {
    const blocks = [{ type: 'section', text: { text: 'Hello' } }];
    expect(formatAsText(blocks)).toBe('Hello');
  });
});

Integration Tests

Test against a real (test) Slack workspace:

describe('Slack Integration', () => {
  it('should list channels', async () => {
    const channels = await slackClient.listChannels();
    expect(channels).toBeInstanceOf(Array);
    expect(channels[0]).toHaveProperty('id');
    expect(channels[0]).toHaveProperty('name');
  });

  it('should post and read messages', async () => {
    // Post a test message
    const posted = await slackClient.postMessage({
      channel: TEST_CHANNEL,
      text: `Test message ${Date.now()}`
    });

    // Read it back
    const messages = await slackClient.readMessages({
      channel: TEST_CHANNEL,
      limit: 1
    });

    expect(messages[0].ts).toBe(posted.ts);
  });
});

End-to-End Tests

Test the full MCP flow with Kiro:

# In Kiro chat session
> "List all public channels"
# Verify: Should return channel list

> "Read the last 5 messages from #test-channel"
# Verify: Should return formatted messages

> "Post 'Hello from Kiro!' to #test-channel"
# Verify: Message appears in Slack

---

Common Pitfalls and Debugging

Pitfall 1: Token Scope Errors

Symptom: missing_scope error from Slack API

Cause: Bot token doesn’t have required permissions

Solution:

# Check your token's scopes
curl -X POST 'https://slack.com/api/auth.test' \
  -H 'Authorization: Bearer xoxb-your-token'

# Response shows: "team", "user_id", but NOT scopes
# Go to api.slack.com/apps > OAuth > Add missing scopes
# Reinstall app to workspace

Pitfall 2: Channel Not Found

Symptom: channel_not_found error

Causes:

• Using channel name instead of ID
• Bot not in private channel
• Channel is archived

Debugging:

# Get channel ID from name
curl -X POST 'https://slack.com/api/conversations.list' \
  -H 'Authorization: Bearer xoxb-your-token' \
  -d 'types=public_channel,private_channel'

# For private channels, bot must be invited
# Use: /invite @your-bot-name in Slack

Pitfall 3: MCP Server Not Starting

Symptom: Kiro shows “Failed to connect to MCP server”

Debugging Steps:

# 1. Test server directly
echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | bun run index.ts

# 2. Check for syntax errors
bun check index.ts

# 3. Verify path in settings.json is absolute

# 4. Check environment variables are set
env | grep SLACK

Pitfall 4: Rate Limiting Issues

Symptom: Intermittent 429 Too Many Requests errors

Solution:

// Implement exponential backoff
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'slack_webapi_rate_limited') {
        const delay = Math.pow(2, i) * 1000;
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

---

Extensions and Challenges

Extension 1: Thread Support

Add ability to read and reply to message threads:

interface ThreadTools {
  read_thread: (params: { channel: string; thread_ts: string }) => Promise<Message[]>;
  reply_to_thread: (params: { channel: string; thread_ts: string; text: string }) => Promise<void>;
}

Extension 2: Reaction Analysis

Track and analyze emoji reactions for sentiment:

Channel Sentiment for #engineering (Today):
  Positive: 45% (+1, thumbsup, heart)
  Neutral:  40% (eyes, thinking_face)
  Negative: 15% (disappointed, x)

Extension 3: User Mention Resolution

Automatically expand <@U12345> to actual usernames in messages.

Extension 4: Multi-Workspace Support

Extend to support multiple Slack workspaces:

{
  "workspaces": {
    "company": { "token": "xoxb-..." },
    "oss-community": { "token": "xoxb-..." }
  }
}

Extension 5: Interactive Components

Handle button clicks and dropdown selections from posted messages.

---

Real-World Connections

How Companies Use Slack AI Integration

Incident Response: Automatically pull relevant Slack discussions when an alert fires, giving on-call engineers immediate context.

Daily Standups: AI summarizes what each team member shared, creating automatic standup reports.

Knowledge Discovery: “What did we decide about the API versioning strategy?” searches across months of discussions.

Automated Updates: CI/CD pipelines post deployment notifications with rich formatting and action buttons.

Production Considerations

Concern	Solution
Token rotation	Use Slack’s token rotation API
Audit logging	Log all bot actions for compliance
Access control	Limit channels bot can access
Multi-tenant	Separate tokens per workspace
High availability	Deploy MCP server redundantly

Industry Patterns

The Slack integration pattern you’re building is used by tools like:

• Linear: Syncs issues with Slack threads
• GitHub: Posts PR notifications with action buttons
• PagerDuty: Creates incident channels automatically
• Notion: Shares page updates to channels

---

Self-Assessment Checklist

Knowledge Verification

• Can you explain how MCP servers communicate with AI agents?
• Do you understand the difference between Bot tokens and User tokens?
• Can you describe three Slack API rate limit tiers?
• What is Block Kit and when would you use it?
• How does the stdio transport work for MCP?

Implementation Verification

• Your server successfully lists channels
• Messages are read with proper timestamp formatting
• Posted messages appear in Slack with your bot’s identity
• Rate limiting prevents 429 errors during heavy use
• Error messages are helpful and actionable

Advanced Verification

• Search works across multiple channels
• User IDs are resolved to readable names
• Block Kit formatting renders correctly in Slack
• The integration handles private channels appropriately
• You can summarize a day’s activity in a channel

Integration Verification

• Kiro can invoke all your Slack tools naturally
• The MCP server starts reliably when Kiro launches
• Environment variables are properly secured
• The tool works in your actual development workflow

---

Summary

This project bridges the gap between AI-assisted development and team communication. By building an MCP server for Slack, you have learned:

1. MCP Architecture: How AI agents extend their capabilities through standardized protocols
2. API Integration: Working with OAuth, rate limits, and external services
3. Message Formatting: Creating rich, interactive messages with Block Kit
4. Production Patterns: Error handling, retries, and security considerations

The patterns you have learned here apply to any external service integration - whether it is Discord, Microsoft Teams, or custom internal tools. The MCP protocol provides a consistent way to expose any API to AI agents.

---

Next Project: P22-test-generator-hook.md - Automatic test generation using PostToolUse hooks