@zeph-to/mcp-server 2.2.0 → 2.3.1

package/README.md

@@ -70,7 +70,7 @@ e.g. a second account:
 | `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_WS_URL` | No | **Deprecated.** WebSocket endpoint for the hook-response fast path. `wsUrl` in `~/.zeph/config.json` wins over it and is where the value belongs; this is read only when the file has none, so a machine that predates the config field keeps working. It will stop being read |
 | `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 push encryption off even when the account has it enabled. A local override for debugging what the server actually received — encryption is already off unless the account opted in (see [Encryption](#encryption)) |
@@ -187,7 +187,9 @@ Returns: `{ actionId: "yes", timedOut: false }`
 
 ### zeph_ask
 
-Ask the user a question with optional quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. Blocks until response or timeout.
+Ask the user a question with quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. Blocks until response or timeout.
+
+`actions` is the steering surface: pass 2–4 buttons on nearly every ask (the next-step candidates plus a safe Done-like `fallback`) and leave it out only when the answer is inherently free-form text — a bare text box on a "done — what next?" ask gives the phone nothing to tap.
 
 Requires `ZEPH_HOOK_ID`.
 
@@ -236,7 +238,7 @@ Returns: `{ value: "feat: add clipboard sync", timedOut: false }` — plus `atta
 
 ### Client timeouts
 
-`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.
+`zeph_ask`, `zeph_prompt`, and `zeph_input` block until the user responds, up to their `timeout` (max 600s). With `wsUrl` set in `~/.zeph/config.json` 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
 

package/dist/config.d.ts

@@ -40,4 +40,20 @@ export declare const loadConfig: () => McpServerConfig;
  *  back to a hostname hash pinned in a sticky file; mirror that order, reading
  *  (never writing) the file so both processes resolve the same id. */
 export declare const listenerDeviceId: () => string;
+/**
+ * A one-line notice for a machine that still exports `ZEPH_WS_URL`, or null.
+ *
+ * The variable is no longer read. Dropping it in silence would repeat the
+ * failure it caused — a value that looks like it is in effect while something
+ * else decides — so it is read here only to say it is being ignored.
+ */
+export declare const legacyWsEnv: (env?: NodeJS.ProcessEnv) => string | undefined;
+/**
+ * What to tell a machine that still exports `ZEPH_WS_URL`, or null. Two
+ * messages, because the two situations differ: an export beside a config file
+ * is dead weight, while an export on its own is still carrying the value.
+ */
+export declare const legacyWsEnvNotice: (config?: {
+    wsUrl?: string;
+}, env?: NodeJS.ProcessEnv) => string | null;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;uCAGmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACvB;AAID,wEAAwE;AACxE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAMlD,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAO,MAMnC,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,MAAM,EAAE,OAAO,MAAM,KAAG,MAGpE,CAAC;AAwGF,eAAO,MAAM,UAAU,QAAO,eAiC7B,CAAC;AA4BF;;;;;sEAKsE;AACtE,eAAO,MAAM,gBAAgB,QAAO,MAQnC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;uCAGmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACvB;AAID,wEAAwE;AACxE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAMlD,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAO,MAMnC,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,MAAM,EAAE,OAAO,MAAM,KAAG,MAGpE,CAAC;AAwGF,eAAO,MAAM,UAAU,QAAO,eAsC7B,CAAC;AA4BF;;;;;sEAKsE;AACtE,eAAO,MAAM,gBAAgB,QAAO,MAQnC,CAAC;AAcF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,MAAM,GAAG,SAK3E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC1B,SAAQ;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,EAC/B,MAAK,MAAM,CAAC,UAAwB,KACrC,MAAM,GAAG,IAKX,CAAC"}

package/dist/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listenerDeviceId = exports.loadConfig = exports.formatPushTitle = exports.detectProjectDir = exports.projectHash = void 0;
+exports.legacyWsEnvNotice = exports.legacyWsEnv = exports.listenerDeviceId = exports.loadConfig = exports.formatPushTitle = exports.detectProjectDir = exports.projectHash = void 0;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const crypto_1 = require("crypto");
@@ -161,7 +161,12 @@ const loadConfig = () => {
     return {
         apiKey,
         baseUrl: (resolvedEnv('ZEPH_BASE_URL') ?? fileConfig.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ''),
-        wsUrl: resolvedEnv('ZEPH_WS_URL') ?? fileConfig.wsUrl,
+        // Config first, environment second — the inverse of what this used to
+        // be. `ZEPH_WS_URL` sat ABOVE ~/.zeph/config.json, so an `export` in a
+        // shell profile silently outranked the file with nothing anywhere to
+        // say it had. It still answers when the file has nothing, so a
+        // self-hosted machine does not quietly lose its WebSocket fast path.
+        wsUrl: fileConfig.wsUrl ?? (0, exports.legacyWsEnv)(),
         hookId: resolvedEnv('ZEPH_HOOK_ID') ?? fileConfig.hookId,
         deviceId: resolvedEnv('ZEPH_DEVICE_ID') ?? fileConfig.deviceId,
         sessionId,
@@ -229,3 +234,30 @@ const detectTmuxSessionName = () => {
         return undefined;
     }
 };
+/**
+ * A one-line notice for a machine that still exports `ZEPH_WS_URL`, or null.
+ *
+ * The variable is no longer read. Dropping it in silence would repeat the
+ * failure it caused — a value that looks like it is in effect while something
+ * else decides — so it is read here only to say it is being ignored.
+ */
+const legacyWsEnv = (env = process.env) => {
+    const value = env.ZEPH_WS_URL;
+    // Same guard resolvedEnv applies: an unexpanded "${ZEPH_WS_URL}" out of an
+    // agent's env block is a placeholder, not a value.
+    return value && !value.startsWith('${') ? value : undefined;
+};
+exports.legacyWsEnv = legacyWsEnv;
+/**
+ * What to tell a machine that still exports `ZEPH_WS_URL`, or null. Two
+ * messages, because the two situations differ: an export beside a config file
+ * is dead weight, while an export on its own is still carrying the value.
+ */
+const legacyWsEnvNotice = (config = {}, env = process.env) => {
+    if (!(0, exports.legacyWsEnv)(env))
+        return null;
+    return config.wsUrl
+        ? '[Config] ZEPH_WS_URL is set but ~/.zeph/config.json wins now — the export does nothing and can go.'
+        : '[Config] ZEPH_WS_URL is deprecated and will stop being read — move the value to "wsUrl" in ~/.zeph/config.json.';
+};
+exports.legacyWsEnvNotice = legacyWsEnvNotice;

package/dist/index.js

@@ -77,6 +77,11 @@ const createServer = (config) => {
 };
 const main = async () => {
     const config = (0, config_js_1.loadConfig)();
+    // Read only to report: the variable used to outrank the config file, and
+    // removing it without a word would leave the same silence behind.
+    const staleWsEnv = (0, config_js_1.legacyWsEnvNotice)(config);
+    if (staleWsEnv)
+        console.error(staleWsEnv);
     // Load or create this host's keypair, if the account has opted in. Runs once
     // per process and caches, so toggling E2E in the app while this server is
     // running has no effect until it restarts.

package/dist/tools/ask.js

@@ -46,7 +46,7 @@ const settleRemoteState = (answer) => {
 };
 const registerAskTool = (server, client, config, waiter) => {
     server.registerTool('zeph_ask', {
-        description: 'Ask the user a question with optional quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. The user can either tap a button or type a response. Blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable. The user may also attach screenshots or files to the answer: those arrive as local absolute paths in the `attachments` field of the result, and reading them is part of reading the answer. NOTE: unlike zeph_notify and zeph_file, this tool is never end-to-end encrypted — the hook route it uses cannot carry the sender key — so do not put secrets in the question or expect a private answer.',
+        description: 'Ask the user a question with quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. The user can either tap a button or type a response. `actions` is the steering surface, not decoration: pass 2–4 buttons on nearly every ask — the next-step candidates you would otherwise write as prose (next command, review, stop) plus a safe Done-like `fallback`. Leave `actions` out ONLY when the answer is inherently free-form text (a name, a path, a paragraph); a bare text box on a "done — what next?" ask leaves the phone with nothing to tap. Blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable. The user may also attach screenshots or files to the answer: those arrive as local absolute paths in the `attachments` field of the result, and reading them is part of reading the answer. NOTE: unlike zeph_notify and zeph_file, this tool is never end-to-end encrypted — the hook route it uses cannot carry the sender key — so do not put secrets in the question or expect a private answer.',
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -65,7 +65,7 @@ const registerAskTool = (server, client, config, waiter) => {
                 .min(1)
                 .max(4)
                 .optional()
-                .describe('Quick-reply buttons (1-4). Omit for text-only input'),
+                .describe('Quick-reply buttons (1-4). Expected on nearly every ask — the phone steers by tapping, so put the next-step candidates here (next command, review, stop) plus a Done-like fallback. Omit ONLY when the answer is inherently free-form text; never omit on a "done — what next?" ask.'),
             placeholder: zod_1.z.string().optional().describe('Input field placeholder hint'),
             inputType: zod_1.z
                 .enum(['text', 'multiline'])

package/package.json

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