@webhooks-cc/mcp 1.22.0 → 1.24.0

package/dist/{chunk-VO7HGSRN.mjs → chunk-SOQIUGLA.mjs}

@@ -487,9 +487,28 @@ function keyText(key) {
 }
 function approvalResultText(result) {
   if (typeof result.key === "string") return keyText(result);
+  if (typeof result.spreadsheetId === "string") {
+    const tabs = Array.isArray(result.tabs) ? result.tabs.join(", ") : "";
+    return `Approved. The chosen spreadsheet is ${String(result.spreadsheetId)} (${String(result.url)}), on connection ${String(result.connectionId)}${tabs ? `; its tabs: ${tabs}` : ""}. Use them in a Sheets destination's config.`;
+  }
+  if (Array.isArray(result.fields)) {
+    return `Approved. AI setup proposed (nothing is saved until you apply it):
+${JSON.stringify(result, null, 2)}`;
+  }
+  if (typeof result.connectionId === "string") {
+    return `Approved. The Google account ${result.email ? `${String(result.email)} ` : ""}is connected as ${result.connectionId}.`;
+  }
   if (typeof result.url === "string") {
     return `Approved. The share link is ${result.url} (anyone with it can read the copy until ${String(result.expiresAt)}).`;
   }
+  if (typeof result.invitedEmail === "string") {
+    const team = typeof result.teamName === "string" ? ` to "${result.teamName}"` : "";
+    const warning = typeof result.warning === "string" ? ` ${result.warning} Tell them to sign up with that address and accept from their Teams page.` : " They get an email; accepting claims one of the team's seats.";
+    return `Approved. Invited ${result.invitedEmail}${team} (invite ${String(result.id)}).${warning}`;
+  }
+  if (typeof result.deleted === "string" && typeof result.teamId === "string") {
+    return `Approved. The team ${result.deleted ? `"${result.deleted}" ` : ""}was deleted; its subscription has ended.`;
+  }
   if (typeof result.removed === "string") {
     return `Approved. The domain ${result.removed} was removed; mail to it is refused now.`;
   }
@@ -564,6 +583,75 @@ function fitArrayField(value, key) {
   }
   return cut(low);
 }
+function isoTime(ms) {
+  if (ms === null || !Number.isFinite(ms)) return null;
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function searchStoppedNote(searchedUntil, order, hasCursor) {
+  const [direction, rest] = order === "asc" ? ["forward", "newer"] : ["back", "older"];
+  const reached = searchedUntil ? `Searched ${direction} to ${searchedUntil}; ${rest} requests were not searched yet.` : `The search stopped before it read everything; ${rest} requests were not searched yet.`;
+  return hasCursor ? `${reached} Call search_requests again with cursor to continue.` : reached;
+}
+var FULL_REQUEST_HINT = "The full request is available from the API (GET /api/requests/{id}), the SDKs (requests.get(id)) or the CLI (whk requests get <id>).";
+var SEARCH_SHORTENED_NOTE = `Some requests were shortened to fit the output (bodyTruncated with bodySize, or shortened: true for a summary); get_request with the id returns as much of one request as fits. ${FULL_REQUEST_HINT}`;
+var REQUEST_SHORTENED_NOTE = `This request was cut to fit the output: its body (bodyTruncated, with bodySize), or everything but a summary (shortened: true). ${FULL_REQUEST_HINT}`;
+function clip(value, max) {
+  return typeof value === "string" ? sliceText(value, max) : void 0;
+}
+function listedSize(request) {
+  return jsonSize([[request]]) - 8;
+}
+function fitSearchRequests(requests, room) {
+  const share = Math.floor(room / Math.max(1, requests.length));
+  const fitted = requests.map(
+    (request) => shortenRequest(request, share, listedSize)
+  );
+  if (fitted.every((request) => listedSize(request) <= share)) return fitted;
+  return requests.map((request) => {
+    const { id, receivedAt } = request;
+    return { id, receivedAt, shortened: true };
+  });
+}
+function shortenRequest(request, share, sizeOf) {
+  if (sizeOf(request) <= share) return request;
+  if (typeof request.body === "string") {
+    const body = request.body;
+    let keep = body.length - (sizeOf(request) - share) - 96;
+    while (keep > 0) {
+      const cut = {
+        ...request,
+        body: sliceText(body, keep),
+        bodyTruncated: true,
+        bodySize: body.length
+      };
+      if (sizeOf(cut) <= share) return cut;
+      keep = Math.floor(keep / 2);
+    }
+  }
+  const email = request.email;
+  const summary = {
+    id: request.id,
+    slug: clip(request.slug, 64),
+    method: clip(request.method, 16),
+    path: clip(request.path, 200),
+    contentType: clip(request.contentType, 100),
+    size: request.size,
+    receivedAt: request.receivedAt,
+    kind: request.kind,
+    ...email ? { subject: clip(email.subject, 200) } : {},
+    shortened: true,
+    ...typeof request.note === "string" ? { note: request.note } : {}
+  };
+  return summary;
+}
+function requestContent(request) {
+  const compact = compactRequest(request);
+  if (jsonSize(compact) <= MAX_BODY_SIZE) return jsonContent(compact);
+  return jsonContent(
+    shortenRequest({ ...compact, note: REQUEST_SHORTENED_NOTE }, MAX_BODY_SIZE, jsonSize)
+  );
+}
 function jsonContent(value) {
   return textContent(serializeJson(value));
 }
@@ -608,6 +696,13 @@ function serializeError(error) {
   } else if (error instanceof WebhooksCCError) {
     payload.code = error.statusCode >= 500 ? "server_error" : "validation_error";
   }
+  if (error instanceof WebhooksCCError && payload.hint === null) {
+    if (error.code === "invalid_cursor") {
+      payload.hint = "The cursor is not one this search returned, or the order changed since. Pass a cursor exactly as a result gave it, or search again without one.";
+    } else if (error.code === "search_busy") {
+      payload.hint = "The account's other searches are still running. Wait retryAfter seconds, then call again with the same inputs.";
+    }
+  }
   return JSON.stringify(payload, null, 2);
 }
 function withErrorHandling(handler) {
@@ -1059,6 +1154,124 @@ function registerTools(target, client, options = {}) {
       return jsonContent({ shared: false, slug, teamId });
     })
   );
+  server.tool(
+    "create_team",
+    "Create a team you own, to share endpoints with its members under a pooled quota. It does nothing until it has a subscription, which the person starts in the browser (Account > Teams); until then it is suspended.",
+    { name: z.string().trim().min(1).max(100).describe("The team's name") },
+    withErrorHandling(async ({ name }) => jsonContent(await client.teams.create(name)))
+  );
+  server.tool(
+    "rename_team",
+    "Rename a team you own.",
+    {
+      teamId: z.string().min(1).describe("Team id (from list_teams)"),
+      name: z.string().trim().min(1).max(100).describe("The new name")
+    },
+    withErrorHandling(async ({ teamId, name }) => {
+      await client.teams.rename(teamId, name);
+      return jsonContent({ renamed: true, teamId, name });
+    })
+  );
+  server.tool(
+    "delete_team",
+    "Delete a team you own: its subscription ends at once, every member loses the endpoints shared with it, and it cannot be undone. Only when the person asks for it. The team's owner must approve it: this returns a link and a code to show them, then call wait_for_approval.",
+    { teamId: z.string().min(1).describe("Team id (from list_teams)") },
+    withErrorHandling(async ({ teamId }) => {
+      const pending = await client.teams.delete(teamId);
+      if (!pending.id) return textContent(`Deleted the team ${teamId}.`);
+      return textContent(approvalAskText(pending));
+    })
+  );
+  server.tool(
+    "remove_team_member",
+    "Remove a member from a team you own: the endpoints they shared with the team stop being shared, and their seat is free for someone else. Only when the person asks for it.",
+    {
+      teamId: z.string().min(1).describe("Team id (from list_teams)"),
+      userId: z.string().min(1).describe("The member's userId (from list_team_members)")
+    },
+    withErrorHandling(async ({ teamId, userId }) => {
+      await client.teams.removeMember(teamId, userId);
+      return jsonContent({ removed: true, teamId, userId });
+    })
+  );
+  server.tool(
+    "leave_team",
+    "Leave a team you belong to: the endpoints you shared with it stop being shared, and you lose access to the ones shared with you through it. An owner cannot leave; they delete the team instead (delete_team). Only when the person asks for it.",
+    { teamId: z.string().min(1).describe("Team id (from list_teams)") },
+    withErrorHandling(async ({ teamId }) => {
+      await client.teams.leave(teamId);
+      return jsonContent({ left: true, teamId });
+    })
+  );
+  server.tool(
+    "invite_to_team",
+    "Invite an email address to a team you own. It emails that address, so the team's owner must approve it: this returns a link and a code to show them, then call wait_for_approval, which returns the invite. Accepting the invite claims one of the team's paid seats. Only when the person asks for it.",
+    {
+      teamId: z.string().min(1).describe("Team id (from list_teams)"),
+      email: z.string().trim().email().describe("The address to invite")
+    },
+    withErrorHandling(async ({ teamId, email }) => {
+      const pending = await client.teams.invite(teamId, email);
+      if (!pending.id) return textContent(approvalResultText({ ...await pending.wait() }));
+      return textContent(approvalAskText(pending));
+    })
+  );
+  server.tool(
+    "list_invites",
+    "List the team invites waiting for you to answer: team, who invited you, when, and the invite id for answer_invite.",
+    {},
+    withErrorHandling(async () => jsonContent(await client.teams.invites.list()))
+  );
+  server.tool(
+    "answer_invite",
+    "Accept or decline a team invite waiting for you (from list_invites). Accepting claims one of the team's paid seats and you join the team, seeing the endpoints shared with it; it fails when the team is full or suspended. Only when the person says which.",
+    {
+      inviteId: z.string().min(1).describe("The invite's id, from list_invites"),
+      answer: z.enum(["accept", "decline"]).describe("accept joins the team; decline turns it down")
+    },
+    withErrorHandling(async ({ inviteId, answer }) => {
+      if (answer === "accept") {
+        await client.teams.invites.accept(inviteId);
+        return jsonContent({ accepted: true, inviteId });
+      }
+      await client.teams.invites.decline(inviteId);
+      return jsonContent({ declined: true, inviteId });
+    })
+  );
+  server.tool(
+    "withdraw_invite",
+    "Withdraw an invite to a team you own before it is answered (pending invites and their ids are in list_team_members). The invite link stops working.",
+    {
+      teamId: z.string().min(1).describe("Team id (from list_teams)"),
+      inviteId: z.string().min(1).describe("The invite's id (from list_team_members' pendingInvites)")
+    },
+    withErrorHandling(async ({ teamId, inviteId }) => {
+      await client.teams.withdrawInvite(teamId, inviteId);
+      return jsonContent({ withdrawn: true, teamId, inviteId });
+    })
+  );
+  server.tool(
+    "quote_team_change",
+    "What changing a team's seat count or plan would cost, read only (owner only): what is due now, any credit, and the price from the renewal. Give seats, or plan (with interval). The change itself is made by the person in the browser.",
+    {
+      teamId: z.string().min(1).describe("Team id (from list_teams)"),
+      seats: z.number().int().min(1).optional().describe("Price this seat count"),
+      plan: z.enum(["team", "team_business"]).optional().describe("Price a move to this plan: team (Teams) or team_business (Team Business)"),
+      interval: z.enum(["month", "year"]).optional().describe("Billing interval for plan (default month; Teams is monthly only)")
+    },
+    withErrorHandling(async ({ teamId, seats, plan, interval }) => {
+      if (seats === void 0 === (plan === void 0)) {
+        throw new Error("Give seats or plan, not both.");
+      }
+      if (seats !== void 0) {
+        if (interval !== void 0) throw new Error("interval goes with plan, not seats.");
+        return jsonContent(await client.billing.quoteTeamSeats(teamId, seats));
+      }
+      return jsonContent(
+        await client.billing.quoteTeamPlan(teamId, plan, interval)
+      );
+    })
+  );
   server.tool(
     "get_endpoint",
     "Get details for a specific webhook endpoint by slug.",
@@ -1152,6 +1365,35 @@ function registerTools(target, client, options = {}) {
       return jsonContent(holder);
     })
   );
+  server.tool(
+    "list_layout_templates",
+    "List the ready-made email layouts (order emails from Shopify, WooCommerce, Etsy and more, payments, bookings, attachments): each with its id, sender, kind, description, the fields it reads and whether it reads line items. Add one with add_layout_template.",
+    { slug: z.string().describe("The endpoint slug") },
+    withErrorHandling(async ({ slug }) => jsonContent(await client.endpoints.layoutTemplates(slug)))
+  );
+  server.tool(
+    "add_layout_template",
+    "Add a ready-made layout (an id from list_layout_templates) to the end of an endpoint's layouts. Emails it matches are parsed from the next one on; check it on a captured email with preview_layouts. Owner only.",
+    {
+      slug: z.string().describe("The endpoint slug"),
+      template: z.string().min(1).describe("The template's id, from list_layout_templates")
+    },
+    withErrorHandling(
+      async ({ slug, template }) => jsonContent(await client.endpoints.addLayoutTemplate(slug, template))
+    )
+  );
+  server.tool(
+    "preview_email_fields",
+    "Dry run of an endpoint's named email fields on a captured email: each field's value (null where it finds nothing), and problems with fields you pass. Nothing is saved. Pass emailFields to try fields before saving them with update_endpoint. Owner only.",
+    {
+      slug: z.string().describe("The endpoint slug"),
+      requestId: z.string().optional().describe("A captured email on the endpoint (default: the newest)"),
+      emailFields: z.array(emailFieldSchema).max(20).optional().describe("Unsaved fields to try instead of the saved ones")
+    },
+    withErrorHandling(
+      async ({ slug, requestId, emailFields }) => jsonContent(await client.endpoints.previewEmailFields(slug, { requestId, emailFields }))
+    )
+  );
   server.tool(
     "preview_response",
     "Dry run of an endpoint's responses: which response rule answers a captured request, and the response with its {{ placeholders }} filled in, exactly as the receiver would send it. Nothing is sent. Pass mockResponse or responseRules to try settings before saving them with update_endpoint.",
@@ -1287,56 +1529,95 @@ function registerTools(target, client, options = {}) {
   );
   server.tool(
     "search_requests",
-    "Search captured webhook requests across endpoints using retained full-text search.",
+    "Search captured requests and emails across endpoints: a substring match on path, headers, body and decoded email fields. One call reads back through history for about 2 seconds and returns { requests, complete, searchedUntil, cursor }. When complete is false, older requests were not searched yet: call again with the cursor and the same filters to continue.",
     {
       slug: z.string().optional().describe("Filter to a specific endpoint slug"),
       method: z.string().optional().describe("Filter by HTTP method"),
       kind: kindSchema,
-      q: z.string().optional().describe("Free-text search across path, body, and headers"),
-      from: durationOrTimestampSchema.optional().describe('Start time as a timestamp or duration like "1h" or "7d"'),
-      to: durationOrTimestampSchema.optional().describe('End time as a timestamp or duration like "1h" or "7d"'),
+      q: z.string().optional().describe(
+        "Substring to find in the path, headers, body and decoded email fields (up to 1,000 characters)"
+      ),
+      from: durationOrTimestampSchema.optional().describe(
+        'Start time as a timestamp (Unix ms) or a duration back from now like "1h" or "7d". A duration is counted from each call, so when you continue with a cursor pass a timestamp to keep the same range.'
+      ),
+      to: durationOrTimestampSchema.optional().describe(
+        'End time as a timestamp (Unix ms) or a duration back from now like "1h" or "7d". A duration is counted from each call, so when you continue with a cursor pass a timestamp to keep the same range.'
+      ),
       limit: z.number().int().min(1).max(200).default(50).describe("Max results to return"),
-      offset: z.number().int().min(0).max(1e4).default(0).describe("Result offset"),
-      order: z.enum(["asc", "desc"]).default("desc").describe("Sort order by received time")
+      offset: z.number().int().min(0).max(1e4).default(0).describe("Matches to skip (first call only; a cursor carries what is left of it)"),
+      order: z.enum(["asc", "desc"]).default("desc").describe("Sort order by received time"),
+      cursor: z.string().optional().describe(
+        "The cursor from a previous search_requests result, to continue that search. Keep the other inputs the same."
+      )
     },
-    withErrorHandling(async ({ slug, method, kind, q, from, to, limit, offset, order }) => {
-      const results = await client.requests.search({
-        slug,
-        method,
-        kind,
-        q,
-        from,
-        to,
-        limit,
-        offset,
-        order
-      });
-      return jsonContent(results.map(compactRequest));
+    withErrorHandling(async ({ slug, method, kind, q, from, to, limit, offset, order, cursor }) => {
+      const page = await client.requests.searchPage(
+        { slug, method, kind, q, from, to, limit, offset, order },
+        { cursor }
+      );
+      const searchedUntil = isoTime(page.searchedUntil);
+      const envelope = (requests2, shortened) => {
+        const notes = [
+          ...page.complete ? [] : [searchStoppedNote(searchedUntil, order, Boolean(page.cursor))],
+          ...shortened ? [SEARCH_SHORTENED_NOTE] : []
+        ];
+        return {
+          requests: requests2,
+          complete: page.complete,
+          searchedUntil,
+          cursor: page.cursor,
+          ...notes.length > 0 ? { note: notes.join(" ") } : {}
+        };
+      };
+      const requests = page.requests.map(compactRequest);
+      if (jsonSize(envelope(requests, false)) <= MAX_BODY_SIZE) {
+        return jsonContent(envelope(requests, false));
+      }
+      const room = MAX_BODY_SIZE - jsonSize(envelope([], true)) - 8;
+      return jsonContent(envelope(fitSearchRequests(requests, room), true));
     })
   );
   server.tool(
     "count_requests",
-    "Count captured webhook requests that match the given filters.",
+    "Count captured requests and emails that match the given filters (q is a substring match on path, headers, body and decoded email fields). Returns { count, exact, searchedUntil, cursor }. With q or method a call counts back through history for about 2 seconds: when exact is false, count covers history back to searchedUntil only, and calling again with the cursor counts the next stretch (add the counts up).",
     {
       slug: z.string().optional().describe("Filter to a specific endpoint slug"),
       method: z.string().optional().describe("Filter by HTTP method"),
       kind: kindSchema,
-      q: z.string().optional().describe("Free-text search across path, body, and headers"),
-      from: durationOrTimestampSchema.optional().describe('Start time as a timestamp or duration like "1h" or "7d"'),
-      to: durationOrTimestampSchema.optional().describe('End time as a timestamp or duration like "1h" or "7d"')
+      q: z.string().optional().describe(
+        "Substring to find in the path, headers, body and decoded email fields (up to 1,000 characters)"
+      ),
+      from: durationOrTimestampSchema.optional().describe(
+        'Start time as a timestamp (Unix ms) or a duration back from now like "1h" or "7d". A duration is counted from each call, so when you continue with a cursor pass a timestamp to keep the same range.'
+      ),
+      to: durationOrTimestampSchema.optional().describe(
+        'End time as a timestamp (Unix ms) or a duration back from now like "1h" or "7d". A duration is counted from each call, so when you continue with a cursor pass a timestamp to keep the same range.'
+      ),
+      cursor: z.string().optional().describe(
+        "The cursor from a previous count_requests result, to count the next stretch. Keep the other inputs the same."
+      )
     },
-    withErrorHandling(async ({ slug, method, kind, q, from, to }) => {
-      const count = await client.requests.count({ slug, method, kind, q, from, to });
-      return jsonContent({ count });
+    withErrorHandling(async ({ slug, method, kind, q, from, to, cursor }) => {
+      const page = await client.requests.countPage({ slug, method, kind, q, from, to }, { cursor });
+      const searchedUntil = isoTime(page.searchedUntil);
+      return jsonContent({
+        count: page.count,
+        exact: page.exact,
+        searchedUntil,
+        cursor: page.cursor,
+        ...page.exact ? {} : {
+          note: `At least ${page.count}, counted ${searchedUntil ? `back to ${searchedUntil}` : "over part of the history"}; ${page.cursor ? "call count_requests again with cursor to count further (the counts add up)." : "there is no cursor to count further with."}`
+        }
+      });
     })
   );
   server.tool(
     "get_request",
-    "Get full details for a specific captured request by ID.",
+    "Get the details of a captured request by ID: method, path, headers and body. A request larger than the tool output has its body cut (bodyTruncated, bodySize) and a note saying where the whole request is available.",
     getRequestShape,
     withErrorHandling(async ({ requestId }) => {
       const request = await client.requests.get(requestId);
-      return jsonContent(compactRequest(request));
+      return requestContent(request);
     })
   );
   server.tool(
@@ -1345,7 +1626,7 @@ function registerTools(target, client, options = {}) {
     waitForRequestShape,
     withErrorHandling(async ({ endpointSlug, timeout, pollInterval }) => {
       const request = await client.requests.waitFor(endpointSlug, { timeout, pollInterval });
-      return jsonContent(compactRequest(request));
+      return requestContent(request);
     })
   );
   server.tool(
@@ -2099,7 +2380,7 @@ function registerTools(target, client, options = {}) {
   );
   server.tool(
     "wait_for_approval",
-    "Wait for the account's owner to answer an approval (from create_api_key, create_share_link, remove_domain or rename_account) and collect what it grants or did, such as the new API key or the share link. If they have not answered yet, call it again.",
+    "Wait for the account's owner to answer an approval (from create_api_key, create_share_link, remove_domain, rename_account, delete_team, invite_to_team, connect_google, pick_spreadsheet or ai_setup) and collect what it grants or did, such as the new API key, the share link or AI setup's proposals. If they have not answered yet, call it again.",
     {
       id: z.string().describe("The approval id"),
       timeout: durationOrTimestampSchema.default("45s").describe('How long to wait for the person, for example "45s"')
@@ -2267,6 +2548,109 @@ function registerTools(target, client, options = {}) {
       return textContent(approvalAskText(pending));
     })
   );
+  server.tool(
+    "list_google_connections",
+    "List the Google accounts connected for Google Sheets destinations (id, email, when connected), and whether Google Sheets is set up on this server.",
+    {},
+    withErrorHandling(async () => jsonContent(await client.google.connections()))
+  );
+  server.tool(
+    "connect_google",
+    "Connect a Google account for Google Sheets destinations. The account's owner must approve it: this returns a link and a code to show them, and approving takes them to Google to choose the account. Then call wait_for_approval for the new connection's id.",
+    {},
+    withErrorHandling(async () => textContent(approvalAskText(await client.google.connect())))
+  );
+  server.tool(
+    "pick_spreadsheet",
+    "Have the account's owner choose an existing spreadsheet from Google Drive with a connected account (to add rows to it from a Sheets destination). Returns a link and a code to show them; the page opens Google's picker. Then call wait_for_approval for the spreadsheet's id and tabs. To use a new spreadsheet instead, call create_spreadsheet.",
+    {
+      connectionId: z.string().describe("The Google connection's id, from list_google_connections")
+    },
+    withErrorHandling(
+      async ({ connectionId }) => textContent(approvalAskText(await client.google.pick(connectionId)))
+    )
+  );
+  server.tool(
+    "create_spreadsheet",
+    "Create a new spreadsheet with a header row in a connected Google account, for a Sheets destination. Needs no approval: the app reaches only spreadsheets it created or that were chosen for it.",
+    {
+      connectionId: z.string().describe("The Google connection's id, from list_google_connections"),
+      title: z.string().max(200).optional().describe("The spreadsheet's title"),
+      sheet: z.string().max(100).optional().describe('The tab rows go to (default "Sheet1")'),
+      headers: z.array(z.string().max(200)).max(50).describe("The header row, one per column")
+    },
+    withErrorHandling(
+      async ({ connectionId, title, sheet, headers }) => jsonContent(await client.google.createSpreadsheet({ connectionId, title, sheet, headers }))
+    )
+  );
+  server.tool(
+    "list_sheet_tabs",
+    "List a spreadsheet's tabs (one created by the app or chosen with pick_spreadsheet), to choose the one a Sheets destination writes to.",
+    {
+      connectionId: z.string().describe("The Google connection's id"),
+      spreadsheetId: z.string().describe("The spreadsheet's id")
+    },
+    withErrorHandling(
+      async ({ connectionId, spreadsheetId }) => jsonContent({ tabs: await client.google.tabs(connectionId, spreadsheetId) })
+    )
+  );
+  server.tool(
+    "disconnect_google",
+    "Disconnect a Google account (id from list_google_connections) and revoke its access at Google. Sheets destinations using it fail until another account is chosen.",
+    {
+      connectionId: z.string().describe("The Google connection's id")
+    },
+    withErrorHandling(async ({ connectionId }) => {
+      await client.google.disconnect(connectionId);
+      return textContent(`Disconnected the Google account ${connectionId}.`);
+    })
+  );
+  server.tool(
+    "ai_setup_status",
+    "Whether AI setup is offered for an endpoint, and how many AI assists the plan has left in a rolling 30 days.",
+    {
+      slug: z.string().describe("The endpoint's slug")
+    },
+    withErrorHandling(async ({ slug }) => jsonContent(await client.ai.status(slug)))
+  );
+  server.tool(
+    "ai_setup",
+    "Have AI propose email fields (or a layout, or a repaired field) from 1 to 5 of an endpoint's captured emails. It sends those emails (subject, sender, recipients, text, headers; never attachments) to Anthropic's model, so the account's owner must approve it: this returns a link and a code to show them, and the page lists the emails. Then call wait_for_approval for the proposals, each with the value it found in every email. Nothing is saved: apply the fields with update_endpoint. Uses one AI assist.",
+    {
+      slug: z.string().describe("The endpoint's slug"),
+      requestIds: z.array(z.string()).min(1).max(5).describe("1 to 5 of the endpoint's email request ids, from list_emails"),
+      ask: z.union([
+        z.object({
+          kind: z.literal("field"),
+          name: z.string().describe("The field's name: letters, digits and _"),
+          description: z.string().describe('What the field is, such as "the order number"')
+        }),
+        z.object({
+          kind: z.literal("layout"),
+          description: z.string().optional().describe("What these emails are")
+        }),
+        z.object({
+          kind: z.literal("repair"),
+          field: z.object({
+            name: z.string(),
+            from: z.string(),
+            header: z.string().optional(),
+            pattern: z.string()
+          }).describe("The field to repair, as the endpoint has it")
+        })
+      ]).describe("What to propose")
+    },
+    withErrorHandling(
+      async ({ slug, requestIds, ask }) => textContent(
+        approvalAskText(
+          await client.ai.setup(slug, {
+            requestIds,
+            ask
+          })
+        )
+      )
+    )
+  );
   server.tool(
     "stop_share",
     "Stop a public preview or live tunnel by its id (from list_shares). The CLI running it is told why and exits.",