# korotovsky/slack-mcp-server architecture

> Architecture diagram of the GitHub repository korotovsky/slack-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/korotovsky/slack-mcp-server
- Repository: https://github.com/korotovsky/slack-mcp-server

## Overview

##### Project Type and Purpose
- This is a standalone backend service written in Go (with helper scripts in Node/NPM for CLI packaging) that implements a Model Context Protocol (MCP) server for Slack.
- It exposes an MCP-compatible endpoint over STDIO or Server-Sent Events (SSE), translates MCP “tool” calls into Slack API calls, caches workspace metadata, and returns structured responses to any MCP client.

##### File Structure Analysis
- Top-level:
- cmd/slack-mcp-server: the entry point (main.go).
- pkg/: the core libraries organized by concern—handler, transport, provider, limiter, text, server, version, test utilities.
- Dockerfile & docker-compose*.yml: containerization and orchestration for dev, test, production, and toolkit debugging.
- npm/: cross-platform CLI wrappers for distributing the Go binary via NPM.
- build/: prebuilt extension artifacts (DXT), CI/CD packaging.
- Patterns & Config:
- MVC-style separation: transport → server core → handler → provider → external Slack.
- Rate limiting (pkg/limiter) inserted before Slack calls.
- Caching layers on local filesystem for users / channels (configurable via ENV).
- CI pipelines (.github/workflows) for unit tests, integration tests, and container releases.

##### README Insights
- Describes supported transports (Stdio, SSE), authentication modes (stealth vs OAuth), features (history fetch, search, posting, caching).
- Environment variables govern ports, host binding, TLS, proxy, caching paths, log levels, and feature toggles.
- Two special “slack://” directory endpoints for channels and users.

a. Main Components
1. MCP Client(s): any tool speaking MCP (via STDIO or SSE)
2. Transport Layer:
- STDIO transport adapter
- SSE transport adapter
3. Server Core (pkg/server):
- Authentication (pkg/server/auth)
- Request dispatcher
4. Rate Limiter (pkg/limiter)
5. Handler Layer (pkg/handler): maps MCP tools to application logic
6. Text Processor (pkg/text): formatting, parsing
7. Provider Layer (pkg/provider/edge + api.go): Slack edge client
8. Cache Store (local JSON files): users cache, channels cache
9. External Service: Slack Web API
10. CLI / Packaging: Docker container, NPM published binaries

b. Relationships & Data Flow
- Slack API responses flow back through Provider → Handler → Server Core → Transport → MCP Client.
- Caching: read-before-API-call from local JSON caches, write-after-API-call to caches.

c. Architectural Patterns
- Layered architecture: separation of transport, business logic, and external integration.
- Adapter pattern for transports and provider.
- Optional feature toggles via ENV variables (Strategy/Feature Toggle).
- Rate-limiting middleware integrated as a cross-cutting concern.

d. Key Technologies
- Go modules (go.mod)
- Docker, docker-compose
- NPM + cross-platform binaries
- GitHub Actions for CI/CD
- SSE & STDIO protocols for real-time and CLI use
- Local JSON files for O(1) cache lookups

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Transport Layer"
        STDIO["Transport Adapter: STDIO"]:::internal
        SSE["Transport Adapter: SSE"]:::internal
    end

    STDIO -->|"MCP tool call"| ServerCore
    SSE -->|"MCP tool call"| ServerCore

    subgraph "Server Core"
        ServerCore["Server Core"]:::internal
        Version["Version Module"]:::internal
    end

    ServerCore -->|"load version"| Version
    ServerCore -->|"dispatch request"| Auth

    Auth["Auth Module (Stealth & OAuth)"]:::internal
    Auth -->|"auth check"| Limiter

    Limiter["Rate Limiter"]:::internal
    Limiter -->|"rate limit"| Channels
    Limiter -->|"rate limit"| Conversations

    subgraph "Handler Layer"
        Channels["Handler: Channels"]:::internal
        Conversations["Handler: Conversations"]:::internal
    end

    Channels -->|"handle channels"| TextProc
    Conversations -->|"handle conversations"| TextProc

    TextProc["Text Processor"]:::integration
    TextProc -->|"format request"| APIInterface

    subgraph "Provider Layer"
        APIInterface["Provider API Interface"]:::integration
        EdgeClient["Slack Edge Client"]:::integration
    end

    APIInterface -->|"call API"| EdgeClient
    EdgeClient -->|"HTTP call"| SlackAPI
    SlackAPI["Slack Web API"]:::external
    SlackAPI -->|"API response"| EdgeClient
    EdgeClient -->|"pass response"| APIInterface
    APIInterface -->|"pass data"| TextProc

    EdgeClient -->|"read/write cache"| CacheUsers
    EdgeClient -->|"read/write cache"| CacheChannels

    CacheUsers["Users Cache (JSON)"]:::external
    CacheChannels["Channels Cache (JSON)"]:::external

    TextProc -->|"parsed response"| Channels
    TextProc -->|"parsed response"| Conversations

    Channels -->|"MCP response"| ServerCore
    Conversations -->|"MCP response"| ServerCore

    ServerCore -->|"send response"| STDIO
    ServerCore -->|"send response"| SSE

    subgraph "Deployment Artifacts"
        CLIMain["CLI Entry Point"]:::deployment
        NPMIndex["NPM CLI: index.js"]:::deployment
        NPMPkg["NPM CLI: package.json"]:::deployment
        Dockerfile["Dockerfile"]:::deployment
        ComposeMain["docker-compose.yml"]:::deployment
        ComposeDev["docker-compose.dev.yml"]:::deployment
        ComposeToolkit["docker-compose.toolkit.yml"]:::deployment
        BuildArt["Build Artifacts (DXT)"]:::deployment
    end

    NPMIndex -->|"invokes"| CLIMain
    NPMPkg -->|"metadata"| NPMIndex
    CLIMain -->|"executes"| ServerCore
    Dockerfile -->|"builds"| Dockerfile
    ComposeMain -->|"orchestrates"| CLIMain
    ComposeDev -->|"orchestrates"| CLIMain
    ComposeToolkit -->|"orchestrates"| CLIMain
    BuildArt -->|"packaged in"| Dockerfile

    classDef internal fill:#cce5ff,stroke:#00529B,color:#00529B
    classDef integration fill:#ffe5cc,stroke:#E07B39,color:#E07B39
    classDef external fill:#e5ffe5,stroke:#2E8B57,color:#2E8B57
    classDef deployment fill:#f3e5ff,stroke:#8E44AD,color:#8E44AD

    click STDIO "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/transport/transport.go"
    click SSE "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/transport/transport.go"
    click ServerCore "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/server/server.go"
    click Version "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/version/version.go"
    click Auth "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/server/auth/sse_auth.go"
    click Limiter "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/limiter/limits.go"
    click Channels "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/handler/channels.go"
    click Conversations "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/handler/conversations.go"
    click TextProc "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/text/text_processor.go"
    click APIInterface "https://github.com/korotovsky/slack-mcp-server/blob/master/pkg/provider/api.go"
    click EdgeClient "https://github.com/korotovsky/slack-mcp-server/tree/master/pkg/provider/edge"
    click CLIMain "https://github.com/korotovsky/slack-mcp-server/blob/master/cmd/slack-mcp-server/main.go"
    click NPMIndex "https://github.com/korotovsky/slack-mcp-server/blob/master/npm/slack-mcp-server/bin/index.js"
    click NPMPkg "https://github.com/korotovsky/slack-mcp-server/blob/master/npm/slack-mcp-server/package.json"
    click Dockerfile "https://github.com/korotovsky/slack-mcp-server/tree/master/Dockerfile"
    click ComposeMain "https://github.com/korotovsky/slack-mcp-server/blob/master/docker-compose.yml"
    click ComposeDev "https://github.com/korotovsky/slack-mcp-server/blob/master/docker-compose.dev.yml"
    click ComposeToolkit "https://github.com/korotovsky/slack-mcp-server/blob/master/docker-compose.toolkit.yml"
    click BuildArt "https://github.com/korotovsky/slack-mcp-server/tree/master/build/extension.dxt/server"
```
