Mattermost MCP Client

Mattermost MCP 主机

一个 Mattermost 集成，连接到 Model Context Protocol (MCP) 服务，利用基于 LangGraph 的 AI Agent 提供智能界面，用于与用户交互以及直接在 Mattermost 中执行工具。

演示

1. 支持频道中的 Github Agent - 搜索现有问题和 PR，如未找到则创建新问题

2. 搜索互联网并使用 Mattermost-MCP-server 发布到频道

向下滚动查看 YouTube 上的完整演示

功能

• 🤖 Langgraph Agent 集成：使用 LangGraph Agent 来理解用户请求并编排响应。
• 🔌 MCP 服务集成：连接到 mcp-servers.json 中定义的多个 MCP 服务。
• 🛠️ 动态工具加载：自动从连接的 MCP 服务发现工具，并将其提供给 AI Agent。将 MCP 工具转换为 langchain 结构化工具。
• 💬 线程感知的对话：在 Mattermost 线程中维护对话上下文，以实现连贯交互。
• 🔄 智能工具使用：AI Agent 可以决定何时使用可用工具（包括链接多个调用）来完成用户请求。
• 🔍 MCP 能力发现：允许用户通过直接命令列出可用的服务、工具、资源和提示词。
• #️⃣ 直接命令界面：使用命令前缀（默认为 #）直接与 MCP 服务交互。

概述

该集成的工作流程如下：

1. Mattermost 连接 (mattermost_client.py)：通过 API 和 WebSocket 连接到 Mattermost 服务，以侦听指定频道中的消息。
2. MCP 连接 (mcp_client.py)：建立连接（主要是 stdio）到 src/mattermost_mcp_host/mcp-servers.json 中定义的每个 MCP 服务。它发现每个服务上的可用工具。
3. Agent 初始化 (agent/llm_agent.py)：创建一个 LangGraphAgent，配置为选择的大模型提供者和从所有连接的 MCP 服务动态加载的工具。
4. 消息处理 (main.py)：
   • 如果消息以命令前缀 (#) 开头，它将被解析为列出服务/工具或通过对应的 MCPClient 调用特定工具的直接命令。
   • 否则，消息（连同线程历史记录）被传递到 LangGraphAgent。
5. Agent 执行：Agent 处理请求，可能通过 MCPClient 实例调用一个或多个 MCP 工具，并生成响应。
6. 响应交付：来自 Agent 或命令执行的最终响应被发布回相应的 Mattermost 频道/线程。

设置

1. 克隆仓库：

   git clone <repository-url>
   cd mattermost-mcp-host
   

2. 安装：

   • 使用 uv（推荐）：

     # 如果还没有安装 uv，请先安装
     # curl -LsSf https://astral.sh/uv/install.sh | sh 
     
     # 激活虚拟环境
     source .venv/bin/activate
     
     # 使用 uv 安装包
     uv sync
     
     # 安装开发依赖
     uv sync --dev --all-extras
     

3. 配置环境（.env 文件）： 复制 .env.example 并填入相应的值，或 在项目根目录创建 .env 文件（或设置环境变量）：

   # Mattermost 详情
   MATTERMOST_URL=http://your-mattermost-url
   MATTERMOST_TOKEN=your-bot-token # 需要发布、读取频道等权限
   MATTERMOST_TEAM_NAME=your-team-name
   MATTERMOST_CHANNEL_NAME=your-channel-name # 机器人监听的频道
   # MATTERMOST_CHANNEL_ID= # 可选：如果提供了频道名称会自动检测
   
   # 大模型配置（Azure OpenAI 为默认）
   DEFAULT_PROVIDER=azure
   AZURE_OPENAI_ENDPOINT=your-azure-endpoint
   AZURE_OPENAI_API_KEY=your-azure-api-key
   AZURE_OPENAI_DEPLOYMENT=your-deployment-name # 例如 gpt-4o
   # AZURE_OPENAI_API_VERSION= # 可选，提供了默认值
   
   # 可选：其他提供商（使用 `[all]` 额外功能安装）
   # OPENAI_API_KEY=...
   # ANTHROPIC_API_KEY=...
   # GOOGLE_API_KEY=...
   
   # 命令前缀
   COMMAND_PREFIX=# 
   

   更多选项详见 .env.example。

4. 配置 MCP 服务： 编辑 src/mattermost_mcp_host/mcp-servers.json 定义你要连接的 MCP 服务。参考 src/mattermost_mcp_host/mcp-servers-example.json。 根据服务配置，你可能需要在系统中安装 npx、uvx、docker 并将其添加到 PATH。

5. 启动集成：

   mattermost-mcp-host
   

前置要求

• Python 3.13.1+
• uv 包管理器
• Mattermost 服务器实例
• 具有 API token 的 Mattermost 机器人账户
• 访问大模型 API（Azure OpenAI）的权限

可选

• 在 mcp-servers.json 中配置的一个或多个 MCP 服务
• Tavily 网络搜索需要在 .env 文件中配置 TAVILY_API_KEY

Mattermost 中的使用

集成运行并连接后：

1. 直接聊天： 直接在配置的频道或与机器人聊天。AI Agent 会作出回应，并根据需要使用工具。它在消息线程内维护上下文。
2. 直接命令： 使用命令前缀（默认 #）执行特定操作：
   • #help - 显示帮助信息。
   • #servers - 列出已配置和已连接的 MCP 服务。
   • #<server_name> tools - 列出 <server_name> 的可用工具。
   • #<server_name> call <tool_name> <json_arguments> - 在 <server_name> 上调用 <tool_name>，参数以 JSON 字符串形式提供。
     • 示例：#my-server call echo '{"message": "Hello MCP!"}'
   • #<server_name> resources - 列出 <server_name> 的可用资源。
   • #<server_name> prompts - 列出 <server_name> 的可用提示词。

后续步骤

• ⚙️ 可配置的大模型后端：通过环境变量支持多个 AI 提供商（默认 Azure OpenAI、OpenAI、Anthropic Claude、Google Gemini）。

Mattermost 设置

1. 创建机器人账户

• 转到 Integrations > Bot Accounts > Add Bot Account
• 给它起个名字并添加描述
• 将访问 token 保存在 .env 文件中

2. 所需的机器人权限

• post_all
• create_post
• read_channel
• create_direct_channel
• read_user

3. 将机器人添加到团队/频道

• 邀请机器人加入你的团队
• 将机器人添加到所需的频道

故障排除

1. 连接问题

• 验证 Mattermost 服务器是否运行
• 检查机器人令牌权限
• 确保团队/频道名称正确

2. AI 提供商问题

• 验证 API 密钥
• 检查 API 配额和限制
• 验证对 API 端点的网络访问

3. MCP 服务问题

• 检查服务器日志
• 验证服务器配置
• 确保已安装必要的依赖项和定义环境变量

演示

使用 Github MCP 服务通过聊天创建问题

(在 YouTube 上)

贡献

欢迎提交 PR。

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。