SLACK MCP CLIENT

Slack MCP 客户端

连接 Slack 与 AI 模型的生产就绪桥梁，全面兼容 MCP。

此客户端可让 AI 模型（OpenAI GPT-4.1、Anthropic Claude 4.5、Ollama 本地模型）通过 Slack 对话与真实工具和系统交互。它基于行业标准的 Model Context Protocol（MCP）构建，可安全访问文件系统、数据库、Kubernetes 集群、Git 仓库和自定义工具。

兼容 MCP Specification 2025-06-18——符合最新的 Model Context Protocol 标准

最近更新

2025 年 10 月：langchaingo v0.1.14，修复流式处理问题、增强 Agent 解析并完善 API 密钥清理。

主要功能

• 通用 MCP 兼容性——支持所有传输方式（HTTP、SSE、stdio）
• 多提供商 LLM 支持——OpenAI GPT-4.1/4o、Anthropic Claude 4.5、Ollama（Llama 3.3、Qwen、Mistral、DeepSeek）
• Agent 模式——借助 LangChain 进行多步推理，处理复杂工作流
• RAG 集成——支持语义搜索的知识库
• 感知线程的上下文——为每个 Slack 线程维护独立的对话历史
• 用户上下文集成——利用缓存的用户信息提供个性化回复
• 唯一工具命名——工具名称加上服务前缀，避免不同 MCP 服务之间发生冲突
• 生产就绪——提供全面的配置、监控和安全保障

使用场景

• DevOps 团队——通过 Slack 实现基础设施自动化和监控
• 开发团队——代码审查、Git 操作和文件管理
• 支持团队——数据库查询、系统状态检查和故障排查
• 一般用途——借助实际工具和系统集成获取 AI 协助

MCP 兼容性

符合官方 Model Context Protocol（2025-06-18 规范）：

• 所有传输方式——HTTP、SSE 和 stdio 协议
• JSON-RPC 2.0——标准通信协议
• 官方 MCP 服务——兼容所有 modelcontextprotocol/servers
• 自定义 MCP 服务——可与任何符合 MCP 标准的服务配合使用
• 安全标准——落实用户同意、数据隐私和工具安全要求

验证 SSE MCP 服务身份

可通过以下设置，对使用 Server-Sent Events（SSE）的 MCP 服务进行身份验证：

示例：

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

请将 YOUR_TOKEN_HERE 替换为实际的身份验证令牌。

工作原理

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. 用户通过 Slack 进行交互，发送消息以触发智能 AI 工作流
2. LLM-MCP Bridge 作为智能编排层，用于：
   • 将请求路由到适当的 LLM 提供商（OpenAI、Anthropic、Ollama）
   • 在 Agent 模式（多步推理）和标准模式（单次响应）之间进行选择
   • 集成 RAG 系统以检索知识并增强上下文
   • 管理多个 MCP 服务中的工具发现与执行
3. 知识与记忆系统提供上下文智能能力：
   • 用于轻量级文档存储的简单 JSON 存储
   • 用于语义搜索和企业级 RAG 的 OpenAI Vector Store
4. 工具生态系统连接各种外部系统：
   • 用于文件管理的文件系统操作
   • 用于仓库交互的 Git 集成
   • Kubernetes 集群管理与监控
   • 通过 HTTP、SSE 或 stdio 协议接入自定义工具
5. 基础设施确保可用于生产环境的部署：
   • 支持环境变量的统一 JSON 配置
   • 用于可观测性和监控的 Prometheus 指标
   • 使用 Langfuse 和 OTLP 提供商的 OpenTelemetry 跟踪
   • 用于调试和分析的结构化日志

功能

• ✅ 多模式 MCP 客户端：
  • 用于实时通信并支持自动重试的 Server-Sent Events（SSE）
  • 用于 JSON-RPC 的 HTTP 传输
  • 用于本地开发和测试的 stdio
• ✅ Slack 集成：
  • 使用 Socket Mode 实现安全且对防火墙友好的通信
  • 同时支持频道和私信
  • 支持 Markdown 和 Block Kit 的丰富消息格式
  • 按线程跟踪对话，每个线程拥有独立上下文
  • 缓存用户上下文，实现个性化交互
  • 可自定义机器人行为和消息历史
• ✅ 多提供商 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）
  • 原生工具调用和统一的 LangChain 网关
• ✅ Agent 模式：
  • 由 LangChain（langchaingo v0.1.14）驱动的自主 AI Agent
  • 增强的多步推理与工具编排
  • 改进了对复杂多行工具调用的解析
  • 可配置 Agent 迭代次数和行为
  • 修复内存泄漏问题，实现可靠的流式响应
  • 高级提示词工程能力
• ✅ RAG（检索增强生成）：
  • 多种提供商：简单 JSON 存储、OpenAI Vector Store
  • 支持 vectorStoreId 的可复用向量存储
  • 可配置搜索参数和相似度指标
  • 支持智能分块的 PDF 导入
  • 用于文档管理的 CLI 工具
• ✅ 统一配置：
  • 单个 JSON 配置文件，并通过 JSON Schema 验证
  • 全面的超时和重试配置
  • 环境变量替换和覆盖
  • 暴露所有底层软件包选项
  • 智能默认值，并支持完全自定义
  • 为工具名称添加服务前缀，以避免命名冲突
• ✅ 可用于生产环境：
  • 支持 Docker 容器并发布到 GHCR
  • 使用 OCI 注册表的 Kubernetes Helm Chart
  • 全面的日志记录和错误处理
  • 测试覆盖并进行安全扫描
• ✅ 监控与可观测性：
  • 集成 Prometheus 指标
  • 跟踪工具调用及错误率
  • 按模型和类型监控 LLM Token 用量
  • 使用 Langfuse 和简单提供商的 OpenTelemetry 跟踪
  • 可配置的可观测性提供商，并支持平稳回退
  • 全面跟踪 LLM 操作和工具调用的 Span
  • 可配置的指标端点和日志级别

安装

从二进制发行版安装

从 GitHub releases 页面下载最新二进制文件，或使用 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

使用二进制文件在本地运行

安装二进制文件后，可按以下步骤在本地运行：

1. 设置环境变量：

# 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 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 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

从旧版配置迁移

如果你有之前版本使用的 mcp-servers.json 文件，可以迁移到新的统一配置格式：

# 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

新配置格式提供：

• 单个文件：所有设置集中在一个 config.json 文件中
• JSON Schema：支持 IDE 自动补全和验证
• 环境变量：使用 ${VAR_NAME} 语法处理密钥
• 智能默认值：基本使用所需的配置最少
• 全面选项：开放所有底层软件包设置

应用程序将连接到 Slack 并开始监听消息。你可以查看日志，了解是否存在错误或连接问题。

RAG 设置与使用

客户端包含改进后的 RAG（检索增强生成）系统，与 LangChain Go 兼容，并提供专业级性能：

RAG 快速入门

1. 在配置中启用 RAG：

{
  "$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. 使用 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

3. 在 Slack 中使用：

配置完成后，大模型可以自动搜索你的知识库：

用户：“我们的休假政策是什么？”

AI：“让我搜索一下知识库中的休假政策信息……” （自动搜索 RAG 数据库）

AI：“根据公司的政策文档，你有 15 天年假……”

RAG 功能

• 🎯 智能搜索：通过词频、文件名加权和短语匹配进行高级相关性评分
• 🔗 兼容 LangChain：可直接替换标准向量存储
• 📈 可扩展：可轻松添加向量嵌入和其他后端

自定义提示词和助手

客户端支持高级提示词工程功能，可用于创建专用 AI 助手：

系统提示词

创建自定义 AI 个性和行为：

# 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

基于配置的提示词

在配置中定义提示词：

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

助手角色

针对不同用例创建专用助手：

• DevOps 助手：具备 Kubernetes、Docker、CI/CD 专业知识
• 销售助手：潜在客户资格判定、异议处理
• HR 助手：政策问题、入职指导
• 支持助手：解决客户问题
• 代码审查助手：安全性、性能、最佳实践

Agent 模式

Agent 模式使用 LangChain 的 Agent 框架，支持更具互动性且上下文感知能力更强的对话。与单次提示词交互不同，Agent 可以进行多步骤推理、更有策略地使用工具，并在整个对话过程中更好地保持上下文。

Agent 模式的工作方式

Agent 模式使用 LangChain 的对话 Agent 框架，提供：

1. 互动式对话：在多轮交流中保持上下文
2. 策略性工具使用：由 Agent 决定何时以及如何使用可用工具
3. 多步骤推理：可将复杂问题拆解为易于处理的步骤
4. 流式响应：在处理过程中提供实时更新
5. 用户上下文集成：结合缓存的用户信息，提供个性化响应
6. 线程上下文感知：为每个 Slack 线程分别保留对话历史

Agent 模式配置

在配置文件中启用 Agent 模式：

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

配置选项

• llm.useAgent：启用 Agent 模式（默认值：false）
• llm.useNativeTools：使用原生 LangChain 工具，而非基于系统提示词的工具（默认值：false）
• llm.customPrompt：用于定义 Agent 行为的系统提示词
• llm.maxAgentIterations：Agent 推理步骤的最大次数（默认值：20）

Agent 模式与标准模式

标准模式：

• 单轮提示词交互
• 在系统提示词中以 JSON 架构描述工具
• 直接解析并执行工具调用
• Token 用量更可预测
• 对话流程更简单

Agent 模式：

• 多轮对话交互
• 根据上下文决定如何使用工具
• 更好地整合用户上下文
• 对话流程更自然
• 推理能力更强

Agent 模式示例

交互式开发咨询：

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]

上下文问题求解：

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 模式最佳实践

1. 系统提示词：设计清晰、具体的系统提示词，引导 Agent 的行为
2. 工具选择：为 Agent 提供适用于其领域的工具
3. 上下文管理：Agent 能在多轮对话中更好地保持上下文
4. 用户个性化：利用用户上下文整合功能，提供个性化回复
5. 工具策略：根据需求，在原生工具和基于系统提示词的工具之间进行选择

限制与注意事项

• OpenAI Agent：langchaingo 中的原生 OpenAI Agent 存在已知问题，因此使用对话式 Agent 作为替代方案
• LangChain 依赖项：Agent 模式需要 LangChain 提供程序
• 权限：检索用户信息可能需要额外的 Slack 权限
• 性能：Agent 模式的性能特征可能与标准模式不同

使用 Helm 部署到 Kubernetes

如需部署到 Kubernetes，helm-chart 目录中提供了 Helm chart。此 chart 提供了一种灵活的方式，可通过适当的配置和密钥管理来部署 slack-mcp-client。

从 GitHub Container Registry 安装

Helm chart 也可直接从 GitHub Container Registry 获取，无需克隆仓库即可轻松安装：

# 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

你可以在浏览器中访问 GitHub Container Registry，查看可用版本。

前提条件

• Kubernetes 1.16+
• Helm 3.0+
• Slack Bot 和 App 令牌

基本安装

# 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

配置选项

Helm chart 支持多种配置选项，包括：

• 设置资源限制和请求
• 通过 ConfigMap 配置 MCP 服务
• 通过 Kubernetes 密钥管理敏感数据
• 自定义部署参数

更多详情请参阅 Helm chart README。

使用来自 GHCR 的 Docker 镜像

Helm chart 默认使用来自 GitHub Container Registry（GHCR）的 Docker 镜像。你可以指定特定版本，也可以使用 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

手动拉取镜像：

# 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

如果你使用的是私有镜像，可以在 values 中配置镜像拉取密钥：

imagePullSecrets:
  - name: my-ghcr-secret

使用 Docker Compose 进行本地测试

在本地测试和开发时，你可以使用 Docker Compose 轻松运行 slack-mcp-client 以及其他 MCP 服务。

设置

1. 创建包含凭据的 .env 文件：

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

2. 创建 mcp-servers.json 文件（或使用示例文件）：

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

3. 启动服务：

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

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Docker Compose 配置

随附的 docker-compose.yml 提供：

• 从 .env 文件加载环境变量
• 挂载用于配置 MCP 服务的卷
• 连接其他 MCP 服务的示例（已注释）

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

你可以轻松扩展此设置，将其他 MCP 服务加入同一网络。

Slack 应用设置

1. 在 https://api.slack.com/apps 创建新的 Slack 应用
2. 启用 Socket Mode 并生成应用级令牌
3. 在 App Home 页面中勾选 Allow users to send Slash commands and messages from the chat tab，以启用向 Slack 应用发送直接消息的功能。
4. 添加以下 Bot Token 权限范围：
   • app_mentions:read
   • chat:write
   • im:history
   • im:read
   • im:write
   • users:read
   • users.profile:read
   • channels:history
   • groups:history
   • mpim:history
5. 启用事件订阅并订阅以下事件：
   • app_mention
   • message.im
6. 将应用安装到你的工作区

有关 Slack 应用配置、令牌设置、所需权限以及常见问题排查的详细说明，请参阅 Slack 配置指南。

大模型集成

客户端通过灵活的集成系统支持多个大模型提供商：

LangChain 网关

LangChain 网关可与各种大模型提供商无缝集成：

• OpenAI：原生支持 GPT 模型（默认）
• Ollama：支持 Llama、Mistral 等模型的本地大模型
• 可扩展：可扩展以支持其他兼容 LangChain 的提供商

LLM-MCP 桥接

自定义的 LLM-MCP 桥接层使任何大模型都能使用 MCP 工具，无需原生函数调用能力：

• 通用兼容性：适用于任何大模型，包括不支持函数调用的大模型
• 模式识别：检测用户提示词或大模型响应是否应触发工具调用
• 自然语言支持：可理解结构化 JSON 工具调用和自然语言请求

配置

可通过环境变量或命令行标志配置大模型提供商：

# 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

在不同提供商之间切换

更改 LLM_PROVIDER 环境变量即可轻松切换提供商：

# Use OpenAI
export LLM_PROVIDER=openai

# Use Anthropic
export LLM_PROVIDER=anthropic

# Use Ollama (local)
export LLM_PROVIDER=ollama

配置

客户端主要采用以下两种配置方式：

环境变量

使用环境变量配置大模型提供商和 Slack 集成：

变量	描述	默认值
SLACK_BOT_TOKEN	Slack API 的 Bot 令牌	（必需）
SLACK_APP_TOKEN	Socket Mode 的应用级令牌	（必需）
OPENAI_API_KEY	用于 OpenAI 身份验证的 API 密钥	（必需）
OPENAI_MODEL	要使用的 OpenAI 模型	gpt-4.1
ANTHROPIC_API_KEY	用于 Anthropic 身份验证的 API 密钥	（Anthropic 必需）
ANTHROPIC_MODEL	要使用的 Anthropic 模型	claude-sonnet-4.5
LOG_LEVEL	日志级别（debug、info、warn、error）	info
LLM_PROVIDER	要使用的大模型提供商（openai、anthropic、ollama）	openai
LANGCHAIN_OLLAMA_URL	使用 LangChain 时 Ollama 的 URL	http://localhost:11434
LANGCHAIN_OLLAMA_MODEL	使用 LangChain 时 Ollama 的模型名称	llama3.3
LANGFUSE_ENDPOINT	用于可观测性的 Langfuse API 端点	（可选）
LANGFUSE_PUBLIC_KEY	用于身份验证的 Langfuse 公钥	（可选）
LANGFUSE_SECRET_KEY	用于身份验证的 Langfuse 密钥	（可选）
OTEL_EXPORTER_OTLP_ENDPOINT	用于简单跟踪的 OTLP 端点	（可选）

监控与可观测性配置

客户端包含全面的监控功能，涵盖指标和分布式跟踪：

Prometheus 指标

• 指标端点：可通过配置的端口访问 /metrics
• 默认端口：8080（可通过 --metrics-port 标志配置）
• 可用指标：
  • slackmcp_tool_invocations_total：工具调用计数器，包含工具名称、服务和错误状态标签
  • slackmcp_llm_tokens：按类型和模型统计大模型令牌用量的直方图

OpenTelemetry 追踪

• 支持的提供程序：
  • simple-otel：向 OTLP 端点提供基础的 OpenTelemetry 追踪（需要配置端点）
  • langfuse-otel：集成 Langfuse 的高级大模型可观测性（需要配置端点和身份验证）
  • disabled：不进行追踪（未配置端点时的默认状态）
• 自动回退：提供程序失败时会自动回退到禁用状态
• 全面追踪：为大模型操作、工具调用和用户交互创建 Span，并附带详细属性

配置和使用示例：

# 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"

统一配置格式

现在，所有配置都通过单个 config.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"
  }
}

如需了解详细配置选项和迁移指南，请参阅配置指南。

自动重新加载功能

客户端支持可选的自动重新加载功能，可在 MCP 服务重启时避免停机，非常适合 MCP 服务可能独立重启的 Kubernetes 部署。

注意：重新加载功能默认处于禁用状态，必须在配置文件中明确启用。

配置

如需启用重新加载功能，请在 config.json 中添加重新加载设置：

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

配置选项：

• enabled：必须设为 true 才能启用重新加载功能（默认值：false）
• interval：自动重新加载的时间间隔（默认值："30m"，最短为 "10s"）

使用方法

自动重新加载：启用后，应用程序会按配置的时间间隔自动重新加载，以重新连接 MCP 服务并刷新工具发现结果。

手动重新加载：即使禁用了自动重新加载，也可以通过信号触发手动重新加载：

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

# Local process
kill -USR1 <process-id>

优点

• 零停机：重新加载期间应用程序持续运行
• 适合 Kubernetes：应用程序组件重启期间，Pod 仍会持续运行
• 按需启用：默认禁用，只有明确配置后才会启用
• 灵活：支持自动（定期）和手动（信号）触发
• 安全：最短间隔验证可避免过于频繁地重新加载

启用后，重新加载功能会自动：

• 重新连接所有已配置的 MCP 服务
• 重新发现可用工具
• 刷新配置设置
• 在整个过程中保持 Slack 连接

非常适合生产环境，因为 MCP 服务可能因更新、扩缩容或维护而重启。

Slack 格式化输出

客户端包含一套全面的 Slack 格式化输出系统，可优化 Slack 中的消息显示效果：

• 自动格式检测：自动检测消息类型（纯文本、Markdown、JSON Block Kit、结构化数据），并应用相应的格式
• Markdown 格式化：支持 Slack 的 mrkdwn 语法，并可自动转换标准 Markdown
  • 将 **bold** 转换为 *bold*，以正确显示 Slack 粗体格式
  • 保留行内代码、引用块、列表和其他格式元素
• 引号字符串优化：自动将双引号字符串转换为行内代码块，以便更清晰地显示
  • 示例：在 Slack 中，"namespace-name" 会显示为 `namespace-name`
  • 提高 ID、时间戳和其他带引号值的可读性
• Block Kit 集成：将结构化数据转换为 Block Kit 布局，以获得更好的视觉呈现效果
  • 自动根据 Slack API 限制进行验证
  • 如果 Block Kit 验证失败，则回退到纯文本

如需了解详情，请参阅 Slack 格式指南。

传输模式

客户端支持三种传输模式：

• SSE（默认）：使用服务器发送事件与 MCP 服务实时通信，并包含自动重试逻辑以增强可靠性
• HTTP：使用 HTTP POST 请求和 JSON-RPC 进行通信
• stdio：使用标准输入/输出进行本地开发和测试

文档

docs/ 目录中提供了完整的文档：

配置与设置

• Slack 配置指南 - Slack 应用设置完整指南，包括所需权限、令牌以及常见问题的排查方法

开发与实现

• 实现说明 - 详细的技术文档，涵盖当前架构、核心组件和实现细节
• 需求规格说明 - 全面的需求文档，包括已实现的功能、质量要求和未来的增强计划

用户指南

• Slack 格式指南 - 消息格式完整指南，包括 Markdown 到 Slack 的转换、Block Kit 布局和自动格式检测
• RAG 实现指南 - 改进版 RAG 系统的详细指南，包含 LangChain Go 兼容性和性能优化
• RAG SQLite 实现 - 使用原生 Go SQLite 集成并提供类似 ChatGPT 的上传体验的实现计划
• 测试指南 - 全面的测试文档，涵盖单元测试、集成测试、手动测试流程和调试

快速链接

• 设置：初始设置请从 Slack 配置指南 开始
• Agent 模式：有关支持工具链式调用的自主 AI Agent，请参阅上方的 Agent 模式部分
• RAG：查看 RAG 实现指南，了解文档知识库集成
• 格式：有关消息格式功能，请参阅 Slack 格式指南
• RAG SQLite：有关采用原生 Go 实现并提供现代化上传体验的方案，请参阅 RAG SQLite 实现
• 开发：查看 实现说明，了解技术细节
• 测试：使用 测试指南了解测试流程和调试方法
• 监控：有关 Prometheus 集成，请参阅上方的指标配置部分
• 依赖项：查看依赖项，了解版本跟踪和升级历史

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

CI/CD 与发布

本项目使用 GitHub Actions 进行持续集成，并使用 GoReleaser 自动发布。

持续集成检查

我们的 CI 流水线会对所有 PR 和提交到 main 分支的代码执行以下检查：

代码质量

• Lint 检查：使用 golangci-lint 检查常见代码问题和风格违规
• Go 模块验证：确保 go.mod 和 go.sum 得到妥善维护
• 格式检查：验证代码是否已使用 gofmt 正确格式化

安全

• 漏洞扫描：使用 govulncheck 检查依赖项中已知的漏洞
• 依赖项扫描：使用 Trivy 扫描依赖项中的漏洞
• SBOM 生成：生成软件物料清单以跟踪依赖项

测试

• 单元测试：运行测试，并进行竞态检测和代码覆盖率报告
• 构建验证：确保代码库能够成功构建

发布流程

更改合并到主分支后：

1. 运行 CI 检查，以验证代码质量和安全性
2. 如果检查成功，将自动创建新版本，其中包括：
   • 根据提交消息进行语义化版本控制
   • 为多个平台构建二进制文件
   • 将 Docker 镜像发布到 GitHub Container Registry
   • 将 Helm chart 发布到 GitHub Container Registry