@zeph-to/mcp-server 2.2.0 → 2.3.0

package/README.md

@@ -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`.
 

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.0",
   "description": "Zeph MCP server — AI agent notifications, prompts, and input via MCP protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",