Content
# Slack MCP Client
**A production-ready bridge between Slack and AI models with full MCP compatibility.**
This client enables AI models (OpenAI GPT-4.1, Anthropic Claude 4.5, Ollama local models) to interact with real tools and systems through Slack conversations. Built on the industry-standard Model Context Protocol (MCP), it provides secure access to filesystems, databases, Kubernetes clusters, Git repositories, and custom tools.
[](https://github.com/tuannvm/slack-mcp-client/actions/workflows/build.yml)
[](https://github.com/tuannvm/slack-mcp-client/blob/main/go.mod)
[](https://github.com/tuannvm/slack-mcp-client/actions/workflows/build.yml)
[](https://github.com/tuannvm/slack-mcp-client/pkgs/container/slack-mcp-client)
[](https://github.com/tuannvm/slack-mcp-client/releases/latest)
[](https://opensource.org/licenses/MIT)
> **Compatible with MCP Specification 2025-06-18** - Compliant with the latest Model Context Protocol standards
## Recent Updates
**Oct 2025**: langchaingo v0.1.14 with streaming fixes, enhanced agent parsing, and API key sanitization.
## Key Features
- **Universal MCP Compatibility** - Supports all transport methods (HTTP, SSE, stdio)
- **Multi-Provider LLM Support** - OpenAI GPT-4.1/4o, Anthropic Claude 4.5, Ollama (Llama 3.3, Qwen, Mistral, DeepSeek)
- **Agent Mode** - Multi-step reasoning with LangChain for complex workflows
- **RAG Integration** - Knowledge base with semantic search capabilities
- **Thread-Aware Context** - Maintains separate conversation history per Slack thread
- **User Context Integration** - Personalized responses with cached user information
- **Unique Tool Naming** - Server-prefixed tool names prevent conflicts across MCP servers
- **Production Ready** - Comprehensive configuration, monitoring, and security
## Use Cases
- **DevOps Teams** - Infrastructure automation and monitoring through Slack
- **Development Teams** - Code review, Git operations, and file management
- **Support Teams** - Database queries, system status checks, and troubleshooting
- **General Use** - AI assistance with actual tools and system integration
## MCP Compatibility
**Compliant with the official Model Context Protocol (2025-06-18 specification):**
- **All Transport Methods** - HTTP, SSE, and stdio protocols
- **JSON-RPC 2.0** - Standard communication protocol
- **Official MCP Servers** - Compatible with all [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
- **Custom MCP Servers** - Works with any MCP-compliant server
- **Security Standards** - Implements user consent, data privacy, and tool safety requirements
## Authenticating to SSE MCP Servers
Authentication with Server-Sent Events (SSE) MCP servers can be achieved using the following setup:
Example:
```json
{
"httpHeaders": {
"Authorization": "Bearer YOUR_TOKEN_HERE"
}
}
```
Make sure to replace `YOUR_TOKEN_HERE` with your actual token for authentication.
## How It Works
```mermaid
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
```
1. **User** interacts through Slack, sending messages that trigger intelligent AI workflows
2. **LLM-MCP Bridge** serves as the intelligent orchestration layer that:
- Routes requests to appropriate LLM providers (OpenAI, Anthropic, Ollama)
- Chooses between Agent Mode (multi-step reasoning) or Standard Mode (single response)
- Integrates RAG system for knowledge retrieval and context enhancement
- Manages tool discovery and execution across multiple MCP servers
3. **Knowledge & Memory** system provides contextual intelligence:
- Simple JSON store for lightweight document storage
- OpenAI Vector Store for semantic search and enterprise-grade RAG
4. **Tool Ecosystem** connects to diverse external systems:
- Filesystem operations for file management
- Git integration for repository interactions
- Kubernetes cluster management and monitoring
- Custom tools via HTTP, SSE, or stdio protocols
5. **Infrastructure** ensures production-ready deployment:
- Unified JSON configuration with environment variable support
- Prometheus metrics for observability and monitoring
- OpenTelemetry tracing with Langfuse and OTLP providers
- Structured logging for debugging and analytics
## Features
- ✅ **Multi-Mode MCP Client**:
- Server-Sent Events (SSE) for real-time communication with automatic retry
- HTTP transport for JSON-RPC
- stdio for local development and testing
- ✅ **Slack Integration**:
- Uses Socket Mode for secure, firewall-friendly communication
- Works with both channels and direct messages
- Rich message formatting with Markdown and Block Kit
- Thread-aware conversation tracking with separate context per thread
- User context caching for personalized interactions
- Customizable bot behavior and message history
- ✅ **Multi-Provider LLM Support**:
- OpenAI (GPT-4.1, GPT-4o, o3-pro)
- Anthropic (Claude Sonnet 4.5, Opus 4.1)
- Ollama (Llama 3.3, Qwen2.5, Mistral, DeepSeek)
- Native tool calling and unified LangChain gateway
- ✅ **Agent Mode**:
- Autonomous AI agents powered by LangChain (langchaingo v0.1.14)
- Enhanced multi-step reasoning and tool orchestration
- Improved parsing for complex multi-line tool calls
- Configurable agent iterations and behavior
- Reliable streaming responses with memory leak fixes
- Advanced prompt engineering capabilities
- ✅ **RAG (Retrieval-Augmented Generation)**:
- Multiple providers: Simple JSON storage, OpenAI Vector Store
- Reusable vector stores with `vectorStoreId` support
- Configurable search parameters and similarity metrics
- PDF ingestion with intelligent chunking
- CLI tools for document management
- ✅ **Unified Configuration**:
- Single JSON configuration file with JSON schema validation
- Comprehensive timeout and retry configuration
- Environment variable substitution and overrides
- All underlying package options exposed
- Smart defaults with full customization capability
- Server-prefixed tool names to prevent naming conflicts
- ✅ **Production Ready**:
- Docker container support with GHCR publishing
- Kubernetes Helm charts with OCI registry
- Comprehensive logging and error handling
- Test coverage with security scanning
- ✅ **Monitoring & Observability**:
- Prometheus metrics integration
- Tool invocation tracking with error rates
- LLM token usage monitoring by model and type
- OpenTelemetry tracing with Langfuse and simple providers
- Configurable observability providers with graceful fallbacks
- Comprehensive span tracking for LLM operations and tool calls
- Configurable metrics endpoint and logging levels
## Installation
### From Binary Release
Download the latest binary from the [GitHub releases page](https://github.com/tuannvm/slack-mcp-client/releases/latest) or install using Go:
```bash
# 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
```
### Running Locally with Binary
After installing the binary, you can run it locally with the following steps:
1. Set up environment variables:
```bash
# 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
```
2. Create a unified configuration file:
```bash
# 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
```
3. Run the application:
```bash
# 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
```
### Migrating from Legacy Configuration
If you have an existing `mcp-servers.json` file from a previous version, you can migrate to the new unified configuration format:
```bash
# 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
```
The new configuration format provides:
- **Single File**: All settings in one `config.json` file
- **JSON Schema**: IDE support with autocomplete and validation
- **Environment Variables**: Use `${VAR_NAME}` syntax for secrets
- **Smart Defaults**: Minimal configuration required for basic usage
- **Comprehensive Options**: All underlying package settings exposed
The application will connect to Slack and start listening for messages. You can check the logs for any errors or connection issues.
### RAG Setup and Usage
The client includes an improved RAG (Retrieval-Augmented Generation) system that's compatible with LangChain Go and provides professional-grade performance:
#### Quick Start with RAG
1. **Enable RAG in your configuration:**
```json
{
"$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
}
}
}
}
```
2. **Ingest documents using CLI:**
```bash
# 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
```
3. **Use in Slack:**
Once configured, the LLM can automatically search your knowledge base:
**User**: "What's our vacation policy?"
**AI**: "Let me search our knowledge base for vacation policy information..."
*(Automatically searches RAG database)*
**AI**: "Based on our company policy documents, you get 15 days of vacation..."
#### RAG Features
- **🎯 Smart Search**: Advanced relevance scoring with word frequency, filename boosting, and phrase matching
- **🔗 LangChain Compatible**: Drop-in replacement for standard vector stores
- **📈 Extensible**: Easy to add vector embeddings and other backends
### Custom Prompts and Assistants
The client supports advanced prompt engineering capabilities for creating specialized AI assistants:
#### System Prompts
Create custom AI personalities and behaviors:
```bash
# 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
```
#### Configuration-Based Prompts
Define prompts in your configuration:
```json
{
"$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
}
}
}
}
```
#### Assistant Roles
Create specialized assistants for different use cases:
- **DevOps Assistant**: Kubernetes, Docker, CI/CD expertise
- **Sales Assistant**: Lead qualification, objection handling
- **HR Assistant**: Policy questions, onboarding guidance
- **Support Assistant**: Customer issue resolution
- **Code Review Assistant**: Security, performance, best practices
### Agent Mode
Agent Mode enables more interactive and context-aware conversations using LangChain's agent framework. Instead of single-prompt interactions, agents can engage in multi-step reasoning, use tools more strategically, and maintain better context throughout conversations.
#### How Agent Mode Works
Agent Mode uses LangChain's conversational agent framework to provide:
1. **Interactive Conversations**: Maintains context across multiple exchanges
2. **Strategic Tool Usage**: Agents decide when and how to use available tools
3. **Multi-Step Reasoning**: Can break down complex problems into manageable steps
4. **Streaming Responses**: Provides real-time updates during processing
5. **User Context Integration**: Incorporates cached user information for personalized responses
6. **Thread Context Awareness**: Maintains separate conversation history per Slack thread
#### Agent Mode Configuration
Enable Agent Mode in your configuration file:
```json
{
"$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}"
}
}
}
}
```
#### Configuration Options
- **`llm.useAgent`**: Enable agent mode (default: false)
- **`llm.useNativeTools`**: Use native LangChain tools vs system prompt-based tools (default: false)
- **`llm.customPrompt`**: System prompt for agent behavior
- **`llm.maxAgentIterations`**: Maximum agent reasoning steps (default: 20)
#### Agent vs Standard Mode
**Standard Mode**:
- Single-prompt interactions
- Tools described in system prompt as JSON schemas
- Direct tool call parsing and execution
- More predictable token usage
- Simpler conversation flow
**Agent Mode**:
- Multi-turn conversational interactions
- Context-aware tool usage decisions
- Better user context integration
- More natural conversation flow
- Enhanced reasoning capabilities
#### Agent Mode Examples
**Interactive Development Consultation**:
```
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]
```
**Contextual Problem Solving**:
```
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]
```
#### Agent Mode Best Practices
1. **System Prompts**: Design clear, specific system prompts that guide the agent's behavior
2. **Tool Selection**: Provide relevant tools for the agent's domain
3. **Context Management**: Agents maintain better context across conversations
4. **User Personalization**: Leverage user context integration for personalized responses
5. **Tool Strategy**: Choose between native tools or system prompt-based tools based on your needs
#### Limitations and Considerations
- **OpenAI Agent**: Native OpenAI agent in langchaingo has known issues, uses conversational agent as workaround
- **LangChain Dependency**: Agent mode requires LangChain provider
- **Permissions**: May require additional Slack permissions for user information retrieval
- **Performance**: Agent mode may have different performance characteristics than standard mode
### Kubernetes Deployment with Helm
For deploying to Kubernetes, a Helm chart is available in the `helm-chart` directory. This chart provides a flexible way to deploy the slack-mcp-client with proper configuration and secret management.
#### Installing from GitHub Container Registry
The Helm chart is also available directly from GitHub Container Registry, allowing for easier installation without needing to clone the repository:
```bash
# 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
```
You can check available versions by visiting the GitHub Container Registry in your browser.
#### Prerequisites
- Kubernetes 1.16+
- Helm 3.0+
- Slack Bot and App tokens
#### Basic Installation
```bash
# 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
```
#### Configuration Options
The Helm chart supports various configuration options including:
- Setting resource limits and requests
- Configuring MCP servers via ConfigMap
- Managing sensitive data via Kubernetes secrets
- Customizing deployment parameters
For more details, see the [Helm chart README](helm-chart/slack-mcp-client/README.md).
#### Using the Docker Image from GHCR
The Helm chart uses the Docker image from GitHub Container Registry (GHCR) by default. You can specify a particular version or use the latest tag:
```yaml
# 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
```
To manually pull the image:
```bash
# 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
```
If you're using private images, you can configure image pull secrets in your values:
```yaml
imagePullSecrets:
- name: my-ghcr-secret
```
### Docker Compose for Local Testing
For local testing and development, you can use Docker Compose to easily run the slack-mcp-client along with additional MCP servers.
#### Setup
1. Create a `.env` file with your credentials:
```bash
# Create .env file from example
cp .env.example .env
# Edit the file with your credentials
nano .env
```
2. Create a `mcp-servers.json` file (or use the example):
```bash
# Create mcp-servers.json from example
cp mcp-servers.json.example mcp-servers.json
# Edit if needed
nano mcp-servers.json
```
3. Start the services:
```bash
# Start services in detached mode
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down
```
#### Docker Compose Configuration
The included `docker-compose.yml` provides:
- Environment variables loaded from `.env` file
- Volume mounting for MCP server configuration
- Examples of connecting to additional MCP servers (commented out)
```yaml
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
```
You can easily extend this setup to include additional MCP servers in the same network.
## Slack App Setup
1. Create a new Slack app at https://api.slack.com/apps
2. Enable Socket Mode and generate an app-level token
3. Check `Allow users to send Slash commands and messages from the chat tab` in App Home page, to enable direct message to Slack app.
4. Add the following 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`
5. Enable Event Subscriptions and subscribe to:
- `app_mention`
- `message.im`
6. Install the app to your workspace
For detailed instructions on Slack app configuration, token setup, required permissions, and troubleshooting common issues, see the [Slack Configuration Guide](docs/configuration.md).
## LLM Integration
The client supports multiple LLM providers through a flexible integration system:
### LangChain Gateway
The LangChain gateway enables seamless integration with various LLM providers:
- **OpenAI**: Native support for GPT models (default)
- **Ollama**: Local LLM support for models like Llama, Mistral, etc.
- **Extensible**: Can be extended to support other LangChain-compatible providers
### LLM-MCP Bridge
The custom LLM-MCP bridge layer enables any LLM to use MCP tools without requiring native function-calling capabilities:
- **Universal Compatibility**: Works with any LLM, including those without function-calling
- **Pattern Recognition**: Detects when a user prompt or LLM response should trigger a tool call
- **Natural Language Support**: Understands both structured JSON tool calls and natural language requests
### Configuration
LLM providers can be configured via environment variables or command-line flags:
```bash
# 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
```
### Switching Between Providers
You can easily switch between providers by changing the `LLM_PROVIDER` environment variable:
```bash
# Use OpenAI
export LLM_PROVIDER=openai
# Use Anthropic
export LLM_PROVIDER=anthropic
# Use Ollama (local)
export LLM_PROVIDER=ollama
```
## Configuration
The client uses two main configuration approaches:
### Environment Variables
Configure LLM providers and Slack integration using environment variables:
| Variable | Description | Default |
| --------------------- | -------------------------------------------- | ---------- |
| SLACK_BOT_TOKEN | Bot token for Slack API | (required) |
| SLACK_APP_TOKEN | App-level token for Socket Mode | (required) |
| OPENAI_API_KEY | API key for OpenAI authentication | (required) |
| OPENAI_MODEL | OpenAI model to use | gpt-4.1 |
| ANTHROPIC_API_KEY | API key for Anthropic authentication | (required for Anthropic) |
| ANTHROPIC_MODEL | Anthropic model to use | claude-sonnet-4.5 |
| LOG_LEVEL | Logging level (debug, info, warn, error) | info |
| LLM_PROVIDER | LLM provider to use (openai, anthropic, ollama) | openai |
| LANGCHAIN_OLLAMA_URL | URL for Ollama when using LangChain | http://localhost:11434 |
| LANGCHAIN_OLLAMA_MODEL| Model name for Ollama when using LangChain | llama3.3 |
| LANGFUSE_ENDPOINT | Langfuse API endpoint for observability | (optional) |
| LANGFUSE_PUBLIC_KEY | Langfuse public key for authentication | (optional) |
| LANGFUSE_SECRET_KEY | Langfuse secret key for authentication | (optional) |
| OTEL_EXPORTER_OTLP_ENDPOINT | OTLP endpoint for simple tracing | (optional) |
### Monitoring & Observability Configuration
The client includes comprehensive monitoring capabilities with both metrics and distributed tracing:
#### Prometheus Metrics
- **Metrics Endpoint**: Accessible at `/metrics` on the configured port
- **Default Port**: 8080 (configurable via `--metrics-port` flag)
- **Metrics Available**:
- `slackmcp_tool_invocations_total`: Counter for tool invocations with labels for tool name, server, and error status
- `slackmcp_llm_tokens`: Histogram for LLM token usage by type and model
#### OpenTelemetry Tracing
- **Supported Providers**:
- `simple-otel`: Basic OpenTelemetry tracing to OTLP endpoints (requires endpoint configuration)
- `langfuse-otel`: Advanced LLM observability with Langfuse integration (requires endpoint and auth)
- `disabled`: No tracing (default when no endpoint configured)
- **Automatic Fallbacks**: Failed providers automatically fall back to disabled state
- **Comprehensive Tracking**: Spans for LLM operations, tool calls, and user interactions with detailed attributes
Example configuration and usage:
```bash
# 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"
```
### Unified Configuration Format
All configuration is now managed through a single `config.json` file with comprehensive options:
```json
{
"$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"
}
}
```
For detailed configuration options and migration guides, see the [Configuration Guide](docs/configuration.md).
## Automatic Reload Feature
The client supports optional automatic reloading to handle MCP server restarts without downtime - perfect for Kubernetes deployments where MCP servers may restart independently.
> **Note**: The reload feature is **disabled by default** and must be explicitly enabled in your configuration file.
### Configuration
To enable reload functionality, add reload settings to your `config.json`:
```json
{
"version": "2.0",
"reload": {
"enabled": true,
"interval": "30m"
}
}
```
**Configuration Options**:
- `enabled`: Must be set to `true` to activate reload functionality (default: `false`)
- `interval`: Time between automatic reloads (default: `"30m"`, minimum: `"10s"`)
### Usage
**Automatic Reload**: When enabled, the application automatically reloads at the configured interval to reconnect to MCP servers and refresh tool discovery.
**Manual Reload**: Even with automatic reload disabled, you can trigger manual reloads using signals:
```bash
# In Kubernetes
kubectl exec -it <pod-name> -- kill -USR1 1
# Local process
kill -USR1 <process-id>
```
### Benefits
- **Zero Downtime**: Application stays running during reload
- **Kubernetes-Friendly**: Pod continues running while application components restart
- **Opt-in**: Disabled by default, only enabled when explicitly configured
- **Flexible**: Both automatic (periodic) and manual (signal) triggers
- **Safe**: Minimum interval validation prevents excessive reloading
When enabled, the reload feature automatically:
- Reconnects to all configured MCP servers
- Rediscovers available tools
- Refreshes configuration settings
- Maintains Slack connection throughout the process
Perfect for production environments where MCP servers may restart due to updates, scaling, or maintenance.
## Slack-Formatted Output
The client includes a comprehensive Slack-formatted output system that enhances message display in Slack:
- **Automatic Format Detection**: Automatically detects message type (plain text, markdown, JSON Block Kit, structured data) and applies appropriate formatting
- **Markdown Formatting**: Supports Slack's mrkdwn syntax with automatic conversion from standard Markdown
- Converts `**bold**` to `*bold*` for proper Slack bold formatting
- Preserves inline code, block quotes, lists, and other formatting elements
- **Quoted String Enhancement**: Automatically converts double-quoted strings to inline code blocks for better visualization
- Example: `"namespace-name"` becomes `` `namespace-name` `` in Slack
- Improves readability of IDs, timestamps, and other quoted values
- **Block Kit Integration**: Converts structured data to Block Kit layouts for better visual presentation
- Automatically validates against Slack API limits
- Falls back to plain text if Block Kit validation fails
For more details, see the [Slack Formatting Guide](docs/format.md).
## Transport Modes
The client supports three transport modes:
- **SSE (default)**: Uses Server-Sent Events for real-time communication with the MCP server, includes automatic retry logic for enhanced reliability
- **HTTP**: Uses HTTP POST requests with JSON-RPC for communication
- **stdio**: Uses standard input/output for local development and testing
## Documentation
Comprehensive documentation is available in the `docs/` directory:
### Configuration & Setup
- **[Slack Configuration Guide](docs/configuration.md)** - Complete guide for setting up your Slack app, including required permissions, tokens, and troubleshooting common issues
### Development & Implementation
- **[Implementation Notes](docs/implementation.md)** - Detailed technical documentation covering the current architecture, core components, and implementation details
- **[Requirements Specification](docs/requirements.md)** - Comprehensive requirements documentation including implemented features, quality requirements, and future enhancements
### User Guides
- **[Slack Formatting Guide](docs/format.md)** - Complete guide to message formatting including Markdown-to-Slack conversion, Block Kit layouts, and automatic format detection
- **[RAG Implementation Guide](docs/rag-json.md)** - Detailed guide for the improved RAG system with LangChain Go compatibility and performance optimizations
- **[RAG SQLite Implementation](docs/rag-sqlite.md)** - Implementation plan for native Go SQLite integration with ChatGPT-like upload experience
- **[Testing Guide](docs/test.md)** - Comprehensive testing documentation covering unit tests, integration tests, manual testing procedures, and debugging
### Quick Links
- **Setup**: Start with the [Slack Configuration Guide](docs/configuration.md) for initial setup
- **Agent Mode**: See the Agent Mode section above for autonomous AI agents with tool chaining
- **RAG**: Check the [RAG Implementation Guide](docs/rag-json.md) for document knowledge base integration
- **Formatting**: See the [Slack Formatting Guide](docs/format.md) for message formatting capabilities
- **RAG SQLite**: See the [RAG SQLite Implementation](docs/rag-sqlite.md) for native Go implementation with modern upload UX
- **Development**: Check the [Implementation Notes](docs/implementation.md) for technical details
- **Testing**: Use the [Testing Guide](docs/test.md) for testing procedures and debugging
- **Monitoring**: See the metrics configuration section above for Prometheus integration
- **Dependencies**: Review [Dependencies](docs/DEPENDENCIES.md) for version tracking and upgrade history
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## CI/CD and Releases
This project uses GitHub Actions for continuous integration and GoReleaser for automated releases.
### Continuous Integration Checks
Our CI pipeline performs the following checks on all PRs and commits to the main branch:
#### Code Quality
- **Linting**: Using golangci-lint to check for common code issues and style violations
- **Go Module Verification**: Ensuring go.mod and go.sum are properly maintained
- **Formatting**: Verifying code is properly formatted with gofmt
#### Security
- **Vulnerability Scanning**: Using govulncheck to check for known vulnerabilities in dependencies
- **Dependency Scanning**: Using Trivy to scan for vulnerabilities in dependencies
- **SBOM Generation**: Creating a Software Bill of Materials for dependency tracking
#### Testing
- **Unit Tests**: Running tests with race detection and code coverage reporting
- **Build Verification**: Ensuring the codebase builds successfully
### Release Process
When changes are merged to the main branch:
1. CI checks are run to validate code quality and security
2. If successful, a new release is automatically created with:
- Semantic versioning based on commit messages
- Binary builds for multiple platforms
- Docker image publishing to GitHub Container Registry
- Helm chart publishing to GitHub Container Registry
