beeperbox 0.7.0 → 0.8.1

package/README.md

@@ -1,18 +1,28 @@
-# beeperbox (lite mode)
+```
+                ╭──────────────────────────────────╮
+                │  ╔╗ ╔═╗╔═╗╔═╗╔═╗╦═╗╔╗ ╔═╗ ╦ ╦    │
+                │  ╠╩╗╠╣ ╠╣ ╠═╝╠╣ ╠╦╝╠╩╗║ ║ ╚╦╝    │
+                │  ╚═╝╚═╝╚═╝╩  ╚═╝╩╚═╚═╝╚═╝ ╩ ╩    │
+                │   one agent ──→ 50+ messengers   │
+                ╰──────────────────────────────────╯
+```
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/beeperbox"><img src="https://img.shields.io/npm/v/beeperbox?label=npm&color=2a4f8c" alt="npm version"></a>
+  <a href="https://github.com/hamr0/beeperbox"><img src="https://img.shields.io/badge/source-github-2a4f8c" alt="source on GitHub"></a>
+  <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
+</p>
 
 **Run beeperbox's MCP verb server against a Beeper Desktop you already have open — no Docker, no Electron, no Xvfb.**
 
 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
+## 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 |
@@ -35,15 +55,29 @@ BEEPER_TOKEN=your-token-here npx beeperbox --stdio
 | `MCP_PORT` | MCP HTTP port | `23375` |
 | `MCP_AUTH_TOKEN` | Optional bearer guard on the MCP endpoint | unset (open on loopback) |
 | `MCP_ALLOWED_HOSTS` | Host/Origin allowlist | `localhost,127.0.0.1,::1` |
+| `MCP_BIND_ADDR` | Interface the MCP server binds | `127.0.0.1` (loopback) |
 
 ## Security
 
-The server binds `0.0.0.0` but is meant to stay loopback-only: it's safe on `127.0.0.1` with no auth. To expose it beyond your machine, set `MCP_AUTH_TOKEN` **and** `MCP_ALLOWED_HOSTS`, and put it behind a tunnel (SSH / Tailscale / TLS reverse proxy) — never raw on a public interface.
+The server binds **loopback only** (`127.0.0.1`) by default, so it's safe with no auth — only processes on your own machine can reach it. Don't just set it to `0.0.0.0`: a same-network attacker can spoof the `Host` header past the allowlist and reach the full tool surface (read every message, send across every network) unauthenticated. To expose it deliberately, set `MCP_BIND_ADDR=0.0.0.0` **and** `MCP_AUTH_TOKEN`, and put it behind a tunnel (SSH / Tailscale / TLS reverse proxy) — never raw on a public interface.
 
 ## Supervision
 
 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#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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beeperbox",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Lite mode for beeperbox — the opinionated MCP verb server for Beeper Desktop, run standalone against a Beeper you already have open (no Docker, no Electron). The full headless-Beeper-in-Docker build lives at github.com/hamr0/beeperbox.",
   "bin": {
     "beeperbox": "server.js"
@@ -34,7 +34,7 @@
     "url": "git+https://github.com/hamr0/beeperbox.git",
     "directory": "mcp"
   },
-  "homepage": "https://github.com/hamr0/beeperbox#lite-mode",
+  "homepage": "https://github.com/hamr0/beeperbox#lite-mode-npx",
   "bugs": "https://github.com/hamr0/beeperbox/issues",
   "author": "hamr0",
   "license": "Apache-2.0"

package/server.js

@@ -22,6 +22,18 @@ const PORT = parseInt(process.env.MCP_PORT || '23375', 10);
 const BEEPER_API = process.env.BEEPER_API || 'http://127.0.0.1:23373';
 const BEEPER_TOKEN = process.env.BEEPER_TOKEN || '';
 
+// Bind address. Defaults to LOOPBACK (127.0.0.1) — the safe default for lite
+// mode (`npx beeperbox` on a laptop), where the process listens directly on the
+// host with no Docker loopback publish in front of it. Binding 0.0.0.0 there
+// would put the full tool surface (read every message, send across every
+// network) on the LAN, reachable unauthenticated by anyone who can spoof the
+// `Host` header — a non-browser attacker trivially can. The container needs
+// 0.0.0.0 (a Docker published port can't reach a loopback-bound process) and
+// sets MCP_BIND_ADDR=0.0.0.0 via the image ENV; there the loopback *publish*
+// (`127.0.0.1:23375:23375`), not the bind, is the boundary. To expose lite mode
+// deliberately, set MCP_BIND_ADDR=0.0.0.0 AND MCP_AUTH_TOKEN AND a tunnel.
+const BIND_ADDR = process.env.MCP_BIND_ADDR || '127.0.0.1';
+
 // ─── http transport hardening ─────────────────────────────────────
 // The HTTP transport is the network-exposed surface (stdio is local-only).
 // Three guards, all configurable so they don't break the documented
@@ -34,10 +46,11 @@ const BEEPER_TOKEN = process.env.BEEPER_TOKEN || '';
 //                       Defaults to loopback; set it for reverse proxies.
 //   MCP_MAX_BODY      — max request body bytes (default 1 MiB) so a large
 //                       POST can't grow the in-memory buffer unbounded.
-// The listener stays bound to 0.0.0.0 ON PURPOSE: a Docker published port
-// is unreachable if the in-container process binds 127.0.0.1, so loopback
-// binding here would break `127.0.0.1:23375:23375`. Auth + Host/Origin
-// checks are the defense, not the bind address.
+// The bind address is MCP_BIND_ADDR (see above): loopback by default (safe for
+// lite mode), 0.0.0.0 in the container (where the loopback PUBLISH is the
+// boundary). In the container, Auth + Host/Origin are the in-container defense;
+// in lite mode the loopback BIND is, because a non-browser client can spoof the
+// Host header past the allowlist.
 const MCP_AUTH_TOKEN = process.env.MCP_AUTH_TOKEN || '';
 const MCP_ALLOWED_HOSTS = new Set(
   (process.env.MCP_ALLOWED_HOSTS || 'localhost,127.0.0.1,::1,[::1]')
@@ -1217,8 +1230,8 @@ function startHttpTransport() {
     });
   });
 
-  server.listen(PORT, '0.0.0.0', () => {
-    console.log(`[beeperbox-mcp] listening on http://0.0.0.0:${PORT}`);
+  server.listen(PORT, BIND_ADDR, () => {
+    console.log(`[beeperbox-mcp] listening on http://${BIND_ADDR}:${PORT}${BIND_ADDR === '0.0.0.0' ? ' (all interfaces — rely on a loopback publish or set MCP_AUTH_TOKEN)' : ' (loopback only)'}`);
     console.log(`[beeperbox-mcp] beeper api: ${BEEPER_API}`);
     console.log(`[beeperbox-mcp] beeper token: ${BEEPER_TOKEN ? 'set' : 'NOT SET (set BEEPER_TOKEN env var)'}`);
     console.log(`[beeperbox-mcp] http auth: ${MCP_AUTH_TOKEN ? 'required (MCP_AUTH_TOKEN set)' : 'OPEN — set MCP_AUTH_TOKEN to require a bearer token'}`);
@@ -1288,6 +1301,7 @@ module.exports = {
   // version + tool names here is what guarantees the two builds can't drift.
   VERSION,
   TOOL_NAMES: TOOLS.map((t) => t.name),
+  BIND_ADDR,
   ledgerPath,
   encodeCursor,
   decodeCursor,