Slack MCP Client in Go

Un cliente bot de Slack que conecta servidores Slack y Model Context Protocol (MCP), permitiendo que los LLMs utilicen herramientas MCP.

GitHub

171

Prueba este MCPPatrocinado

Documentación

Cliente MCP de Slack

Un puente listo para producción entre Slack y modelos de IA con compatibilidad total con MCP.

Este cliente permite que los modelos de IA (OpenAI GPT-4.1, Anthropic Claude 4.5, modelos locales de Ollama) interactúen con herramientas y sistemas reales a través de conversaciones de Slack. Construido sobre el Protocolo de Contexto de Modelos (MCP) estándar de la industria, proporciona acceso seguro a sistemas de archivos, bases de datos, clústeres de Kubernetes, repositorios de Git y herramientas personalizadas.

Compatible con la Especificación MCP 2025-06-18 - Cumple con los estándares más recientes del Protocolo de Contexto de Modelos

Actualizaciones Recientes

Oct 2025: langchaingo v0.1.14 con correcciones de streaming, análisis mejorado de agentes y saneamiento de claves API.

Características Principales

Compatibilidad Universal con MCP - Soporta todos los métodos de transporte (HTTP, SSE, stdio)
Soporte Multi-Proveedor de LLM - OpenAI GPT-4.1/4o, Anthropic Claude 4.5, Ollama (Llama 3.3, Qwen, Mistral, DeepSeek)
Modo Agente - Razonamiento de múltiples pasos con LangChain para flujos de trabajo complejos
Integración RAG - Base de conocimiento con capacidades de búsqueda semántica
Contexto Consciente de Hilos - Mantiene historial de conversación separado por hilo de Slack
Integración de Contexto de Usuario - Respuestas personalizadas con información de usuario en caché
Nombres de Herramientas Únicos - Nombres de herramientas con prefijo de servidor previenen conflictos entre servidores MCP
Listo para Producción - Configuración integral, monitoreo y seguridad

Casos de Uso

Equipos de DevOps - Automatización de infraestructura y monitoreo a través de Slack
Equipos de Desarrollo - Revisión de código, operaciones de Git y gestión de archivos
Equipos de Soporte - Consultas a bases de datos, verificación de estado del sistema y resolución de problemas
Uso General - Asistencia de IA con herramientas reales e integración de sistemas

Compatibilidad con MCP

Cumple con el Protocolo de Contexto de Modelos oficial (especificación 2025-06-18):

Todos los Métodos de Transporte - Protocolos HTTP, SSE y stdio
JSON-RPC 2.0 - Protocolo de comunicación estándar
Servidores MCP Oficiales - Compatible con todos los modelcontextprotocol/servers
Servidores MCP Personalizados - Funciona con cualquier servidor compatible con MCP
Estándares de Seguridad - Implementa consentimiento del usuario, privacidad de datos y requisitos de seguridad de herramientas

Autenticación en Servidores MCP SSE

La autenticación con servidores MCP de Eventos Enviados por el Servidor (SSE) se puede lograr utilizando la siguiente configuración:

Ejemplo:

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

Asegúrate de reemplazar YOUR_TOKEN_HERE con tu token real para la autenticación.

Cómo 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

Usuario interactúa a través de Slack, enviando mensajes que activan flujos de trabajo de IA inteligentes
Puente LLM-MCP sirve como la capa de orquestación inteligente que:
- Enruta solicitudes a los proveedores de LLM apropiados (OpenAI, Anthropic, Ollama)
- Elige entre Modo Agente (razonamiento de múltiples pasos) o Modo Estándar (respuesta única)
- Integra el sistema RAG para recuperación de conocimiento y mejora de contexto
- Gestiona el descubrimiento y ejecución de herramientas en múltiples servidores MCP
Sistema de Conocimiento y Memoria proporciona inteligencia contextual:
- Almacenamiento JSON simple para almacenamiento de documentos ligero
- Almacén de Vectores de OpenAI para búsqueda semántica y RAG de nivel empresarial
Ecosistema de Herramientas se conecta a diversos sistemas externos:
- Operaciones de sistema de archivos para gestión de archivos
- Integración de Git para interacciones con repositorios
- Gestión y monitoreo de clústeres de Kubernetes
- Herramientas personalizadas mediante protocolos HTTP, SSE o stdio
Infraestructura asegura un despliegue listo para producción:
- Configuración JSON unificada con soporte de variables de entorno
- Métricas de Prometheus para observabilidad y monitoreo
- Trazado de OpenTelemetry con proveedores Langfuse y OTLP
- Registro estructurado para depuración y análisis

Características

✅ Cliente MCP Multi-Modo:
- Eventos Enviados por el Servidor (SSE) para comunicación en tiempo real con reintento automático
- Transporte HTTP para JSON-RPC
- stdio para desarrollo y pruebas locales
✅ Integración de Slack:
- Utiliza el Modo Socket para comunicación segura y compatible con firewalls
- Funciona tanto con canales como con mensajes directos
- Formato de mensajes enriquecido con Markdown y Block Kit
- Seguimiento de conversaciones consciente de hilos con contexto separado por hilo
- Caché de contexto de usuario para interacciones personalizadas
- Comportamiento del bot y historial de mensajes personalizables
✅ Soporte Multi-Proveedor 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)
- Llamada de herramientas nativa y puerta de enlace unificada de LangChain
✅ Modo Agente:
- Agentes de IA autónomos impulsados por LangChain (langchaingo v0.1.14)
- Razonamiento de múltiples pasos mejorado y orquestación de herramientas
- Análisis mejorado para llamadas de herramientas complejas de múltiples líneas
- Iteraciones y comportamiento de agente configurables
- Respuestas de streaming confiables con correcciones de fugas de memoria
- Capacidades avanzadas de ingeniería de prompts
✅ RAG (Generación Aumentada por Recuperación):
- Múltiples proveedores: Almacenamiento JSON simple, Almacén de Vectores de OpenAI
- Almacenes de vectores reutilizables con soporte de vectorStoreId
- Parámetros de búsqueda y métricas de similitud configurables
- Ingestión de PDF con fragmentación inteligente
- Herramientas CLI para gestión de documentos
✅ Configuración Unificada:
- Archivo de configuración JSON único con validación de esquema JSON
- Configuración integral de tiempo de espera y reintentos
- Sustitución y anulación de variables de entorno
- Todas las opciones de paquetes subyacentes expuestas
- Valores predeterminados inteligentes con capacidad de personalización completa
- Nombres de herramientas con prefijo de servidor para prevenir conflictos de nombres
✅ Listo para Producción:
- Soporte de contenedores Docker con publicación GHCR
- Gráficos Helm de Kubernetes con registro OCI
- Registro y manejo de errores integrales
- Cobertura de pruebas con escaneo de seguridad
✅ Monitoreo y Observabilidad:
- Integración de métricas de Prometheus
- Seguimiento de invocación de herramientas con tasas de error
- Monitoreo de uso de tokens LLM por modelo y tipo
- Trazado de OpenTelemetry con proveedores Langfuse y simples
- Proveedores de observabilidad configurables con respaldos elegantes
- Seguimiento integral de spans para operaciones LLM y llamadas de herramientas
- Punto final de métricas y niveles de registro configurables

Instalación

Desde una Versión Binaria

Descarga el binario más reciente desde la página de versiones de GitHub o instala 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

Ejecución Local con Binario

Después de instalar el binario, puedes ejecutarlo localmente con los siguientes pasos:

Configura las variables de entorno:

# 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

Crea un archivo de configuración 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

Ejecuta la aplicación:

# 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

Migración desde Configuración Legada

Si tienes un archivo mcp-servers.json existente de una versión anterior, puedes migrar al nuevo formato de configuración unificada:

# 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

El nuevo formato de configuración proporciona:

Archivo Único: Todos los ajustes en un archivo config.json
Esquema JSON: Soporte de IDE con autocompletado y validación
Variables de Entorno: Usa la sintaxis ${VAR_NAME} para secretos
Valores Predeterminados Inteligentes: Configuración mínima requerida para uso básico
Opciones Integrales: Todos los ajustes de paquetes subyacentes expuestos

La aplicación se conectará a Slack y comenzará a escuchar mensajes. Puedes revisar los registros para detectar errores o problemas de conexión.

Configuración y Uso de RAG

El cliente incluye un sistema RAG (Generación Aumentada por Recuperación) mejorado que es compatible con LangChain Go y proporciona rendimiento de nivel profesional:

Inicio Rápido con RAG

Habilita RAG en tu configuración:

{
  "$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
      }
    }
  }
}

Ingesta 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

Uso en Slack:

Una vez configurado, el LLM puede buscar automáticamente en tu base de conocimiento:

Usuario: "¿Cuál es nuestra política de vacaciones?"

IA: "Déjame buscar en nuestra base de conocimiento información sobre la política de vacaciones..." (Busca automáticamente en la base de datos RAG)

IA: "Según los documentos de política de nuestra empresa, tienes 15 días de vacaciones..."

Características de RAG

🎯 Búsqueda Inteligente: Puntuación de relevancia avanzada con frecuencia de palabras, refuerzo de nombres de archivo y coincidencia de frases
🔗 Compatible con LangChain: Reemplazo directo para almacenes de vectores estándar
📈 Extensible: Fácil de agregar incrustaciones de vectores y otros backends

Prompts Personalizados y Asistentes

El cliente admite capacidades avanzadas de ingeniería de prompts para crear asistentes de IA especializados:

Prompts de Sistema

Crea personalidades y comportamientos 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 Basados en Configuración

Define prompts en tu configuración:

{
  "$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
      }
    }
  }
}

Roles de Asistente

Crea asistentes especializados para diferentes casos de uso:

Asistente de DevOps: Experiencia en Kubernetes, Docker, CI/CD
Asistente de Ventas: Calificación de clientes potenciales, manejo de objeciones
Asistente de RRHH: Preguntas de políticas, orientación de incorporación
Asistente de Soporte: Resolución de problemas de clientes
Asistente de Revisión de Código: Seguridad, rendimiento, mejores prácticas

Modo Agente

El Modo Agente permite conversaciones más interactivas y conscientes del contexto utilizando el marco de agentes de LangChain. En lugar de interacciones de un solo prompt, los agentes pueden participar en razonamiento de múltiples pasos, usar herramientas más estratégicamente y mantener mejor contexto a lo largo de las conversaciones.

Cómo Funciona el Modo Agente

El Modo Agente utiliza el marco de agente conversacional de LangChain para proporcionar:

Conversaciones Interactivas: Mantiene contexto a través de múltiples intercambios
Uso Estratégico de Herramientas: Los agentes deciden cuándo y cómo usar las herramientas disponibles
Razonamiento de Múltiples Pasos: Puede descomponer problemas complejos en pasos manejables
Respuestas de Streaming: Proporciona actualizaciones en tiempo real durante el procesamiento
Integración de Contexto de Usuario: Incorpora información de usuario en caché para respuestas personalizadas
Conciencia de Contexto de Hilos: Mantiene historial de conversación separado por hilo de Slack

Configuración del Modo Agente

Habilita el Modo Agente en tu archivo de configuración:

{
  "$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}"
      }
    }
  }
}

Opciones de Configuración

llm.useAgent: Habilita el modo agente (predeterminado: false)
llm.useNativeTools: Usa herramientas nativas de LangChain vs herramientas basadas en prompt de sistema (predeterminado: false)
llm.customPrompt: Prompt de sistema para el comportamiento del agente
llm.maxAgentIterations: Pasos máximos de razonamiento del agente (predeterminado: 20)

Modo Agente vs Modo Estándar

Modo Estándar:

Interacciones de un solo prompt
Herramientas descritas en el prompt de sistema como esquemas JSON
Análisis y ejecución directa de llamadas de herramientas
Uso de tokens más predecible
Flujo de conversación más simple

Modo Agente:

Interacciones conversacionales de múltiples turnos
Decisiones de uso de herramientas conscientes del contexto
Mejor integración de contexto de usuario
Flujo de conversación más natural
Capacidades de razonamiento mejoradas

Ejemplos del Modo Agente

Consulta de Desarrollo Interactiva:

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]

Resolución 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]

Mejores Prácticas del Modo Agente

Prompts de Sistema: Diseña prompts de sistema claros y específicos que guíen el comportamiento del agente
Selección de Herramientas: Proporciona herramientas relevantes para el dominio del agente
Gestión de Contexto: Los agentes mantienen mejor contexto a través de las conversaciones
Personalización de Usuario: Aprovecha la integración de contexto de usuario para respuestas personalizadas
Estrategia de Herramientas: Elige entre herramientas nativas o herramientas basadas en prompt de sistema según tus necesidades

Limitaciones y Consideraciones

Agente de OpenAI: El agente nativo de OpenAI en langchaingo tiene problemas conocidos, usa agente conversacional como solución alternativa
Dependencia de LangChain: El modo agente requiere el proveedor de LangChain
Permisos: Puede requerir permisos adicionales de Slack para la recuperación de información de usuario
Rendimiento: El modo agente puede tener características de rendimiento diferentes al modo estándar

Despliegue en Kubernetes con Helm

Para implementar en Kubernetes, hay un chart de Helm disponible en el directorio helm-chart. Este chart proporciona una forma flexible de implementar slack-mcp-client con la configuración adecuada y la gestión de secretos.

Instalación desde GitHub Container Registry

El chart de Helm también está disponible directamente desde GitHub Container Registry, lo que permite una instalación más sencilla sin necesidad de clonar el repositorio:

# 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

Puedes consultar las versiones disponibles visitando GitHub Container Registry en tu navegador.

Requisitos previos

Kubernetes 1.16+
Helm 3.0+
Tokens de Slack Bot y App

Instalación 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

Opciones de configuración

El chart de Helm admite varias opciones de configuración, incluyendo:

Establecer límites y solicitudes de recursos
Configurar servidores MCP mediante ConfigMap
Gestionar datos sensibles mediante secretos de Kubernetes
Personalizar los parámetros de implementación

Para más detalles, consulta el README del chart de Helm.

Uso de la imagen Docker desde GHCR

El chart de Helm utiliza la imagen Docker de GitHub Container Registry (GHCR) por defecto. Puedes especificar una versión concreta o usar la etiqueta latest:

# 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 extraer la imagen 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

Si usas imágenes privadas, puedes configurar los secretos de extracción de imágenes en tus valores:

imagePullSecrets:
  - name: my-ghcr-secret

Docker Compose para pruebas locales

Para pruebas y desarrollo locales, puedes usar Docker Compose para ejecutar fácilmente slack-mcp-client junto con servidores MCP adicionales.

Configuración

Crea un archivo .env con tus credenciales:

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

Crea un archivo mcp-servers.json (o usa el ejemplo):

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

Inicia los servicios:

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

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Configuración de Docker Compose

El docker-compose.yml incluido proporciona:

Variables de entorno cargadas desde el archivo .env
Montaje de volúmenes para la configuración del servidor MCP
Ejemplos de conexión a servidores MCP adicionales (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

Puedes ampliar fácilmente esta configuración para incluir servidores MCP adicionales en la misma red.

Configuración de la aplicación Slack

Crea una nueva aplicación Slack en https://api.slack.com/apps
Habilita el modo Socket y genera un token a nivel de aplicación
Marca Allow users to send Slash commands and messages from the chat tab en la página de inicio de la aplicación, para habilitar mensajes directos a la aplicación de Slack.
Añade los siguientes ámbitos de token de bot:
- app_mentions:read
- chat:write
- im:history
- im:read
- im:write
- users:read
- users.profile:read
- channels:history
- groups:history
- mpim:history
Habilita las suscripciones a eventos y suscríbete a:
- app_mention
- message.im
Instala la aplicación en tu espacio de trabajo

Para instrucciones detalladas sobre la configuración de la aplicación Slack, la configuración de tokens, los permisos necesarios y la resolución de problemas comunes, consulta la Guía de configuración de Slack.

Integración con LLM

El cliente admite múltiples proveedores de LLM mediante un sistema de integración flexible:

LangChain Gateway

La puerta de enlace de LangChain permite una integración perfecta con varios proveedores de LLM:

OpenAI: Soporte nativo para modelos GPT (por defecto)
Ollama: Soporte de LLM local para modelos como Llama, Mistral, etc.
Extensible: Se puede ampliar para admitir otros proveedores compatibles con LangChain

Puente LLM-MCP

La capa de puente LLM-MCP personalizada permite que cualquier LLM use herramientas MCP sin necesidad de capacidades nativas de llamada a funciones:

Compatibilidad universal: Funciona con cualquier LLM, incluidos aquellos sin llamada a funciones
Reconocimiento de patrones: Detecta cuándo una solicitud de usuario o respuesta de LLM debe activar una llamada a herramienta
Soporte de lenguaje natural: Comprende tanto llamadas a herramientas JSON estructuradas como solicitudes en lenguaje natural

Configuración

Los proveedores de LLM se pueden configurar mediante variables de entorno o banderas de línea de comandos:

# 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

Cambio entre proveedores

Puedes cambiar fácilmente entre proveedores modificando la variable de entorno LLM_PROVIDER:

# Use OpenAI
export LLM_PROVIDER=openai

# Use Anthropic
export LLM_PROVIDER=anthropic

# Use Ollama (local)
export LLM_PROVIDER=ollama

Configuración

El cliente utiliza dos enfoques principales de configuración:

Variables de entorno

Configura los proveedores de LLM y la integración con Slack mediante variables de entorno:

Variable	Descripción	Predeterminado
SLACK_BOT_TOKEN	Token de bot para la API de Slack	(obligatorio)
SLACK_APP_TOKEN	Token a nivel de aplicación para el modo Socket	(obligatorio)
OPENAI_API_KEY	Clave API para la autenticación de OpenAI	(obligatorio)
OPENAI_MODEL	Modelo de OpenAI a usar	gpt-4.1
ANTHROPIC_API_KEY	Clave API para la autenticación de Anthropic	(obligatorio para Anthropic)
ANTHROPIC_MODEL	Modelo de Anthropic a usar	claude-sonnet-4.5
LOG_LEVEL	Nivel de registro (debug, info, warn, error)	info
LLM_PROVIDER	Proveedor de LLM a usar (openai, anthropic, ollama)	openai
LANGCHAIN_OLLAMA_URL	URL para Ollama al usar LangChain	http://localhost:11434
LANGCHAIN_OLLAMA_MODEL	Nombre del modelo para Ollama al usar LangChain	llama3.3
LANGFUSE_ENDPOINT	Endpoint de API de Langfuse para observabilidad	(opcional)
LANGFUSE_PUBLIC_KEY	Clave pública de Langfuse para autenticación	(opcional)
LANGFUSE_SECRET_KEY	Clave secreta de Langfuse para autenticación	(opcional)
OTEL_EXPORTER_OTLP_ENDPOINT	Endpoint OTLP para trazado simple	(opcional)

Configuración de monitoreo y observabilidad

El cliente incluye capacidades integrales de monitoreo con métricas y trazado distribuido:

Métricas de Prometheus

Endpoint de métricas: Accesible en /metrics en el puerto configurado
Puerto predeterminado: 8080 (configurable mediante la bandera --metrics-port)
Métricas disponibles:
- slackmcp_tool_invocations_total: Contador de invocaciones de herramientas con etiquetas para nombre de herramienta, servidor y estado de error
- slackmcp_llm_tokens: Histograma para el uso de tokens de LLM por tipo y modelo

Trazado de OpenTelemetry

Proveedores compatibles:
- simple-otel: Trazado básico de OpenTelemetry a endpoints OTLP (requiere configuración de endpoint)
- langfuse-otel: Observabilidad avanzada de LLM con integración de Langfuse (requiere endpoint y autenticación)
- disabled: Sin trazado (predeterminado cuando no se configura ningún endpoint)
Alternativas automáticas: Los proveedores fallidos pasan automáticamente al estado deshabilitado
Seguimiento integral: Spans para operaciones de LLM, llamadas a herramientas e interacciones de usuario con atributos detallados

Ejemplo de configuración y 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 configuración unificado

Toda la configuración ahora se gestiona mediante un único archivo config.json con opciones integrales:

{
  "$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 opciones de configuración detalladas y guías de migración, consulta la Guía de configuración.

Función de recarga automática

El cliente admite la recarga automática opcional para manejar reinicios del servidor MCP sin tiempo de inactividad, perfecto para implementaciones de Kubernetes donde los servidores MCP pueden reiniciarse de forma independiente.

Nota: La función de recarga está deshabilitada por defecto y debe habilitarse explícitamente en tu archivo de configuración.

Configuración

Para habilitar la funcionalidad de recarga, añade la configuración de recarga a tu config.json:

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

Opciones de configuración:

enabled: Debe establecerse en true para activar la funcionalidad de recarga (predeterminado: false)
interval: Tiempo entre recargas automáticas (predeterminado: "30m", mínimo: "10s")

Uso

Recarga automática: Cuando está habilitada, la aplicación se recarga automáticamente en el intervalo configurado para reconectarse a los servidores MCP y actualizar el descubrimiento de herramientas.

Recarga manual: Incluso con la recarga automática deshabilitada, puedes activar recargas manuales mediante señales:

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

# Local process
kill -USR1 <process-id>

Beneficios

Cero tiempo de inactividad: La aplicación permanece en ejecución durante la recarga
Amigable con Kubernetes: El pod continúa ejecutándose mientras los componentes de la aplicación se reinician
Opt-in: Deshabilitada por defecto, solo se habilita cuando se configura explícitamente
Flexible: Tanto disparadores automáticos (periódicos) como manuales (señales)
Seguro: La validación del intervalo mínimo evita recargas excesivas

Cuando está habilitada, la función de recarga automáticamente:

Se reconecta a todos los servidores MCP configurados
Redescubre las herramientas disponibles
Actualiza la configuración
Mantiene la conexión de Slack durante todo el proceso

Perfecta para entornos de producción donde los servidores MCP pueden reiniciarse debido a actualizaciones, escalado o mantenimiento.

Salida con formato de Slack

El cliente incluye un sistema integral de salida con formato de Slack que mejora la visualización de mensajes en Slack:

Detección automática de formato: Detecta automáticamente el tipo de mensaje (texto plano, markdown, JSON Block Kit, datos estructurados) y aplica el formato adecuado
Formato Markdown: Admite la sintaxis mrkdwn de Slack con conversión automática desde Markdown estándar
- Convierte **bold** a *bold* para un formato de negrita adecuado en Slack
- Conserva código en línea, citas en bloque, listas y otros elementos de formato
Mejora de cadenas entre comillas: Convierte automáticamente cadenas entre comillas dobles a bloques de código en línea para una mejor visualización
- Ejemplo: "namespace-name" se convierte en `namespace-name` en Slack
- Mejora la legibilidad de IDs, marcas de tiempo y otros valores entre comillas
Integración con Block Kit: Convierte datos estructurados a diseños de Block Kit para una mejor presentación visual
- Valida automáticamente contra los límites de la API de Slack
- Vuelve a texto plano si la validación de Block Kit falla

Para más detalles, consulta la Guía de formato de Slack.

Modos de transporte

El cliente admite tres modos de transporte:

SSE (predeterminado): Usa Server-Sent Events para comunicación en tiempo real con el servidor MCP, incluye lógica de reintento automático para mayor fiabilidad
HTTP: Usa solicitudes HTTP POST con JSON-RPC para la comunicación
stdio: Usa entrada/salida estándar para desarrollo y pruebas locales

Documentación

Hay documentación integral disponible en el directorio docs/:

Configuración y puesta en marcha

Guía de configuración de Slack - Guía completa para configurar tu aplicación de Slack, incluidos permisos necesarios, tokens y resolución de problemas comunes

Desarrollo e implementación

Notas de implementación - Documentación técnica detallada que cubre la arquitectura actual, componentes principales y detalles de implementación
Especificación de requisitos - Documentación integral de requisitos que incluye funciones implementadas, requisitos de calidad y mejoras futuras

Guías de usuario

Guía de formato de Slack - Guía completa de formato de mensajes que incluye conversión de Markdown a Slack, diseños de Block Kit y detección automática de formato
Guía de implementación de RAG - Guía detallada para el sistema RAG mejorado con compatibilidad con LangChain Go y optimizaciones de rendimiento
Implementación de RAG SQLite - Plan de implementación para la integración nativa de SQLite en Go con experiencia de carga similar a ChatGPT
Guía de pruebas - Documentación integral de pruebas que cubre pruebas unitarias, pruebas de integración, procedimientos de prueba manuales y depuración

Enlaces rápidos

Configuración: Comience con la Guía de configuración de Slack para la configuración inicial
Modo agente: Consulte la sección Modo agente anterior para agentes de IA autónomos con encadenamiento de herramientas
RAG: Consulte la Guía de implementación de RAG para la integración de la base de conocimiento de documentos
Formato: Consulte la Guía de formato de Slack para las capacidades de formato de mensajes
RAG SQLite: Consulte la Implementación de RAG SQLite para la implementación nativa en Go con UX de carga moderna
Desarrollo: Consulte las Notas de implementación para detalles técnicos
Pruebas: Utilice la Guía de pruebas para procedimientos de prueba y depuración
Monitoreo: Consulte la sección de configuración de métricas anterior para la integración con Prometheus
Dependencias: Revise Dependencias para el seguimiento de versiones y el historial de actualizaciones

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar un Pull Request.

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para obtener más detalles.

CI/CD y lanzamientos

Este proyecto utiliza GitHub Actions para la integración continua y GoReleaser para lanzamientos automatizados.

Comprobaciones de integración continua

Nuestro pipeline de CI realiza las siguientes comprobaciones en todos los PR y confirmaciones (commits) a la rama principal:

Calidad del código

Linting: Uso de golangci-lint para verificar problemas comunes de código y violaciones de estilo
Verificación de módulos de Go: Asegurar que go.mod y go.sum se mantengan correctamente
Formato: Verificar que el código esté correctamente formateado con gofmt

Seguridad

Escaneo de vulnerabilidades: Uso de govulncheck para verificar vulnerabilidades conocidas en dependencias
Escaneo de dependencias: Uso de Trivy para escanear vulnerabilidades en dependencias
Generación de SBOM: Creación de una lista de materiales de software (SBOM) para el seguimiento de dependencias

Pruebas

Pruebas unitarias: Ejecución de pruebas con detección de condiciones de carrera y reporte de cobertura de código
Verificación de compilación: Asegurar que el código se compile correctamente

Proceso de lanzamiento

Cuando los cambios se fusionan en la rama principal:

Se ejecutan comprobaciones de CI para validar la calidad y seguridad del código
Si tienen éxito, se crea automáticamente un nuevo lanzamiento con:
- Versionado semántico basado en mensajes de confirmación
- Compilaciones binarias para múltiples plataformas
- Publicación de imágenes Docker en GitHub Container Registry
- Publicación de gráficos Helm en GitHub Container Registry