Project Structure & Organization

This document provides an overview of the Slack MCP Server project structure, source code organization, and architectural design patterns.

Directory Structure

slack-mcp-server/
├── slack_mcp/                 # Main package directory
│   ├── mcp/                   # MCP server implementation
│   │   ├── model/             # Data models and schemas
│   │   ├── cli/               # Command-line interface
│   │   ├── server.py          # MCP server implementation
│   │   └── __init__.py
│   ├── webhook/               # Webhook server implementation
│   │   ├── event/             # Event handling and models
│   │   ├── cli/               # Webhook CLI interface
│   │   ├── server.py          # FastAPI webhook server
│   │   ├── models.py          # Pydantic models for Slack events
│   │   └── entry.py           # Entry points and runners
│   ├── client/                # Slack client management
│   │   ├── factory.py         # Client factory patterns
│   │   └── manager.py         # Client lifecycle management
│   ├── backends/              # Queue backend abstractions
│   │   ├── base/              # Base backend interfaces
│   │   └── queue/             # Queue backend implementations
│   ├── integrated_server.py   # Integrated MCP + webhook server
│   └── __init__.py
├── test/                      # Test suite
│   ├── unit_test/             # Unit tests
│   ├── integration_test/      # Integration tests
│   ├── contract_test/         # Contract tests
│   └── e2e_test/              # End-to-end tests
├── examples/                  # Usage examples
├── scripts/                   # Build and deployment scripts
├── docs/                      # Documentation (Docusaurus)
└── pyproject.toml            # Project configuration

Core Components

MCP Server (slack_mcp/mcp/)

The MCP server implements the Model Context Protocol for Slack integration:

• server.py: Main MCP server implementation with tool registration
• model/: Pydantic models for MCP requests and responses
• cli/: Command-line interface for running the MCP server

Key Features:

• Multiple transport support (stdio, SSE, HTTP)
• Slack API integration through registered tools
• Async/await patterns for non-blocking operations
• Comprehensive error handling and logging

Webhook Server (slack_mcp/webhook/)

FastAPI-based webhook server for receiving Slack events:

• server.py: FastAPI application with webhook endpoints
• models.py: Pydantic models for Slack event payloads
• event/: Event processing and handler management
• entry.py: Server runners and entry points

Key Features:

• Request signature verification for security
• Event publishing to queue backends
• URL verification challenge handling
• Standalone and integrated deployment modes

Client Management (slack_mcp/client/)

Centralized Slack client management:

• factory.py: Factory patterns for client creation
• manager.py: Client lifecycle and token management

Backend Abstraction (slack_mcp/backends/)

Queue backend abstraction layer:

• base/: Abstract base classes and interfaces
• queue/: Concrete queue backend implementations

Design Patterns

Factory Pattern

Used extensively for creating clients and server instances:

# Client factory
from slack_mcp.client.factory import create_slack_client

# Server factory functions
from slack_mcp.integrate.integrated_server import create_integrated_app

Strategy Pattern

Transport mechanism selection and queue backend selection:

# Transport strategy
if transport == "sse":
    mcp_app = server.sse_app(mount_path=mount_path)
elif transport == "streamable-http":
    mcp_app = server.streamable_http_app()

Repository Pattern

Backend abstraction for different queue systems:

# Queue backend strategy
backend = get_backend(backend_type)
await backend.publish(topic, event_data)

Command Pattern

MCP tools as command objects:

@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    return [
        types.Tool(name="slack_post_message", description="..."),
        # ... other tools
    ]

Configuration Management

Environment-Based Configuration

• .env files for local development
• Environment variables for production
• Centralized configuration validation

CLI Integration

• Comprehensive command-line interfaces
• Argument parsing with validation
• Help text and documentation

Testing Strategy

Test Organization

• Unit Tests: Component-level testing with mocks
• Integration Tests: Cross-component interaction testing
• Contract Tests: API contract validation
• End-to-End Tests: Full workflow testing

Test Utilities

• Shared fixtures and test data
• Mock factories for external dependencies
• Test configuration management

Development Workflow

Code Organization Principles

1. Separation of Concerns: Clear boundaries between MCP, webhook, and client code
2. Dependency Injection: Loose coupling through factory patterns
3. Async/Await: Non-blocking operations throughout
4. Type Hints: Comprehensive type annotations for better IDE support
5. Error Handling: Consistent error patterns and logging

Package Management

• UV: Fast Python package management
• Lock Files: Reproducible dependency resolution
• Development Dependencies: Separate dev/test requirements

Code Quality

• Linting: Pylint, MyPy type checking
• Formatting: Consistent code style
• Pre-commit Hooks: Automated quality checks

Extension Points

Adding New MCP Tools

1. Create tool function in slack_mcp/mcp/server.py
2. Define input/output models in slack_mcp/mcp/model/
3. Register tool with MCP server
4. Add comprehensive tests

Adding New Event Handlers

1. Extend event models in slack_mcp/webhook/event/
2. Implement handler logic
3. Register with webhook server
4. Add queue publishing logic

Adding New Queue Backends

1. Implement backend interface in slack_mcp/backends/queue/
2. Add backend selection logic
3. Update configuration options
4. Add backend-specific tests

This modular architecture ensures maintainability, testability, and extensibility while providing clear boundaries between different system components.