viber-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A macOS-only MCP server that sends and reads Viber Desktop messages by automating the running, signed-in Viber app — Viber has no API, its message DB is encrypted, and its Qt accessibility tree is unusable, so everything is done via the viber:// URL scheme, synthetic HID input, and screen OCR.

Commands

uv sync                                    # install deps (Python managed by uv)

# Standalone client = the way to test/run tools without Claude (spawns a fresh server each call,
# so it always uses the latest code). Subcommands map 1:1 to tools:
uv run client.py list                      # advertise tools
uv run client.py open|openread|search "<name-or-+E164>"
uv run client.py send  "<to>" "<text>" [--dry-run]
uv run client.py reply "<text>"            # into the currently-open chat
uv run client.py draft "<text>"            # paste into open chat, do NOT send
uv run client.py note  "<text>"            # save to My Notes
uv run client.py chats | read | contacts

# Register with Claude Code (user scope):
claude mcp add --transport stdio --scope user viber -- uv --directory "$(pwd)" run server.py

There is no test suite, linter, or build step. Verify changes by driving the real app with client.py and screenshotting the Viber window (viber_ocr.capture_window) to confirm the outcome — the returned verified flag is best-effort and gives false negatives.

After editing server code, the registered MCP server keeps running the old code until reconnected (/mcp → reconnect viber, or restart Claude Code); client.py always runs fresh code.

Architecture

The code is split into platform-neutral domain logic and a platform Backend (so the app is port-ready for Windows/Linux — see "Porting" below):

• server.py — FastMCP stdio server; thin @mcp.tool() wrappers only. Tools: send_message, reply, open_chat, open_and_read, read_open_chat, list_chats, put_draft, search_and_open, save_to_my_notes, open_my_notes, list_contacts.
• viber_send.py — platform-neutral write/navigation logic: recipient resolution (contacts.json alias → E.164), the send pipeline, search-result scoring, panel detection, send verification. Holds a module-level backend = get_backend() and calls only its semantic methods. Raises SendError.
• viber_ocr.py — platform-neutral read side: read_open_chat() / read_chat_list() format backend.observe() output (read_chat_list keeps only left-column x<0.30). Raises OCRError.
• backends/ — the platform layer.
  • base.py — Backend ABC + OCRError. Semantic interface: app_running/focus/open_url, observe()→[{text,x,y}], clipboard, type_text/select_all/delete/paste, and element clicks click_compose/send/search/result(norm_y)/panel_close. The domain never sees pixels or key codes.
  • macos.py — MacBackend: all Quartz/Vision/AppKit code AND the macOS Viber-layout constants (element pixel/fraction offsets). This is the only file with OS APIs.
  • __init__.py — get_backend() picks the backend by sys.platform (macOS only today).
• client.py — standalone MCP stdio client for testing.
• contacts.json — name→E.164 map, git-ignored (real numbers); ship contacts.example.json.