mcp-zenskar 2.2.5 → 2.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Zenskar MCP Server
 
-MCP server for the Zenskar API. 113 tools covering customers, contracts, invoices, payments, credit notes, accounting, products, plans, entitlements, billable metrics, and more.
+MCP server for the Zenskar API. 115 tools covering customers, contracts, invoices, payments, credit notes, accounting, products, plans, entitlements, billable metrics, and more.
 
 ## What it does
 
@@ -290,6 +290,7 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `getRawMetricLogs`      | Get recent event rows for a Usage Event using the same preview-query path as the frontend                      |
 | `getRawMetricBySlug`    | Get a Usage Event by API slug; backend/API may also call it a raw metric                                       |
 | `ingestRawMetricEvent`  | Ingest a usage event                                                                                           |
+| `ingestRawMetricEventsBulk` | Ingest multiple usage events (up to 500) for a resource slug in a single call                              |
 
 ### Entitlements
 

package/dist/mcp-config.json

@@ -2903,6 +2903,46 @@
         "prependBody": "## Usage Event Ingested\n\nThe usage event was ingested successfully:\n\n"
       }
     },
+    {
+      "name": "ingestRawMetricEventsBulk",
+      "description": "Ingest MULTIPLE Usage Events for the specified resource slug in a single API call (bulk ingestion). Use this instead of calling ingestRawMetricEvent once per event — it sends one HTTP request carrying every event, which is far more efficient for CSV/batch imports. Each element of 'events' has the same shape as ingestRawMetricEvent's 'event' arg: customer_id, timestamp, and a data map with schema-compliant types. If importing from a CSV (or any source) whose column names don't clearly correspond to the expected fields (customer_id, timestamp, data.*), confirm the mapping with the user before constructing events — do not guess a mapping silently. Limit: 500 events per call — split larger batches into multiple calls. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Ingest Usage Events (Bulk)",
+        "description": "This will ingest ALL of the listed Usage Events for the selected Usage Event schema in one request. Review the full payload carefully — approving this ingests every event shown, not just one.",
+        "warningText": "Ensure every event's data payload matches the Usage Event schema (raw metric schema) before proceeding. Up to 500 events are ingested in a single call; review the count and a sample of entries before confirming.",
+        "confirmText": "Ingest Usage Events",
+        "cancelText": "Cancel",
+        "sensitiveFields": ["rawMetricSlug", "events"]
+      },
+      "args": [
+        {
+          "name": "rawMetricSlug",
+          "description": "Slug of the Usage Event resource (raw metric), e.g. api_usage_events.",
+          "type": "string",
+          "required": true,
+          "position": "path"
+        },
+        {
+          "name": "events",
+          "description": "Array of Usage Event payloads, each containing customer_id, timestamp, and a data map with schema-compliant types — same shape as ingestRawMetricEvent's 'event' arg, but plural. customer_id and timestamp are mandatory on EVERY event; MCP does not auto-add them. Events are validated server-side against the raw metric's real schema before anything is sent — an unknown data field or wrong type is rejected with the exact list of valid fields, so you do NOT need to pre-fetch the schema via getRawMetricBySlug first; only do so if you're unsure what fields/types this raw metric expects. Maximum 500 events per call — if you have more, split into multiple calls to this tool. Prefer 100–200 events per call: batches approaching 500 consume significant context, more so under stateless approval (the batch is base64-packed into the approval token and echoed back verbatim). Example event shape: {\"customer_id\": \"example_customer\", \"timestamp\": \"2025-01-01 00:00:00\", \"data\": {\"String\": \"sample value\", \"Int64\": 10, \"Float64\": 42.5}}.",
+          "type": "array",
+          "required": true,
+          "position": "body"
+        }
+      ],
+      "requestTemplate": {
+        "url": "/usage/{rawMetricSlug}",
+        "method": "POST",
+        "headers": {
+          "Content-Type": "application/json",
+          "apiversion": "20240301"
+        }
+      },
+      "responseTemplate": {
+        "prependBody": "## Usage Events Ingested (Bulk)\n\nThe usage events were ingested successfully:\n\n"
+      }
+    },
     {
       "name": "extractContractFromRaw",
       "description": "Extract structured contract data from raw text content using AI. This tool analyzes natural language contract descriptions and extracts key fields like dates, products, pricing, and billing terms. The extracted data can then be used to create a customer and contract via createCustomer and createContract tools.",
@@ -3751,21 +3791,21 @@
     },
     {
       "name": "expireContract",
-      "description": "THE ONLY tool that can expire, end, terminate or cancel a contract — use it whenever the user wants a contract to stop on a given date, including when they phrase it as 'update the expiry date'. Do NOT use updateContract for this. Expire an ACTIVE or PAUSED contract by adjusting its end_date. Allowed status transitions: ACTIVE→EXPIRED, PAUSED→EXPIRED. EXPIRED is terminal — calling on an already-expired contract returns 400; do NOT retry, do NOT escalate to deleteContract or any other destructive tool as a fallback. Verify contract.status via getContractById before calling. Idempotency: NO. The contract expires at end of day 23:59:59.999999. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "description": "THE ONLY tool that can expire, end, terminate or cancel contracts — use it whenever the user wants contracts to stop on a given date, including when they phrase it as 'update the expiry date'. Do NOT use updateContract for this. To expire SEVERAL contracts, pass every id in contractIds on a SINGLE call — never call this tool once per contract, as each call raises its own approval dialog and only the most recent one can be approved. Expire an ACTIVE or PAUSED contract by adjusting its end_date. Allowed status transitions: ACTIVE→EXPIRED, PAUSED→EXPIRED. EXPIRED is terminal — calling on an already-expired contract returns 400; do NOT retry, do NOT escalate to deleteContract or any other destructive tool as a fallback. Verify contract.status via getContractById before calling. Idempotency: NO. The contract expires at end of day 23:59:59.999999. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
       "needsApproval": true,
       "approvalConfig": {
         "title": "Expire Contract",
         "description": "This will set the contract's end_date and transition status to EXPIRED. EXPIRED is terminal.",
-        "warningText": "Once expired, the contract cannot be re-activated through this endpoint. Future-dated phases beyond the expiry will be removed.",
+        "warningText": "Approving this expires EVERY contract listed in contractIds — review the full list before confirming. Expiry is terminal: contracts cannot be re-activated through this endpoint, and future-dated phases beyond the expiry will be removed.",
         "confirmText": "Expire Contract",
         "cancelText": "Cancel",
-        "sensitiveFields": ["contractId", "expiry_date"]
+        "sensitiveFields": ["contractIds", "expiry_date"]
       },
       "args": [
         {
-          "name": "contractId",
-          "description": "The unique identifier (UUID) of the contract to expire.",
-          "type": "string",
+          "name": "contractIds",
+          "description": "UUIDs of the contracts to expire. Always a list, even for one contract. Pass every contract in one call. Each contract expires independently. The result reports each one.",
+          "type": "array",
           "required": true,
           "position": "path"
         },
@@ -3777,8 +3817,9 @@
           "position": "body"
         }
       ],
+      "bulkOver": { "listArg": "contractIds", "maxBatch": 25 },
       "requestTemplate": {
-        "url": "/contract_v2/{contractId}/expire",
+        "url": "/contract_v2/{contractIds}/expire",
         "method": "PATCH",
         "headers": {
           "Content-Type": "application/json"