关键词

Zulip集成消息工具协作助手AI增强聊天机器人

项目简介

Zulip MCP 服务器是一个实现了 Model Context Protocol (MCP) 的后端应用。它通过 MCP 协议，将 Zulip 工作空间的各项功能（如发送消息、获取用户信息、管理频道等）以及相关上下文信息，以结构化的资源和可调用的工具形式提供给 LLM (大型语言模型) 客户端使用。这使得 LLM 能够理解 Zulip 环境并与其进行编程化交互。

主要功能点

  • 资源 (Resources): 提供 Zulip 工作空间的结构化上下文信息，例如：
    • 用户目录：浏览组织成员列表及其角色。
    • 频道目录：查看可用频道列表和权限。
    • 消息格式指南：获取 Zulip Markdown 语法参考。
    • 组织信息：获取服务器设置和策略。
    • 用户组：列出可用于提及或权限的用户组。
  • 工具 (Tools): 封装 Zulip REST API，允许 LLM 执行具体操作，共有 19 个工具，涵盖：
    • 消息操作：发送、获取、编辑、删除消息，上传文件，添加/移除表情反应，获取已读回执。
    • 计划消息与草稿：创建、编辑计划消息，获取、编辑草稿。
    • 频道管理：获取订阅的频道，通过名称/ID 获取频道信息，获取频道主题。
    • 用户操作：通过邮箱/ID 获取用户信息，列出所有用户，更新用户状态，获取用户组。

安装步骤

  1. 克隆仓库并安装依赖： 打开终端，执行以下命令： 
    git clone https://github.com/avisekrath/zulip-mcp-server.git
cd zulip-mcp-server
npm install
  2. 配置环境变量： 复制示例配置文件并编辑，填入您的 Zulip 实例地址、机器人邮箱和 API 密钥： 
    cp .env.example .env
# 使用文本编辑器打开 .env 文件，填入您的信息
    '.env' 文件内容示例： 
    ZULIP_URL=https://your-organization.zulipchat.com
[email protected]
ZULIP_API_KEY=your-api-key-here
NODE_ENV=production
  3. 构建并运行服务器： 
    npm run build
npm start
    服务器将在标准输入/输出 (stdio) 上运行，等待 MCP 客户端连接。

MCP客户端配置

MCP 客户端（如 Claude Desktop, Cursor IDE, Raycast MCP Extension 等）需要配置服务器的启动方式才能连接。以下是常见的 JSON 配置格式，您需要根据您的客户端类型和服务器实际安装路径进行调整：

{
  "mcpServers": {
    "zulip": {
      "command": "node",  // 启动 Node.js 运行时
      "args": ["/path/to/zulip-mcp-server/dist/server.js"], // 指定编译后的服务器文件路径
      "env": { // 可选：在此处设置 Zulip 凭据环境变量
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "[email protected]",
        "ZULIP_API_KEY": "your-api-key-here"
      },
      // 或者，如果您使用了 .env 文件且配置了 cwd，可以省略 env 部分
      // "cwd": "/path/to/zulip-mcp-server", // 设置工作目录到服务器根目录
      "name": "Zulip Integration", // 在客户端中显示的服务器名称
      "description": "Provides access to Zulip messaging and user data.", // 客户端中显示的服务器描述
      "capabilities": { // 声明服务器提供的能力，有助于客户端理解
        "tools": true,
        "resources": true
        // 其他能力如 prompts, events 根据实际实现可能需要添加
      }
    }
  }
}

请注意： 将 '/path/to/zulip-mcp-server' 替换为您实际安装此服务器的目录路径。环境变量也可以直接在运行 MCP 客户端的环境中设置，而不在客户端配置的 'env' 部分。

基本使用方法 (供LLM参考)

  1. 连接测试与概览: 第一次使用或连接失败时，先调用 'get-started' 工具检查连接并获取基本信息。
  2. 查找用户: 如果需要向特定用户发送私信，使用 'search-users' 工具通过姓名查找用户的准确邮箱地址。切勿直接使用显示名称发送私信。
  3. 查找频道: 使用 'get-subscribed-channels' 工具获取您已订阅频道的准确名称列表。频道名称区分大小写。
  4. 发送消息:
    • 发送到频道：调用 'send-message' 工具，设置 'type' 为 "stream"，'to' 为频道名称，'topic' 为主题（频道消息必须有主题），'content' 为消息内容。
    • 发送私信：调用 'send-message' 工具，设置 'type' 为 "direct"，'to' 为通过 'search-users' 获得的收件人邮箱地址（多个收件人可使用逗号分隔），'content' 为消息内容。
  5. 获取消息: 调用 'get-messages' 工具，可以使用 'narrow' 参数进行过滤（例如按频道、主题、发送者或关键词过滤），使用 'anchor', 'num_before', 'num_after' 控制获取范围。
  6. 其他操作: 根据需求调用其他工具，如 'edit-message', 'delete-message', 'add-emoji-reaction', 'upload-file', 'get-topics-in-channel' 等。使用时请参考对应工具的参数说明。

该服务器还提供了 'message-formatting-guide' 资源，其中详细说明了 Zulip 支持的 Markdown 语法，包括如何提及用户 ('@Full Name')、提及频道 ('#channelname')、使用代码块等。LLM 在生成消息内容时应参考此指南。

信息

分类

AI与计算

访问项目