diff --git a/CHANGELOG.md b/CHANGELOG.md index b57c612..3ced85b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ Published tags on GHCR: `:X.Y.Z` (exact, immutable), `:X.Y` (rolling within a mi ### 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`). +- **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` was reshaped onto the same `bare`-ecosystem skeleton (banner, badges, quick start, a compact 12-verb map, the bare-ecosystem footer) but kept lighter than the full README — still a focused lite-mode landing page, not a copy; cross-links repointed to the renamed/added anchors (`#quick-start-container`, `#the-mcp`). ## [0.8.0] — 2026-06-16 `[MINOR]` diff --git a/mcp/README.md b/mcp/README.md index 3c32f0b..967ac21 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -1,4 +1,17 @@ -# beeperbox (lite mode) +``` + ╭──────────────────────────────────╮ + │ ╔╗ ╔═╗╔═╗╔═╗╔═╗╦═╗╔╗ ╔═╗ ╦ ╦ │ + │ ╠╩╗╠╣ ╠╣ ╠═╝╠╣ ╠╦╝╠╩╗║ ║ ╚╦╝ │ + │ ╚═╝╚═╝╚═╝╩ ╚═╝╩╚═╚═╝╚═╝ ╩ ╩ │ + │ one agent ──→ 50+ messengers │ + ╰──────────────────────────────────╯ +``` + +

+ npm version + source on GitHub + license: Apache 2.0 +

**Run beeperbox's MCP verb server against a Beeper Desktop you already have open — no Docker, no Electron, no Xvfb.** @@ -7,12 +20,9 @@ This is the *lite* half of [beeperbox](https://github.com/hamr0/beeperbox). The - **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 +## Quick start -1. **Beeper Desktop** running locally. -2. **Developer API enabled:** Beeper → **Settings → Developers** → enable the API and create an access token (the same token the container uses). - -## Run +**Prereqs:** Beeper Desktop running locally, with the Developer API enabled — Beeper → **Settings → Developers** → enable the API and create an access token (the same token the container uses). ```sh BEEPER_TOKEN=your-token-here npx beeperbox @@ -20,12 +30,22 @@ BEEPER_TOKEN=your-token-here npx beeperbox That starts the MCP HTTP server on `http://127.0.0.1:23375`, pointed at the local Beeper Desktop API on `http://127.0.0.1:23373`. On boot it logs a one-line reachability verdict (`preflight OK: … N account(s)` or `preflight FAIL: …`) so a misconfigured token or API is obvious immediately. -For stdio transport (Claude Code, Cursor, Cline, Continue, bareagent): +For stdio transport (Claude Code, Cursor, Cline, Continue, [bareagent](https://npmjs.com/package/bare-agent)): ```sh BEEPER_TOKEN=your-token-here npx beeperbox --stdio ``` +## The 12 tools + +One opinionated MCP verb layer over Beeper — every tool returns a normalized `Chat` / `Message` schema, propagates `chat_id` + `network` onto every message, and is documented in-schema for the model. Reach across all 50+ networks without knowing which bridge you're talking to. + +- **Read / triage** — `list_accounts` · `list_inbox` · `list_unread` · `get_chat` · `read_chat` · `search_messages` +- **Write / act** — `send_message` · `note_to_self` · `react_to_message` · `archive_chat` +- **Watch / reach** — `poll_messages` (read-only watch primitive, restart-safe cursor, `source` echo-guard) · `download_asset` (attachment bytes; every message carries `attachments[]`) + +Full schemas and usage in the [main README](https://github.com/hamr0/beeperbox#the-mcp). + ## Config | Env | Meaning | Default | @@ -45,6 +65,19 @@ 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-npx) 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#the-mcp) and [docs/GUIDE.md](https://github.com/hamr0/beeperbox/blob/master/docs/GUIDE.md) for the complete tool reference and the container build. + +## The bare ecosystem + +Local-first, composable agent infrastructure. Same API patterns throughout — mix and match, each module works standalone. + +- **[bareagent](https://npmjs.com/package/bare-agent)** — the think→act→observe loop. *Goal in → coordinated actions out.* +- **[bareguard](https://npmjs.com/package/bareguard)** — the single gate every action passes through. *Action in → allow / deny / ask-a-human out.* +- **[litectx](https://npmjs.com/package/litectx)** — code + memory graph with activation decay. *Query in → ranked context out.* +- **[barebrowse](https://npmjs.com/package/barebrowse)** — a real browser for agents. *URL in → pruned snapshot out.* +- **[baremobile](https://npmjs.com/package/baremobile)** — Android + iOS device control. *Screen in → pruned snapshot out.* +- **beeperbox** *(this)* — 50+ messaging networks via one MCP server. *Chat in → unified message stream out.* + +## License -[Apache-2.0](https://github.com/hamr0/beeperbox/blob/master/LICENSE) +[Apache-2.0](https://github.com/hamr0/beeperbox/blob/master/LICENSE). Independent wrapper around Beeper Desktop, no affiliation with Beeper / Automattic.