@zaapi/open-api-mcp 1.2.0 → 1.4.0

package/dist/tools/tickets/get-ticket-by-id.js

@@ -1,20 +1,20 @@
 import { z } from 'zod';
-import { describeHttpRequest, expand } from '../common.js';
+import { expand } from '../common.js';
+import { envelope, ticket } from '../responses.js';
 const queryKeys = ['ticketId', 'expand'];
 export const getTicketById = {
     name: 'getTicketById',
     title: 'Get a ticket by ID',
-    description: `Required scope: tickets:read. ${describeHttpRequest('GET', '/v1/tickets', queryKeys)} Fetch a single ticket. Pass expand=account,conversation,assignee,handledBy to replace those ids with names.`,
+    description: 'Fetch one ticket by id, including its custom field values and the conversationId and contactId that the message and contact tools need. Read this before updateTicketField or closeTicket: the response carries the ticketFieldsUpdatedAt those calls must echo back. Requires the tickets:read scope.',
+    scope: 'tickets:read',
     method: 'GET',
     path: '/v1/tickets',
     queryKeys,
     inputSchema: z.object({
-        ticketId: z
-            .string()
-            .min(1)
-            .describe('Query parameter. The ID of the ticket.'),
-        expand: expand('Comma-separated related objects to include: account, conversation, assignee, handledBy.'),
+        ticketId: z.string().min(1).describe('The ID of the ticket.'),
+        expand: expand(['account', 'conversation', 'assignee', 'handledBy'], 'Replace these ids with the named object, saving a follow-up call.'),
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(ticket, 'The ticket.'),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=get-ticket-by-id.js.map

package/dist/tools/tickets/get-ticket-by-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-ticket-by-id.js","sourceRoot":"","sources":["../../../src/tools/tickets/get-ticket-by-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAqB,MAAM,cAAc,CAAC;AAE9E,MAAM,SAAS,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AAElD,MAAM,CAAC,MAAM,aAAa,GAAiB;IACzC,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EAAE,iCAAiC,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,CAAC,8GAA8G;IAChN,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,aAAa;IACnB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,wCAAwC,CAAC;QACrD,MAAM,EAAE,MAAM,CACZ,yFAAyF,CAC1F;KACF,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"get-ticket-by-id.js","sourceRoot":"","sources":["../../../src/tools/tickets/get-ticket-by-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAqB,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,SAAS,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AAElD,MAAM,CAAC,MAAM,aAAa,GAAiB;IACzC,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EACT,wSAAwS;IAC1S,KAAK,EAAE,cAAc;IACrB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,aAAa;IACnB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QAC7D,MAAM,EAAE,MAAM,CACZ,CAAC,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,CAAC,EACpD,mEAAmE,CACpE;KACF,CAAC;IACF,YAAY,EAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC7C,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/dist/tools/tickets/list-ticket-fields.js

@@ -1,16 +1,19 @@
 import { z } from 'zod';
-import { describeHttpRequest, expand } from '../common.js';
+import { expand } from '../common.js';
+import { envelope, ticketField } from '../responses.js';
 const queryKeys = ['expand'];
 export const listTicketFields = {
     name: 'listTicketFields',
     title: 'List ticket fields',
-    description: `Required scope: tickets:read. ${describeHttpRequest('GET', '/v1/tickets/fields', queryKeys)} Full catalog of custom ticket field definitions, in display order. Not paginated. Pass expand=accounts to include the accounts each field applies to.`,
+    description: "Full catalog of the store's custom ticket field definitions, in display order. Not paginated. Call this first whenever a request names a field by its label — the ids, data types and select options here are what updateTicketField and the listTickets advancedFilters.ticketFields filter take. Requires the tickets:read scope.",
+    scope: 'tickets:read',
     method: 'GET',
     path: '/v1/tickets/fields',
     queryKeys,
     inputSchema: z.object({
-        expand: expand('Pass accounts to include the accounts each field applies to.'),
+        expand: expand(['accounts'], 'Include the accounts each field applies to.'),
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(ticketField), 'Every ticket field definition on the store, in display order.'),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=list-ticket-fields.js.map

package/dist/tools/tickets/list-ticket-fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-ticket-fields.js","sourceRoot":"","sources":["../../../src/tools/tickets/list-ticket-fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAqB,MAAM,cAAc,CAAC;AAE9E,MAAM,SAAS,GAAG,CAAC,QAAQ,CAAU,CAAC;AAEtC,MAAM,CAAC,MAAM,gBAAgB,GAAiB;IAC5C,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EAAE,iCAAiC,mBAAmB,CAAC,KAAK,EAAE,oBAAoB,EAAE,SAAS,CAAC,wJAAwJ;IACjQ,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,oBAAoB;IAC1B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CACZ,8DAA8D,CAC/D;KACF,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"list-ticket-fields.js","sourceRoot":"","sources":["../../../src/tools/tickets/list-ticket-fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAqB,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAExD,MAAM,SAAS,GAAG,CAAC,QAAQ,CAAU,CAAC;AAEtC,MAAM,CAAC,MAAM,gBAAgB,GAAiB;IAC5C,IAAI,EAAE,kBAAkB;IACxB,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EACT,qUAAqU;IACvU,KAAK,EAAE,cAAc;IACrB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,oBAAoB;IAC1B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC,CAAC,UAAU,CAAC,EAAE,6CAA6C,CAAC;KAC5E,CAAC;IACF,YAAY,EAAE,QAAQ,CACpB,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,EACpB,+DAA+D,CAChE;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

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

@@ -1,37 +1,39 @@
 import { z } from 'zod';
-import { describeHttpRequest, expand, fieldValue, paginationFields, paginationQueryKeys, } from '../common.js';
+import { expand, fieldValue, paginationFields, paginationQueryKeys, } from '../common.js';
+import { envelope, ticket } from '../responses.js';
 const TICKET_FILTER_ARRAY_MAX = 20;
 export const listTickets = {
     name: 'listTickets',
     title: 'List tickets',
-    description: `Required scope: tickets:read. ${describeHttpRequest('POST', '/v1/tickets/list', paginationQueryKeys)} Page through tickets, newest message first. An omitted or empty JSON body returns open, non-spam tickets that are not snoozed. When conversationId is set and statuses is omitted, open and closed tickets for that conversation are returned. Do not send assigneeUserIds together with unassigned: true.`,
+    description: 'The main way into the store: page through tickets, newest message first, and read the conversationId and contactId off them to reach messages, labels and contacts. Send no filters at all for the current queue — open, non-spam, not snoozed. Setting conversationId with statuses omitted returns every ticket on that thread instead, open and closed. assigneeUserIds and handledByUserIds take user UUIDs, the userId from listUsers rather than the id beside it, and assigneeUserIds cannot be combined with unassigned: true. Requires the tickets:read scope.',
+    scope: 'tickets:read',
     method: 'POST',
     path: '/v1/tickets/list',
     queryKeys: paginationQueryKeys,
     inputSchema: z.object({
         ...paginationFields,
-        expand: expand('Pass account,conversation,assignee,handledBy to replace those ids with names.'),
+        expand: expand(['account', 'conversation', 'assignee', 'handledBy'], 'Replace these ids on every ticket with the named object, saving a follow-up call.'),
         statuses: z
             .array(z.enum(['open', 'closed']))
             .optional()
-            .describe('JSON body. Open and/or closed tickets. Omit to return open tickets only. When conversationId is set, omitting statuses returns every status for that conversation.'),
+            .describe('Open and/or closed tickets. Omit to return open tickets only. When conversationId is set, omitting statuses returns every status for that conversation.'),
         conversationId: z
             .string()
             .min(1)
             .optional()
-            .describe('JSON body. Restrict results to tickets belonging to this conversation.'),
+            .describe('Restrict results to tickets belonging to this conversation.'),
         accountIds: z
             .array(z.string())
             .optional()
-            .describe('JSON body. Restrict results to these account IDs.'),
+            .describe('Restrict results to these account IDs, from listAccounts.'),
         assigneeUserIds: z
             .array(z.string())
             .optional()
-            .describe('JSON body. Restrict results to these assignee user IDs. Cannot be combined with unassigned: true.'),
+            .describe('Restrict results to these assignee user UUIDs (User.userId). Cannot be combined with unassigned: true.'),
         handledByUserIds: z
             .array(z.string())
             .optional()
-            .describe('JSON body. Restrict results to tickets handled by these user IDs.'),
+            .describe('Restrict results to tickets handled by these user UUIDs (User.userId).'),
         resolutionStatuses: z
             .array(z.enum([
             'none',
@@ -41,19 +43,16 @@ export const listTickets = {
             'ai_partial_resolution',
         ]))
             .optional()
-            .describe('JSON body. Restrict results to these resolution statuses.'),
+            .describe('Restrict results to these resolution statuses.'),
         unassigned: z
             .boolean()
             .optional()
-            .describe('JSON body. When true, only tickets with no assignee. Cannot be combined with assigneeUserIds.'),
-        isFollowUp: z
-            .boolean()
-            .optional()
-            .describe('JSON body. Filter by follow-up flag.'),
+            .describe('When true, only tickets with no assignee. Cannot be combined with assigneeUserIds.'),
+        isFollowUp: z.boolean().optional().describe('Filter by follow-up flag.'),
         isSpam: z
             .boolean()
             .optional()
-            .describe('JSON body. Filter by spam flag. Defaults to non-spam tickets when omitted.'),
+            .describe('Filter by spam flag. Defaults to non-spam tickets when omitted.'),
         advancedFilters: z
             .object({
             labels: z
@@ -66,12 +65,12 @@ export const listTickets = {
                 labelIds: z.array(z.string()).min(1).max(TICKET_FILTER_ARRAY_MAX),
             })
                 .optional()
-                .describe('JSON body. Filter tickets by conversation labels.'),
+                .describe('Filter tickets by conversation labels. Label ids come from listLabels.'),
             ticketFields: z
                 .array(z.object({
                 ticketFieldId: z
                     .string()
-                    .describe('Custom field id, or a system key: aiCsat, aiSummary, salesRevenue, isConverted.'),
+                    .describe('Custom field id from listTicketFields, or a system key: aiCsat, aiSummary, salesRevenue, isConverted.'),
                 operator: z.enum([
                     'equal',
                     'not_equal',
@@ -99,13 +98,13 @@ export const listTickets = {
                     .describe('Upper bound for between. Required with min when operator is between.'),
             }))
                 .optional()
-                .describe('JSON body. Filter on custom ticket fields or system fields.'),
+                .describe('Filter on custom ticket fields or system fields.'),
             waitingForReply: z
                 .object({
                 value: z.number().int().min(1).max(43200),
             })
                 .optional()
-                .describe('JSON body. Tickets where the buyer has been waiting at least this many minutes (1–43200).'),
+                .describe('Tickets where the buyer has been waiting at least this many minutes (1–43200).'),
             openedAt: z
                 .object({
                 operator: z.enum(['between', 'greater_than', 'less_than']),
@@ -123,11 +122,12 @@ export const listTickets = {
                     .describe('ISO 8601 date-time. Upper bound when operator is between.'),
             })
                 .optional()
-                .describe('JSON body. Filter by ticket opened-at time.'),
+                .describe('Filter by ticket opened-at time.'),
         })
             .optional()
-            .describe('JSON body. Optional extra filters on labels, ticket fields, waiting time, and opened-at.'),
+            .describe('Optional extra filters on labels, ticket fields, waiting time, and opened-at.'),
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(ticket), 'A page of tickets, newest message first.', { paginated: true }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=list-tickets.js.map

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

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

package/dist/tools/tickets/update-ticket-field.js

@@ -1,26 +1,33 @@
 import { z } from 'zod';
-import { describeHttpRequest, expand, fieldValue, } from '../common.js';
+import { expand, fieldValue } from '../common.js';
+import { envelope, ticket } from '../responses.js';
 const queryKeys = ['expand'];
 export const updateTicketField = {
     name: 'updateTicketField',
     title: 'Update a ticket field value',
-    description: `Required scope: tickets:write. ${describeHttpRequest('PATCH', '/v1/tickets/fields', queryKeys)} Set or clear one field on a ticket. Send null as newValue to unset. Send ticketFieldsUpdatedAt from the last read; a mismatch returns 409.`,
+    description: 'Set or clear exactly one custom field on a ticket, and return the updated ticket. Resolve ticketFieldId with listTicketFields and read the ticket first: ticketFieldsUpdatedAt must be the value from that read, or the write is rejected with 409 because someone else changed a field in the meantime — re-read and retry. Send null as newValue to unset. Requires the tickets:write scope.',
+    scope: 'tickets:write',
     method: 'PATCH',
     path: '/v1/tickets/fields',
     queryKeys,
     inputSchema: z.object({
-        expand: expand('Related objects to include on the updated ticket: account, conversation, assignee, handledBy.'),
-        ticketId: z.string().min(1).describe('JSON body. The ID of the ticket.'),
+        expand: expand(['account', 'conversation', 'assignee', 'handledBy'], 'Replace these ids on the returned ticket with the named object.'),
+        ticketId: z.string().min(1).describe('The ID of the ticket.'),
         ticketFieldId: z
             .string()
             .min(1)
-            .describe('JSON body. The ID of the ticket field.'),
+            .describe('The ID of the ticket field, from listTicketFields.'),
         ticketFieldsUpdatedAt: z
             .string()
             .optional()
-            .describe('JSON body. ISO 8601 date-time from the last read. Omit if the ticket has never had a field update.'),
-        newValue: fieldValue.describe('JSON body. The new field value. Send null to unset.'),
+            .describe('ISO 8601 date-time. The ticketFieldsUpdatedAt you last read. Omit only when the ticket has never had a field update.'),
+        newValue: fieldValue.describe('The new value, matching the field dataType. Send null to unset.'),
     }),
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    outputSchema: envelope(ticket, 'The ticket after the update.'),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
 };
 //# sourceMappingURL=update-ticket-field.js.map

package/dist/tools/tickets/update-ticket-field.js.map

@@ -1 +1 @@
-{"version":3,"file":"update-ticket-field.js","sourceRoot":"","sources":["../../../src/tools/tickets/update-ticket-field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,MAAM,EACN,UAAU,GAEX,MAAM,cAAc,CAAC;AAEtB,MAAM,SAAS,GAAG,CAAC,QAAQ,CAAU,CAAC;AAEtC,MAAM,CAAC,MAAM,iBAAiB,GAAiB;IAC7C,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,6BAA6B;IACpC,WAAW,EAAE,kCAAkC,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,EAAE,SAAS,CAAC,6IAA6I;IACzP,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,oBAAoB;IAC1B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CACZ,+FAA+F,CAChG;QACD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kCAAkC,CAAC;QACxE,aAAa,EAAE,CAAC;aACb,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,wCAAwC,CAAC;QACrD,qBAAqB,EAAE,CAAC;aACrB,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,oGAAoG,CACrG;QACH,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAC3B,qDAAqD,CACtD;KACF,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE;CAC7D,CAAC"}
+{"version":3,"file":"update-ticket-field.js","sourceRoot":"","sources":["../../../src/tools/tickets/update-ticket-field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAqB,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,SAAS,GAAG,CAAC,QAAQ,CAAU,CAAC;AAEtC,MAAM,CAAC,MAAM,iBAAiB,GAAiB;IAC7C,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,6BAA6B;IACpC,WAAW,EACT,gYAAgY;IAClY,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,OAAO;IACf,IAAI,EAAE,oBAAoB;IAC1B,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CACZ,CAAC,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,CAAC,EACpD,iEAAiE,CAClE;QACD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QAC7D,aAAa,EAAE,CAAC;aACb,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,oDAAoD,CAAC;QACjE,qBAAqB,EAAE,CAAC;aACrB,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,sHAAsH,CACvH;QACH,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAC3B,iEAAiE,CAClE;KACF,CAAC;IACF,YAAY,EAAE,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;IAC9D,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,KAAK;QACtB,aAAa,EAAE,IAAI;KACpB;CACF,CAAC"}

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

@@ -1,10 +1,12 @@
 import { z } from 'zod';
-import { describeHttpRequest, expand } from '../common.js';
+import { expand } from '../common.js';
+import { envelope, user } from '../responses.js';
 const queryKeys = ['userId', 'expand'];
 export const listUsers = {
     name: 'listUsers',
     title: 'List users',
-    description: `Required scope: users:read. ${describeHttpRequest('GET', '/v1/users', queryKeys)} Full list of users on the store. Not paginated. Optionally filter to one userId (UUID). Pass expand=role to include { id, name } for the role.`,
+    description: 'Full list of the seats on the store, with the role of each. Not paginated. Call this to turn an agent’s name into an id — and take userId, the UUID, not the id beside it: userId is what ticket assignment, handledBy and the listTeams filter match on. Requires the users:read scope.',
+    scope: 'users:read',
     method: 'GET',
     path: '/v1/users',
     queryKeys,
@@ -13,9 +15,10 @@ export const listUsers = {
             .string()
             .min(1)
             .optional()
-            .describe('Query parameter. Restrict to this user (UUID).'),
-        expand: expand('Pass role to include { id, name } for the role. Without expand, the response keeps roleId.'),
+            .describe('Restrict to this user UUID.'),
+        expand: expand(['role'], 'Replace roleId with { id, name }.'),
     }),
-    annotations: { readOnlyHint: true },
+    outputSchema: envelope(z.array(user), 'Every user seat on the store.'),
+    annotations: { readOnlyHint: true, openWorldHint: true },
 };
 //# sourceMappingURL=list-users.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"list-users.js","sourceRoot":"","sources":["../../../src/tools/users/list-users.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAqB,MAAM,cAAc,CAAC;AAE9E,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAEhD,MAAM,CAAC,MAAM,SAAS,GAAiB;IACrC,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,YAAY;IACnB,WAAW,EAAE,+BAA+B,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,CAAC,iJAAiJ;IAC/O,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,WAAW;IACjB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CAAC,gDAAgD,CAAC;QAC7D,MAAM,EAAE,MAAM,CACZ,4FAA4F,CAC7F;KACF,CAAC;IACF,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;CACpC,CAAC"}
+{"version":3,"file":"list-users.js","sourceRoot":"","sources":["../../../src/tools/users/list-users.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAqB,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAEhD,MAAM,CAAC,MAAM,SAAS,GAAiB;IACrC,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,YAAY;IACnB,WAAW,EACT,0RAA0R;IAC5R,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,WAAW;IACjB,SAAS;IACT,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,EAAE;aACV,QAAQ,CAAC,6BAA6B,CAAC;QAC1C,MAAM,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,mCAAmC,CAAC;KAC9D,CAAC;IACF,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,+BAA+B,CAAC;IACtE,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;CACzD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaapi/open-api-mcp",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "MCP server for the Zaapi Open API",
   "homepage": "https://github.com/Zaapi/zaapi-open-api-mcp#readme",
   "bugs": {