@pergy-ai/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauricio Urdaneta Uribe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @pergy-ai/mcp
+
+A voice inbox for your AI agents. This MCP server lets an agent **notify a user** and **await their reply** — so a long-running agent can ask a question, hand off, and resume on the answer.
+
+## Install
+
+No clone needed — run it with `npx`:
+
+```bash
+npx @pergy-ai/mcp
+```
+
+Or wire it into an MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "pergy": {
+      "command": "npx",
+      "args": ["-y", "@pergy-ai/mcp"],
+      "env": { "PERGY_BACKEND_URL": "https://pergy.ai" }
+    }
+  }
+}
+```
+
+First-time pairing (link the server to your Pergy account):
+
+```bash
+npx -p @pergy-ai/mcp pergy-mcp-onboard
+```
+
+## 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`).
+- **`poll_answer`** — fetch the answer to a specific request by id.
+- **`set_task_state`** — report progress on a request: `in_progress` / `completed` / `needs_input`.
+
+## Configuration
+
+- `PERGY_BACKEND_URL` — the Pergy API base (defaults to the hosted backend).
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+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 OptionSchema = z.object({
+  id: z.string(),
+  label: z.string()
+});
+var VisualSchema = z.object({
+  url: z.string().url(),
+  label: z.string().optional()
+});
+var AgentSchema = z.object({
+  name: z.string()
+});
+var NotifyRequestSchema = z.object({
+  context: ContextTiersSchema,
+  options: z.array(OptionSchema).optional(),
+  visuals: z.array(VisualSchema).optional(),
+  agent: AgentSchema,
+  /** Git repo the agent is working in ("owner/name"), when applicable. */
+  repo: z.string().optional(),
+  /** Git branch the agent is on, when applicable. */
+  branch: z.string().optional(),
+  /** 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"),
+  /** The request this one was spawned from, for a clarification. */
+  parentId: z.string().optional()
+});
+var NotifyStatusSchema = z.enum(["pending", "answered", "ignored"]);
+var AgentStateSchema = z.enum(["idle", "in_progress", "completed", "needs_input"]);
+var SetTaskStateSchema = z.object({
+  state: z.enum(["in_progress", "completed", "needs_input"])
+});
+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") })
+]);
+var AwaitItemSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("reply"),
+    threadId: z.string(),
+    notificationId: z.string(),
+    answer: UserAnswerSchema
+  }),
+  z.object({
+    type: z.literal("remind"),
+    threadId: z.string(),
+    notificationId: z.string(),
+    remindAt: z.string().datetime({ offset: true }),
+    /** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
+    remindInSeconds: z.number()
+  }),
+  z.object({ type: z.literal("idle") })
+]);
+var NotifyResponseSchema = z.object({
+  id: z.string(),
+  status: NotifyStatusSchema,
+  createdAt: z.string().datetime(),
+  answer: UserAnswerSchema.optional(),
+  answeredAt: z.string().datetime().optional()
+});
+var UserResponseSchema = z.object({
+  requestId: z.string(),
+  answer: UserAnswerSchema,
+  answeredAt: z.string().datetime()
+});
+var InboxItemSchema = z.object({
+  id: z.string(),
+  context: ContextTiersSchema,
+  options: z.array(OptionSchema).optional(),
+  visuals: z.array(VisualSchema).optional(),
+  agent: z.string(),
+  nickname: z.string(),
+  repo: z.string().optional(),
+  branch: z.string().optional(),
+  createdAt: z.string().datetime(),
+  snoozedUntil: z.string().datetime().optional(),
+  agentState: AgentStateSchema.default("idle"),
+  parentId: z.string().optional()
+});
+var SnoozeRequestSchema = z.object({
+  requestId: z.string(),
+  until: z.string().datetime()
+});
+var DeviceAgentTokenSchema = z.object({
+  token: z.string(),
+  deviceId: z.string(),
+  agentName: z.string(),
+  /** User-chosen session label; defaults to `<agent> <device>`. */
+  nickname: z.string(),
+  createdAt: z.string().datetime()
+});
+var PairingStatusSchema = z.enum(["pending", "approved", "denied", "expired"]);
+var DeviceCodeSchema = z.object({
+  device_code: z.string(),
+  user_code: z.string(),
+  verification_uri: z.string().url(),
+  verification_uri_complete: z.string().url(),
+  interval: z.number(),
+  expires_in: z.number()
+});
+var DeviceInfoSchema = z.object({
+  code: z.string(),
+  agent: z.string(),
+  device: z.string().nullable(),
+  status: PairingStatusSchema
+});
+var DeviceTokenSchema = z.object({
+  access_token: z.string(),
+  nickname: z.string(),
+  agent: z.string(),
+  device: z.string().nullable()
+});
+
+// src/index.ts
+import { z as z2 } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+// src/client.ts
+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 TOKEN_PATH = join(homedir(), ".pergy", "token.json");
+function loadToken() {
+  if (process.env.PERGY_TOKEN) return process.env.PERGY_TOKEN;
+  if (existsSync(TOKEN_PATH)) {
+    try {
+      const raw = readFileSync(TOKEN_PATH, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed.access_token) return parsed.access_token;
+    } catch {
+    }
+  }
+  return "";
+}
+async function submitNotification(req) {
+  const token = loadToken();
+  const res = await fetch(`${BACKEND_URL}/api/notify`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(req)
+  });
+  if (!res.ok) throw new Error(`notify failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function awaitTask(opts = {}) {
+  const intervalMs = opts.intervalMs ?? 5e3;
+  const windowMs = opts.windowMs ?? 3e5;
+  const doSleep = opts.sleep ?? sleep;
+  const now = opts.now ?? Date.now;
+  const token = loadToken();
+  const start = now();
+  while (true) {
+    const res = await fetch(`${BACKEND_URL}/api/await`, {
+      headers: { authorization: `Bearer ${token}` }
+    });
+    if (!res.ok) throw new Error(`await failed: ${res.status} ${await res.text()}`);
+    const item = await res.json();
+    if (item.type !== "idle") return item;
+    if (now() - start >= windowMs) return { type: "idle" };
+    await doSleep(intervalMs);
+  }
+}
+async function setTaskState(id, state) {
+  const res = await fetch(`${BACKEND_URL}/api/notify/${id}/state`, {
+    method: "PATCH",
+    headers: { "content-type": "application/json", authorization: `Bearer ${loadToken()}` },
+    body: JSON.stringify({ state })
+  });
+  if (!res.ok) throw new Error(`set_task_state failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+async function pollAnswer(id) {
+  const token = loadToken();
+  const res = await fetch(`${BACKEND_URL}/api/poll/${id}`, {
+    headers: { authorization: `Bearer ${token}` }
+  });
+  if (!res.ok) throw new Error(`poll failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+
+// src/index.ts
+var PollAnswerSchema = z2.object({
+  id: z2.string().describe("Request id returned by notify_user.")
+});
+var AwaitTaskSchema = z2.object({});
+var SetTaskStateToolSchema = z2.object({
+  notificationId: z2.string(),
+  state: SetTaskStateSchema.shape.state
+});
+function detectGit() {
+  const run = (cmd) => {
+    try {
+      return execSync(cmd, { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" }).trim();
+    } catch {
+      return "";
+    }
+  };
+  const remote = run("git remote get-url origin");
+  const match = remote.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/);
+  const branch = run("git rev-parse --abbrev-ref HEAD");
+  return {
+    repo: match ? match[1] : void 0,
+    branch: branch && branch !== "HEAD" ? branch : void 0
+  };
+}
+var server = new Server(
+  { name: "pergy", version: "0.0.0" },
+  { capabilities: { tools: {} } }
+);
+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.",
+      inputSchema: zodToJsonSchema(NotifyRequestSchema, { target: "openApi3" })
+    },
+    {
+      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" })
+    },
+    {
+      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: "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" })
+    }
+  ]
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  switch (request.params.name) {
+    case "notify_user": {
+      const parsed = NotifyRequestSchema.parse(request.params.arguments);
+      const git = detectGit();
+      const enriched = {
+        ...parsed,
+        repo: parsed.repo ?? git.repo,
+        branch: parsed.branch ?? git.branch
+      };
+      const result = await submitNotification(enriched);
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
+    case "poll_answer": {
+      const { id } = PollAnswerSchema.parse(request.params.arguments);
+      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();
+      return { content: [{ type: "text", text: JSON.stringify(item) }] };
+    }
+    case "set_task_state": {
+      const { notificationId, state } = SetTaskStateToolSchema.parse(request.params.arguments);
+      const result = await setTaskState(notificationId, state);
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
+    default:
+      throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+});
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/onboard.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+// src/onboard.ts
+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 AGENT_NAME = process.env.PERGY_AGENT ?? "mcp-agent";
+var TOKEN_PATH = join(homedir(), ".pergy", "token.json");
+function openBrowser(url) {
+  const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
+  const args = platform() === "win32" ? ["/c", "start", url] : [url];
+  execFile(cmd, args, (err) => {
+    if (err) {
+    }
+  });
+}
+function saveToken(token) {
+  const dir = join(homedir(), ".pergy");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(TOKEN_PATH, JSON.stringify(token, null, 2) + "\n", { mode: 384 });
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function requestCode() {
+  const res = await fetch(`${BACKEND_URL}/api/device/code`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ agent: AGENT_NAME })
+  });
+  if (!res.ok) throw new Error(`/api/device/code failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+async function pollToken(deviceCode) {
+  const res = await fetch(`${BACKEND_URL}/api/device/token`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ device_code: deviceCode })
+  });
+  if (res.ok) return await res.json();
+  const body = await res.json().catch(() => ({ error: "unknown" }));
+  const err = body.error ?? "unknown";
+  if (err === "authorization_pending") return null;
+  if (err === "expired_token") throw new Error("Device code expired. Please re-run onboarding.");
+  if (err === "access_denied") throw new Error("Access denied by user. Onboarding cancelled.");
+  throw new Error(`Unexpected error from /api/device/token: ${err}`);
+}
+async function main() {
+  console.log(`
+Pergy MCP onboarding (agent: "${AGENT_NAME}")
+`);
+  const code = await requestCode();
+  console.log("Open this URL in your browser to approve the connection:\n");
+  console.log(`  ${code.verification_uri_complete}
+`);
+  console.log(`  (User code: ${code.user_code})
+`);
+  openBrowser(code.verification_uri_complete);
+  const intervalMs = (code.interval ?? 5) * 1e3;
+  const expiresAt = Date.now() + code.expires_in * 1e3;
+  process.stdout.write("Waiting for approval");
+  while (Date.now() < expiresAt) {
+    await sleep(intervalMs);
+    process.stdout.write(".");
+    try {
+      const token = await pollToken(code.device_code);
+      if (token !== null) {
+        saveToken(token);
+        console.log(`
+
+Paired! Token saved to ${TOKEN_PATH} (mode 0600).`);
+        console.log("Treat this token like a password \u2014 it grants account access. Never log, echo, or commit it.");
+        console.log(`  Nickname : ${token.nickname}`);
+        console.log(`  Agent    : ${token.agent}`);
+        console.log(`  Device   : ${token.device ?? "(none)"}
+`);
+        return;
+      }
+    } catch (err) {
+      console.error(`
+
+${err.message}
+`);
+      process.exit(1);
+    }
+  }
+  console.error("\n\nDevice code expired without approval. Please re-run onboarding.\n");
+  process.exit(1);
+}
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});
+export {
+  TOKEN_PATH
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@pergy-ai/mcp",
+  "version": "0.1.0",
+  "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",
+  "bin": {
+    "mcp": "./dist/index.js",
+    "pergy-mcp": "./dist/index.js",
+    "pergy-mcp-onboard": "./dist/onboard.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mauurda/pergy.git",
+    "directory": "apps/mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.24.1",
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "@pergy/schema": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/onboard.ts --format esm --clean",
+    "dev": "tsup src/index.ts src/onboard.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}