wazap-mcp 0.9.0 → 0.9.3

package/AGENT.md

@@ -0,0 +1,17 @@
+# wazap setup, driven by an agent
+
+You are setting up WhatsApp access for the person you are working with. Use the pairing-code flow (it is plain text); never the QR.
+
+wazap keeps stdout for the MCP protocol and writes every human-readable line to stderr, so read stderr as well: run each command with `2>&1`.
+
+1. Run `npx wazap-mcp status --json`. If `linked` is true, skip to step 5.
+2. Ask the person for their WhatsApp number in international format (e.g. +15550100) and whether the agent may send messages (default: no).
+3. Start the link IN THE BACKGROUND and keep reading its output:
+   `npx wazap-mcp login --phone <number> --no-writes --yes 2>&1` (or `--writes`).
+   Within ~10 s the output contains a line `pairing code: XXXX-XXXX`.
+4. Show the person exactly: "On your phone: WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead → enter XXXX-XXXX". Keep reading the output until `Linked as …` and then `Synced N chats …` appear (up to 3 minutes). If the output says the code expired, run step 3 again.
+5. Register wazap with the client you are running in: `npx wazap-mcp connect <client>` where <client> is claude-code, claude-desktop, cursor, codex, vscode or gemini. Tell the person what the command printed as `Next`.
+6. Verify: `npx wazap-mcp status --json` must show `linked: true` and no failing check. If the client needs a restart, say so; otherwise call the `get_status` tool and then `learn`.
+7. Done when `get_status` returns `connected`. Then offer: "what did I miss on WhatsApp today?"
+
+Errors: every wazap error prints `✗ message` and `→ fix`; do what the fix says, do not retry blindly. One process owns the session, so while the `login` of step 3 runs, no server and no other wazap command may touch the same data dir; two servers on one data dir refuse to start. Stop the other one first.

package/README.md

@@ -19,18 +19,30 @@ WhatsApp multi-device protocol over a WebSocket.
 The npm package is `wazap-mcp`; the command it installs is `wazap`.
 
 ```bash
-npx wazap-mcp login                  # link your account with a pairing code
-npx wazap-mcp connect claude-code    # write the MCP entry for your agent
+npx wazap-mcp setup
 ```
 
+That is the whole install. It links your account, finds the MCP clients
+installed on this machine, writes their config and tells you what to restart.
+
+Or have your agent do it. Paste this:
+
+*Set up WhatsApp for me: run `npx wazap-mcp setup --agent` and follow what it prints.*
+
 Then ask your agent: *"what did I miss on WhatsApp today?"*
 
-`login` asks for your number in international format, prints an 8-character
-code, and you enter it on your phone under **Settings → Linked devices → Link a
-device → Link with phone number instead**. Prefer a QR code? `npx wazap-mcp login --qr`.
+Below are the steps `setup` runs for you. Each is still its own command when you
+want to run it by hand.
+
+`npx wazap-mcp login` shows a QR code; scan it from **Settings → Linked devices
+→ Link a device**. No camera handy, or linking over SSH? `npx wazap-mcp login --phone +15550100`
+prints an 8-character code you type under *Link with phone number instead*.
 It ends by asking whether the agent may send messages; the answer is no unless
 you say yes, and `npx wazap-mcp config writes on` changes it later.
 
+`npx wazap-mcp connect claude-code` writes the MCP entry for one client. The
+table under **Connect a client** has the rest.
+
 `npx wazap-mcp` on its own is safe to run: it prints where you stand and what to do
 next, and starts no server. When something is off, `npx wazap-mcp status` is the
 first thing to run — it checks Node, the data directory, the lock, the
@@ -122,7 +134,7 @@ wazap ships five [Agent Skills](https://agentskills.io) that teach an agent the
 
 | Skill | What the agent does |
 | --- | --- |
-| `wazap-setup` | Diagnose with `wazap status`, link by pairing code, connect a client with `wazap connect`, repair an expired session |
+| `wazap-setup` | Diagnose with `wazap status`, link by QR or pairing code, connect a client with `wazap connect`, repair an expired session |
 | `whatsapp-inbox` | "What did I miss?" Triage into *needs you / FYI / noise*, ranked, plus forgotten replies. Read-only |
 | `whatsapp-recall` | "Find the invoice Dan sent." Search with query variants, page back in time, download and read the file. Read-only |
 | `whatsapp-groups` | Catch up on a 300-message group: decisions, dates, what is asked of you. Read-only |
@@ -174,14 +186,32 @@ created `0700` with credentials written `0600`:
   history/      per-chat message history, so a restart is not amnesia
   store.json    chat-list snapshot
   server.lock   pid of the running server
+  daemon.json   loopback endpoint a second wazap bridges to
   .env          optional settings, see .env.example
 ```
 
 Credential writes go to a temp file and are renamed into place, so killing the
 process mid-write cannot leave you re-linking your phone.
 
-One server per data directory: a second `wazap serve` on the same directory
-exits with code 2 and tells you the pid of the one already running.
+## Several clients at once
+
+Claude Desktop, Claude Code and Cursor each launch their own `wazap`. WhatsApp
+allows one socket per linked device, so they share one session instead of
+fighting over it. The first `wazap` on a data directory owns the session and
+opens an MCP endpoint on `127.0.0.1`; every later one bridges to it over that
+endpoint. There is nothing to configure, and no client can tell the difference.
+The owner publishes `<data-dir>/daemon.json` (`0600`) with its pid, its port
+and the token a bridge authenticates with.
+
+A bridge serves whatever the owner exposes, so an owner started `--read-only`
+makes every client read-only, whatever flags that client was launched with.
+
+When the owner exits, the bridges exit with it, and the next `wazap` a client
+starts becomes the new owner.
+
+`WAZAP_NO_SHARE=1` opts out: a second `wazap` on the same directory exits with
+code 2 naming the pid of the one already running. An explicit `--http` is a
+server of its own rather than a bridge, and is refused the same way.
 
 ## Read-only mode
 
@@ -218,7 +248,7 @@ Run wazap on a server of your own when the agent is not on your laptop: another
 ```bash
 npm install -g wazap-mcp
 sudo useradd --system --home /var/lib/wazap --create-home wazap
-sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +40722123456   # pairing code works over SSH
+sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +15550100   # pairing code works over SSH
 sudo -u wazap tee /var/lib/wazap/.env >/dev/null <<END
 WAZAP_READ_TOKEN=$(openssl rand -hex 32)
 WAZAP_WRITE_TOKEN=$(openssl rand -hex 32)
@@ -235,7 +265,7 @@ The unit binds loopback only. Put TLS in front with the two-line [`deploy/Caddyf
 ```bash
 git clone https://github.com/razvangirgiz/wazap && cd wazap
 printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env
-docker compose run --rm wazap login --phone +40722123456   # once; the session lands in the wazap-data volume
+docker compose run --rm wazap login --phone +15550100   # once; the session lands in the wazap-data volume
 docker compose up -d
 curl -s http://127.0.0.1:8766/healthz
 ```

package/dist/auth-state.js

@@ -106,7 +106,10 @@ export function readLinkedAccount(dir) {
     catch {
         throw new WazapError("SESSION_CORRUPT", `Stored credentials in ${dir} are unreadable.`, RESET_FIX);
     }
-    if (!creds.registered || !creds.me?.id)
+    // Baileys itself treats an account with `me` as linked (socket.js: `if (!creds.me)`
+    // pairs a device, else logs in). `registered` is only ever set by the
+    // pairing-code flow, so a QR-linked session would look unlinked forever.
+    if (!creds.me?.id)
         return null;
     const number = creds.me.id.split(":")[0].split("@")[0];
     return { id: `${number}@s.whatsapp.net`, name: creds.me.name || "", number };

package/dist/banner.js

@@ -1,7 +1,13 @@
-export const BANNER = `██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
+import { brand, dim } from "./ui.js";
+export const BANNER_ART = `██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
 ██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
 ██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
 ██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
 ╚███╔███╔╝██║  ██║███████╗██║  ██║██║
- ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝
-WhatsApp for your AI agent.`;
+ ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝`;
+export const TAGLINE = "WhatsApp for your AI agent.";
+export const BANNER = `${BANNER_ART}\n${TAGLINE}`;
+/** Painted per line, so a wrapped terminal cannot bleed the colour onward. */
+export function banner() {
+    return `${BANNER_ART.split("\n").map(brand).join("\n")}\n${dim(TAGLINE)}`;
+}

package/dist/bridge.js

@@ -0,0 +1,64 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, CallToolResultSchema, ListToolsRequestSchema, ListToolsResultSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { WAZAP_VERSION } from "./config.js";
+import { readDaemon } from "./daemon.js";
+import { log } from "./logger.js";
+const HEARTBEAT_MS = 1_000;
+/**
+ * Serve this client from the session another process already owns: an MCP server
+ * on our stdio, every tool call forwarded to the daemon's loopback endpoint and
+ * its answer returned untouched.
+ *
+ * `daemonFile` is here because the heartbeat re-reads the sidecar, and DaemonInfo
+ * carries no path.
+ */
+export async function runBridge(daemon, daemonFile) {
+    let left = false;
+    /** Exit 1 so the client restarts us, and the restart becomes the new daemon. */
+    const leave = (reason) => {
+        if (left)
+            return;
+        left = true;
+        log(`${reason}, exiting so the next start can own the session`);
+        process.exit(1);
+    };
+    const client = new Client({ name: "wazap-bridge", version: WAZAP_VERSION });
+    await client.connect(new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${daemon.port}/mcp`), {
+        requestInit: { headers: { Authorization: `Bearer ${daemon.token}` } },
+    }));
+    const caps = client.getServerCapabilities() ?? {};
+    const server = new Server(client.getServerVersion() ?? { name: "wazap", version: daemon.version }, {
+        // Only what we forward: the daemon has no resources or prompts, and we have
+        // no handler for them.
+        capabilities: { tools: caps.tools ?? {} },
+        instructions: client.getInstructions(),
+    });
+    server.setRequestHandler(ListToolsRequestSchema, (req) => client.request({ method: "tools/list", params: req.params }, ListToolsResultSchema));
+    server.setRequestHandler(CallToolRequestSchema, (req) => client.request({ method: "tools/call", params: req.params }, CallToolResultSchema));
+    client.onclose = () => leave(`the session holder (pid ${daemon.pid}) closed the connection`);
+    client.onerror = () => leave(`lost the connection to the session holder (pid ${daemon.pid})`);
+    // A dead daemon does not close the client: the transport retries its stream and
+    // reports nothing, measured. So the liveness of the pid is ours to watch.
+    const heartbeat = setInterval(() => {
+        if (readDaemon(daemonFile)?.pid !== daemon.pid) {
+            leave(`the session holder (pid ${daemon.pid}) gave up the session`);
+            return;
+        }
+        try {
+            process.kill(daemon.pid, 0);
+        }
+        catch {
+            leave(`the session holder (pid ${daemon.pid}) is gone`);
+        }
+    }, HEARTBEAT_MS);
+    heartbeat.unref();
+    await server.connect(new StdioServerTransport());
+    log(`sharing the WhatsApp session held by pid ${daemon.pid}`);
+    // Our own client leaving is not a failure. The upstream stream holds the event
+    // loop open, so without this the bridge outlives the client it was started for.
+    process.stdin.on("end", () => process.exit(0));
+    process.stdin.on("close", () => process.exit(0));
+}