zulipmcp: Instructions file for Codex

zulipmcp

Public open-source repo. All code, commits, and PRs are visible to the world.

Rules

• Nothing WindBorne-specific. No internal URLs, emails, Zulip instances, or infra references.
• No internal context in PRs, commits, or comments.
• Elegant, general code. Type hints everywhere. Minimal dependencies.

Architecture

• core.py — Zulip API wrappers. No MCP dependency. Returns Python objects.
• mcp.py — MCP tool layer + SessionState. Thin wrappers over core.py. Hooks system lives here.
• agent_backends.py — Claude/Codex/OpenCode command builders for the listener. No Zulip API dependency.
• hermes_plugin/zulip/ — Native Hermes gateway transport. It does not use MCP session state.

Separation is load-bearing: core.py must stay MCP-agnostic so it works as a standalone library import.

Gotchas

• listen() is async, everything else is sync. It runs get_events() in a thread executor to interleave MCP keepalive pings. Don't make other tools async — FastMCP handles sync tools fine.
• Event queue narrow does NOT filter reactions. is_dismiss_reaction() receives reactions from all streams — it fetches the reacted-on message to verify stream/topic. Don't remove that check.
• _session is module-level singleton. One session per process. Don't add multi-session — MCP is one-client-per-server.
• reply() checks for missed messages before sending. The last_seen_message_id bookkeeping is subtle — trace it carefully before changing.
• Send tools enforce MAX_MESSAGE_LENGTH. Zulip silently truncates over-limit messages and still reports success — the guard returns an error to the caller instead. It measures the normalized form (post normalize_zulip_markdown()), since normalization can grow content. Override with ZULIP_MAX_MESSAGE_LENGTH for non-default realm caps.
• Two dismiss-check paths exist intentionally. listen() catches via events, reply() via REST poll. Both needed — user might react during tool execution (not listening).
• Interrupt-file reads must go through _consume_interrupt_file(). It claims via atomic rename before reading, so a writer replacing the file mid-consume can't have its content deleted unread — and it decodes with errors="replace" so a bad-bytes file can't wedge every future poll. Don't inline a read+delete elsewhere.
• ZULIPMCP_READ_ONLY is enforced only by core._ReadOnlyAdapter on get_client()'s session (refuses every non-GET). WRITE_TAG hiding is UX; tag every new write tool. A bare requests call or a second zulip.Client bypasses the guard, and a read needing a non-GET would weaken it, so add neither. Unknown flag values must keep raising.
• Private stream security is asymmetric on purpose. Unset BOT_ALLOWED_PRIVATE_STREAMS = no access (default-deny); only __ALL__ unlocks DM reads. Unset BOT_ALLOWED_WRITE_STREAMS = all writes allowed (backwards-compat). Don't "fix" the asymmetry. Tools don't re-check: new narrow reads must go through fetch_narrow, whose _check_read_scope refuses any narrow that doesn't name an allowed scope before fetching, then drops strays via _is_readable. Single-message reads that return content must go through core.get_message_by_id, whose _is_readable call is their only gate. Never subtract hidden streams with negated terms instead: narrows ride the GET query string and break past ~50 terms.
• Unread/mention markers read flags off the message dict; missing flags renders no marker. A fetch path that drops them fails silently (message events carry them beside the message; get_events merges them in). unread is human-only (bots never mark read) and skips the account's own messages (API-sent messages start unread for their sender).
• <msg> blocks are a trust boundary. format_messages builds them: bodies via escape_msg_text (every < → <, Unicode tag characters dropped), attributes via escape_msg_attr (adds ", >); headers printed above blocks (set_context, get_messages) escape names too. Don't exempt code blocks or escape only tag-shaped <msg (anything reading surrounding text is bypassable), and don't escape names in output without blocks (nothing to protect; breaks round-tripping into tool args). Look-alikes are out of scope: this guards who said what, not injection in general.
• Logging is configured in run_server() only — not at import, not in __main__. Library importers own their root logger and must get no files; wrappers call run_server() directly.
• configure() must be called before run_server(). run_server() may auto-init a session that reads hook state.
• auto_typing_start=False gates starts only; listen()/end_session() still send "stop", and reply() sends "stop" in place of its start. Zulip keys the indicator per user, not per process, so gating stops can't isolate an external owner — it would only leave a stale bar on idle/exit, and a reply with no stop leaves the pre-reply status stranded under the new message until the server expiry. Don't gate the stops. set_context() stays a no-op there: a stop that early would wipe whatever the owner posted at boot.
• Codex MCP config is not .mcp.json native. The listener translates .mcp.json into Codex -c mcp_servers... overrides. Keep secrets in env/header fields; env refs in command/args/cwd/url must fail closed to avoid argv leaks.
• OpenCode MCP config is not .mcp.json native. The listener translates .mcp.json into inline JSON via OPENCODE_CONFIG_CONTENT. Header values are embedded directly (no env-var indirection like Codex). Env refs in command/args/url are rejected.
• core.py send paths (send_message/send_direct_message/edit_message) rewrite markdown via normalize_zulip_markdown(). Blank lines are injected before tables and bold/link combos Zulip breaks on are rewritten. Fenced/indented code is exempt from both fixes; inline code spans are exempt only for the bold/link rewrite. The Hermes gateway adapter sends via the raw client and is NOT normalized. ZULIPMCP_MARKDOWN_AUTOFIX=0 disables all of it.
• remove_reaction() needs explicit reaction_type for custom emoji. Zulip's DELETE reactions endpoint defaults reaction_type to unicode_emoji — custom emoji removals fail silently without it. The listen indicator caches _listen_reaction_type alongside _listen_emoji; always pass both when removing.