zulipmcp 是一个开源项目，目标是在 Zulip 中运行 AI 智能体，使其成为可被 @ 提及的机器人，或者接入任意 MCP（Model Context Protocol）客户端使用，同时也可作为 Python 库直接导入。
一、用途与定位 zulipmcp 在 Zulip 与 AI 智能体后端之间充当桥梁：MCP 服务器负责提供全部 Zulip 工具，监听器（listener）负责智能体会话的生命周期管理。它既支持以 @ 提及方式在 Zulip 流/话题中触发智能体，也支持由已有协调进程直接启动一个编码智能体会话，还能把 Zulip 接入任意 MCP 客户端。
二、主要能力
- 实时消息监听：listen 工具使用 Zulip 的实时事件 API（长轮询）而非反复调用 GET /messages。进入时先补齐自 last_seen_message_id 以来的消息，按需将机器人订阅到流，注册针对该流/话题的事件队列，然后通过 GET /events 长轮询。服务器会阻塞直到有消息到达或约 90 秒心跳超时，据称比每 2 秒轮询高效约 30 倍。若队列过期（BAD_EVENT_QUEUE_ID），会自动重新注册；退出时在 finally 块中删除队列。监听期间会在最后一条消息上添加耳朵 emoji 作为视觉提示，停止监听时移除；若领域配置了名为 robot_ear 的自定义 emoji，则改用该 emoji。每个长轮询周期后通过 ctx.info() 发送 MCP keepalive ping。
- 回复不漏消息：调用 reply 时会先检查是否有新消息。如果在大模型思考期间有人发帖，这些消息会被获取并连同“消息已发送”确认一起返回，使模型总能看到遗漏内容并作出反应。last_seen_message_id 会更新为最新值（遗漏消息或已发送消息中较新者）。
- 会话关闭：用户可在任意机器人消息上使用可配置 emoji（默认 :stop_sign:）回应来关闭机器人会话。关闭检查在 listen()（通过回应事件）和 reply() 之前（通过 REST API 轮询）都会执行，覆盖用户在机器人忙碌时回应的竞态条件。可通过 configure(dismiss_emoji={"stop_sign", "wave"}) 自定义。
- 输入状态指示：set_context() 时以及每次 reply() 之后启动输入指示，listen() 和 end_session() 时停止，让用户看到机器人在“输入中”。若有其他进程驱动该指示，可用 configure(auto_typing_start=False) 抑制自动启动，避免覆盖；停止仍会执行。显式的 typing() / stop_typing() 工具不受影响。
- 机器人可见性过滤：包含 /nobots 或 /nb 的话题对机器人完全隐藏；以 /nobots 或 /nb 开头的消息也会被过滤。这样人类可以进行机器人看不到的私密对话。
- 出站 Markdown 规范化：每次发送/回复/编辑前会运行 normalize_zulip_markdown()，修复 Zulip 渲染器处理不当的两种 GFM 习惯：表格前缺少空行，以及粗体与链接组合（a 会渲染为字面星号且链接不可点击；紧邻 ** 的裸 URL 会破坏自动链接）。围栏代码块和缩进代码块始终不动；行内代码段在粗体/链接修复中也予以保留。Hermes 网关通过原始客户端发送，不做规范化。可用 ZULIPMCP_MARKDOWN_AUTOFIX=0 完全禁用。
- Python 库：zulipmcp 也可直接作为 Python 库导入。
三、安装与使用方式 安装包：uv add zulipmcp --git https://github.com/windborne/zulipmcp.git 在项目根目录添加 .zuliprc 文件，填入 Zulip 机器人凭据（机器人类型必须为 "generic"）。 在 .mcp.json 中添加 MCP 服务器：{ "mcpServers" : { "zulip" : { "command" : " uv " , "args" : [ " run " , " python " , " -m " , " zulipmcp.mcp " ] } } } 重启 MCP 客户端后，Zulip 工具即可用。 环境要求：Python >=3.10（用 uv 管理）；用于 Zulip API 认证的 .zuliprc 文件；监听模式下需安装并认证所选后端 CLI（默认 claude，--backend codex 用 codex，--backend opencode 用 opencode）。
四、适用场景
- 在 Zulip 流/话题中以 @ 提及方式驱动 AI 智能体；首次提及激活话题后，后续消息无需再提及。
- 由已有协调进程直接启动一个 Claude Code 或 Codex 会话（不监听 Zulip、不因提及而生成），启动器只启动一个前台编码智能体进程并复用内置会话指令；当协调者应继续工作时以后台进程运行。默认以可续期的两小时区间监听，区间超时不会直接退出。可用 --trigger-message-id 和 --session-user-email（元数据可用时）；仅在智能体不应使用其现有全局 MCP 配置时传 --zuliprc 或 --mcp-config。
- Hermes 网关：使用原生 hermes_plugin/zulip 网关适配器而非子进程监听器。每个流/话题映射到自己的持久 Hermes 会话，zulipmcp 仍作为显式 Zulip API 工具层。每条用户消息是一次全新的 Hermes 轮次，有全新的迭代预算；输入、常规回复投递、状态反应、审批反应和 :stop_sign: 中断由适配器处理；首次激活只加入同话题历史；网关重启后需再提及一次以重新激活话题，Hermes 会恢复同一已存储会话。详见插件 README。
- 对每个 (stream, topic) 生成一个无头智能体会话；每个会话自动设置 TRIGGER_MESSAGE_ID 和 SESSION_USER_EMAIL，使 set_context() 锚定到 @ 提及处，钩子可识别请求者。
五、设计与限制说明
- 监听器故意不设置模型或推理默认值；后端 CLI 和模型别名会随时间变化，请使用后端用户配置或在 -- 之后传标志。生产环境建议在部署配置中固定精确的后端模型 ID，而非依赖别名。
- 自定义 --system-prompt 文件是后端指令，不是初始任务；监听器仍会发送简短的每会话引导提示，包含目标流/话题和 Zulip 生命周期约定：初始化上下文、通过 reply() 发送可见文本、需要让出等待后续时调用 listen()。
- Codex 会话启动时启用网页搜索，以匹配 Claude Code 的默认网络抓取能力。对 Codex，.mcp.json 适配器为翻译后的 stdio MCP 服务器白名单化继承的环境变量名，在 argv 中不放入环境变量值；并在存在时转发 Zulip 的直接自动初始化 SESSION_STREAM / SESSION_TOPIC 对，将 tool_timeout_sec 至少设为 3 小时，使长时间运行的 listen() 工具能等待后续消息。该适配器有意保守：拒绝 Claude SSE 配置，只翻译 command 和可流式 HTTP url 的服务器，环境变量占位符仅支持 env/header 值。
- OpenCode 会话通过 OPENCODE_CONFIG_CONTENT（内联 JSON）接收完整配置。.mcp.json 适配器把基于 command 的服务器翻译为 OpenCode 的 local 类型（合并 command + args 为单个数组），基于 url 的翻译为 remote 类型，将 env 重命名为 environment。每个翻译后的服务器获得 3 小时 MCP 超时，使 listen() 能阻塞等待后续；listen() 在长轮询循环中发送 MCP 进度通知，OpenCode 用它重置每次调用超时。系统提示文件路径通过 instructions 配置字段传入。
- 监听器有意保持最小化：不含并发上限、工作区隔离、过期看门狗和仪表盘——需要时自行添加。
- 仅同话题历史会在首次激活时加入。
六、环境变量 资料中提到环境变量部分存在（“Environment Variables”），但未提供具体变量清单，暂未提供。
整体而言，zulipmcp 面向需要在 Zulip 中部署 AI 智能体、或将 Zulip 接入 MCP 生态的开发者，提供实时监听、会话生命周期管理、文件处理和 Markdown 输出修正等能力，同时保留以 Python 库方式集成和按需扩展的灵活性。
