@zeph-to/mcp-server 1.14.0 → 1.14.1

package/README.md

@@ -5,7 +5,9 @@
 [![node](https://img.shields.io/node/v/@zeph-to/mcp-server.svg)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/@zeph-to/mcp-server.svg)](./LICENSE)
 
-Zeph MCP server for AI agents. Send notifications, copy to clipboard, request confirmations, and collect text input from users across their devices — all via the [Model Context Protocol](https://modelcontextprotocol.io).
+Zeph MCP server — the agent side of the round trip. Your agent finishes a build or hits a decision, calls `zeph_ask`, and the question lands on the user's phone as buttons + a text field; the reply comes back into the same tool call and the agent keeps going. Also: one-way notifications, clipboard, files, and channel broadcasts — all via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+Works with Claude Code, Cursor, Windsurf, Gemini CLI, and any MCP client. Part of the Zeph toolchain: [`@zeph-to/cli`](https://github.com/zeph-to/cli) (installer, push CLI, tmux remote control) · [`zeph-to/plugin`](https://github.com/zeph-to/plugin) (Claude Code plugin bundling this server) · the [Zeph app](https://zeph.to) on your phone.
 
 ## Setup
 
@@ -57,12 +59,17 @@ Add to `~/.claude/settings.json`:
 | `ZEPH_HOOK_ID` | No | Hook ID (optional — only needed for interactive tools like `zeph_ask`/`zeph_prompt`/`zeph_input`) |
 | `ZEPH_DEVICE_ID` | No | Target device ID (optional — only needed for interactive tools like `zeph_ask`/`zeph_prompt`/`zeph_input`). Omit to send to all devices |
 | `ZEPH_BASE_URL` | No | API base URL (default: `https://api.zeph.to/v1`) |
+| `ZEPH_WS_URL` | No | WebSocket endpoint for the hook-response fast path — `zeph_ask`/`zeph_prompt`/`zeph_input` answers arrive the moment the user submits them instead of on the next poll. Falls back to pure polling when unset. Also read from `wsUrl` in `~/.zeph/config.json` |
 | `ZEPH_DISABLE_SESSION_CACHE` | No | Set to `1`/`true` to skip writing the session-id handoff file under `~/.cache/zeph/`. Useful for read-only filesystems, ephemeral CI runners, or sandboxed envs that audit filesystem writes. The plugin's stop hook still works without it (transcript-path UUID extraction is the primary path; the cache is a fallback for older Claude Code versions). |
+| `ZEPH_SESSION_ID` | No | Override the session id attached to pushes (grouping in the app). Auto-detected from the newest Claude Code transcript when unset |
+| `ZEPH_DISABLE_ENCRYPTION` | No | Set to `1`/`true` to force E2E-style push encryption off, even when the account has keys. Useful while cleaning up legacy key state |
 
 \* If env vars are not set, the server reads from `~/.zeph/config.json` (created by `npx @zeph-to/cli install`). Unresolved `${...}` interpolations are also treated as unset.
 
 ## Tools
 
+Push titles are automatically prefixed with the project directory name — `myapp · Build complete` — so the phone feed stays scannable when several sessions push at once.
+
 ### zeph_notify
 
 Send a one-way push notification. Supports optional URL (auto-switches to link type).
@@ -188,7 +195,7 @@ Returns: `{ value: "feat: add clipboard sync", timedOut: false }`
 
 ### Client timeouts
 
-`zeph_ask`, `zeph_prompt`, and `zeph_input` block until the user responds, up to their `timeout` (max 600s). That whole time the MCP request stays open. To keep the client from giving up early, the server emits a `notifications/progress` every 5s while waiting. Clients must either set a per-request timeout above the tool's `timeout`, or reset their timeout on progress notifications. Claude Code does the latter by default.
+`zeph_ask`, `zeph_prompt`, and `zeph_input` block until the user responds, up to their `timeout` (max 600s). With `ZEPH_WS_URL` configured the response arrives over WebSocket the instant it's submitted; otherwise the server polls. Either way the MCP request stays open the whole time. To keep the client from giving up early, the server emits a `notifications/progress` every 5s while waiting. Clients must either set a per-request timeout above the tool's `timeout`, or reset their timeout on progress notifications. Claude Code does the latter by default.
 
 ## Resources
 
@@ -207,13 +214,27 @@ Lists channels the user owns or subscribes to. Use to find `channelId` for `zeph
 | Situation | Tool | Example |
 |-----------|------|---------|
 | Long task finished | `zeph_notify` | Build complete, test results, deploy done |
-| Need user decision | `zeph_prompt` | Choose deploy target, confirm destructive action |
-| Need free-form input | `zeph_input` | Commit message, env var value, description |
+| Need a decision (buttons + optional free text) | `zeph_ask` | "Tests green. Deploy?" with a custom-instruction escape hatch |
+| Decision from fixed options only | `zeph_prompt` | Choose deploy target, confirm destructive action |
+| Free-form input only | `zeph_input` | Commit message, env var value, description |
 | Share code/logs | `zeph_file` | Error logs, test reports, generated config |
 | Share snippet | `zeph_clipboard` | API key, URL, shell command |
 
 ### Recommended patterns
 
+**Decision gate with an escape hatch (preferred):**
+```
+zeph_ask(
+  title: "Tests green. Deploy to production?",
+  actions: [
+    { id: "deploy", label: "Deploy", style: "primary" },
+    { id: "hold", label: "Hold", style: "secondary" }
+  ],
+  placeholder: "Or tell me what to do instead...",
+  fallback: "hold"
+)
+```
+
 **Task completion notification:**
 ```
 zeph_notify(
@@ -271,7 +292,7 @@ The API key needs the following scopes:
 
 - `push:read` — for `zeph_list`
 - `push:write` — for `zeph_notify`, `zeph_clipboard`, `zeph_dismiss`, `zeph_dismiss_all`, `zeph_file`
-- `hook:write` — for `zeph_prompt` and `zeph_input`
+- `hook:write` — for `zeph_ask`, `zeph_prompt`, and `zeph_input`
 - `channel:read` — for `zeph://channels` resource
 
 Create an API key with the **MCP** preset in Settings > API Keys for the correct permissions.

package/dist/crypto.d.ts

@@ -1,7 +1,8 @@
 /**
  * Device-shared encryption for MCP server — self-contained ECDH P-256 +
  * AES-256-GCM. Mirrors @zeph/crypto API but bundled inline (no external
- * dependency). Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ * dependency). Uses Web Crypto API via node:crypto webcrypto — Node.js 18+
+ * (the `crypto` global only exists unflagged from Node 19, so we import it).
  *
  * Threat model honesty (do not call this "E2E" without a footnote):
  *

package/dist/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAoJH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAsE5E,CAAC;AA8BF,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAqB,CAAC;AACpE,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA+B,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAaA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAQlE,CAAC"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA0JH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAsE5E,CAAC;AAmCF,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAqB,CAAC;AACpE,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA+B,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAaA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAQlE,CAAC"}

package/dist/crypto.js

@@ -2,7 +2,8 @@
 /**
  * Device-shared encryption for MCP server — self-contained ECDH P-256 +
  * AES-256-GCM. Mirrors @zeph/crypto API but bundled inline (no external
- * dependency). Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ * dependency). Uses Web Crypto API via node:crypto webcrypto — Node.js 18+
+ * (the `crypto` global only exists unflagged from Node 19, so we import it).
  *
  * Threat model honesty (do not call this "E2E" without a footnote):
  *
@@ -33,6 +34,11 @@ exports.encryptFileForSelf = exports.encryptPushBodyForSelf = exports.getPublicK
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+const node_crypto_1 = require("node:crypto");
+// Node 18 has no `crypto` global (unflagged only from 19.0.0) — resolve the
+// Web Crypto implementation explicitly so encryption works on the declared
+// minimum runtime instead of silently staying disabled.
+const crypto = node_crypto_1.webcrypto;
 // ─── Base64 helpers ───
 const toBase64 = (buffer) => Buffer.from(buffer).toString('base64');
 const fromBase64 = (base64) => {
@@ -208,7 +214,12 @@ exports.initCrypto = initCrypto;
 const fetchServerKeys = async (apiKey, baseUrl) => {
     try {
         const url = `${baseUrl.replace(/\/$/, '')}/users/me/keys`;
-        const res = await fetch(url, { headers: { 'X-API-Key': apiKey } });
+        // Bounded: index.ts awaits initCrypto before connecting the MCP
+        // transport, so a hanging fetch here would block server startup.
+        const res = await fetch(url, {
+            headers: { 'X-API-Key': apiKey },
+            signal: AbortSignal.timeout(5_000),
+        });
         if (!res.ok)
             return null;
         const json = await res.json();

package/dist/tools/notify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/tools/notify.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AASrE,eAAO,MAAM,kBAAkB,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,SAmHnG,CAAC"}
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/tools/notify.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AASrE,eAAO,MAAM,kBAAkB,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,SA2HnG,CAAC"}

package/dist/tools/notify.js

@@ -48,6 +48,7 @@ const registerNotifyTool = (server, client, config) => {
                 let uploadContentType = fileType;
                 let fileIv;
                 let fileEncryptedKey;
+                let fileEncrypted = false;
                 if (canEncrypt) {
                     try {
                         const encrypted = await (0, crypto_js_1.encryptFileForSelf)(fileMarkdown);
@@ -55,6 +56,7 @@ const registerNotifyTool = (server, client, config) => {
                         uploadContentType = 'application/octet-stream';
                         fileIv = encrypted.iv;
                         fileEncryptedKey = encrypted.encryptedKey;
+                        fileEncrypted = true;
                     }
                     catch (err) {
                         console.error('[Crypto] File encryption failed, sending plaintext:', err);
@@ -74,17 +76,21 @@ const registerNotifyTool = (server, client, config) => {
                     targetDeviceId: deviceId,
                     sessionId: config.sessionId,
                 };
+                let pushEncrypted = false;
                 if (canEncrypt) {
                     try {
                         const enc = await (0, crypto_js_1.encryptPushBodyForSelf)({ title: pushTitle, body: preview, url });
                         pushPayload = { ...pushPayload, title: undefined, body: enc.body, isEncrypted: enc.isEncrypted, encryptedKey: enc.encryptedKey, senderPublicKey: enc.senderPublicKey };
+                        pushEncrypted = true;
                     }
                     catch (err) {
                         console.error('[Crypto] Push encryption failed, sending plaintext:', err);
                     }
                 }
                 const result = await client.sendPush(pushPayload);
-                return (0, error_format_js_1.textResult)({ pushId: result.data.pushId, fileKey: upload.data.fileKey, autoFile: true, encrypted: canEncrypt });
+                // Report what actually went out — an encryption failure above falls
+                // back to plaintext, so `canEncrypt` alone would over-claim.
+                return (0, error_format_js_1.textResult)({ pushId: result.data.pushId, fileKey: upload.data.fileKey, autoFile: true, encrypted: fileEncrypted && pushEncrypted });
             }
             // Short body — encrypt push only
             let pushPayload = {
@@ -96,17 +102,19 @@ const registerNotifyTool = (server, client, config) => {
                 targetDeviceId: deviceId,
                 sessionId: config.sessionId,
             };
+            let pushEncrypted = false;
             if (canEncrypt) {
                 try {
                     const enc = await (0, crypto_js_1.encryptPushBodyForSelf)({ title: pushTitle, body: cleanBody, url });
                     pushPayload = { ...pushPayload, title: undefined, body: enc.body, isEncrypted: enc.isEncrypted, encryptedKey: enc.encryptedKey, senderPublicKey: enc.senderPublicKey };
+                    pushEncrypted = true;
                 }
                 catch (err) {
                     console.error('[Crypto] Push encryption failed, sending plaintext:', err);
                 }
             }
             const result = await client.sendPush(pushPayload);
-            return (0, error_format_js_1.textResult)({ pushId: result.data.pushId, encrypted: canEncrypt });
+            return (0, error_format_js_1.textResult)({ pushId: result.data.pushId, encrypted: pushEncrypted });
         }
         catch (err) {
             return (0, error_format_js_1.formatToolError)(err);

package/dist/ws-wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws-wait.d.ts","sourceRoot":"","sources":["../src/ws-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,WAAW,MAAM;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CACxF;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAMhD,MAAM,WAAW,gBAAgB;IAC7B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,+DAA+D;IAC/D,WAAW,IAAI,OAAO,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,OAAO,CAAC,EAAE,SAAS,CAAC;CACvB;AAQD,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAY;IACrC,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,SAAS,CAA8C;gBAEnD,IAAI,EAAE,yBAAyB;IAM3C,uEAAuE;IACvE,OAAO,IAAI,OAAO;IAIlB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB;IAgB5C,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,cAAc;CAUzB"}
+{"version":3,"file":"ws-wait.d.ts","sourceRoot":"","sources":["../src/ws-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,WAAW,MAAM;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CACxF;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAMhD,MAAM,WAAW,gBAAgB;IAC7B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,+DAA+D;IAC/D,WAAW,IAAI,OAAO,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,OAAO,CAAC,EAAE,SAAS,CAAC;CACvB;AAQD,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAY;IACrC,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,SAAS,CAA8C;gBAEnD,IAAI,EAAE,yBAAyB;IAM3C,uEAAuE;IACvE,OAAO,IAAI,OAAO;IAIlB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB;IAgB5C,OAAO,CAAC,YAAY;IAmCpB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,cAAc;CAUzB"}

package/dist/ws-wait.js

@@ -72,9 +72,15 @@ class HookResponseWaiter {
             return;
         try {
             const sep = this.wsUrl.includes('?') ? '&' : '?';
+            // KNOWN TRADEOFF: apiKey rides the query string — the WHATWG
+            // WebSocket (Node 21+ global) can't set headers, and the API GW
+            // $connect route authenticates on the query param. It can land in
+            // gateway access logs; first-message auth needs a server change.
             const sock = this.factory(`${this.wsUrl}${sep}apiKey=${encodeURIComponent(this.apiKey)}`);
             this.sock = sock;
             sock.addEventListener('open', () => {
+                if (this.sock !== sock)
+                    return; // stale socket — already replaced
                 this.connected = true;
                 this.pingTimer = setInterval(() => {
                     try {
@@ -88,7 +94,12 @@ class HookResponseWaiter {
                 this.pingTimer.unref?.();
             });
             sock.addEventListener('message', (event) => this.handleMessage(event.data));
-            const drop = () => this.teardownSocket();
+            // Guard against stale events: 'error' and 'close' both fire on a
+            // dying socket, and a new subscribe() may have already created a
+            // replacement between them — a late event from the old socket
+            // must not tear down the new one.
+            const drop = () => { if (this.sock === sock)
+                this.teardownSocket(); };
             sock.addEventListener('close', drop);
             sock.addEventListener('error', drop);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/mcp-server",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "description": "Zeph MCP server — AI agent notifications, prompts, and input via MCP protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",