Slack MCP Client in Go

Um cliente bot do Slack que faz a ponte entre o Slack e servidores do Model Context Protocol (MCP), permitindo que LLMs utilizem ferramentas MCP.

GitHub

171

Experimente este MCPPatrocinado

Documentação

Slack MCP Client

Uma ponte pronta para produção entre Slack e modelos de IA com compatibilidade total com MCP.

Este cliente permite que modelos de IA (OpenAI GPT-4.1, Anthropic Claude 4.5, modelos locais Ollama) interajam com ferramentas e sistemas reais por meio de conversas no Slack. Construído sobre o Model Context Protocol (MCP), padrão da indústria, ele fornece acesso seguro a sistemas de arquivos, bancos de dados, clusters Kubernetes, repositórios Git e ferramentas personalizadas.

Compatível com a Especificação MCP 2025-06-18 - Em conformidade com os padrões mais recentes do Model Context Protocol

Atualizações Recentes

Out 2025: langchaingo v0.1.14 com correções de streaming, análise aprimorada de agentes e sanitização de chaves de API.

Principais Recursos

Compatibilidade MCP Universal - Suporta todos os métodos de transporte (HTTP, SSE, stdio)
Suporte Multi-Provedor de LLM - OpenAI GPT-4.1/4o, Anthropic Claude 4.5, Ollama (Llama 3.3, Qwen, Mistral, DeepSeek)
Modo Agente - Raciocínio de múltiplas etapas com LangChain para fluxos de trabalho complexos
Integração RAG - Base de conhecimento com recursos de busca semântica
Contexto Ciente de Threads - Mantém histórico de conversa separado por thread do Slack
Integração de Contexto do Usuário - Respostas personalizadas com informações de usuário em cache
Nomenclatura Única de Ferramentas - Nomes de ferramentas com prefixo do servidor evitam conflitos entre servidores MCP
Pronto para Produção - Configuração, monitoramento e segurança abrangentes

Casos de Uso

Equipes de DevOps - Automação e monitoramento de infraestrutura por meio do Slack
Equipes de Desenvolvimento - Revisão de código, operações Git e gerenciamento de arquivos
Equipes de Suporte - Consultas a bancos de dados, verificações de status do sistema e solução de problemas
Uso Geral - Assistência de IA com ferramentas reais e integração de sistemas

Compatibilidade MCP

Em conformidade com o Model Context Protocol oficial (especificação 2025-06-18):

Todos os Métodos de Transporte - Protocolos HTTP, SSE e stdio
JSON-RPC 2.0 - Protocolo de comunicação padrão
Servidores MCP Oficiais - Compatível com todos os modelcontextprotocol/servers
Servidores MCP Personalizados - Funciona com qualquer servidor compatível com MCP
Padrões de Segurança - Implementa consentimento do usuário, privacidade de dados e requisitos de segurança de ferramentas

Autenticação em Servidores MCP SSE

A autenticação com servidores MCP Server-Sent Events (SSE) pode ser alcançada usando a seguinte configuração:

Exemplo:

{
  "httpHeaders": {
    "Authorization": "Bearer YOUR_TOKEN_HERE"
  }
}

Certifique-se de substituir YOUR_TOKEN_HERE pelo seu token real para autenticação.

Como Funciona

flowchart LR
    User([👤 User]) --> Slack{🔗 Slack Interface}

    subgraph Infrastructure[Observability]
        Config[📋 Unified Config<br/>JSON Schema]
        Monitoring[📊 Monitoring<br/>Prometheus Metrics]
        Tracing[🔍 OpenTelemetry Tracing<br/>Langfuse & OTLP]
        Logging[📝 Structured Logging<br/>Debug & Analytics]
    end
    
    subgraph Core[Features]
        Slack --> Bridge[🌉 LLM-MCP Bridge<br/>Orchestration Layer]
        
        subgraph LLM[🤖 AI Processing]
            Bridge --> LLMRegistry[LLM Provider Registry]
            LLMRegistry --> OpenAI[OpenAI<br/>GPT-4o]
            LLMRegistry --> Anthropic[Anthropic<br/>Claude]
            LLMRegistry --> Ollama[Ollama<br/>Local Models]
            
            Bridge --> Agent{🎯 Agent Mode?}
            Agent -->|Yes| LangChain[🔄 LangChain Agent<br/>Multi-step Reasoning]
            Agent -->|No| Standard[⚡ Standard Mode<br/>Single Response]
        end
        
        subgraph Knowledge[📚 Knowledge & Memory]
            Bridge --> RAG[🧠 RAG System]
            RAG --> SimpleRAG[📄 JSON Store<br/>Simple Documents]
            RAG --> VectorRAG[🔍 OpenAI Vector Store<br/>Semantic Search]
        end
        
        subgraph Tools[🛠️ MCP Mode]
            Bridge --> MCPManager[MCP Client]
            MCPManager --> FileSystem[📁 Filesystem MCP Server<br/>Read/Write Files]
            MCPManager --> Git[🌿 Git MCP Server <br/>Repository Tools]
            MCPManager --> Kubernetes[☸️ Kubernetes MCP Server<br/>Cluster Management]
        end
    end
    
    
    Config -.-> Core
    Core -.-> Monitoring
    Core -.-> Tracing
    Core -.-> Logging
    
    style Core fill:#F8F9FA,stroke:#6C757D,stroke-width:3px
    style LLM fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
    style Knowledge fill:#E8F5E8,stroke:#388E3C,stroke-width:2px
    style Tools fill:#FFF3E0,stroke:#F57C00,stroke-width:2px
    style Infrastructure fill:#F3E5F5,stroke:#7B1FA2,stroke-width:2px
    
    style User fill:#4CAF50,stroke:#2E7D32,stroke-width:2px,color:#fff
    style Slack fill:#4A90E2,stroke:#1565C0,stroke-width:2px,color:#fff
    style Bridge fill:#FF9800,stroke:#E65100,stroke-width:2px,color:#fff
    style LangChain fill:#9C27B0,stroke:#4A148C,stroke-width:2px,color:#fff
    style RAG fill:#2196F3,stroke:#0D47A1,stroke-width:2px,color:#fff

Usuário interage por meio do Slack, enviando mensagens que acionam fluxos de trabalho de IA inteligentes
Ponte LLM-MCP serve como a camada de orquestração inteligente que:
- Roteia solicitações para provedores de LLM apropriados (OpenAI, Anthropic, Ollama)
- Escolhe entre Modo Agente (raciocínio de múltiplas etapas) ou Modo Padrão (resposta única)
- Integra o sistema RAG para recuperação de conhecimento e aprimoramento de contexto
- Gerencia descoberta e execução de ferramentas em vários servidores MCP
O sistema de Conhecimento e Memória fornece inteligência contextual:
- Armazenamento JSON simples para armazenamento leve de documentos
- OpenAI Vector Store para busca semântica e RAG de nível empresarial
O Ecossistema de Ferramentas conecta-se a diversos sistemas externos:
- Operações de sistema de arquivos para gerenciamento de arquivos
- Integração Git para interações com repositórios
- Gerenciamento e monitoramento de clusters Kubernetes
- Ferramentas personalizadas via protocolos HTTP, SSE ou stdio
A Infraestrutura garante implantação pronta para produção:
- Configuração JSON unificada com suporte a variáveis de ambiente
- Métricas Prometheus para observabilidade e monitoramento
- Rastreamento OpenTelemetry com provedores Langfuse e OTLP
- Registro estruturado para depuração e análise

Recursos

✅ Cliente MCP Multimodo:
- Server-Sent Events (SSE) para comunicação em tempo real com nova tentativa automática
- Transporte HTTP para JSON-RPC
- stdio para desenvolvimento e teste locais
✅ Integração Slack:
- Usa Socket Mode para comunicação segura e amigável a firewalls
- Funciona com canais e mensagens diretas
- Formatação rica de mensagens com Markdown e Block Kit
- Rastreamento de conversas ciente de threads com contexto separado por thread
- Cache de contexto do usuário para interações personalizadas
- Comportamento do bot e histórico de mensagens personalizáveis
✅ Suporte Multi-Provedor de LLM:
- OpenAI (GPT-4.1, GPT-4o, o3-pro)
- Anthropic (Claude Sonnet 4.5, Opus 4.1)
- Ollama (Llama 3.3, Qwen2.5, Mistral, DeepSeek)
- Chamada de ferramentas nativa e gateway LangChain unificado
✅ Modo Agente:
- Agentes de IA autônomos alimentados por LangChain (langchaingo v0.1.14)
- Raciocínio de múltiplas etapas aprimorado e orquestração de ferramentas
- Análise aprimorada para chamadas de ferramentas complexas de várias linhas
- Iterações e comportamento do agente configuráveis
- Respostas de streaming confiáveis com correções de vazamento de memória
- Recursos avançados de engenharia de prompt
✅ RAG (Geração Aumentada por Recuperação):
- Vários provedores: armazenamento JSON simples, OpenAI Vector Store
- Armazenamentos de vetores reutilizáveis com suporte a vectorStoreId
- Parâmetros de busca e métricas de similaridade configuráveis
- Ingestão de PDF com fragmentação inteligente
- Ferramentas CLI para gerenciamento de documentos
✅ Configuração Unificada:
- Arquivo de configuração JSON único com validação de esquema JSON
- Configuração abrangente de tempo limite e nova tentativa
- Substituição e sobreposição de variáveis de ambiente
- Todas as opções de pacotes subjacentes expostas
- Padrões inteligentes com capacidade total de personalização
- Nomes de ferramentas com prefixo do servidor para evitar conflitos de nomenclatura
✅ Pronto para Produção:
- Suporte a contêiner Docker com publicação GHCR
- Gráficos Helm Kubernetes com registro OCI
- Registro e tratamento de erros abrangentes
- Cobertura de teste com varredura de segurança
✅ Monitoramento e Observabilidade:
- Integração de métricas Prometheus
- Rastreamento de invocação de ferramentas com taxas de erro
- Monitoramento de uso de tokens LLM por modelo e tipo
- Rastreamento OpenTelemetry com provedores Langfuse e simples
- Provedores de observabilidade configuráveis com fallbacks graciosos
- Rastreamento abrangente de spans para operações LLM e chamadas de ferramentas
- Endpoint de métricas e níveis de registro configuráveis

Instalação

A partir do Lançamento Binário

Baixe o binário mais recente na página de lançamentos do GitHub ou instale usando Go:

# Install latest version using Go
go install github.com/tuannvm/slack-mcp-client@latest

# Or build from source
git clone https://github.com/tuannvm/slack-mcp-client.git
cd slack-mcp-client
make build
# Binary will be in ./bin/slack-mcp-client

Executando Localmente com Binário

Após instalar o binário, você pode executá-lo localmente com as seguintes etapas:

Configure as variáveis de ambiente:

# Using environment variables directly
export SLACK_BOT_TOKEN="xoxb-your-bot-token"
export SLACK_APP_TOKEN="xapp-your-app-token"
export OPENAI_API_KEY="sk-your-openai-key"
export OPENAI_MODEL="gpt-4.1"  # or gpt-4o, o3-pro
export LOG_LEVEL="info"

# Or create a .env file and source it
cat > .env << EOL
SLACK_BOT_TOKEN="xoxb-your-bot-token"
SLACK_APP_TOKEN="xapp-your-app-token"
OPENAI_API_KEY="sk-your-openai-key"
OPENAI_MODEL="gpt-4o"
LOG_LEVEL="info"
EOL

source .env

Crie um arquivo de configuração unificado:

# Create config.json with the new unified configuration format
cat > config.json << EOL
{
  "\$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json",
  "version": "2.0",
  "slack": {
    "botToken": "\${SLACK_BOT_TOKEN}",
    "appToken": "\${SLACK_APP_TOKEN}"
  },
  "llm": {
    "provider": "openai",
    "useNativeTools": true,
    "providers": {
      "openai": {
        "model": "gpt-4o",
        "apiKey": "\${OPENAI_API_KEY}",
        "temperature": 0.7
      }
    }
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "\$HOME"]
    }
  },
  "monitoring": {
    "enabled": true,
    "metricsPort": 8080,
    "loggingLevel": "info"
  },
  "observability": {
    "enabled": true,
    "provider": "simple-otel",
    "endpoint": "${OTEL_EXPORTER_OTLP_ENDPOINT}",
    "serviceName": "slack-mcp-client",
    "serviceVersion": "1.0.0"
  }
}
EOL

Execute o aplicativo:

# Run with unified configuration (looks for config.json in current directory)
slack-mcp-client --config config.json

# Enable debug mode with structured logging
slack-mcp-client --config config.json --debug

# Validate configuration before running
slack-mcp-client --config-validate --config config.json

# Configure metrics port via config file or flag
slack-mcp-client --config config.json --metrics-port 9090

Migrando da Configuração Legada

Se você tiver um arquivo mcp-servers.json existente de uma versão anterior, poderá migrar para o novo formato de configuração unificado:

# Automatic migration (recommended)
slack-mcp-client --migrate-config --config legacy-mcp-servers.json --output config.json

# Manual migration: Use examples as templates
cp examples/minimal.json config.json
# Edit config.json with your specific settings

# Validate the new configuration
slack-mcp-client --config-validate --config config.json

O novo formato de configuração fornece:

Arquivo Único: Todas as configurações em um arquivo config.json
Esquema JSON: Suporte a IDE com autocompletar e validação
Variáveis de Ambiente: Use a sintaxe ${VAR_NAME} para segredos
Padrões Inteligentes: Configuração mínima necessária para uso básico
Opções Abrangentes: Todas as configurações de pacotes subjacentes expostas

O aplicativo se conectará ao Slack e começará a ouvir mensagens. Você pode verificar os logs para quaisquer erros ou problemas de conexão.

Configuração e Uso do RAG

O cliente inclui um sistema RAG (Geração Aumentada por Recuperação) aprimorado que é compatível com LangChain Go e fornece desempenho de nível profissional:

Início Rápido com RAG

Habilite o RAG na sua configuração:

{
  "$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json",
  "version": "2.0",
  "slack": {
    "botToken": "${SLACK_BOT_TOKEN}",
    "appToken": "${SLACK_APP_TOKEN}"
  },
  "llm": {
    "provider": "openai",
    "useNativeTools": true,
    "providers": {
      "openai": {
        "model": "gpt-4o",
        "apiKey": "${OPENAI_API_KEY}"
      }
    }
  },
  "rag": {
    "enabled": true,
    "provider": "simple",
    "chunkSize": 1000,
    "providers": {
      "simple": {
        "databasePath": "./knowledge.json"
      },
      "openai": {
        "indexName": "my-knowledge-base",
        "vectorStoreId": "vs_existing_store_id",
        "dimensions": 1536,
        "maxResults": 10
      }
    }
  }
}

Ingira documentos usando CLI:

# Ingest PDF files from a directory
slack-mcp-client --rag-ingest ./company-docs --rag-db ./knowledge.json

# Test search functionality
slack-mcp-client --rag-search "vacation policy" --rag-db ./knowledge.json

# Get database statistics
slack-mcp-client --rag-stats --rag-db ./knowledge.json

Use no Slack:

Uma vez configurado, o LLM pode pesquisar automaticamente sua base de conhecimento:

Usuário: "Qual é a nossa política de férias?"

IA: "Deixe-me pesquisar nossa base de conhecimento para obter informações sobre a política de férias..." (Pesquisa automaticamente o banco de dados RAG)

IA: "Com base nos documentos de política da empresa, você tem 15 dias de férias..."

Recursos do RAG

🎯 Busca Inteligente: Pontuação de relevância avançada com frequência de palavras, aumento de nome de arquivo e correspondência de frases
🔗 Compatível com LangChain: Substituição direta para armazenamentos de vetores padrão
📈 Extensível: Fácil adicionar embeddings de vetores e outros backends

Prompts Personalizados e Assistentes

O cliente suporta recursos avançados de engenharia de prompt para criar assistentes de IA especializados:

Prompts de Sistema

Crie personalidades e comportamentos de IA personalizados:

# Create a custom system prompt file
cat > sales-assistant.txt << EOL
You are SalesGPT, a helpful sales assistant specializing in B2B software sales.

Your expertise includes:
- Lead qualification and discovery
- Solution positioning and value propositions  
- Objection handling and negotiation
- CRM best practices and sales processes

Always:
- Ask qualifying questions to understand prospect needs
- Provide specific, actionable sales advice
- Reference industry best practices
- Maintain a professional yet friendly tone

When discussing pricing, always emphasize value over cost.
EOL

# Use the custom prompt
slack-mcp-client --system-prompt ./sales-assistant.txt

Prompts Baseados em Configuração

Defina prompts na sua configuração:

{
  "$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json",
  "version": "2.0",
  "slack": {
    "botToken": "${SLACK_BOT_TOKEN}",
    "appToken": "${SLACK_APP_TOKEN}"
  },
  "llm": {
    "provider": "openai",
    "useNativeTools": true,
    "customPrompt": "You are a helpful DevOps assistant specializing in Kubernetes and cloud infrastructure.",
    "providers": {
      "openai": {
        "model": "gpt-4.1",
        "apiKey": "${OPENAI_API_KEY}",
        "temperature": 0.7
      }
    }
  }
}

Funções de Assistente

Crie assistentes especializados para diferentes casos de uso:

Assistente de DevOps: Especialista em Kubernetes, Docker, CI/CD
Assistente de Vendas: Qualificação de leads, tratamento de objeções
Assistente de RH: Perguntas sobre políticas, orientação de integração
Assistente de Suporte: Resolução de problemas do cliente
Assistente de Revisão de Código: Segurança, desempenho, melhores práticas

Modo Agente

O Modo Agente permite conversas mais interativas e cientes de contexto usando a estrutura de agentes do LangChain. Em vez de interações de prompt único, os agentes podem se envolver em raciocínio de múltiplas etapas, usar ferramentas mais estrategicamente e manter melhor contexto ao longo das conversas.

Como Funciona o Modo Agente

O Modo Agente usa a estrutura de agente conversacional do LangChain para fornecer:

Conversas Interativas: Mantém contexto em múltiplas trocas
Uso Estratégico de Ferramentas: Os agentes decidem quando e como usar as ferramentas disponíveis
Raciocínio de Múltiplas Etapas: Pode dividir problemas complexos em etapas gerenciáveis
Respostas em Streaming: Fornece atualizações em tempo real durante o processamento
Integração de Contexto do Usuário: Incorpora informações de usuário em cache para respostas personalizadas
Consciência de Contexto de Thread: Mantém histórico de conversa separado por thread do Slack

Configuração do Modo Agente

Habilite o Modo Agente no seu arquivo de configuração:

{
  "$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json",
  "version": "2.0",
  "slack": {
    "botToken": "${SLACK_BOT_TOKEN}",
    "appToken": "${SLACK_APP_TOKEN}"
  },
  "llm": {
    "provider": "openai",
    "useNativeTools": true,
    "useAgent": true,
    "customPrompt": "You are a DevOps expert specializing in Kubernetes and cloud infrastructure. Always think through problems step by step.",
    "maxAgentIterations": 20,
    "providers": {
      "openai": {
        "model": "gpt-4.1",
        "apiKey": "${OPENAI_API_KEY}",
        "temperature": 0.7
      }
    }
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "github-mcp-server",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Opções de Configuração

llm.useAgent: Habilita o modo agente (padrão: false)
llm.useNativeTools: Usa ferramentas nativas do LangChain vs ferramentas baseadas em prompt de sistema (padrão: false)
llm.customPrompt: Prompt de sistema para comportamento do agente
llm.maxAgentIterations: Número máximo de etapas de raciocínio do agente (padrão: 20)

Modo Agente vs Modo Padrão

Modo Padrão:

Interações de prompt único
Ferramentas descritas no prompt de sistema como esquemas JSON
Análise e execução direta de chamadas de ferramentas
Uso de tokens mais previsível
Fluxo de conversa mais simples

Modo Agente:

Interações conversacionais de múltiplas voltas
Decisões de uso de ferramentas cientes de contexto
Melhor integração de contexto do usuário
Fluxo de conversa mais natural
Capacidades de raciocínio aprimoradas

Exemplos do Modo Agente

Consulta de Desenvolvimento Interativa:

User: "I need help optimizing my React app performance"

Agent Response:
🤖 I'd be happy to help optimize your React app performance! Let me understand your current setup better.

[Agent maintains conversation context and asks relevant follow-up questions]
Agent: "What specific performance issues are you experiencing? Are you seeing slow renders, large bundle sizes, or something else?"

User: "The app takes too long to load initially"

Agent: "Let me check your current bundle setup and suggest optimizations..."
[Agent uses filesystem tools to analyze the project structure and provides targeted advice]

Resolução de Problemas Contextual:

User: "Can you help me with my deployment pipeline?"

Agent Response:
🤖 I'll help you with your deployment pipeline. Since I know you're working on a React project, let me check your current CI/CD setup.

[Agent leverages previous conversation context and user information to provide personalized assistance]
[Agent strategically uses relevant tools based on the conversation flow]

Melhores Práticas do Modo Agente

Prompts de Sistema: Projete prompts de sistema claros e específicos que orientem o comportamento do agente
Seleção de Ferramentas: Forneça ferramentas relevantes para o domínio do agente
Gerenciamento de Contexto: Os agentes mantêm melhor contexto entre conversas
Personalização do Usuário: Aproveite a integração de contexto do usuário para respostas personalizadas
Estratégia de Ferramentas: Escolha entre ferramentas nativas ou baseadas em prompt de sistema com base nas suas necessidades

Limitações e Considerações

Agente OpenAI: O agente OpenAI nativo no langchaingo tem problemas conhecidos, usa agente conversacional como solução alternativa
Dependência do LangChain: O modo agente requer provedor LangChain
Permissões: Pode exigir permissões adicionais do Slack para recuperação de informações do usuário
Desempenho: O modo agente pode ter características de desempenho diferentes do modo padrão

Implantação Kubernetes com Helm

Para implantação no Kubernetes, um Helm chart está disponível no diretório helm-chart. Este chart oferece uma maneira flexível de implantar o slack-mcp-client com configuração adequada e gerenciamento de segredos.

Instalação a partir do GitHub Container Registry

O Helm chart também está disponível diretamente no GitHub Container Registry, permitindo uma instalação mais fácil sem precisar clonar o repositório:

# Add the OCI repository to Helm (only needed once)
helm registry login ghcr.io -u USERNAME -p GITHUB_TOKEN

# Pull the Helm chart
helm pull oci://ghcr.io/tuannvm/charts/slack-mcp-client --version 0.1.0

# Or install directly
helm install my-slack-bot oci://ghcr.io/tuannvm/charts/slack-mcp-client --version 0.1.0 -f values.yaml

Você pode verificar as versões disponíveis visitando o GitHub Container Registry no seu navegador.

Pré-requisitos

Kubernetes 1.16+
Helm 3.0+
Tokens do Slack Bot e do App

Instalação Básica

# Create a values file with your configuration
cat > values.yaml << EOL
secret:
  create: true

env:
  SLACK_BOT_TOKEN: "xoxb-your-bot-token"
  SLACK_APP_TOKEN: "xapp-your-app-token"
  OPENAI_API_KEY: "sk-your-openai-key"
  OPENAI_MODEL: "gpt-4o"
  LOG_LEVEL: "info"

# Optional: Configure MCP servers
configMap:
  create: true
EOL

# Install the chart
helm install my-slack-bot ./helm-chart/slack-mcp-client -f values.yaml

Opções de Configuração

O Helm chart suporta várias opções de configuração, incluindo:

Definição de limites e solicitações de recursos
Configuração de servidores MCP via ConfigMap
Gerenciamento de dados sensíveis via segredos do Kubernetes
Personalização de parâmetros de implantação

Para mais detalhes, consulte o README do Helm chart.

Usando a Imagem Docker do GHCR

O Helm chart usa a imagem Docker do GitHub Container Registry (GHCR) por padrão. Você pode especificar uma versão específica ou usar a tag mais recente:

# In your values.yaml
image:
  repository: ghcr.io/tuannvm/slack-mcp-client
  tag: "latest"  # Or use a specific version like "1.0.0"
  pullPolicy: IfNotPresent

Para baixar a imagem manualmente:

# Pull the latest image
docker pull ghcr.io/tuannvm/slack-mcp-client:latest

# Or pull a specific version
docker pull ghcr.io/tuannvm/slack-mcp-client:1.0.0

Se você estiver usando imagens privadas, pode configurar segredos de pull de imagem nos seus valores:

imagePullSecrets:
  - name: my-ghcr-secret

Docker Compose para Testes Locais

Para testes e desenvolvimento locais, você pode usar o Docker Compose para executar facilmente o slack-mcp-client junto com servidores MCP adicionais.

Configuração

Crie um arquivo .env com suas credenciais:

# Create .env file from example
cp .env.example .env
# Edit the file with your credentials
nano .env

Crie um arquivo mcp-servers.json (ou use o exemplo):

# Create mcp-servers.json from example
cp mcp-servers.json.example mcp-servers.json
# Edit if needed
nano mcp-servers.json

Inicie os serviços:

# Start services in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Configuração do Docker Compose

O docker-compose.yml incluído fornece:

Variáveis de ambiente carregadas do arquivo .env
Montagem de volume para configuração do servidor MCP
Exemplos de conexão a servidores MCP adicionais (comentados)

version: '3.8'

services:
  slack-mcp-client:
    image: ghcr.io/tuannvm/slack-mcp-client:latest
    container_name: slack-mcp-client
    environment:
      - SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN}
      - SLACK_APP_TOKEN=${SLACK_APP_TOKEN}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - OPENAI_MODEL=${OPENAI_MODEL:-gpt-4o}
    volumes:
      - ./mcp-servers.json:/app/mcp-servers.json:ro

Você pode facilmente estender esta configuração para incluir servidores MCP adicionais na mesma rede.

Configuração do Slack App

Crie um novo app do Slack em https://api.slack.com/apps
Ative o Socket Mode e gere um token de nível de app
Marque Allow users to send Slash commands and messages from the chat tab na página inicial do App para habilitar mensagens diretas para o app do Slack.
Adicione os seguintes Bot Token Scopes:
- app_mentions:read
- chat:write
- im:history
- im:read
- im:write
- users:read
- users.profile:read
- channels:history
- groups:history
- mpim:history
Ative as Assinaturas de Eventos e assine:
- app_mention
- message.im
Instale o app no seu workspace

Para instruções detalhadas sobre configuração do app Slack, configuração de tokens, permissões necessárias e solução de problemas comuns, consulte o Guia de Configuração do Slack.

Integração com LLM

O cliente suporta múltiplos provedores de LLM através de um sistema de integração flexível:

LangChain Gateway

O gateway LangChain permite integração perfeita com vários provedores de LLM:

OpenAI: Suporte nativo para modelos GPT (padrão)
Ollama: Suporte a LLM local para modelos como Llama, Mistral, etc.
Extensível: Pode ser estendido para suportar outros provedores compatíveis com LangChain

Ponte LLM-MCP

A camada de ponte LLM-MCP personalizada permite que qualquer LLM use ferramentas MCP sem exigir capacidades nativas de chamada de função:

Compatibilidade Universal: Funciona com qualquer LLM, incluindo aqueles sem chamada de função
Reconhecimento de Padrões: Detecta quando um prompt do usuário ou resposta do LLM deve acionar uma chamada de ferramenta
Suporte a Linguagem Natural: Entende tanto chamadas de ferramenta JSON estruturadas quanto solicitações em linguagem natural

Configuração

Os provedores de LLM podem ser configurados via variáveis de ambiente ou flags de linha de comando:

# Set OpenAI as the provider (default)
export LLM_PROVIDER="openai"
export OPENAI_MODEL="gpt-4.1"  # or gpt-4o, o3-pro

# Use Anthropic
export LLM_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export ANTHROPIC_MODEL="claude-sonnet-4.5"  # or claude-opus-4.1

# Or use Ollama
export LLM_PROVIDER="ollama"
export LANGCHAIN_OLLAMA_URL="http://localhost:11434"
export LANGCHAIN_OLLAMA_MODEL="llama3.3"  # or qwen2.5-coder, mistral-small-3, deepseek-r1

Alternando Entre Provedores

Você pode facilmente alternar entre provedores alterando a variável de ambiente LLM_PROVIDER:

# Use OpenAI
export LLM_PROVIDER=openai

# Use Anthropic
export LLM_PROVIDER=anthropic

# Use Ollama (local)
export LLM_PROVIDER=ollama

Configuração

O cliente usa duas abordagens principais de configuração:

Variáveis de Ambiente

Configure provedores de LLM e integração com Slack usando variáveis de ambiente:

Variável	Descrição	Padrão
SLACK_BOT_TOKEN	Token do bot para a API do Slack	(obrigatório)
SLACK_APP_TOKEN	Token de nível de app para Socket Mode	(obrigatório)
OPENAI_API_KEY	Chave da API para autenticação OpenAI	(obrigatório)
OPENAI_MODEL	Modelo OpenAI a ser usado	gpt-4.1
ANTHROPIC_API_KEY	Chave da API para autenticação Anthropic	(obrigatório para Anthropic)
ANTHROPIC_MODEL	Modelo Anthropic a ser usado	claude-sonnet-4.5
LOG_LEVEL	Nível de log (debug, info, warn, error)	info
LLM_PROVIDER	Provedor de LLM a ser usado (openai, anthropic, ollama)	openai
LANGCHAIN_OLLAMA_URL	URL para Ollama ao usar LangChain	http://localhost:11434
LANGCHAIN_OLLAMA_MODEL	Nome do modelo para Ollama ao usar LangChain	llama3.3
LANGFUSE_ENDPOINT	Endpoint da API Langfuse para observabilidade	(opcional)
LANGFUSE_PUBLIC_KEY	Chave pública Langfuse para autenticação	(opcional)
LANGFUSE_SECRET_KEY	Chave secreta Langfuse para autenticação	(opcional)
OTEL_EXPORTER_OTLP_ENDPOINT	Endpoint OTLP para rastreamento simples	(opcional)

Configuração de Monitoramento e Observabilidade

O cliente inclui capacidades abrangentes de monitoramento com métricas e rastreamento distribuído:

Métricas Prometheus

Endpoint de Métricas: Acessível em /metrics na porta configurada
Porta Padrão: 8080 (configurável via flag --metrics-port)
Métricas Disponíveis:
- slackmcp_tool_invocations_total: Contador para invocações de ferramentas com rótulos para nome da ferramenta, servidor e status de erro
- slackmcp_llm_tokens: Histograma para uso de tokens do LLM por tipo e modelo

Rastreamento OpenTelemetry

Provedores Suportados:
- simple-otel: Rastreamento OpenTelemetry básico para endpoints OTLP (requer configuração de endpoint)
- langfuse-otel: Observabilidade avançada de LLM com integração Langfuse (requer endpoint e autenticação)
- disabled: Sem rastreamento (padrão quando nenhum endpoint é configurado)
Fallbacks Automáticos: Provedores com falha automaticamente voltam para o estado desabilitado
Rastreamento Abrangente: Spans para operações de LLM, chamadas de ferramentas e interações do usuário com atributos detalhados

Exemplo de configuração e uso:

# Access metrics endpoint
curl http://localhost:8080/metrics

# Run with custom metrics port
slack-mcp-client --metrics-port 9090

# Enable Langfuse tracing (example)
export LANGFUSE_ENDPOINT="https://cloud.langfuse.com"
export LANGFUSE_PUBLIC_KEY="pk-your-public-key"  
export LANGFUSE_SECRET_KEY="sk-your-secret-key"

# Enable simple OTLP tracing (example)
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"

Formato de Configuração Unificado

Toda a configuração agora é gerenciada através de um único arquivo config.json com opções abrangentes:

{
  "$schema": "https://github.com/tuannvm/slack-mcp-client/schema/config-schema.json",
  "version": "2.0",
  "slack": {
    "botToken": "${SLACK_BOT_TOKEN}",
    "appToken": "${SLACK_APP_TOKEN}",
    "messageHistory": 50,
    "thinkingMessage": "Processing..."
  },
  "llm": {
    "provider": "openai",
    "useNativeTools": true,
    "useAgent": false,
    "customPrompt": "You are a helpful assistant.",
    "maxAgentIterations": 20,
    "providers": {
      "openai": {
        "model": "gpt-4o",
        "apiKey": "${OPENAI_API_KEY}",
        "temperature": 0.7,
        "maxTokens": 2000
      },
      "anthropic": {
        "model": "claude-sonnet-4.5",
        "apiKey": "${ANTHROPIC_API_KEY}",
        "temperature": 0.7
      }
    }
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "initializeTimeoutSeconds": 30,
      "tools": {
        "allowList": ["read_file", "write_file", "list_directory"],
        "blockList": ["delete_file"]
      }
    },
    "web-api": {
      "url": "http://localhost:8080/mcp",
      "transport": "sse",
      "initializeTimeoutSeconds": 30
    }
  },
  "rag": {
    "enabled": true,
    "provider": "openai",
    "chunkSize": 1000,
    "providers": {
      "openai": {
        "vectorStoreId": "vs_existing_store_id",
        "dimensions": 1536,
        "maxResults": 10
      }
    }
  },
  "timeouts": {
    "httpRequestTimeout": "30s",
    "toolProcessingTimeout": "3m",
    "mcpInitTimeout": "30s"
  },
  "retry": {
    "maxAttempts": 3,
    "baseBackoff": "500ms",
    "maxBackoff": "5s"
  },
  "monitoring": {
    "enabled": true,
    "metricsPort": 8080,
    "loggingLevel": "info"
  },
  "observability": {
    "enabled": true,
    "provider": "langfuse-otel",
    "endpoint": "${LANGFUSE_ENDPOINT}",
    "publicKey": "${LANGFUSE_PUBLIC_KEY}",
    "secretKey": "${LANGFUSE_SECRET_KEY}",
    "serviceName": "slack-mcp-client",
    "serviceVersion": "1.0.0"
  }
}

Para opções de configuração detalhadas e guias de migração, consulte o Guia de Configuração.

Recurso de Recarga Automática

O cliente suporta recarga automática opcional para lidar com reinicializações do servidor MCP sem tempo de inatividade - perfeito para implantações Kubernetes onde os servidores MCP podem reiniciar independentemente.

Nota: O recurso de recarga está desabilitado por padrão e deve ser explicitamente habilitado no seu arquivo de configuração.

Configuração

Para habilitar a funcionalidade de recarga, adicione as configurações de recarga ao seu config.json:

{
  "version": "2.0",
  "reload": {
    "enabled": true,
    "interval": "30m"
  }
}

Opções de Configuração:

enabled: Deve ser definido como true para ativar a funcionalidade de recarga (padrão: false)
interval: Tempo entre recargas automáticas (padrão: "30m", mínimo: "10s")

Uso

Recarga Automática: Quando habilitada, o aplicativo recarrega automaticamente no intervalo configurado para reconectar aos servidores MCP e atualizar a descoberta de ferramentas.

Recarga Manual: Mesmo com a recarga automática desabilitada, você pode acionar recargas manuais usando sinais:

# In Kubernetes
kubectl exec -it <pod-name> -- kill -USR1 1

# Local process
kill -USR1 <process-id>

Benefícios

Zero Tempo de Inatividade: O aplicativo permanece em execução durante a recarga
Amigável ao Kubernetes: O pod continua em execução enquanto os componentes do aplicativo reiniciam
Opt-in: Desabilitado por padrão, apenas habilitado quando explicitamente configurado
Flexível: Tanto gatilhos automáticos (periódicos) quanto manuais (sinais)
Seguro: Validação de intervalo mínimo evita recargas excessivas

Quando habilitado, o recurso de recarga automaticamente:

Reconecta a todos os servidores MCP configurados
Redescobre ferramentas disponíveis
Atualiza as configurações
Mantém a conexão Slack durante todo o processo

Perfeito para ambientes de produção onde os servidores MCP podem reiniciar devido a atualizações, escalonamento ou manutenção.

Saída Formatada para Slack

O cliente inclui um sistema abrangente de saída formatada para Slack que melhora a exibição de mensagens no Slack:

Detecção Automática de Formato: Detecta automaticamente o tipo de mensagem (texto simples, markdown, JSON Block Kit, dados estruturados) e aplica a formatação apropriada
Formatação Markdown: Suporta a sintaxe mrkdwn do Slack com conversão automática de Markdown padrão
- Converte **bold** para *bold* para formatação em negrito adequada do Slack
- Preserva código inline, citações em bloco, listas e outros elementos de formatação
Aprimoramento de Strings Entre Aspas: Converte automaticamente strings entre aspas duplas em blocos de código inline para melhor visualização
- Exemplo: "namespace-name" torna-se `namespace-name` no Slack
- Melhora a legibilidade de IDs, timestamps e outros valores entre aspas
Integração Block Kit: Converte dados estruturados em layouts Block Kit para melhor apresentação visual
- Valida automaticamente contra os limites da API do Slack
- Volta para texto simples se a validação do Block Kit falhar

Para mais detalhes, consulte o Guia de Formatação do Slack.

Modos de Transporte

O cliente suporta três modos de transporte:

SSE (padrão): Usa Server-Sent Events para comunicação em tempo real com o servidor MCP, incluindo lógica de nova tentativa automática para maior confiabilidade
HTTP: Usa solicitações HTTP POST com JSON-RPC para comunicação
stdio: Usa entrada/saída padrão para desenvolvimento e testes locais

Documentação

Documentação abrangente está disponível no diretório docs/:

Configuração e Setup

Guia de Configuração do Slack - Guia completo para configurar seu app Slack, incluindo permissões necessárias, tokens e solução de problemas comuns

Desenvolvimento e Implementação

Notas de Implementação - Documentação técnica detalhada cobrindo a arquitetura atual, componentes principais e detalhes de implementação
Especificação de Requisitos - Documentação abrangente de requisitos incluindo funcionalidades implementadas, requisitos de qualidade e melhorias futuras

Guias do Usuário

Guia de Formatação do Slack - Guia completo para formatação de mensagens incluindo conversão Markdown-para-Slack, layouts Block Kit e detecção automática de formato
Guia de Implementação RAG - Guia detalhado para o sistema RAG melhorado com compatibilidade LangChain Go e otimizações de desempenho
Implementação RAG SQLite - Plano de implementação para integração nativa Go SQLite com experiência de upload estilo ChatGPT
Guia de Testes - Documentação abrangente de testes cobrindo testes unitários, testes de integração, procedimentos de teste manual e depuração

Links Rápidos

Configuração: Comece com o Guia de Configuração do Slack para a configuração inicial
Modo Agente: Consulte a seção Modo Agente acima para agentes de IA autônomos com encadeamento de ferramentas
RAG: Confira o Guia de Implementação de RAG para integração de base de conhecimento de documentos
Formatação: Consulte o Guia de Formatação do Slack para recursos de formatação de mensagens
RAG SQLite: Consulte a Implementação de RAG SQLite para implementação nativa em Go com UX moderna de upload
Desenvolvimento: Confira as Notas de Implementação para detalhes técnicos
Testes: Use o Guia de Testes para procedimentos de teste e depuração
Monitoramento: Consulte a seção de configuração de métricas acima para integração com Prometheus
Dependências: Revise Dependências para rastreamento de versões e histórico de atualizações

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

CI/CD e Lançamentos

Este projeto usa GitHub Actions para integração contínua e GoReleaser para lançamentos automatizados.

Verificações de Integração Contínua

Nosso pipeline de CI realiza as seguintes verificações em todos os PRs e commits para a branch principal:

Qualidade de Código

Linting: Usando golangci-lint para verificar problemas comuns de código e violações de estilo
Verificação de Módulos Go: Garantindo que go.mod e go.sum sejam mantidos adequadamente
Formatação: Verificando se o código está formatado corretamente com gofmt

Segurança

Varredura de Vulnerabilidades: Usando govulncheck para verificar vulnerabilidades conhecidas nas dependências
Varredura de Dependências: Usando Trivy para escanear vulnerabilidades nas dependências
Geração de SBOM: Criando uma Lista de Materiais de Software para rastreamento de dependências

Testes

Testes Unitários: Executando testes com detecção de corrida e relatórios de cobertura de código
Verificação de Build: Garantindo que o código seja compilado com sucesso

Processo de Lançamento

Quando alterações são mescladas na branch principal:

As verificações de CI são executadas para validar qualidade e segurança do código
Se bem-sucedidas, um novo lançamento é criado automaticamente com:
- Versionamento semântico baseado nas mensagens de commit
- Builds binários para múltiplas plataformas
- Publicação de imagem Docker no GitHub Container Registry
- Publicação de Helm chart no GitHub Container Registry