zulipmcp

Zulip에서 AI 에이전트를 @멘션 가능한 봇으로 실행하거나 모든 MCP 클라이언트에 연결하세요. Python 라이브러리로도 작동합니다.

빠른 시작

1. 패키지 설치:

   uv add zulipmcp --git https://github.com/windborne/zulipmcp.git

2. Zulip 봇 자격 증명이 포함된 .zuliprc 파일을 프로젝트 루트에 추가하세요. 봇 생성 방법에 대한 지침은 봇 또는 통합 추가를 참조하세요. 봇 유형은 "generic"이어야 합니다.

3. .mcp.json에 MCP 서버를 추가하세요:

   {
     "mcpServers": {
       "zulip": {
         "command": "uv",
         "args": ["run", "python", "-m", "zulipmcp.mcp"]
       }
     }
   }

4. MCP 클라이언트를 다시 시작하세요. 이제 Zulip 도구를 사용할 수 있습니다.

요구 사항

• Python >=3.10, uv로 관리

• Zulip API 인증을 위한 .zuliprc 파일 (빠른 시작 참조)

진입점

라이브러리 사용법

zulipmcp는 Python 라이브러리로 직접 가져와서 사용할 수도 있습니다:

import zulipmcp

# Fetch and format recent messages
messages = zulipmcp.get_messages(hours_back=24, channels=["engineering"])
print(zulipmcp.format_messages(messages))

# Send a message
zulipmcp.send_message("engineering", "general", "Hello from Python!")

# Configure MCP hooks before starting the server
zulipmcp.configure(
    message_prefix=lambda: "[bot] ",
    on_session_end=lambda session: print(f"Session ended in #{session.stream}"),
)

리스너

선택 사항인 zulipmcp.listener 모듈은 Zulip에서 @멘션을 감시하고 (스트림, 토픽)당 하나의 헤드리스 Claude Code 세션을 생성합니다. 이는 Zulip 이벤트와 Claude Code를 연결하는 접착제 역할을 합니다. MCP 서버는 모든 Zulip 도구를 처리하고, 리스너는 수명 주기만 관리합니다.

# Minimal -- uses ./.zuliprc, ./.mcp.json (if present), and the bundled default prompt
uv run python -m zulipmcp.listener

# Full -- override MCP config and system prompt
uv run python -m zulipmcp.listener \
    --mcp-config .mcp.json \
    --system-prompt agent.md \
    --log-dir ./logs

# Pass flags through to Claude Code (everything after --)
uv run python -m zulipmcp.listener -- --strict-mcp-config --model opus

플래그:

각 세션에는 TRIGGER_MESSAGE_ID와 SESSION_USER_EMAIL이 자동으로 설정되므로 set_context()가 @멘션에 고정되고 후크가 요청자를 식별할 수 있습니다.

리스너는 의도적으로 최소한으로 설계되었습니다(~230줄). 동시성 제한, 작업 공간 격리, 정체 감시자, 대시보드는 생략되었습니다. 필요할 때 추가하세요.

주요 설계 세부 정보

메시지 수신

listen 도구는 반복적인 GET /messages 호출 대신 Zulip의 실시간 이벤트 API(롱 폴링)를 사용합니다. 시작 시 last_seen_message_id 이후의 모든 메시지를 따라잡고, 필요한 경우 봇을 스트림에 구독시키며, 스트림/토픽에 대한 좁은 이벤트 큐를 등록한 다음 GET /events를 통해 롱 폴링합니다. 서버는 메시지가 도착하거나 약 90초(하트비트)가 지날 때까지 차단되므로 2초마다 폴링하는 것보다 약 30배 더 효율적입니다. 큐가 만료되면(BAD_EVENT_QUEUE_ID) 자동으로 다시 등록합니다. 큐는 종료 시 finally 블록에서 삭제됩니다.

수신 중임을 시각적으로 나타내기 위해 마지막 메시지에 robot_ear 이모지가 추가되며, 수신이 중지되면 제거됩니다. MCP 유지 핑은 각 롱 폴링 주기 후에 ctx.info()를 통해 전송됩니다.

답장 시 메시지 누락 방지

reply가 호출되면 전송 전에 새 메시지가 있는지 확인합니다. LLM이 생각하는 동안 누군가 게시물을 올렸다면, 해당 메시지를 가져와 "메시지 전송" 확인과 함께 반환합니다. 이렇게 하면 LLM은 항상 놓친 내용을 확인하고 그에 따라 반응할 수 있습니다. last_seen_message_id는 누락된 메시지나 전송된 메시지 중 가장 최신 것으로 업데이트되므로 아무것도 놓치지 않습니다.

세션 종료

사용자는 봇 메시지에 구성 가능한 이모지(기본값: :stop_sign:)로 반응하여 봇 세션을 종료할 수 있습니다. 종료 확인은 listen() 중(반응 이벤트를 통해)과 reply() 전(REST API 폴링을 통해) 모두 실행되므로, 봇이 작업 중일 때 사용자가 반응하는 경쟁 상태를 처리합니다. configure(dismiss_emoji={"stop_sign", "wave"})로 사용자 지정하세요.

봇 가시성 필터링

/nobots 또는 /nb가 포함된 토픽은 봇에게 완전히 숨겨집니다. /nobots 또는 /nb로 시작하는 메시지도 필터링됩니다. 이를 통해 인간은 봇이 볼 수 없는 비공개 대화를 나눌 수 있습니다.

환경 변수

라이선스

MIT