@paigy/mcp 0.8.0 → 0.8.2

package/README.md

@@ -20,7 +20,7 @@ approve).
 No clone needed. Add it to Claude Code (`-s user` = available in every project; drop it for just the current one):
 
 ```bash
-claude mcp add paigy -s user -- npx -y @paigy/mcp
+claude mcp add paigy -s user -- npx -y @paigy/mcp@latest
 ```
 
 Or wire it into any MCP client config:
@@ -30,7 +30,7 @@ Or wire it into any MCP client config:
   "mcpServers": {
     "paigy": {
       "command": "npx",
-      "args": ["-y", "@paigy/mcp"]
+      "args": ["-y", "@paigy/mcp@latest"]
     }
   }
 }
@@ -39,12 +39,57 @@ Or wire it into any MCP client config:
 First-time pairing (link the server to your Paigy account):
 
 ```bash
-npx -p @paigy/mcp paigy-mcp-onboard
+npx -p @paigy/mcp@latest 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@latest
+```
+
+Or add the entry to `~/.codex/config.toml` by hand:
+
+```toml
+[mcp_servers.paigy]
+command = "npx"
+args = ["-y", "@paigy/mcp@latest"]
+env = { PAIGY_AGENT = "codex" }
+```
+
+Then pair: `npx -p @paigy/mcp@latest 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@latest
+```
+
+`-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@latest"],
+      "env": { "PAIGY_AGENT": "gemini" }
+    }
+  }
+}
+```
+
+Then pair: `npx -p @paigy/mcp@latest 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.
@@ -57,6 +102,17 @@ It talks to the hosted backend by default — no config needed. Set
 
 - `PAIGY_BACKEND_URL` — the Paigy API base (defaults to the hosted backend).
 
+## Publishing (maintainers)
+
+Tool input schemas are generated from zod in `src/schema.ts` as draft-2020-12 JSON
+Schema, and `src/schema.test.ts` guards that every tool stays valid (strict clients
+like the Anthropic API reject anything else). **A schema fix only reaches agents once
+a new version is published to npm** — 0.8.0 once shipped *without* a committed fix and
+400'd strict clients for weeks. So after any change under `src/schema*` or the tool
+definitions: **bump the version and `pnpm publish`** (don't rely on the commit alone).
+Install recipes pin `@paigy/mcp@latest` so a fresh `npx` picks up the new version; if a
+stale one sticks, `rm -rf ~/.npm/_npx` and restart the client.
+
 ## License
 
 MIT

package/dist/{chunk-XXBSXCOC.js → chunk-AILC3H3U.js}

@@ -1,9 +1,13 @@
+import {
+  BACKEND_URL,
+  reach
+} from "./chunk-GU7C5H6L.js";
+
 // src/device.ts
 import { execFile } from "child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { homedir, platform } from "os";
 import { join } from "path";
-var BACKEND_URL = process.env.PAIGY_BACKEND_URL ?? "https://paigy.ai";
 var AGENT_NAME = process.env.PAIGY_AGENT ?? "mcp-agent";
 var TOKEN_PATH = join(homedir(), ".paigy", "token.json");
 function openBrowser(url) {
@@ -33,14 +37,14 @@ function deleteToken() {
   return true;
 }
 async function revokeToken(token) {
-  const res = await fetch(`${BACKEND_URL}/api/device/revoke`, {
+  const res = await reach(`${BACKEND_URL}/api/device/revoke`, {
     method: "POST",
     headers: { authorization: `Bearer ${token}` }
   });
   return res.ok;
 }
 async function requestCode(agent = AGENT_NAME) {
-  const res = await fetch(`${BACKEND_URL}/api/device/code`, {
+  const res = await reach(`${BACKEND_URL}/api/device/code`, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ agent })
@@ -49,7 +53,7 @@ async function requestCode(agent = AGENT_NAME) {
   return await res.json();
 }
 async function pollToken(deviceCode) {
-  const res = await fetch(`${BACKEND_URL}/api/device/token`, {
+  const res = await reach(`${BACKEND_URL}/api/device/token`, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({ device_code: deviceCode })

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

@@ -1,3 +1,8 @@
+import {
+  BACKEND_URL,
+  reach
+} from "./chunk-GU7C5H6L.js";
+
 // ../../packages/schema/dist/index.js
 import { z } from "zod";
 var ContextSchema = z.object({
@@ -134,6 +139,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 +164,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 +182,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 +207,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 +229,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,12 +270,16 @@ 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";
 import { homedir } from "os";
 import { join } from "path";
-var BACKEND_URL = process.env.PAIGY_BACKEND_URL ?? "https://paigy.ai";
 var TOKEN_PATH = join(homedir(), ".paigy", "token.json");
 function loadToken() {
   if (process.env.PAIGY_TOKEN) return process.env.PAIGY_TOKEN;
@@ -273,7 +300,7 @@ function ensureAuthed(res) {
 }
 async function submitNotification(req) {
   const token = loadToken();
-  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/notify`, {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/notify`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
     body: JSON.stringify(req)
@@ -290,7 +317,7 @@ async function awaitReply(notificationId, opts = {}) {
   const token = loadToken();
   const start = now();
   while (true) {
-    const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/await?notificationId=${encodeURIComponent(notificationId)}`, {
+    const res = ensureAuthed(await reach(`${BACKEND_URL}/api/await?notificationId=${encodeURIComponent(notificationId)}`, {
       headers: { authorization: `Bearer ${token}` }
     }));
     if (!res.ok) throw new Error(`await failed: ${res.status} ${await res.text()}`);
@@ -302,14 +329,14 @@ async function awaitReply(notificationId, opts = {}) {
 }
 async function checkReplies() {
   const token = loadToken();
-  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/pending`, {
+  const res = ensureAuthed(await reach(`${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 = ensureAuthed(await fetch(`${BACKEND_URL}/api/notify/${id}/state`, {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/notify/${id}/state`, {
     method: "PATCH",
     headers: { "content-type": "application/json", authorization: `Bearer ${loadToken()}` },
     body: JSON.stringify({ state })
@@ -318,7 +345,7 @@ async function setTaskState(id, state) {
   return await res.json();
 }
 async function registerDelivery(mode) {
-  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/delivery`, {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/delivery`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${loadToken()}` },
     body: JSON.stringify({ mode })
@@ -328,7 +355,7 @@ async function registerDelivery(mode) {
 }
 async function scheduleCallback(req) {
   const token = loadToken();
-  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/callback`, {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/callback`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
     body: JSON.stringify(req)
@@ -338,7 +365,7 @@ async function scheduleCallback(req) {
 }
 async function pollAnswer(id) {
   const token = loadToken();
-  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/poll/${id}`, {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/poll/${id}`, {
     headers: { authorization: `Bearer ${token}` }
   }));
   if (!res.ok) throw new Error(`poll failed: ${res.status} ${await res.text()}`);

package/dist/chunk-GU7C5H6L.js

@@ -0,0 +1,15 @@
+// src/http.ts
+var BACKEND_URL = process.env.PAIGY_BACKEND_URL ?? "https://paigy.ai";
+var NETWORK_MSG = `Can't reach ${BACKEND_URL} \u2014 the connection was blocked or dropped before an HTTP response. If this agent runs in a sandboxed environment with a network allowlist (e.g. Claude Code on the web, CI), ask the user to add the Paigy domain (paigy.ai) to the environment's allowed domains, then retry.`;
+async function reach(url, init) {
+  try {
+    return await fetch(url, init);
+  } catch (e) {
+    throw new Error(`${NETWORK_MSG} (${e?.message ?? String(e)})`);
+  }
+}
+
+export {
+  BACKEND_URL,
+  reach
+};

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   scheduleCallback,
   setTaskState,
   submitNotification
-} from "./chunk-4MRCUW5I.js";
+} from "./chunk-BUELEUTV.js";
 import {
   deleteToken,
   openBrowser,
@@ -21,7 +21,8 @@ import {
   revokeToken,
   saveToken,
   sleep
-} from "./chunk-XXBSXCOC.js";
+} from "./chunk-AILC3H3U.js";
+import "./chunk-GU7C5H6L.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -32,7 +33,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 +107,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,8 @@ import {
   checkReplies,
   registerDelivery,
   wakeChannel
-} from "./chunk-4MRCUW5I.js";
+} from "./chunk-BUELEUTV.js";
+import "./chunk-GU7C5H6L.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";

package/dist/onboard.js

@@ -7,7 +7,8 @@ import {
   requestCode,
   saveToken,
   sleep
-} from "./chunk-XXBSXCOC.js";
+} from "./chunk-AILC3H3U.js";
+import "./chunk-GU7C5H6L.js";
 
 // src/onboard.ts
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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",