@zaapi/open-api-mcp 1.2.0 → 1.3.0

package/dist/client.js

@@ -1,6 +1,7 @@
 import { loadConfig } from './config.js';
 const PAGE_SIZE_HEADER = 'x-pagination-page-size';
 const NEXT_CURSOR_HEADER = 'x-pagination-next-cursor';
+const RETRY_AFTER_HEADER = 'retry-after';
 export class ZaapiClient {
     config;
     fetchFn;
@@ -8,6 +9,9 @@ export class ZaapiClient {
         this.config = config;
         this.fetchFn = fetchFn;
     }
+    get baseUrl() {
+        return this.config.baseUrl;
+    }
     static fromEnv(env = process.env, fetchFn = fetch) {
         return new ZaapiClient(loadConfig(env), fetchFn);
     }
@@ -40,6 +44,7 @@ export class ZaapiClient {
                 pageSize: response.headers.get(PAGE_SIZE_HEADER) ?? undefined,
                 nextCursor: response.headers.get(NEXT_CURSOR_HEADER) ?? undefined,
             },
+            retryAfter: response.headers.get(RETRY_AFTER_HEADER) ?? undefined,
         };
     }
     buildUrl(path, query) {

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoB,MAAM,aAAa,CAAC;AAsB3D,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AAClD,MAAM,kBAAkB,GAAG,0BAA0B,CAAC;AAEtD,MAAM,OAAO,WAAW;IAEH;IACA;IAFnB,YACmB,MAAmB,EACnB,UAAmB,KAAK;QADxB,WAAM,GAAN,MAAM,CAAa;QACnB,YAAO,GAAP,OAAO,CAAiB;IACxC,CAAC;IAEJ,MAAM,CAAC,OAAO,CACZ,MAA2B,OAAO,CAAC,GAAG,EACtC,UAAmB,KAAK;QAExB,OAAO,IAAI,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAqB;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QACvD,MAAM,OAAO,GAA2B;YACtC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC/B,MAAM,EAAE,kBAAkB;SAC3B,CAAC;QAEF,MAAM,IAAI,GAAgB,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QAC9D,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YAC7C,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;YAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,IAAI,GAAY,IAAI,CAAC;QACzB,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC;gBACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,GAAG,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,IAAI;YACJ,UAAU,EAAE;gBACV,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,SAAS;gBAC7D,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,SAAS;aAClE;SACF,CAAC;IACJ,CAAC;IAEO,QAAQ,CAAC,IAAY,EAAE,KAA+B;QAC5D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;QACxB,CAAC;QAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBAC1C,SAAS;YACX,CAAC;YACD,GAAG,CAAC,YAAY,CAAC,GAAG,CAClB,GAAG,EACH,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/instructions.js

@@ -0,0 +1,73 @@
+export const INSTRUCTIONS = `Zaapi is a shared inbox for sellers. Customer conversations from LINE, Instagram, Facebook, WhatsApp, Shopee, Lazada, TikTok, email and the web widget land in one place, and the team works them as tickets.
+
+This server exposes the public Zaapi Open API. The API key selects the store, so every call is already scoped to one store and there is no storeId argument anywhere.
+
+# How the data links together
+
+- **Account** — one connected channel inbox (a LINE OA, an Instagram account, a Shopee shop, a mailbox). \`listAccounts\`.
+- **Contact** — one person. Holds name, emails, phones, addresses, and \`customFields\` keyed by contact field id. \`getContactById\`, \`searchContacts\`, \`listContacts\`.
+- **Conversation** — one ongoing thread between a contact and an account, on one channel. Carries \`contactId\`, \`accountId\`, \`labelIds\`, an unread count and a last-message snippet. \`filterConversations\`.
+- **Ticket** — one unit of work over a slice of a conversation's timeline, with \`ticketNumber\`, an assignee, an open/closed state, and \`ticketFields\` keyed by ticket field id. A conversation accumulates many tickets over its life and has at most one open at a time. \`listTickets\`, \`getTicketById\`.
+- **Message** — one customer-facing message on a conversation. \`getMessages\`, \`searchMessages\`.
+- **Internal comment** — a seller-private note on a conversation. Never delivered to the customer. \`listInternalComments\`.
+- **User** — a seat on the store. **Team** — a named group of users. \`listUsers\`, \`listTeams\`.
+- **Label** — a tag applied to a conversation. \`listLabels\`.
+- **Ticket field / contact field** — the store's custom field definitions. \`listTicketFields\`, \`listContactFields\`.
+
+Contact → many conversations (one per channel it writes from) → many tickets over time. A ticket also carries \`conversationId\`, \`contactId\` and \`accountId\` directly, so one \`listTickets\` call usually gives you every id the rest of the task needs.
+
+Note what hangs off which object. **Labels, messages and internal comments belong to the conversation, not to the ticket** — labelling or reading a thread affects every ticket on it. **Ticket fields belong to the ticket**; **contact fields belong to the contact**.
+
+# Where to start
+
+There is no endpoint that lists conversations or messages on their own. Every read starts from one of these:
+
+- **A queue, a person's workload, a filtered set of work** → \`listTickets\`. With no filters it returns the live queue: open, non-spam, not snoozed, newest message first. This is the default entry point.
+- **A topic, a phrase, something the customer said** → \`searchMessages\`. The only way to reach a thread from its content. Every hit carries \`conversationId\`.
+- **A person by name, email or phone** → \`searchContacts\`, then \`filterConversations\` with the \`contactId\` for their threads.
+- **A ticket number or id already in hand** → \`getTicketById\`.
+
+From a \`conversationId\` you can reach everything else: \`getMessages\` for the thread, \`listInternalComments\` for private notes, \`listTickets\` with \`conversationId\` for its full ticket history (set \`statuses\` or omit it to include closed ones), \`filterConversations\` for labels and the contact.
+
+# Custom fields
+
+\`ticketFields\` and \`customFields\` are maps keyed by **field id**, never by field name. When a request names a field in words ("order number", "loyalty tier"), call \`listTicketFields\` or \`listContactFields\` first and match on \`name\` to get the id. Those catalogs also give you \`dataType\`, \`selectOptions\` and \`regex\` — a value that does not match the definition is rejected.
+
+Ticket fields additionally accept four system keys wherever a \`ticketFieldId\` is taken: \`isConverted\`, \`salesRevenue\`, \`aiCsat\`, \`aiSummary\`.
+
+# Users and assignment
+
+\`listUsers\` returns two identifiers per seat and they are not interchangeable. **\`userId\` (a UUID) is the one that matters**: it is what \`assigneeUserId\` and \`handledBy\` hold on a ticket, and what \`listTickets\` \`assigneeUserIds\` / \`handledByUserIds\`, \`closeTicket\` \`handledBy\` and \`listTeams\` \`userId\` all match on. The \`id\` beside it is the seat record and filters nothing.
+
+There is no team filter on tickets. To scope work to a team, read its members with \`listTeams\` and pass their UUIDs as \`assigneeUserIds\`.
+
+# Pagination
+
+Every paged result returns \`pagination.nextCursor\`. Pass it back verbatim as \`cursor\` for the next page; its absence means you have reached the end. Most list tools take \`pageSize\` up to 100 — ask for what you need in one call instead of walking small pages. \`searchContacts\` and \`searchMessages\` are fixed at 10 per page and reject \`pageSize\`.
+
+Results can be large. Prefer a filter over fetching pages and discarding them.
+
+# expand
+
+Read tools take an \`expand\` list that replaces or supplements ids with the named object in the same response — \`expand: ["account","assignee"]\` on \`listTickets\` saves a \`listAccounts\` and a \`listUsers\` call. The allowed values differ per tool and are enumerated on each \`expand\` argument; anything else is rejected with 400.
+
+# Writing
+
+- \`sendPlainTextMessage\` reaches a real customer on the channel and cannot be recalled. Confirm the wording with the user before sending. For something only the team should see, use \`createInternalComment\`.
+- \`closeTicket\` ends the ticket fronting a conversation. Confirm before calling it.
+- \`updateTicketField\` and \`updateContactField\` write **one field per call** and use optimistic concurrency: echo back the timestamp from your most recent read (\`ticketFieldsUpdatedAt\` on a ticket; \`customFieldsUpdatedAt\`, or \`updatedAt\` when that is absent, on a contact). A **409** means someone else wrote in between — re-read the record and retry with the fresh timestamp. Do not retry with the same one.
+- \`createContact\` rejects a duplicate email or phone with **409**. That means the person is already on file, so search before creating. Custom fields cannot be set at creation; create, then write each field.
+- \`updateConversationLabels\` only accepts label ids that already exist. Resolve names with \`listLabels\` first; it does not create labels.
+- Several writes — \`sendPlainTextMessage\`, \`createInternalComment\`, \`updateContactField\`, \`updateConversationLabels\`, \`markConversationRead\` — return only an acknowledgement. Re-read the resource if you need to confirm the result.
+
+# Results and errors
+
+Every result is \`{ status, data, pagination? }\`, with the API envelope already unwrapped. Failures set \`isError\` and return \`{ status, error }\`, where \`error\` carries the API message, a \`requestId\` to quote to Zaapi support, and a \`hint\` when there is a specific way to recover.
+
+- **400** — usually an invalid \`expand\` value or a filter combination the API rejects. Read the message; do not retry unchanged.
+- **401 / 403** — the key is invalid or its usage plan is missing the scope that tool needs. Each tool names its scope. Not retryable; tell the user which scope to add.
+- **404** — the id does not exist on this store, or (on \`markConversationRead\`) the conversation has no open ticket.
+- **409** — a concurrent write. Re-read, then retry.
+- **429** — throttled by the usage plan. Back off before retrying.
+`;
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuE3B,CAAC"}

package/dist/server.js

@@ -1,45 +1,167 @@
+import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/server';
+import { INSTRUCTIONS } from './instructions.js';
 import { splitInput, tools } from './tools/index.js';
+const FALLBACK_VERSION = '0.0.0';
+export function serverVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const manifest = require('../package.json');
+        return manifest.version ?? FALLBACK_VERSION;
+    }
+    catch {
+        return FALLBACK_VERSION;
+    }
+}
 export function createZaapiServer(client) {
     const server = new McpServer({
         name: 'zaapi',
-        version: '1.0.0',
-    });
+        version: serverVersion(),
+    }, { instructions: INSTRUCTIONS });
     for (const tool of tools) {
         server.registerTool(tool.name, {
             title: tool.title,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
             annotations: tool.annotations,
+            _meta: transportMeta(tool),
         }, createToolHandler(client, tool));
     }
     return server;
 }
+export function transportMeta(tool) {
+    return {
+        'co.zaapi/http': {
+            method: tool.method,
+            path: tool.path,
+            queryKeys: [...tool.queryKeys],
+            bodyKeys: tool.method === 'GET' ? [] : 'all other arguments',
+            scope: tool.scope,
+        },
+    };
+}
 export function createToolHandler(client, tool) {
     return async (input) => {
         const args = input && typeof input === 'object' && !Array.isArray(input)
             ? input
             : {};
         const { query, body } = splitRequest(tool, args);
-        const result = await client.request({
-            method: tool.method,
-            path: tool.path,
-            query,
-            body,
-        });
+        let result;
+        try {
+            result = await client.request({
+                method: tool.method,
+                path: tool.path,
+                query,
+                body,
+            });
+        }
+        catch (error) {
+            return transportFailure(client, tool, error);
+        }
+        if (result.status >= 400) {
+            return errorResult(tool, result);
+        }
+        const pagination = {
+            ...(result.pagination.pageSize
+                ? { pageSize: result.pagination.pageSize }
+                : {}),
+            ...(result.pagination.nextCursor
+                ? { nextCursor: result.pagination.nextCursor }
+                : {}),
+        };
         const payload = {
             status: result.status,
             data: unwrapOpenApiEnvelope(result.body),
-            ...(result.pagination.pageSize || result.pagination.nextCursor
-                ? { pagination: result.pagination }
-                : {}),
+            ...(Object.keys(pagination).length > 0 ? { pagination } : {}),
         };
+        if (tool.outputSchema && !tool.outputSchema.safeParse(payload).success) {
+            return textResult({
+                status: result.status,
+                error: {
+                    message: `The Open API returned a ${tool.name} response that does not match its documented shape.`,
+                    code: 'unexpected_response_shape',
+                    hint: 'Treat the raw body below as untyped. Report this to Zaapi support with the requestId if it persists.',
+                    body: result.body,
+                },
+            }, true);
+        }
         return {
             content: [{ type: 'text', text: JSON.stringify(payload) }],
-            isError: result.status >= 400,
+            ...(tool.outputSchema ? { structuredContent: payload } : {}),
+            isError: false,
         };
     };
 }
+function textResult(payload, isError) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload) }],
+        isError,
+    };
+}
+function transportFailure(client, tool, error) {
+    const cause = error instanceof Error ? error : undefined;
+    const detail = cause?.cause instanceof Error ? cause.cause.message : undefined;
+    return textResult({
+        status: 0,
+        error: {
+            message: `Could not reach the Zaapi Open API at ${client.baseUrl}${tool.path}: ${cause?.message ?? String(error)}${detail ? ` (${detail})` : ''}`,
+            code: 'transport_error',
+            baseUrl: client.baseUrl,
+            path: tool.path,
+            hint: 'The request never reached the API, so nothing was changed. Check network access and that ZAAPI_BASE_URL points at the right host, then retry.',
+        },
+    }, true);
+}
+function errorResult(tool, result) {
+    const envelope = result.body &&
+        typeof result.body === 'object' &&
+        !Array.isArray(result.body)
+        ? result.body
+        : undefined;
+    const inner = envelope && typeof envelope.error === 'object' && envelope.error !== null
+        ? envelope.error
+        : undefined;
+    const message = (typeof inner?.message === 'string' ? inner.message : undefined) ??
+        (typeof envelope?.message === 'string' ? envelope.message : undefined) ??
+        (typeof result.body === 'string' && result.body
+            ? result.body
+            : undefined) ??
+        `Request failed with status ${result.status}.`;
+    const requestId = typeof envelope?.requestId === 'string' ? envelope.requestId : undefined;
+    const hint = remediation(tool, result.status, result.retryAfter);
+    return textResult({
+        status: result.status,
+        error: {
+            message,
+            statusCode: result.status,
+            ...(requestId ? { requestId } : {}),
+            ...(hint ? { hint } : {}),
+        },
+    }, true);
+}
+function remediation(tool, status, retryAfter) {
+    switch (status) {
+        case 400:
+            return 'The arguments were rejected. Check any expand values against the ones this tool lists, and check filter combinations. Do not retry unchanged.';
+        case 401:
+            return 'ZAAPI_API_KEY is missing, malformed, or not a key for this host. Keys start with zaapi_. Not retryable.';
+        case 403:
+            return `The key's usage plan is missing the ${tool.scope} scope, or the key does not cover this store. Not retryable — ask the user to grant ${tool.scope} in Settings → Developers.`;
+        case 404:
+            return 'No such record on this store. Re-read the id from the list or search tool that produced it.';
+        case 409:
+            return 'A concurrent write. Re-read the record and retry with the timestamp from that fresh read — retrying with the same one will fail again.';
+        case 429:
+            return retryAfter
+                ? `Throttled by the usage plan. Wait ${retryAfter} seconds before retrying.`
+                : 'Throttled by the usage plan. Back off before retrying.';
+        default:
+            return status >= 500
+                ? 'The Open API failed. Retry once after a short pause; if it persists, quote the requestId to Zaapi support.'
+                : undefined;
+    }
+}
 function unwrapOpenApiEnvelope(body) {
     if (body === null || typeof body !== 'object' || Array.isArray(body)) {
         return body;

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools/accounts/list-accounts.js

@@ -1,32 +1,22 @@
 import { z } from 'zod';
-import { describeHttpRequest, paginationFields, } from '../common.js';
+import { paginationFields } from '../common.js';
+import { account, channel, envelope } from '../responses.js';
 const queryKeys = ['channel', 'pageSize', 'cursor'];
 export const listAccounts = {
     name: 'listAccounts',
     title: 'List accounts',
-    description: `Required scope: accounts:read. ${describeHttpRequest('GET', '/v1/accounts', queryKeys)} Page through the channel accounts connected to the store. Only active accounts are returned. Filter to a single channel when needed. Each account includes a status of healthy, unhealthy, or disconnected.`,
+    description: 'Page through the channel inboxes connected to the store — the LINE, Instagram, Shopee, email and other accounts that conversations arrive on. Only active accounts are returned, oldest first. Each carries a status of healthy, unhealthy or disconnected; sending on anything other than healthy may fail at the channel, so check here first when a send does not land. Requires the accounts:read scope.',
+    scope: 'accounts:read',
     method: 'GET',
     path: '/v1/accounts',
     queryKeys,
     inputSchema: z.object({
-        channel: z
-            .enum([
-            'line',
-            'instagram',
-            'facebook',
-            'lazada',
-            'shopee',
-            'tiktok',
-            'drunken_lullabies',
-            'whatsapp',
-            'widget',
-            'gmail',
-            'outlook',
-        ])
+        channel: channel
             .optional()
-            .describe('Query parameter. Return only the accounts on this channel.'),
+            .describe('Return only the accounts on this channel.'),
         ...paginationFields,
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(account), 'A page of connected channel accounts.', { paginated: true }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=list-accounts.js.map

package/dist/tools/accounts/list-accounts.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-accounts.js","sourceRoot":"","sources":["../../../src/tools/accounts/list-accounts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,gBAAgB,GAEjB,MAAM,cAAc,CAAC;AAEtB,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,CAAU,CAAC;AAE7D,MAAM,CAAC,MAAM,YAAY,GAAiB;IACxC,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,eAAe;IACtB,WAAW,EAAE,kCAAkC,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,SAAS,CAAC,8MAA8M;IAClT,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,cAAc;IACpB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,OAAO,EAAE,CAAC;aACP,IAAI,CAAC;YACJ,MAAM;YACN,WAAW;YACX,UAAU;YACV,QAAQ;YACR,QAAQ;YACR,QAAQ;YACR,mBAAmB;YACnB,UAAU;YACV,QAAQ;YACR,OAAO;YACP,SAAS;SACV,CAAC;aACD,QAAQ,EAAE;aACV,QAAQ,CAAC,4DAA4D,CAAC;QACzE,GAAG,gBAAgB;KACpB,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"list-accounts.js","sourceRoot":"","sources":["../../../src/tools/accounts/list-accounts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAqB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE7D,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,CAAU,CAAC;AAE7D,MAAM,CAAC,MAAM,YAAY,GAAiB;IACxC,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,eAAe;IACtB,WAAW,EACT,8YAA8Y;IAChZ,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,cAAc;IACpB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,OAAO,EAAE,OAAO;aACb,QAAQ,EAAE;aACV,QAAQ,CAAC,2CAA2C,CAAC;QACxD,GAAG,gBAAgB;KACpB,CAAC;IACF,YAAY,EAAE,QAAQ,CACpB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAChB,uCAAuC,EACvC,EAAE,SAAS,EAAE,IAAI,EAAE,CACpB;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/common.js

@@ -1,33 +1,27 @@
 import { z } from 'zod';
-export function describeHttpRequest(method, path, queryKeys) {
-    const query = queryKeys.length > 0
-        ? `Query parameters: ${queryKeys.join(', ')}.`
-        : 'There are no query parameters.';
-    const body = method === 'GET'
-        ? 'There is no JSON body.'
-        : queryKeys.length === 0
-            ? 'All arguments are sent as a JSON body.'
-            : 'All other arguments are sent as a JSON body.';
-    return `${method} ${path}. ${query} ${body}`;
-}
 export const pageSize = z
     .number()
     .int()
     .min(1)
     .max(100)
     .optional()
-    .describe('Query parameter. Items per page. Defaults to 20. Maximum 100.');
+    .describe('Items per page. Defaults to 20. Maximum 100.');
 export const messagePageSize = z
     .number()
     .int()
     .min(1)
     .max(100)
     .optional()
-    .describe('Query parameter. Items per page. Defaults to 15. Maximum 100.');
+    .describe('Items per page. Defaults to 15. Maximum 100.');
 export const cursor = z
     .string()
     .optional()
-    .describe('Query parameter. Opaque token from the previous page x-pagination-next-cursor header.');
+    .describe('Opaque token from the previous page. Pass back pagination.nextCursor from the last result, verbatim.');
+export const searchQuery = z
+    .string()
+    .min(1)
+    .max(150)
+    .describe('Free-text search query. 1 to 150 characters.');
 export const fieldValue = z.union([
     z.string(),
     z.number(),
@@ -36,18 +30,20 @@ export const fieldValue = z.union([
     z.array(z.string()),
     z.array(z.number()),
 ]);
-export const expand = (description) => z
-    .preprocess((value) => {
-    if (typeof value !== 'string') {
-        return value;
-    }
-    return value
-        .split(',')
-        .map((name) => name.trim())
-        .filter(Boolean);
-}, z.array(z.string()))
-    .optional()
-    .describe(`Query parameter. ${description}`);
+export function expand(values, description) {
+    return z
+        .preprocess((value) => {
+        if (typeof value !== 'string') {
+            return value;
+        }
+        return value
+            .split(',')
+            .map((name) => name.trim())
+            .filter(Boolean);
+    }, z.array(z.enum(values)))
+        .optional()
+        .describe(`${description} Any other value is rejected with 400.`);
+}
 export const paginationQueryKeys = ['pageSize', 'cursor', 'expand'];
 export const paginationFields = {
     pageSize,

package/dist/tools/common.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/tools/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,MAAM,UAAU,mBAAmB,CACjC,MAAkB,EAClB,IAAY,EACZ,SAA4B;IAE5B,MAAM,KAAK,GACT,SAAS,CAAC,MAAM,GAAG,CAAC;QAClB,CAAC,CAAC,qBAAqB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC9C,CAAC,CAAC,gCAAgC,CAAC;IACvC,MAAM,IAAI,GACR,MAAM,KAAK,KAAK;QACd,CAAC,CAAC,wBAAwB;QAC1B,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YACtB,CAAC,CAAC,wCAAwC;YAC1C,CAAC,CAAC,8CAA8C,CAAC;IACvD,OAAO,GAAG,MAAM,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC;KACtB,MAAM,EAAE;KACR,GAAG,EAAE;KACL,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,EAAE;KACV,QAAQ,CAAC,+DAA+D,CAAC,CAAC;AAE7E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,EAAE;KACR,GAAG,EAAE;KACL,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,EAAE;KACV,QAAQ,CAAC,+DAA+D,CAAC,CAAC;AAE7E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC;KACpB,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,QAAQ,CACP,uFAAuF,CACxF,CAAC;AAEJ,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC;IAChC,CAAC,CAAC,MAAM,EAAE;IACV,CAAC,CAAC,MAAM,EAAE;IACV,CAAC,CAAC,OAAO,EAAE;IACX,CAAC,CAAC,IAAI,EAAE;IACR,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACnB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,WAAmB,EAAE,EAAE,CAC5C,CAAC;KACE,UAAU,CAAC,CAAC,KAAK,EAAE,EAAE;IACpB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK;SACT,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;KACtB,QAAQ,EAAE;KACV,QAAQ,CAAC,oBAAoB,WAAW,EAAE,CAAC,CAAC;AAEjD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAE7E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,QAAQ;IACR,MAAM;CACP,CAAC"}
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/tools/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0BxB,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC;KACtB,MAAM,EAAE;KACR,GAAG,EAAE;KACL,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,EAAE;KACV,QAAQ,CAAC,8CAA8C,CAAC,CAAC;AAE5D,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,EAAE;KACR,GAAG,EAAE;KACL,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,EAAE;KACV,QAAQ,CAAC,8CAA8C,CAAC,CAAC;AAE5D,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC;KACpB,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,QAAQ,CACP,sGAAsG,CACvG,CAAC;AAEJ,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,CAAC,8CAA8C,CAAC,CAAC;AAE5D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC;IAChC,CAAC,CAAC,MAAM,EAAE;IACV,CAAC,CAAC,MAAM,EAAE;IACV,CAAC,CAAC,OAAO,EAAE;IACX,CAAC,CAAC,IAAI,EAAE;IACR,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACnB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CACpB,CAAC,CAAC;AAOH,MAAM,UAAU,MAAM,CACpB,MAAS,EACT,WAAmB;IAEnB,OAAO,CAAC;SACL,UAAU,CACT,CAAC,KAAK,EAAE,EAAE;QACR,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,KAAK;aACT,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;aAC1B,MAAM,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC,EACD,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CACxB;SACA,QAAQ,EAAE;SACV,QAAQ,CAAC,GAAG,WAAW,wCAAwC,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAE7E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,QAAQ;IACR,MAAM;CACP,CAAC"}

package/dist/tools/contacts/create-contact.js

@@ -1,10 +1,11 @@
 import { z } from 'zod';
-import { describeHttpRequest } from '../common.js';
+import { contact, envelope } from '../responses.js';
 const queryKeys = [];
 export const createContact = {
     name: 'createContact',
     title: 'Create a contact',
-    description: `Required scope: contacts:write. ${describeHttpRequest('POST', '/v1/contacts', queryKeys)} Create a contact. A contact whose email or phone already exists on the store is rejected with 409.`,
+    description: 'Create a contact on the store. Search first with searchContacts: an email or phone that already exists is rejected with 409, and that 409 means the person is already on file rather than that the call was malformed. Custom fields cannot be set here — create the contact, then write each one with updateContactField. Requires the contacts:write scope.',
+    scope: 'contacts:write',
     method: 'POST',
     path: '/v1/contacts',
     queryKeys,
@@ -13,24 +14,29 @@ export const createContact = {
             .string()
             .min(1)
             .max(50)
-            .describe('JSON body. First name of the contact. Maximum 50 characters.'),
+            .describe('First name of the contact. Maximum 50 characters.'),
         lastName: z
             .string()
             .max(50)
             .optional()
-            .describe('JSON body. Last name of the contact. Maximum 50 characters.'),
+            .describe('Last name of the contact. Maximum 50 characters.'),
         email: z
             .string()
             .email()
             .max(100)
             .optional()
-            .describe('JSON body. Primary email address. Maximum 100 characters.'),
+            .describe('Primary email address. Maximum 100 characters. Must be unique on the store.'),
         phone: z
             .string()
             .max(15)
             .optional()
-            .describe('JSON body. Primary phone number in E.164 format. Maximum 15 characters.'),
+            .describe('Primary phone number in E.164 format. Maximum 15 characters. Must be unique on the store.'),
     }),
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    outputSchema: envelope(contact, 'The contact that was created.'),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
 };
 //# sourceMappingURL=create-contact.js.map

package/dist/tools/contacts/create-contact.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-contact.js","sourceRoot":"","sources":["../../../src/tools/contacts/create-contact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAqB,MAAM,cAAc,CAAC;AAEtE,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,aAAa,GAAiB;IACzC,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,kBAAkB;IACzB,WAAW,EAAE,mCAAmC,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,qGAAqG;IAC3M,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,cAAc;IACpB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,CAAC,8DAA8D,CAAC;QAC3E,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,EAAE;aACV,QAAQ,CAAC,6DAA6D,CAAC;QAC1E,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,KAAK,EAAE;aACP,GAAG,CAAC,GAAG,CAAC;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,2DAA2D,CAAC;QACxE,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,EAAE;aACV,QAAQ,CACP,yEAAyE,CAC1E;KACJ,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE;CAC7D,CAAC"}
+{"version":3,"file":"create-contact.js","sourceRoot":"","sources":["../../../src/tools/contacts/create-contact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,aAAa,GAAiB;IACzC,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,kBAAkB;IACzB,WAAW,EACT,+VAA+V;IACjW,KAAK,EAAE,gBAAgB;IACvB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,cAAc;IACpB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,CAAC,mDAAmD,CAAC;QAChE,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,EAAE;aACV,QAAQ,CAAC,kDAAkD,CAAC;QAC/D,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,KAAK,EAAE;aACP,GAAG,CAAC,GAAG,CAAC;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,6EAA6E,CAC9E;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,EAAE;aACV,QAAQ,CACP,2FAA2F,CAC5F;KACJ,CAAC;IACF,YAAY,EAAE,QAAQ,CAAC,OAAO,EAAE,+BAA+B,CAAC;IAChE,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,aAAa,EAAE,IAAI;KACpB;CACF,CAAC"}

package/dist/tools/contacts/get-contact-by-id.js

@@ -1,19 +1,18 @@
 import { z } from 'zod';
-import { describeHttpRequest } from '../common.js';
+import { contact, envelope } from '../responses.js';
 const queryKeys = ['contactId'];
 export const getContactById = {
     name: 'getContactById',
     title: 'Get a contact by ID',
-    description: `Required scope: contacts:read. ${describeHttpRequest('GET', '/v1/contacts', queryKeys)} Fetch a single contact, including custom field values.`,
+    description: 'Fetch one contact in full, including custom field values and the customFieldsUpdatedAt that updateContactField must echo back. Read this before writing a field. To see the contact’s threads, pass the same id to filterConversations. Requires the contacts:read scope.',
+    scope: 'contacts:read',
     method: 'GET',
     path: '/v1/contacts',
     queryKeys,
     inputSchema: z.object({
-        contactId: z
-            .string()
-            .min(1)
-            .describe('Query parameter. The ID of the contact.'),
+        contactId: z.string().min(1).describe('The ID of the contact.'),
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(contact, 'The contact.'),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=get-contact-by-id.js.map

package/dist/tools/contacts/get-contact-by-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-contact-by-id.js","sourceRoot":"","sources":["../../../src/tools/contacts/get-contact-by-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAqB,MAAM,cAAc,CAAC;AAEtE,MAAM,SAAS,GAAG,CAAC,WAAW,CAAU,CAAC;AAEzC,MAAM,CAAC,MAAM,cAAc,GAAiB;IAC1C,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,qBAAqB;IAC5B,WAAW,EAAE,kCAAkC,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,SAAS,CAAC,yDAAyD;IAC7J,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,cAAc;IACpB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,yCAAyC,CAAC;KACvD,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"get-contact-by-id.js","sourceRoot":"","sources":["../../../src/tools/contacts/get-contact-by-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,SAAS,GAAG,CAAC,WAAW,CAAU,CAAC;AAEzC,MAAM,CAAC,MAAM,cAAc,GAAiB;IAC1C,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,qBAAqB;IAC5B,WAAW,EACT,2QAA2Q;IAC7Q,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,cAAc;IACpB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,wBAAwB,CAAC;KAChE,CAAC;IACF,YAAY,EAAE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAC/C,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/contacts/list-contact-fields.js

@@ -1,14 +1,16 @@
 import { z } from 'zod';
-import { describeHttpRequest } from '../common.js';
+import { contactField, envelope } from '../responses.js';
 const queryKeys = [];
 export const listContactFields = {
     name: 'listContactFields',
     title: 'List contact fields',
-    description: `Required scope: contacts:read. ${describeHttpRequest('GET', '/v1/contacts/fields', queryKeys)} Full catalog of contact field definitions for the store. Not paginated.`,
+    description: "Full catalog of the store's contact field definitions. Not paginated. Call this first whenever a request names a field by its label — the ids, data types and select options here are what updateContactField takes, and what the customFields map on a contact is keyed by. Requires the contacts:read scope.",
+    scope: 'contacts:read',
     method: 'GET',
     path: '/v1/contacts/fields',
     queryKeys,
     inputSchema: z.object({}),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(contactField), 'Every contact field definition on the store.'),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=list-contact-fields.js.map

package/dist/tools/contacts/list-contact-fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-contact-fields.js","sourceRoot":"","sources":["../../../src/tools/contacts/list-contact-fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAqB,MAAM,cAAc,CAAC;AAEtE,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,iBAAiB,GAAiB;IAC7C,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,qBAAqB;IAC5B,WAAW,EAAE,kCAAkC,mBAAmB,CAAC,KAAK,EAAE,qBAAqB,EAAE,SAAS,CAAC,0EAA0E;IACrL,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,qBAAqB;IAC3B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACzB,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"list-contact-fields.js","sourceRoot":"","sources":["../../../src/tools/contacts/list-contact-fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEzD,MAAM,SAAS,GAAG,EAAW,CAAC;AAE9B,MAAM,CAAC,MAAM,iBAAiB,GAAiB;IAC7C,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,qBAAqB;IAC5B,WAAW,EACT,gTAAgT;IAClT,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,qBAAqB;IAC3B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACzB,YAAY,EAAE,QAAQ,CACpB,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,EACrB,8CAA8C,CAC/C;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/contacts/list-contacts.js

@@ -1,10 +1,12 @@
 import { z } from 'zod';
-import { describeHttpRequest, paginationFields, } from '../common.js';
+import { paginationFields } from '../common.js';
+import { contact, envelope } from '../responses.js';
 const queryKeys = ['pageSize', 'cursor'];
 export const listContacts = {
     name: 'listContacts',
     title: 'List contacts',
-    description: `Required scope: contacts:read. ${describeHttpRequest('POST', '/v1/contacts/list', queryKeys)} Search and page through contacts, most recently updated first.`,
+    description: 'Page through contacts, optionally filtered by a free-text search or an updated-at window. Ordered by most recently updated, or by relevance then recency when search is set; a whitespace-only search is treated as omitted. Use this to walk or sync the book; for ranked lookup of one person by name, email or phone, searchContacts is the better tool. Requires the contacts:read scope.',
+    scope: 'contacts:read',
     method: 'POST',
     path: '/v1/contacts/list',
     queryKeys,
@@ -14,16 +16,19 @@ export const listContacts = {
             .string()
             .max(100)
             .optional()
-            .describe('JSON body. Free-text search across name, email, and phone. Maximum 100 characters.'),
+            .describe('Free-text match across name, email and phone. Maximum 100 characters.'),
         updatedAfter: z
             .string()
             .optional()
-            .describe('JSON body. ISO 8601 date-time. Return only contacts updated on or after this time.'),
+            .describe('ISO 8601 date-time. Only contacts updated on or after this time.'),
         updatedBefore: z
             .string()
             .optional()
-            .describe('JSON body. ISO 8601 date-time. Return only contacts updated before this time.'),
+            .describe('ISO 8601 date-time. Only contacts updated before this time.'),
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(contact), 'A page of contacts.', {
+        paginated: true,
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=list-contacts.js.map