@paigy/mcp 0.8.0 → 0.8.1

package/README.md

@@ -45,6 +45,51 @@ npx -p @paigy/mcp paigy-mcp-onboard
 It talks to the hosted backend by default — no config needed. Set
 `PAIGY_BACKEND_URL=http://localhost:3000` only for local development.
 
+### Codex CLI (OpenAI)
+
+Codex speaks MCP, so the same server drops in. Add it (writes `~/.codex/config.toml`):
+
+```bash
+codex mcp add paigy --env PAIGY_AGENT=codex -- npx -y @paigy/mcp
+```
+
+Or add the entry to `~/.codex/config.toml` by hand:
+
+```toml
+[mcp_servers.paigy]
+command = "npx"
+args = ["-y", "@paigy/mcp"]
+env = { PAIGY_AGENT = "codex" }
+```
+
+Then pair: `npx -p @paigy/mcp paigy-mcp-onboard` (or have the agent call the `pair` tool).
+
+### Gemini CLI
+
+```bash
+gemini mcp add -s user -e PAIGY_AGENT=gemini paigy npx -y @paigy/mcp
+```
+
+`-s user` makes it available across all projects — omit it for just the current one.
+Or add the entry to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "paigy": {
+      "command": "npx",
+      "args": ["-y", "@paigy/mcp"],
+      "env": { "PAIGY_AGENT": "gemini" }
+    }
+  }
+}
+```
+
+Then pair: `npx -p @paigy/mcp paigy-mcp-onboard`.
+
+> `PAIGY_AGENT` just names the agent on the device-approval screen (defaults to
+> `mcp-agent`) — set it per client so you can tell your connected agents apart.
+
 ## Tools
 
 - **`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.

package/dist/{chunk-4MRCUW5I.js → chunk-2BJSWNUX.js}

@@ -134,6 +134,14 @@ var InboxItemSchema = z.object({
   createdAt: z.string().datetime(),
   snoozedUntil: z.string().datetime().optional(),
   agentState: AgentStateSchema.default("idle"),
+  /** Whose action the item is waiting on: "you" = an agent asked you (the default,
+   *  every agent→user notification); "agent" = you sent a request and it's awaiting the
+   *  agent (held in the inbox until the agent replies on the thread). */
+  turn: z.enum(["you", "agent"]).default("you"),
+  /** Hard error reason on an awaiting request (turn="agent") — the wake failed to reach
+   *  the agent (provider-agnostic; set server-side). Absent = no hard error, though the
+   *  client may still flag a stall by age. Drives the inbox error badge + Retry. */
+  error: z.string().optional(),
   parentId: z.string().optional(),
   select: z.enum(["one", "many", "rank", "confirm"]).default("one"),
   confirmStyle: z.enum(["yesno", "approve"]).default("yesno").describe(
@@ -151,6 +159,16 @@ var PushTokenSchema = z.object({
   alertToken: z.string().min(1).optional(),
   platform: z.literal("ios")
 });
+var MissedCallSchema = z.enum([
+  "retry_10m",
+  "retry_30m",
+  "retry_60m",
+  "backoff_gentle",
+  "backoff_standard",
+  "backoff_aggressive",
+  "inbox",
+  "dismiss"
+]);
 var UserSettingsSchema = z.object({
   permissions: z.object({
     call: z.boolean(),
@@ -159,7 +177,10 @@ var UserSettingsSchema = z.object({
   }),
   sessionMode: z.enum(["default", "all_calls", "silent"]),
   silentPush: z.boolean(),
-  autoCallback: z.boolean()
+  autoCallback: z.boolean(),
+  /** Opt-in (default false) to using your content to improve Paigy and train models. */
+  improveConsent: z.boolean(),
+  missedCall: MissedCallSchema.default("backoff_standard")
 });
 var HistoryItemSchema = z.object({
   id: z.string(),
@@ -181,7 +202,13 @@ var ConnectionSummarySchema = z.object({
   agent: z.string(),
   device: z.string().nullable(),
   nickname: z.string(),
-  createdAt: z.string().datetime()
+  createdAt: z.string().datetime(),
+  /** Most recent notification on this connection, either direction. Null = no contact yet.
+   *  Drives the agents-page recency grouping (Today / This week / …). */
+  lastContactAt: z.string().datetime().nullable(),
+  /** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
+   *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
+  managed: z.boolean()
 });
 var CreateRequestSchema = z.object({
   /** The connection (token id) to send to, from GET /api/tokens. */
@@ -197,15 +224,6 @@ var OAuthStartSchema = z.object({
   provider: z.enum(["cma"]),
   returnTo: z.string().min(1)
 });
-var SetProviderSchema = z.object({
-  provider: z.enum(["cma"]),
-  /** Provider-side agent id (e.g. CMA `agent_…`). */
-  agentRef: z.string().min(1),
-  /** Provider-side environment id (e.g. CMA `env_…`). */
-  environmentId: z.string().min(1),
-  /** The delegated API key Paigy holds (in Vault) to spawn sessions on the user's behalf. */
-  apiKey: z.string().min(1)
-});
 var DeliveryConfigSchema = z.object({
   tokenId: z.string(),
   mode: DeliveryModeSchema,
@@ -247,6 +265,11 @@ var DeviceTokenSchema = z.object({
   agent: z.string(),
   device: z.string().nullable()
 });
+var SupportRequestSchema = z.object({
+  email: z.string().email().max(320),
+  message: z.string().trim().min(1).max(5e3),
+  name: z.string().trim().max(120).optional()
+});
 
 // src/client.ts
 import { existsSync, readFileSync } from "fs";

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   scheduleCallback,
   setTaskState,
   submitNotification
-} from "./chunk-4MRCUW5I.js";
+} from "./chunk-2BJSWNUX.js";
 import {
   deleteToken,
   openBrowser,
@@ -32,7 +32,33 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { execSync } from "child_process";
 import { z } from "zod";
+
+// src/schema.ts
 import { zodToJsonSchema } from "zod-to-json-schema";
+function draft2020(node) {
+  if (Array.isArray(node)) return node.map(draft2020);
+  if (node && typeof node === "object") {
+    const o = node;
+    for (const [excl, lim] of [["exclusiveMinimum", "minimum"], ["exclusiveMaximum", "maximum"]]) {
+      if (typeof o[excl] === "boolean") {
+        if (o[excl] === true && typeof o[lim] === "number") {
+          o[excl] = o[lim];
+          delete o[lim];
+        } else delete o[excl];
+      }
+    }
+    for (const k of Object.keys(o)) o[k] = draft2020(o[k]);
+    return o;
+  }
+  return node;
+}
+function json(s) {
+  const schema = zodToJsonSchema(s, { target: "jsonSchema2019-09", $refStrategy: "none" });
+  delete schema.$schema;
+  return draft2020(schema);
+}
+
+// src/index.ts
 var PollAnswerSchema = z.object({
   id: z.string().describe("Request id returned by notify_user.")
 });
@@ -80,47 +106,47 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "pair",
       description: "Pair this agent with the user's Paigy account (one-time) \u2014 required before notify_user/await_reply work. Two steps: (1) call with NO args to start; it opens the user's browser and returns { verification_uri_complete, user_code, device_code } \u2014 show the user the URL + user_code and ask them to approve. (2) call again passing that device_code to finish; it waits for approval and saves the token. If it returns { status:'pending' }, the user hasn't approved yet \u2014 call again with the same device_code to keep waiting.",
-      inputSchema: zodToJsonSchema(PairSchema, { target: "openApi3" })
+      inputSchema: json(PairSchema)
     },
     {
       name: "unpair",
       description: "Log out / unpair this agent from the user's Paigy account: revokes the token server-side (it stops working everywhere) and deletes the local ~/.paigy/token.json. Takes no arguments. After this, notify_user/await_reply won't work until the user pairs again with the pair tool.",
-      inputSchema: zodToJsonSchema(z.object({}), { target: "openApi3" })
+      inputSchema: json(z.object({}))
     },
     {
       name: "notify_user",
       description: "Notify the user via Paigy 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; 'push' is a quiet passive notification (no sound); 'banner' sends a time-sensitive banner/lock-screen push (a 'paige') they tap to open \u2014 for when you need them soon-ish but not enough to ring them; 'call' rings their phone now as a voice call \u2014 only when you genuinely need them in the moment (blocked/waiting, time-sensitive). ON A CALL, your title + description are READ ALOUD by a voice \u2014 write them to be HEARD, not read: keep it short and conversational, front-load the ask, and refer to things BY NAME, not by ID or code (say 'the pull request about the agents page', not 'PR #235'; 'the login-bug ticket', not 'ABC-1234'). Spell out only what's natural to say out loud. MATCH the answer shape to the question \u2014 pick the best tool for the job, not always yes/no. The user can ALWAYS add free text on top of any shape, so structuring loses nothing. Choose `select`: yes/no \u2192 select:'confirm' \u2192 {kind:'confirm', approved:boolean}. Approve/deny an action \u2192 select:'confirm' + confirmStyle:'approve' \u2192 {kind:'confirm', approved:boolean}. Both are answerable right from the banner. Pick one of several \u2192 options + select:'one' \u2192 {kind:'option', optionId}. Pick several / a subset \u2192 options + select:'many' \u2192 {kind:'multi', optionIds:[...]}. Rank or prioritize \u2192 options + select:'rank', user taps in preferred order \u2192 {kind:'ranked', optionIds:[...]}. For visual choices give each option a sandboxed `html` or an `image` preview (e.g. layout/UI alternatives). Only leave options off (pure free text / voice) when the answer genuinely can't be structured. Plus optional visuals. 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. To follow up on a call (e.g. the user asked you to 'call me back when it's done'), reuse the threadId from that call's reply so it threads as the same conversation.",
-      inputSchema: zodToJsonSchema(NotifyRequestSchema, { target: "openApi3" })
+      inputSchema: json(NotifyRequestSchema)
     },
     {
       name: "poll_answer",
       description: "Fetch the user's answer to a previous notify_user request. Returns status pending | answered | ignored, with the answer once present. Errors if the id is unknown or expired.",
-      inputSchema: zodToJsonSchema(PollAnswerSchema, { target: "openApi3" })
+      inputSchema: json(PollAnswerSchema)
     },
     {
       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. A CALL answer can come back as {kind:'turns', turns:[{prompt,reply}]} \u2014 the ordered log of that call. Read turns[0].reply as the user's main instruction and any later turns as their follow-up (e.g. the end-of-call 'call me back when it's done / I have a blocking question' reply). If they asked for a callback, re-engage in the SAME thread (notify_user with the reply's threadId) when the task is done or you hit a blocker \u2014 urgency:'call' for a blocker, 'banner'/'push'/'inbox' for done. Paigy has no scheduler; the callback is yours to send (use ScheduleWakeup/cron for timing).",
-      inputSchema: zodToJsonSchema(AwaitReplySchema, { target: "openApi3" })
+      inputSchema: json(AwaitReplySchema)
     },
     {
       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), still-pending notifications you sent, and `requests` \u2014 new requests the user started toward you (each { notificationId, threadId, text }, returned once). Act on each request and reply with notify_user on the SAME threadId. 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. Also returns owedCallbacks: callbacks now due that you promised \u2014 fulfill each with notify_user on its threadId.",
-      inputSchema: zodToJsonSchema(CheckRepliesSchema, { target: "openApi3" })
+      inputSchema: json(CheckRepliesSchema)
     },
     {
       name: "set_task_state",
       description: "Report progress on a request you received: in_progress (you started working), completed (done), or needs_input (you need more from the user \u2014 usually paired with a notify_user carrying parentId = this request's id).",
-      inputSchema: zodToJsonSchema(SetTaskStateToolSchema, { target: "openApi3" })
+      inputSchema: json(SetTaskStateToolSchema)
     },
     {
       name: "register_delivery",
       description: "Choose how Paigy reaches you when a reply or new request lands. 'self_hosted' makes Paigy PUSH it instantly over a realtime channel instead of you polling \u2014 but it only helps if a `paigy listen` daemon is running (npx -y @paigy/mcp paigy-listen), which the user runs once. 'poll' (default) keeps the catch-up model (check_replies / await_reply). Either way no work is ever lost: a missed push is reconciled by your next check_replies sweep.",
-      inputSchema: zodToJsonSchema(RegisterDeliveryToolSchema, { target: "openApi3" })
+      inputSchema: json(RegisterDeliveryToolSchema)
     },
     {
       name: "schedule_callback",
       description: "Promise the user a follow-up you'll keep even if you go idle. Use it when they ask you to report back: trigger 'on_done' (when you finish \u2014 fires when you call set_task_state completed), 'on_blocked' (if you hit a blocker \u2014 fires on set_task_state needs_input), or 'scheduled' with dueInSeconds (e.g. 'remind me in 10 min'). Pass the threadId of the conversation and a short note. Fulfill it by calling notify_user on that threadId; check_replies re-lists due callbacks until you do.",
-      inputSchema: zodToJsonSchema(ScheduleCallbackSchema, { target: "openApi3" })
+      inputSchema: json(ScheduleCallbackSchema)
     }
   ]
 }));

package/dist/listen.js

@@ -4,7 +4,7 @@ import {
   checkReplies,
   registerDelivery,
   wakeChannel
-} from "./chunk-4MRCUW5I.js";
+} from "./chunk-2BJSWNUX.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";

package/package.json

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