From 1d15fe64ef3465cc49284ccb8af5f677383de86b Mon Sep 17 00:00:00 2001 From: hamr0 Date: Tue, 16 Jun 2026 15:05:15 +0200 Subject: [PATCH] =?UTF-8?q?docs(readme):=20refresh=20for=20v0.6=E2=86=92v0?= =?UTF-8?q?.8,=20add=20MCP=20tool=20map?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure the root README onto the shared bare-ecosystem skeleton and bring it current with the last three releases: - Lead names both run modes (Docker + npx); new "Two ways to run" table contrasts Container vs Lite and states the single-file version-parity guarantee. Retitle Quick start (container) / Lite mode (npx); drop the now-redundant inline comparison table. - New "The MCP" section maps all 12 verbs (Read/triage · Write/act · Watch/reach), surfacing the previously undocumented poll_messages watch primitive + restart-safe cursor + source echo-guard (0.6.0) and attachments[] + download_asset byte reach (0.7.0). - Bump stale BEEPERBOX_IMAGE_TAG pin 0.7.0 -> 0.8.0. - Repoint mcp/README.md cross-links to the renamed anchors (#quick-start-container, #lite-mode-npx); keep it a focused lite-mode landing page, not a copy of the full README. - CHANGELOG: record under [Unreleased] / Documentation. Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 6 +++++ README.md | 63 +++++++++++++++++++++++++++++++++++++++++---------- mcp/README.md | 4 ++-- 3 files changed, 59 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 86b1baa..b57c612 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,12 @@ beeperbox follows [Semantic Versioning 2.0.0](https://semver.org/) with one conc Published tags on GHCR: `:X.Y.Z` (exact, immutable), `:X.Y` (rolling within a minor), `:X` (rolling within a major — always `:0` today), `:latest` (newest release tag, rebuilt weekly to pick up upstream Beeper AppImage drift), `:edge` (every push to `master`, may break). +## [Unreleased] + +### Documentation + +- **README rewrite to reflect v0.6 → v0.8.** The root README was restructured onto the shared `bare`-ecosystem skeleton and brought current with the last three releases. The lead now names both run modes (Docker *and* `npx`), a **Two ways to run** table up top contrasts Container vs Lite (where Beeper lives, deps, start command, first-run login) and states the same-single-file version-parity guarantee, and `Quick start` / `Lite mode` are retitled **Quick start (container)** / **Lite mode (`npx`)** with the now-redundant inline comparison table dropped. New **The MCP** section — the "what's inside" map — documents all 12 verbs grouped Read/triage · Write/act · Watch/reach, surfacing the previously undocumented `poll_messages` watch primitive + restart-safe cursor + `source` echo-guard (0.6.0) and `attachments[]` + `download_asset` byte reach (0.7.0). Stale `BEEPERBOX_IMAGE_TAG=0.7.0` pin example bumped to `0.8.0`. The npm-page `mcp/README.md` is deliberately kept as a focused lite-mode landing page (not a copy of the full README); its two cross-links were repointed to the renamed anchors (`#quick-start-container`, `#lite-mode-npx`). + ## [0.8.0] — 2026-06-16 `[MINOR]` **Lite mode** — a first-class, supported way to run beeperbox's MCP verb server standalone against a Beeper Desktop the user already runs locally (no Docker, no Electron, no Xvfb). Driven by [multis](https://github.com/hamr0/multis), beeperbox's first consumer: laptop users with Beeper already open get the verbs without the whole container, while the container stays the answer for always-on/VPS. Same single `mcp/server.js` either way, so the tool surface and `serverInfo.version` are identical by construction — lite mode is the *packaging*, not a fork. MINOR per the versioning policy (new runtime behavior — a boot preflight + new distribution mode), and it carries one bug fix that also mattered to the container. Validated live: the full send → restart → poll round-trip echo-guard persistence was proven against a real Beeper account running on the host. diff --git a/README.md b/README.md index 73f49ad..4d9d48e 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,25 @@ license: Apache 2.0

-**One Docker container that plugs your AI agent into 50+ messengers through a single MCP endpoint.** +**Plug your AI agent into 50+ messengers through a single MCP endpoint — in Docker, or as a one-line `npx`.** WhatsApp, iMessage, Signal, Telegram, Discord, Slack, Messenger, Instagram, LinkedIn, Google Messages, Matrix — everything [Beeper](https://www.beeper.com/) bridges, reachable from one HTTP or MCP endpoint instead of 50 per-platform SDKs, OAuth dances, and rate-limit quirks. If you only need Telegram, this is overkill — use [openclaw](https://github.com/openclaw/openclaw) or any BotFather library. If you need reach across many networks from one agent, keep reading. -## Quick start +## Two ways to run + +Same MCP server, same 12 tools, same `serverInfo.version` — by construction, because both modes run the [same single file](mcp/server.js). Pick by where Beeper lives: + +| | **Container** | **Lite** (`npx`) | +|---|---|---| +| Beeper Desktop | bundled, headless, in Docker | **you** supply it (already open on your machine) | +| Needs | Docker + compose | just Node 18+ | +| Start | `docker compose up -d` | `npx beeperbox` | +| Best for | always-on, VPS, headless | laptop users with Beeper already running | +| First-run login | noVNC at `:6080` | already done in your local Beeper | + +The container is the full appliance (headless Beeper + raw API + MCP). Lite mode is **just the MCP verb layer** pointed at a Beeper you already run — no Docker, no Electron, no Xvfb. New in [v0.8.0](CHANGELOG.md). + +## Quick start (container) Prereqs: Docker + compose plugin, ~1 GB disk, ~600 MB RAM, a Beeper account. @@ -29,7 +43,7 @@ curl -LO https://raw.githubusercontent.com/hamr0/beeperbox/master/docker-compose docker compose up -d ``` -Pulls the pre-built multi-arch image (`ghcr.io/hamr0/beeperbox:latest`, `linux/amd64` + `linux/arm64`). No clone, no build. Pin a version with `BEEPERBOX_IMAGE_TAG=0.7.0 docker compose up -d`, or track master with `:edge` (may break). +Pulls the pre-built multi-arch image (`ghcr.io/hamr0/beeperbox:latest`, `linux/amd64` + `linux/arm64`). No clone, no build. Pin a version with `BEEPERBOX_IMAGE_TAG=0.8.0 docker compose up -d`, or track master with `:edge` (may break). **2. Log in once** @@ -68,15 +82,7 @@ Done. All three are env-overridable (`BEEPERBOX_NOVNC_PORT`, `BEEPERBOX_HOST_PORT`, `BEEPERBOX_MCP_PORT`) so you can run multiple instances on one VPS. For remote access use SSH tunnel, Tailscale, or a TLS reverse proxy — never drop the `127.0.0.1` prefix. -## Lite mode - -Two ways to run beeperbox, same verb layer: - -| | **Container** (above) | **Lite mode** | -|---|---|---| -| Beeper Desktop | bundled, headless, in Docker | **you** supply it (already open on your machine) | -| Needs | Docker | just Node 18+ | -| Best for | always-on, VPS, headless | laptop users with Beeper already running | +## Lite mode (`npx`) Lite mode runs only the MCP verb server against a Beeper Desktop you already run locally — no Docker, no Electron, no Xvfb. It's the same single file the container runs, so the tool surface and `serverInfo.version` are identical by construction. @@ -117,6 +123,39 @@ BEEPER_TOKEN=your-token-here npx beeperbox --stdio **What lite mode is *not*:** it does not bundle or headless-run Beeper (that's the container's job). No new verbs, no transport changes — it's the same server, packaged and safe to run standalone. +## The MCP + +Not a thin proxy over Beeper's raw API — an **opinionated 12-tool verb layer** built for an LLM to drive. Every tool returns one normalized `Chat` / `Message` schema (so the agent never learns a second shape), propagates `chat_id` + `network` onto every message (no second lookup to know where a hit came from), and is documented in-schema for the model. Reach across all 50+ networks; the agent never knows which bridge it's talking to. + +**Read / triage** + +| Tool | What it does | +|---|---| +| `list_accounts` | Which networks are connected (WhatsApp, Telegram, Discord …) — slug + label + display name | +| `list_inbox` | Most recently active chats, with unread counts and last-activity time | +| `list_unread` | The "what needs me right now?" view — only chats with `unread_count > 0` | +| `get_chat` | One chat's current metadata by ID | +| `read_chat` | Recent messages of a chat, chronological, normalized | +| `search_messages` | Full-text search across every chat | + +**Write / act** + +| Tool | What it does | +|---|---| +| `send_message` | The headline write — reply or initiate; markdown, `reply_to_message_id`, returns the new message ID | +| `note_to_self` | The agent's private command/control channel — recorded, excluded from every inbox view | +| `react_to_message` | Lightest "I saw it" — a unicode emoji, visible to the sender on every network | +| `archive_chat` | The "done with this conversation" primitive (Beeper exposes no mark-as-read) | + +**Watch / reach** — the last two releases + +| Tool | What it does | +|---|---| +| `poll_messages` | Read-only **watch primitive**: "what arrived since this cursor?" Seed once, persist the opaque cursor, poll with zero side effects. The cursor is **restart-safe** — survives a container/process restart with no missed or duplicated messages. Each message carries a `source` field (`"api"` for beeperbox's own sends, `"external"` otherwise) so a poll loop never answers itself. *(v0.6.0)* | +| `download_asset` | The MCP-only way to reach attachment **bytes** (base64). Every `Message` now carries `attachments[]` (`{type, file_name, mime_type, src_url, size, is_voice_note}`); fetch by `src_url` or by `chat_id`+`message_id`. Byte-capped and timeout-bounded; a defense-in-depth guard refuses `file://` paths outside Beeper's media cache. *(v0.7.0)* | + +Reliable echo-suppression (`source` + the optional `client_tag` idempotency tag) means an agent on a poll loop can send *and* watch the same chat without mistaking its own messages for inbound — the wiring that lets [multis](https://github.com/hamr0/multis) drop its text-prefix hacks. + ## Build from source Only if you're hacking on the image itself or running air-gapped: diff --git a/mcp/README.md b/mcp/README.md index 9f56855..3c32f0b 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -4,7 +4,7 @@ This is the *lite* half of [beeperbox](https://github.com/hamr0/beeperbox). The full project ships a Docker image with a headless Beeper Desktop inside; lite mode is the same single-file, zero-dependency MCP server pointed at a Beeper Desktop **you** run on your laptop. Identical verb surface, identical version — you just supply Beeper. -- **Always-on / VPS / no local Beeper?** Use the [Docker image](https://github.com/hamr0/beeperbox#quick-start). +- **Always-on / VPS / no local Beeper?** Use the [Docker image](https://github.com/hamr0/beeperbox#quick-start-container). - **Beeper already open on your machine?** Use this. ## Prerequisites @@ -45,6 +45,6 @@ The server binds **loopback only** (`127.0.0.1`) by default, so it's safe with n There's no Docker restart policy in lite mode. For an always-on setup, run it under `systemd` or `pm2`. -See the [full README](https://github.com/hamr0/beeperbox#lite-mode) and [docs/GUIDE.md](https://github.com/hamr0/beeperbox/blob/master/docs/GUIDE.md) for the complete tool reference and the container build. +See the [full README](https://github.com/hamr0/beeperbox#lite-mode-npx) and [docs/GUIDE.md](https://github.com/hamr0/beeperbox/blob/master/docs/GUIDE.md) for the complete tool reference and the container build. [Apache-2.0](https://github.com/hamr0/beeperbox/blob/master/LICENSE)