@pergy-ai/mcp 0.2.1 → 0.3.1

package/README.md

@@ -34,7 +34,7 @@ It talks to the hosted backend by default — no config needed. Set
 
 ## Tools
 
-- **`notify_user`** — notify the user (three standalone context tiers: short / medium / long, plus optional options — each an answerable choice that can carry a sandboxed `html` or `image` preview for visual "pick one" decisions — visuals, `urgency`, and `parentId` for a clarification). Returns a request id + thread id.
+- **`notify_user`** — notify the user (context: title + description chunks, plus optional options — each an answerable choice that can carry a sandboxed `html` or `image` preview for visual "pick one" decisions — visuals, `urgency`, and `parentId` for a clarification). Returns a request id + thread id. If a reply comes back as `{kind:'clarify', chunks:[...]}`, respond via notify_user with the SAME threadId and an expanded description.
 - **`await_reply`** — wait for the user's reply to a specific notification (pass its id). Scoped: will not return replies meant for other notifications. Returns `reply` / `remind` / `idle`.
 - **`check_replies`** — catch-up sweep: returns replies you haven't consumed yet (now marked seen) plus still-pending notifications.
 - **`poll_answer`** — fetch the answer to a specific request by id.

package/dist/index.js

@@ -11,10 +11,9 @@ import { execSync } from "child_process";
 
 // ../../packages/schema/dist/index.js
 import { z } from "zod";
-var ContextTiersSchema = z.object({
-  short: z.string().describe("The minimum words needed to communicate the message \u2014 a headline."),
-  medium: z.string().describe("A standalone ~3 sentence version."),
-  long: z.string().describe("A standalone version of 1-3 paragraphs.")
+var ContextSchema = z.object({
+  title: z.string().min(1).describe("One-line headline of what you need (required, non-empty)."),
+  description: z.array(z.string().min(1)).min(1).describe("Semantic chunks of detail (each a standalone, non-empty piece). The user can select chunks to ask you to expand.")
 });
 var OptionSchema = z.object({
   id: z.string(),
@@ -36,7 +35,7 @@ var AgentSchema = z.object({
   name: z.string()
 });
 var NotifyRequestSchema = z.object({
-  context: ContextTiersSchema,
+  context: ContextSchema,
   options: z.array(OptionSchema).optional(),
   visuals: z.array(VisualSchema).optional(),
   agent: AgentSchema,
@@ -47,10 +46,13 @@ var NotifyRequestSchema = z.object({
   /** Continue an existing conversation; omitted = start a new thread. */
   threadId: z.string().uuid().optional(),
   createdAt: z.string().datetime(),
-  /** Whether this should ring the user (SP3) or sit in the inbox. Inert until SP3. */
-  urgency: z.enum(["inbox", "call"]).default("inbox"),
+  urgency: z.enum(["inbox", "call"]).default("inbox").describe(
+    "'inbox' (default) = sits silently in the inbox for the user to get to. 'call' = rings the user's phone now (a CallKit voice call) \u2014 use only when you genuinely need them in the moment (blocked and waiting, time-sensitive). context.title becomes what they see on the ring, so make it specific."
+  ),
   /** The request this one was spawned from, for a clarification. */
-  parentId: z.string().optional()
+  parentId: z.string().optional(),
+  /** How the user answers the options: pick one (default), pick several, or pick & order. */
+  select: z.enum(["one", "many", "rank"]).default("one")
 });
 var NotifyStatusSchema = z.enum(["pending", "answered", "ignored"]);
 var AgentStateSchema = z.enum(["idle", "in_progress", "completed", "needs_input"]);
@@ -60,7 +62,10 @@ var SetTaskStateSchema = z.object({
 var UserAnswerSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("option"), optionId: z.string() }),
   z.object({ kind: z.literal("text"), text: z.string() }),
-  z.object({ kind: z.literal("ignored") })
+  z.object({ kind: z.literal("ignored") }),
+  z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()) }),
+  z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()) }),
+  z.object({ kind: z.literal("clarify"), chunks: z.array(z.string()).min(1) })
 ]);
 var AwaitItemSchema = z.discriminatedUnion("type", [
   z.object({
@@ -102,7 +107,7 @@ var UserResponseSchema = z.object({
 var InboxItemSchema = z.object({
   id: z.string(),
   status: NotifyStatusSchema,
-  context: ContextTiersSchema,
+  context: ContextSchema,
   options: z.array(OptionSchema).optional(),
   visuals: z.array(VisualSchema).optional(),
   agent: z.string(),
@@ -112,7 +117,8 @@ var InboxItemSchema = z.object({
   createdAt: z.string().datetime(),
   snoozedUntil: z.string().datetime().optional(),
   agentState: AgentStateSchema.default("idle"),
-  parentId: z.string().optional()
+  parentId: z.string().optional(),
+  select: z.enum(["one", "many", "rank"]).default("one")
 });
 var SnoozeRequestSchema = z.object({
   requestId: z.string(),
@@ -264,14 +270,14 @@ var server = new Server(
   { name: "pergy", version: "0.0.0" },
   {
     capabilities: { tools: {} },
-    instructions: "On startup, call check_replies once to pick up any replies or pending work you missed while away. To wait for the answer to something you just asked, call await_reply with that notification's id \u2014 it's scoped to that one request, so it never returns replies meant for other requests. Use check_replies again only when re-booting or after waiting a long time on something else. Never end a turn that still needs the user without notify_user + await_reply."
+    instructions: "On startup, call check_replies once to pick up any replies or pending work you missed while away. To wait for the answer to something you just asked, call await_reply with that notification's id \u2014 it's scoped to that one request, so it never returns replies meant for other requests. Use check_replies again only when re-booting or after waiting a long time on something else. Never end a turn that still needs the user without notify_user + await_reply. If a reply comes back as { kind: 'clarify', chunks: [...] }, the user wants more detail on those chunks \u2014 respond by calling notify_user again with the SAME threadId and an expanded description covering them."
   }
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: "notify_user",
-      description: "Notify the user via Pergy and get a request id to poll for their answer. Provide context in three STANDALONE tiers (each must communicate on its own, not as a delta): short = minimum words, a headline; medium = ~3 sentences; long = 1-3 paragraphs. Plus optional options (answerable choices; each may carry a sandboxed `html` or an `image` preview for a visual 'pick one' \u2014 e.g. show layout/UI alternatives) and visuals. Pass `threadId` from a prior notify_user result or an await_reply reply to continue that conversation thread; omit it to start a new one.",
+      description: "Notify the user via Pergy and get a request id to poll for their answer. Provide context.title (a specific, non-empty one-line headline \u2014 this is what the user sees first, and what shows on the ring for a call) and context.description (an array of standalone, non-empty detail chunks the user can selectively ask you to expand). Set `urgency`: 'inbox' (default) drops it silently in their inbox; 'call' rings their phone now as a voice call \u2014 use 'call' only when you genuinely need them in the moment (blocked/waiting, time-sensitive), not for routine FYIs. Plus optional options (answerable choices; each may carry a sandboxed `html` or an `image` preview for a visual 'pick one' \u2014 e.g. show layout/UI alternatives) and visuals. Use `select` to control how the user answers options: 'one' (default) = pick a single option; 'many' = multi-select, user checks any subset \u2192 answer arrives as {kind:'multi', optionIds:[...]}; 'rank' = select and order, user taps options in preferred order \u2192 answer arrives as {kind:'ranked', optionIds:[...]} (ordered by choice). If a reply comes back as {kind:'clarify', chunks:[...]}, the user wants more detail on those chunks \u2014 respond via notify_user with the SAME threadId and an expanded description. Pass `threadId` from a prior notify_user result or an await_reply reply to continue that conversation thread; omit it to start a new one.",
       inputSchema: zodToJsonSchema(NotifyRequestSchema, { target: "openApi3" })
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pergy-ai/mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Pergy MCP server — a voice inbox for your AI agents. Lets an agent notify a user and await their reply.",
   "license": "MIT",
   "type": "module",