@pergy-ai/mcp 0.1.0 → 0.2.1

package/README.md

@@ -4,21 +4,20 @@ A voice inbox for your AI agents. This MCP server lets an agent **notify a user*
 
 ## Install
 
-No clone needed — run it with `npx`:
+No clone needed. Add it to Claude Code (`-s user` = available in every project; drop it for just the current one):
 
 ```bash
-npx @pergy-ai/mcp
+claude mcp add pergy -s user -- npx -y @pergy-ai/mcp
 ```
 
-Or wire it into an MCP client config:
+Or wire it into any MCP client config:
 
 ```json
 {
   "mcpServers": {
     "pergy": {
       "command": "npx",
-      "args": ["-y", "@pergy-ai/mcp"],
-      "env": { "PERGY_BACKEND_URL": "https://pergy.ai" }
+      "args": ["-y", "@pergy-ai/mcp"]
     }
   }
 }
@@ -30,10 +29,14 @@ First-time pairing (link the server to your Pergy account):
 npx -p @pergy-ai/mcp pergy-mcp-onboard
 ```
 
+It talks to the hosted backend by default — no config needed. Set
+`PERGY_BACKEND_URL=http://localhost:3000` only for local development.
+
 ## Tools
 
-- **`notify_user`** — notify the user (three standalone context tiers: short / medium / long, plus optional options, visuals, `urgency`, and `parentId` for a clarification). Returns a request id + thread id.
-- **`await_task`** — wait for the user's next reply (`reply` / `remind` / `idle`).
+- **`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.
+- **`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.
 - **`set_task_state`** — report progress on a request: `in_progress` / `completed` / `needs_input`.
 

package/dist/index.js

@@ -18,7 +18,15 @@ var ContextTiersSchema = z.object({
 });
 var OptionSchema = z.object({
   id: z.string(),
-  label: z.string()
+  label: z.string(),
+  // .describe() flows into the MCP notify_user JSON schema (zodToJsonSchema), so
+  // the constraints below are what an agent reads when deciding to use these.
+  html: z.string().max(16384).describe(
+    "Optional sandboxed HTML/CSS preview for a visual 'pick one' (shown in the option card). Untrusted-sandboxed: NO JavaScript, NO external network or images \u2014 inline CSS and data: URIs only; <=16KB. Use for layout/CSS mockups, tables, diffs. For a hosted image use `image` instead."
+  ).optional(),
+  image: z.string().url().describe(
+    "Optional image URL rendered as the option's preview (plain image, not sandboxed). For agent-generated HTML/CSS mockups, use `html` instead."
+  ).optional()
 });
 var VisualSchema = z.object({
   url: z.string().url(),
@@ -71,6 +79,14 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
   }),
   z.object({ type: z.literal("idle") })
 ]);
+var PendingRepliesSchema = z.object({
+  replies: z.array(
+    z.object({ threadId: z.string(), notificationId: z.string(), answer: UserAnswerSchema })
+  ),
+  pending: z.array(
+    z.object({ threadId: z.string(), notificationId: z.string(), createdAt: z.string() })
+  )
+});
 var NotifyResponseSchema = z.object({
   id: z.string(),
   status: NotifyStatusSchema,
@@ -85,6 +101,7 @@ var UserResponseSchema = z.object({
 });
 var InboxItemSchema = z.object({
   id: z.string(),
+  status: NotifyStatusSchema,
   context: ContextTiersSchema,
   options: z.array(OptionSchema).optional(),
   visuals: z.array(VisualSchema).optional(),
@@ -101,6 +118,13 @@ var SnoozeRequestSchema = z.object({
   requestId: z.string(),
   until: z.string().datetime()
 });
+var PushTokenSchema = z.object({
+  voipToken: z.string().min(1),
+  platform: z.enum(["ios"])
+});
+var UserSettingsSchema = z.object({
+  callsEnabled: z.boolean()
+});
 var DeviceAgentTokenSchema = z.object({
   token: z.string(),
   deviceId: z.string(),
@@ -139,7 +163,7 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 import { existsSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-var BACKEND_URL = process.env.PERGY_BACKEND_URL ?? "http://localhost:3000";
+var BACKEND_URL = process.env.PERGY_BACKEND_URL ?? "https://pergy.ai";
 var TOKEN_PATH = join(homedir(), ".pergy", "token.json");
 function loadToken() {
   if (process.env.PERGY_TOKEN) return process.env.PERGY_TOKEN;
@@ -164,7 +188,7 @@ async function submitNotification(req) {
   return await res.json();
 }
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-async function awaitTask(opts = {}) {
+async function awaitReply(notificationId, opts = {}) {
   const intervalMs = opts.intervalMs ?? 5e3;
   const windowMs = opts.windowMs ?? 3e5;
   const doSleep = opts.sleep ?? sleep;
@@ -172,7 +196,7 @@ async function awaitTask(opts = {}) {
   const token = loadToken();
   const start = now();
   while (true) {
-    const res = await fetch(`${BACKEND_URL}/api/await`, {
+    const res = await fetch(`${BACKEND_URL}/api/await?notificationId=${encodeURIComponent(notificationId)}`, {
       headers: { authorization: `Bearer ${token}` }
     });
     if (!res.ok) throw new Error(`await failed: ${res.status} ${await res.text()}`);
@@ -182,6 +206,14 @@ async function awaitTask(opts = {}) {
     await doSleep(intervalMs);
   }
 }
+async function checkReplies() {
+  const token = loadToken();
+  const res = await fetch(`${BACKEND_URL}/api/pending`, {
+    headers: { authorization: `Bearer ${token}` }
+  });
+  if (!res.ok) throw new Error(`check_replies failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
 async function setTaskState(id, state) {
   const res = await fetch(`${BACKEND_URL}/api/notify/${id}/state`, {
     method: "PATCH",
@@ -204,7 +236,10 @@ async function pollAnswer(id) {
 var PollAnswerSchema = z2.object({
   id: z2.string().describe("Request id returned by notify_user.")
 });
-var AwaitTaskSchema = z2.object({});
+var AwaitReplySchema = z2.object({
+  notificationId: z2.string().describe("The id returned by notify_user \u2014 waits for the user's reply to THIS notification only.")
+});
+var CheckRepliesSchema = z2.object({});
 var SetTaskStateToolSchema = z2.object({
   notificationId: z2.string(),
   state: SetTaskStateSchema.shape.state
@@ -227,13 +262,16 @@ function detectGit() {
 }
 var server = new Server(
   { name: "pergy", version: "0.0.0" },
-  { capabilities: { tools: {} } }
+  {
+    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."
+  }
 );
 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 and visuals. Pass `threadId` from a prior notify_user result or an await_task 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 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.",
       inputSchema: zodToJsonSchema(NotifyRequestSchema, { target: "openApi3" })
     },
     {
@@ -242,9 +280,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: zodToJsonSchema(PollAnswerSchema, { target: "openApi3" })
     },
     {
-      name: "await_task",
-      description: "Wait for the user's next input, then return it. Call this after notify_user to stay engaged: it polls for up to ~5 minutes (checking every few seconds) and returns { type: 'reply', threadId, notificationId, answer } when the user responds, { type: 'remind', threadId, notificationId, remindAt, remindInSeconds } when the user defers (snoozes) \u2014 call ScheduleWakeup(remindInSeconds) (it's pre-computed; if it exceeds the ~1h cap, wake at the cap and re-schedule, or use a cron), end your turn, and call await_task again when it fires \u2014 or { type: 'idle' } if nothing arrives in the window. On a reply, act on it and \u2014 if you still need the user \u2014 call notify_user again with the SAME threadId, then await_task again. On idle, call again to keep waiting, or stop and schedule a re-check. Never end a turn that still needs the user without going through notify_user + await_task.",
-      inputSchema: zodToJsonSchema(AwaitTaskSchema, { target: "openApi3" })
+      name: "await_reply",
+      description: "Wait for the user's reply to THE specific notification you sent for the current request (pass its id from notify_user). This is how you wait for your answer in-context. Polls ~5 min; returns { type:'reply', answer } when they respond, { type:'remind', remindInSeconds } on snooze (ScheduleWakeup then await_reply again), or { type:'idle' }. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications/requests, so concurrent requests don't cross.",
+      inputSchema: zodToJsonSchema(AwaitReplySchema, { target: "openApi3" })
+    },
+    {
+      name: "check_replies",
+      description: "The catch-up router for everything NOT tied to your current request: returns replies the user sent that you haven't seen yet (now marked seen) plus still-pending notifications you sent. Use it when booting up / starting a session, or when you've been waiting a long time on something else, to discover acks or work you're unaware of. To wait on a request you just sent, use await_reply instead.",
+      inputSchema: zodToJsonSchema(CheckRepliesSchema, { target: "openApi3" })
     },
     {
       name: "set_task_state",
@@ -271,11 +314,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const result = await pollAnswer(id);
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     }
-    case "await_task": {
-      AwaitTaskSchema.parse(request.params.arguments ?? {});
-      const item = await awaitTask();
+    case "await_reply": {
+      const { notificationId } = AwaitReplySchema.parse(request.params.arguments);
+      const item = await awaitReply(notificationId);
       return { content: [{ type: "text", text: JSON.stringify(item) }] };
     }
+    case "check_replies": {
+      CheckRepliesSchema.parse(request.params.arguments ?? {});
+      const result = await checkReplies();
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
     case "set_task_state": {
       const { notificationId, state } = SetTaskStateToolSchema.parse(request.params.arguments);
       const result = await setTaskState(notificationId, state);

package/dist/onboard.js

@@ -5,7 +5,7 @@ import { execFile } from "child_process";
 import { mkdirSync, writeFileSync } from "fs";
 import { homedir, platform } from "os";
 import { join } from "path";
-var BACKEND_URL = process.env.PERGY_BACKEND_URL ?? "http://localhost:3000";
+var BACKEND_URL = process.env.PERGY_BACKEND_URL ?? "https://pergy.ai";
 var AGENT_NAME = process.env.PERGY_AGENT ?? "mcp-agent";
 var TOKEN_PATH = join(homedir(), ".pergy", "token.json");
 function openBrowser(url) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pergy-ai/mcp",
-  "version": "0.1.0",
+  "version": "0.2.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",