wazap-mcp 0.9.8 → 0.11.0

package/AGENT.md

@@ -6,12 +6,13 @@ wazap keeps stdout for the MCP protocol and writes every human-readable line to
 
 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:
+3. If you already have the `whatsapp` tools (the Claude Desktop bundle, or any client wazap is connected to), call `link_account` with the number. It returns the code within ~10 s and needs no terminal. Otherwise 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`.
+4. Show the person exactly: "On your phone: WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead → enter XXXX-XXXX". After `link_account`, call `get_status` every 10 seconds until it says `connected` (up to 3 minutes); after the command, keep reading the output until `Linked as …` and then `Synced N chats …` appear. If the code expired, run step 3 again.
+5. If step 1 reported `install.kind: "npx"`, run `npm i -g wazap-mcp` first: Claude Desktop and the background service cannot launch from the npx cache, which npm clears. 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`. Then, for claude-code, codex, cursor and opencode, run `npx wazap-mcp skills install <client>`, which copies the five workflow skills where that client reads them. The other clients need no such step, because the server hands them the same five workflows as MCP prompts.
 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?"
+8. Ask whether wazap should keep running after this client closes, and whether cloud agents should reach it. For the first, run `npx wazap-mcp service install`, which writes a launchd agent or a systemd user unit and starts it. For the second, also run `npx wazap-mcp expose`. It opens a tunnel, prints an https URL and a consent password, and restarts the service. Give an agent the URL only. The password is for the person, on their consent page; never paste it into a chat, a config file or a message.
 
 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

@@ -8,7 +8,7 @@
 ```
 
 **WhatsApp for your AI agent.** An MCP server that puts your WhatsApp account —
-chats, messages, media, contacts, groups — behind 23 tools any MCP client can
+chats, messages, media, contacts, groups — behind 25 tools any MCP client can
 call. Pairing-code login, no browser, no phone-number reseller, ~20 MB of RAM.
 
 Built on [Baileys](https://github.com/WhiskeySockets/Baileys), which speaks the
@@ -23,7 +23,12 @@ 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.
+installed on this machine, writes their config, copies the five skills where
+that client reads them, and tells you what to restart. When you started through
+`npx`, `setup` offers to install wazap globally so Claude Desktop and the
+background service have a path that does not change. It also offers to
+`brew install` whisper-cpp, ffmpeg or Tailscale when a step needs one and it is
+missing, and to restart Claude Desktop itself once it has connected it.
 
 ### Or the path your harness prefers
 
@@ -82,7 +87,7 @@ it would write.
 | `gemini` | `~/.gemini/settings.json` |
 | `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
 | `opencode` | `mcp.whatsapp` in `~/.config/opencode/opencode.json` |
-| anything remote | client's MCP URL field: `https://your-host/mcp` with header `Authorization: Bearer <token>` (see [Self-host](#self-host)) |
+| anything remote | client's MCP URL field: `https://your-host/mcp` with header `Authorization: Bearer <token>`, or just the URL once [OAuth](#hosted-agents-oauth) is on (see [Self-host](#self-host)) |
 
 ### Other MCP clients
 
@@ -159,26 +164,93 @@ Download `wazap-<version>.mcpb` from [Releases](https://github.com/razvangirgiz/
 and double-click it. Claude Desktop installs the server, its Node dependencies
 and the icon, and shows two settings: **Read-only**, ticked, and **Data
 directory**, empty. `wazap connect claude-desktop` does the same job by editing
-`claude_desktop_config.json`, and needs `npx` at launch; the bundle does not.
+`claude_desktop_config.json`. Claude Desktop starts its servers without your
+shell PATH, so that entry is the absolute path to `node` when wazap is installed
+globally, and `npx` otherwise; `wazap setup` checks that the entry it wrote is
+one Claude Desktop can actually launch.
 
-Linking the account still needs a terminal once: `npx wazap-mcp login`. The
-bundle reads the session that login writes to `~/.wazap`.
+Then ask Claude to link your WhatsApp. It calls `link_account` with your number,
+hands back an 8-character code, and you type that code into **WhatsApp →
+Settings → Linked devices → Link a device → Link with phone number instead**.
+No terminal at any point. `npx wazap-mcp login` does the same job from a shell
+when you have one.
 
 Untick **Read-only** to let Claude send. It ships ticked because a bundle that
 can message people from your number before you have said so is the wrong
 default, and because the setting cannot be left unanswered: the manifest format
 has no way to omit an argument, so the box you see is the answer the server gets.
+`link_account` is registered either way. Read-only exists to stop Claude
+messaging people from your number, and relinking your own dead session messages
+nobody.
 
 Build it yourself with `npm run bundle:mcpb`, which stages `dist/`, the
 manifest, the icon and a fresh production `node_modules`, then packs them with
 [`@anthropic-ai/mcpb`](https://github.com/modelcontextprotocol/mcpb).
 
+### Keep it running
+
+A wazap started by a client lives as long as that client does. Quit Claude Code
+and the session is gone until you open it again. Two commands change that.
+Staying up and being reachable are separate choices.
+
+```bash
+npx wazap-mcp service install
+```
+
+That writes a launchd agent on macOS (`~/Library/LaunchAgents/com.wazap.server.plist`)
+or a systemd user unit on Linux (`~/.config/systemd/user/wazap.service`), starts
+it, and waits for `/healthz` to answer. The unit runs `serve --http` on
+`127.0.0.1:8766` with the absolute path of this Node and this install, so it
+survives a reboot and a logout. Point any client at
+`http://127.0.0.1:8766/mcp`, or keep using the stdio entry. A second wazap on
+the same data directory becomes a bridge onto the session this one holds.
+
+`service status` prints the pid, the health check and whether the unit still
+runs the version you have installed. `service logs` tails it. `service restart`
+picks up an upgrade; `service uninstall` removes the unit and leaves your
+session and credentials alone. `wazap login` needs the session to itself, so it
+stops the service, pairs, and starts it again on its own.
+
+A sleeping Mac is an offline wazap. System Settings → Lock Screen, or Battery →
+Options, has the switch that keeps it awake on power.
+
+```bash
+npx wazap-mcp expose
+```
+
+That gives the running service a public `https` URL, for agents that are not on
+this machine: a cloud agent, claude.ai, ChatGPT. It uses Tailscale Funnel if
+`tailscale` is installed, Cloudflare Tunnel if `cloudflared` is, opens the
+tunnel, writes `WAZAP_PUBLIC_URL` and a fresh `WAZAP_OAUTH_PASSWORD` into
+`<data-dir>/.env`, restarts the service and checks the URL from here. It then
+prints the MCP URL and the password once.
+
+Give an agent the URL only. It signs in on a consent page on your own host with
+that password and picks read or read-and-send there; `wazap status` lists who
+holds a grant. See [Hosted agents (OAuth)](#hosted-agents-oauth) for what that
+page does. `npx wazap-mcp expose off` takes the tunnel down and keeps the
+password, so the next `expose` hands agents the same one.
+
+`npx wazap-mcp setup` asks all of this once, as its fourth step.
+
+### Upgrade
+
+```bash
+npx wazap-mcp update
+```
+
+One command for what used to be three. It compares this install against the
+registry, installs the new package when wazap is global, restarts the service so
+it runs the new code, and copies the new skills into every harness that keeps
+them. `--dry-run` prints the plan and touches nothing.
+
 ## Tools
 
 | Tool | Kind | What it does |
 | --- | --- | --- |
 | `learn` | read | The guide to every tool, id format and error code. Call it first. |
 | `get_status` | read | Connection status, sync state, linked account, named-contact count, versions, data dir. |
+| `link_account` | read | Pair the account without a terminal: returns the code to type into the phone. Registered in read-only mode too. |
 | `list_chats` | read | Conversations newest-first; filter `all`/`unread`/`groups`/`individual`/`archived`. |
 | `read_messages` | read | Messages in a chat; `before` pages further back, pulling older history from the phone; `types` narrows to one or more message types, e.g. `["call"]`. |
 | `get_recent_messages` | read | Everything from the last N hours, grouped by chat. The catch-up tool. `include_system` adds WhatsApp's own notices, `types` narrows to one or more message types. |
@@ -238,6 +310,10 @@ wazap transcribe download            # fetch and verify the model
 wazap transcribe test recording.ogg  # prove it before you trust it
 ```
 
+`wazap setup` and `wazap transcribe download` offer that `brew install`
+themselves when either binary is missing, and go straight on to the model in the
+same run. `--no-brew` turns the offer off everywhere.
+
 Models land in `<data-dir>/models/` and are checked against a SHA-256 pinned in
 the source; an interrupted download resumes where it stopped.
 
@@ -300,22 +376,25 @@ wazap ships five [Agent Skills](https://agentskills.io) that teach an agent the
 | `whatsapp-groups` | Catch up on a 300-message group: decisions, dates, what is asked of you. Read-only |
 | `whatsapp-send` | Draft in the chat's own register, show recipient and text, send only after the user says yes |
 
-Install everything (server and skills) as a Claude Code plugin:
+`wazap setup` copies them into every client it connects, so there is usually
+nothing to run. The command behind it, for a harness `setup` never offered or
+for a checkout you want to install by hand:
 
-```
-/plugin marketplace add razvangirgiz/wazap
-/plugin install wazap@wazap
+```bash
+npx wazap-mcp skills install codex     # or claude-code, cursor, opencode, agents
 ```
 
-Every other harness gets them with one command:
+With no harness named it installs into every client it finds on this machine.
+For Claude Code the other route is the plugin, which carries the server as well:
 
-```bash
-npx wazap-mcp skills install codex     # or cursor, opencode, agents
+```
+/plugin marketplace add razvangirgiz/wazap
+/plugin install wazap@wazap
 ```
 
 | Harness | Where the five directories land |
 | --- | --- |
-| `claude-code` | nowhere — the plugin above already carries them |
+| `claude-code` | `~/.claude/skills/` |
 | `codex` | `~/.agents/skills/`, the directory Codex documents for user skills. Cursor and OpenCode read it too |
 | `cursor` | `~/.cursor/skills/` |
 | `opencode` | `~/.config/opencode/skills/` |
@@ -324,6 +403,13 @@ npx wazap-mcp skills install codex     # or cursor, opencode, agents
 Re-running overwrites, so an upgrade is the same command. `--dry-run` lists
 what it would copy.
 
+A client with no skills directory is not left out. The server registers each of
+the five as an MCP prompt of the same name, and sends a short `instructions`
+block that names all five and says when each applies, so an agent that never saw
+the skill files still follows them. That is how Claude Desktop, VS Code and
+Windsurf get the workflows. A bridged session and a self-hosted HTTP server
+carry them the same way.
+
 ## Errors
 
 Every failure is a structured `{ error, message, fix }` rather than a stack
@@ -331,7 +417,8 @@ trace, so an agent can decide whether to retry, ask the user, or stop.
 
 | Code | Meaning |
 | --- | --- |
-| `NOT_LINKED` | No account linked. Run `npx wazap-mcp login`. |
+| `NOT_LINKED` | No account linked. Call `link_account`, or run `npx wazap-mcp login`. |
+| `ALREADY_LINKED` | `link_account` was called on a session that is already linked. Call `get_status`. |
 | `SESSION_EXPIRED` | Unlinked from the phone. Run `npx wazap-mcp login`. |
 | `SESSION_CORRUPT` | Credentials unreadable. Run `npx wazap-mcp logout` then `login`. |
 | `NOT_CONNECTED` | Still connecting or reconnecting. |
@@ -363,6 +450,7 @@ created `0700` with credentials written `0600`:
   store.json    chat-list snapshot
   server.lock   pid of the running server
   daemon.json   loopback endpoint a second wazap bridges to
+  oauth.json    registered agents and hashed OAuth grants, when OAuth is on
   .env          optional settings, see .env.example
 ```
 
@@ -410,10 +498,14 @@ WAZAP_WRITE_TOKEN=$(openssl rand -hex 32) \
 npx wazap-mcp serve --http --host 0.0.0.0 --port 8766
 ```
 
-Streamable HTTP at `/mcp`, with a health check at `/healthz`. Two bearer tokens:
+Streamable HTTP at `/mcp`, with a health check at `/healthz`. That check answers
+`{ ok, status, since }`. It turns 503 once the socket has been anything but
+connected for two minutes, so a tunnel or a monitor sees a real outage rather
+than a reconnect in progress. Two bearer tokens:
 the read token gets the read tools, the write token also unlocks the write
 tools, so a leaked read token can never message anyone. wazap refuses to bind a
-non-loopback address without a read token.
+non-loopback address without a read token. Agents that cannot carry a header
+sign in with [OAuth](#hosted-agents-oauth) instead.
 
 ## Self-host
 
@@ -448,9 +540,70 @@ curl -s http://127.0.0.1:8766/healthz
 
 The container publishes `8766` on loopback only; add the same TLS proxy in front. Upgrading is `git pull && docker compose up -d --build`; the volume keeps the session.
 
+### From a machine without a public address
+
+A laptop or a box behind NAT can still serve hosted agents through a tunnel, with no port opened and TLS done at the edge. `npx wazap-mcp expose` does the whole thing with Tailscale Funnel or Cloudflare Tunnel, whichever is installed. See [Keep it running](#keep-it-running).
+
+wazap keeps binding loopback either way; only the tunnel reaches it.
+
+<details>
+<summary>By hand, with Cloudflare Tunnel and a domain on Cloudflare</summary>
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create wazap
+cloudflared tunnel route dns wazap wazap.example.com
+cloudflared tunnel run --url http://127.0.0.1:8766 wazap
+```
+
+Set `WAZAP_PUBLIC_URL=https://wazap.example.com` for OAuth and keep `cloudflared` running the way you keep wazap running (a systemd unit, a launchd agent). Tailscale Funnel or ngrok work the same way: whatever ends at `https://your-host` with `/mcp` behind it.
+
+</details>
+
 ### Which clients can reach it
 
-Claude Code, Claude Desktop, Cursor, Codex, VS Code and any client with an "MCP URL + header" field connect with the bearer token. claude.ai Connectors require OAuth rather than a static token, so they cannot use a self-hosted wazap yet. Keep the read token in clients that only need to read; hand out the write token deliberately.
+Claude Code, Claude Desktop, Cursor, Codex, VS Code, Poke and any client with an "MCP URL + header" field connect with the bearer token. Keep the read token in clients that only need to read; hand out the write token deliberately.
+
+claude.ai Connectors, ChatGPT and some hosted agents will not take a static header. They want OAuth, which is the next section.
+
+### Hosted agents (OAuth)
+
+Two more lines in the same `.env` turn wazap into its own OAuth 2.1 server:
+
+```bash
+WAZAP_PUBLIC_URL=https://wazap.example.com
+WAZAP_OAUTH_PASSWORD=$(openssl rand -base64 18)
+```
+
+Then give an agent nothing but `https://wazap.example.com/mcp`. It finds the
+authorization server at `/.well-known/oauth-protected-resource/mcp`, registers
+itself (RFC 7591, so there is no client id to paste anywhere), and sends you to
+a page on your own host that asks two things: the password above, and whether
+this agent may only read or also send. A refresh token keeps the agent signed
+in until you revoke it; access tokens rotate every 24 hours on their own.
+
+Tested against the flow claude.ai, ChatGPT and Poke use: S256 PKCE, public
+clients, `/token` with refresh, `/revoke`. The bearer tokens keep working next
+to it, so a laptop client on a header and a hosted agent on OAuth share one
+server.
+
+What to know before exposing it:
+
+- `WAZAP_PUBLIC_URL` must be `https` and a bare origin, no path: the
+  endpoints live at its root. The password travels to it.
+- The password is the whole identity layer. Use a long one. A consent page
+  takes three wrong guesses and is gone; five from one address lock that
+  address out for fifteen minutes; twenty from anywhere close the page for
+  everyone for fifteen minutes.
+- With OAuth on, `/mcp` never answers an unauthenticated request, whether or
+  not a read token is set.
+- Grants live in `<data-dir>/oauth.json` as hashes. Delete the file to sign
+  every agent out at once, running server included; `wazap status` lists who
+  holds one. Disconnecting an agent on its side revokes its refresh token and
+  every access token it minted. A refresh token unused for ninety days is
+  dropped.
+- A read grant never sees a write tool, whatever scope the agent requested.
+  The radio button on the consent page is the only thing that decides.
 
 ## Settings
 
@@ -464,6 +617,8 @@ Claude Code, Claude Desktop, Cursor, Codex, VS Code and any client with an "MCP
 | `WAZAP_TRANSPORT` | `stdio` | `stdio` or `http`. |
 | `WAZAP_HOST` / `WAZAP_PORT` | `127.0.0.1` / `8766` | HTTP bind address. |
 | `WAZAP_READ_TOKEN` / `WAZAP_WRITE_TOKEN` | unset | HTTP bearer tokens. |
+| `WAZAP_PUBLIC_URL` | unset | The `https` address agents reach the server at. With the password, turns OAuth on. |
+| `WAZAP_OAUTH_PASSWORD` | unset | What the consent page asks for. At least 8 characters. |
 | `WAZAP_NO_UPDATE_CHECK` | `0` | `1` stops `status` asking npm for a newer version. |
 | `WAZAP_TRANSCRIBE` | `off` | `local`, `openai` or `off`. |
 | `WAZAP_TRANSCRIBE_AUTO` | `1` | Transcribe incoming voice notes in the background. |

package/dist/auth-state.js

@@ -117,6 +117,11 @@ export function readLinkedAccount(dir) {
 export function clearAuth(dir) {
     rmSync(dir, { recursive: true, force: true });
 }
+/** Everything a logout deletes: the credentials, and the store they decrypt. */
+export function clearSession(p) {
+    clearAuth(p.authDir);
+    rmSync(p.storeFile, { force: true });
+}
 const APP_STATE_SYNC_VERSION = "app-state-sync-version";
 /**
  * The same auth state with the app state sync journal held at zero: reads of it

package/dist/bridge.js

@@ -2,7 +2,7 @@ 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 { CallToolRequestSchema, CallToolResultSchema, GetPromptRequestSchema, GetPromptResultSchema, ListPromptsRequestSchema, ListPromptsResultSchema, ListToolsRequestSchema, ListToolsResultSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { WAZAP_VERSION } from "./config.js";
 import { readDaemon } from "./daemon.js";
 import { log } from "./logger.js";
@@ -31,13 +31,18 @@ export async function runBridge(daemon, daemonFile) {
     }));
     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 ?? {} },
+        // Only what we forward: the daemon has no resources, and we have no handler
+        // for them. The SDK refuses a handler for a capability we did not declare,
+        // so the prompts pair is registered under the same condition.
+        capabilities: { tools: caps.tools ?? {}, ...(caps.prompts ? { prompts: caps.prompts } : {}) },
         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));
+    if (caps.prompts) {
+        server.setRequestHandler(ListPromptsRequestSchema, (req) => client.request({ method: "prompts/list", params: req.params }, ListPromptsResultSchema));
+        server.setRequestHandler(GetPromptRequestSchema, (req) => client.request({ method: "prompts/get", params: req.params }, GetPromptResultSchema));
+    }
     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