mcp-zenskar 1.1.10 → 1.1.12

package/README.md

@@ -1,18 +1,17 @@
 # Zenskar MCP Server
 
-MCP server for the Zenskar API. 103 tools covering customers, contracts, invoices, payments, credit notes, accounting, products, plans, quotes, and more.
+MCP server for the Zenskar API. 103 tools covering customers, contracts, invoices, payments, credit notes, accounting, products, plans, and more.
 
 ## What it does
 
-- Customers: list, search, create, update, addresses, contacts, payment methods
-- Contracts: create, read, update, delete, amend, add phases and pricing, expire
+- Customers: list, search, create, update, delete, addresses, contacts, payment methods
+- Contracts: create, read, update, delete, amend, add phases and pricing, pause/resume, expire
 - Invoices: list, get, approve, void, generate, credit notes, download
 - Payments: create, edit, refund, delete, auto-charge
 - Credit notes: list, create against invoice, get by ID
 - Accounting: chart of accounts, journal entries and lines, balance sheet, income statement, account balances
 - Products: CRUD, pricing configurations
 - Plans: list, create, add products, preview estimates
-- Quotes: create, preview, accept (converts to contract)
 - Business entities: list, get, create, update
 - Jobs: monitor async operations
 - Custom attributes and tax categories
@@ -91,6 +90,7 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `getCustomerById` | Get a customer by ID |
 | `createCustomer` | Create a customer with address and tax info |
 | `updateCustomer` | Update customer details (partial update) |
+| `deleteCustomer` | Permanently delete a customer by ID (only allowed when they have no active contracts or unpaid invoices) |
 
 ### Contacts
 | Tool | Description |
@@ -99,6 +99,7 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `getContactById` | Get a contact by ID |
 | `createContact` | Create a contact for a customer |
 | `updateContact` | Update a contact's details |
+| `deleteContact` | Delete a contact by ID |
 
 ### Contracts
 | Tool | Description |
@@ -112,6 +113,9 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `createContractPhase` | Add a phase to a contract (add-ons, expansions) |
 | `createContractPhasePricing` | Add pricing to a contract phase |
 | `expireContract` | Expire an active contract |
+| `pauseContract` | Pause an active contract from a given start date, with an unpause-extension policy (`extend` or `overlap`) and optional end date for auto-resume |
+| `editPauseContract` | Edit an existing pause phase — set or change the resume date, shift the start, or change the unpause policy |
+| `resumeContract` | Resume a paused contract |
 | `createContractPrompt` | Create a contract prompt |
 | `extractContractFromRaw` | Extract contract data from raw text using AI |
 
@@ -133,7 +137,8 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `generateInvoicePaymentLink` | Generate a payment link for an invoice |
 | `payInvoice` | Initiate payment for an invoice |
 | `approveInvoice` | Approve an invoice for billing |
-| `voidInvoice` | Void an approved unpaid invoice |
+| `voidInvoice` | Void an invoice |
+| `deleteInvoice` | Delete a draft invoice |
 | `generateInvoice` | Generate an invoice for a contract and date range |
 | `createInvoiceCreditNote` | Create a credit note against an invoice |
 | `createInvoiceCharge` | Auto-charge an invoice via payment gateway |
@@ -171,8 +176,6 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `listPlans` | List plan templates |
 | `getPlanById` | Get a plan by ID with phases and pricing |
 | `createPlan` | Create a plan template |
-| `addProductsToPlan` | Add products to an existing plan |
-| `previewPlanEstimate` | Preview estimated billing for a plan |
 
 ### Accounting
 | Tool | Description |
@@ -189,14 +192,6 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `getAccountBalance` | Get balance for a specific GL account |
 | `recogniseRevenue` | Trigger revenue recognition up to a date |
 
-### Quotes
-| Tool | Description |
-|---|---|
-| `createQuote` | Create a quote/proposal |
-| `previewQuoteEstimate` | Preview estimated billing for a quote |
-| `getQuoteById` | Get a quote by ID |
-| `acceptQuote` | Accept a quote, converting to a contract |
-
 ### Custom Attributes and Tax
 | Tool | Description |
 |---|---|
@@ -227,6 +222,7 @@ Once configured, you can ask Claude to interact with your Zenskar data:
 | `updateCustomerAddress` | Update a customer address |
 | `listPaymentMethods` | List payment methods for a customer |
 | `attachPaymentMethod` | Attach a payment method to a customer |
+| `deletePaymentMethod` | Delete a payment method from a customer |
 
 ### Metrics and Usage Events
 | Tool | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-zenskar",
-  "version": "1.1.10",
+  "version": "1.1.12",
   "description": "Model Context Protocol (MCP) server for Zenskar API - customer management, invoicing, and billing operations",
   "main": "src/server.js",
   "bin": {

package/src/mcp-config.json

@@ -586,7 +586,18 @@
     },
     {
       "name": "payInvoice",
-      "description": "Initiate payment for an invoice using a payload.",
+      "description": "Initiate payment for an invoice using a payload. MONEY-MOVING ACTION — only call when the user explicitly authorizes payment for this specific invoice. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Pay Invoice",
+        "description": "This will initiate a payment against the invoice using the provided payload.",
+        "warningText": "Money-moving action — funds will be charged. Verify the invoice and amount before confirming.",
+        "confirmText": "Pay Invoice",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "payload"
+        ]
+      },
       "args": [
         {
           "name": "payload",
@@ -965,7 +976,7 @@
     },
     {
       "name": "createRawMetric",
-      "description": "Create a new Usage Event schema. In backend/API terminology this resource is called a raw metric. This defines the schema used for ingesting usage events.",
+      "description": "Create a new Usage Event schema. In backend/API terminology this resource is called a raw metric. This defines the schema used for ingesting usage events. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
       "needsApproval": true,
       "approvalConfig": {
         "title": "Create Usage Event Schema",
@@ -1829,7 +1840,7 @@
     },
     {
       "name": "createEntitlement",
-      "description": "Creates a new entitlement in the system with various attributes including name, description, type, units, and product association.",
+      "description": "Creates a new entitlement in the system with various attributes including name, description, type, units, and product association. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
       "needsApproval": true,
       "approvalConfig": {
         "title": "Create New Entitlement",
@@ -1906,7 +1917,7 @@
     },
     {
       "name": "approveInvoice",
-      "description": "Approves an invoice. This changes the invoice status to approved and may trigger billing processes.",
+      "description": "Approve an invoice; sets status to approved. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
       "needsApproval": true,
       "approvalConfig": {
         "title": "Approve Invoice",
@@ -1958,7 +1969,7 @@
     },
     {
       "name": "recogniseRevenue",
-      "description": "Recognizes revenue for the organization up to a specified end date. This triggers revenue recognition processing for all eligible transactions.",
+      "description": "Recognize revenue for the organization up to a specified end_date. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
       "needsApproval": true,
       "approvalConfig": {
         "title": "Recognise Revenue",
@@ -1992,7 +2003,7 @@
     },
     {
       "name": "createBusinessEntity",
-      "description": "Creates a new business entity in the system with various attributes including name, address, contact details, tax configuration, and logo.",
+      "description": "Creates a new business entity in the system with various attributes including name, address, contact details, tax configuration, and logo. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
       "needsApproval": true,
       "approvalConfig": {
         "title": "Create New Business Entity",
@@ -2305,7 +2316,7 @@
     },
     {
       "name": "ingestRawMetricEvent",
-      "description": "Ingest a Usage Event for the specified resource slug. Backend/API terminology may also call the target resource a raw metric.",
+      "description": "Ingest a Usage Event for the specified resource slug. Backend/API terminology may also call the target resource a raw metric. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
       "needsApproval": true,
       "approvalConfig": {
         "title": "Ingest Usage Event",
@@ -2719,7 +2730,18 @@
     },
     {
       "name": "deleteContract",
-      "description": "Delete a contract by its ID. Only works on draft contracts. Returns the deleted contract object with a deleted_at timestamp.",
+      "description": "Permanently delete a DRAFT contract. ONLY works on contracts with status='draft'. Do NOT call on ACTIVE, EXPIRED, or PAUSED contracts. DESTRUCTIVE: removes all phases, products, and pricing associations. NEVER call as automatic recovery from another failed operation (e.g., do not retry as a fallback after expireContract or voidInvoice fails). ONLY call when the user explicitly says 'delete' or 'remove' for THIS draft contract. If a non-destructive action fails, surface the error verbatim and stop. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Draft Contract",
+        "description": "This will permanently delete the draft contract along with all its phases, products, and pricing associations.",
+        "warningText": "DESTRUCTIVE — this cannot be undone. Only draft contracts may be deleted; verify status before confirming.",
+        "confirmText": "Delete Contract",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "contractId"
+        ]
+      },
       "args": [
         {
           "name": "contractId",
@@ -2956,7 +2978,19 @@
     },
     {
       "name": "expireContract",
-      "description": "Expire an active contract. Only works on contracts with status 'active'. Optionally specify an expiry_date (defaults to today). The contract expires at end of day 23:59:59.999999.",
+      "description": "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.",
+        "confirmText": "Expire Contract",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "contractId",
+          "expiry_date"
+        ]
+      },
       "args": [
         {
           "name": "contractId",
@@ -2967,7 +3001,7 @@
         },
         {
           "name": "expiry_date",
-          "description": "Date to expire the contract (e.g. 2026-12-31). Defaults to today if not provided.",
+          "description": "Date to expire the contract (e.g. 2026-12-31). Defaults to today if not provided. Must not be earlier than contract.start_date.",
           "type": "string",
           "required": false,
           "position": "body"
@@ -2986,7 +3020,18 @@
     },
     {
       "name": "voidInvoice",
-      "description": "Void an invoice by its ID. Only works on approved invoices that have not been fully paid. Voiding reverses the invoice and creates appropriate accounting entries.",
+      "description": "Void an invoice. ONLY works on approved or paid invoices with invoice_total == 0 (zero-balance, typically after a full credit-note offset). For non-zero approved invoices, issue a credit note via createInvoiceCreditNote first to bring the balance to zero, then void. If the call returns INVOICE_CANNOT_BE_VOIDED, surface that error verbatim — do NOT retry, do NOT escalate to deleteInvoice. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Void Invoice",
+        "description": "This will set the invoice status to 'void' and post the corresponding accounting entries. Only zero-balance approved/paid invoices are eligible.",
+        "warningText": "Voiding affects accounting records and cannot be easily undone.",
+        "confirmText": "Void Invoice",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "invoiceId"
+        ]
+      },
       "args": [
         {
           "name": "invoiceId",
@@ -3007,6 +3052,40 @@
         "prependBody": "## Invoice Voided\n\n"
       }
     },
+    {
+      "name": "deleteInvoice",
+      "description": "Permanently delete a draft invoice. ONLY works on status='draft'. For approved invoices, use voidInvoice (with caveats) or createInvoiceCreditNote — do NOT call deleteInvoice on approved invoices. DESTRUCTIVE: record removed permanently. ONLY call when the user explicitly says 'delete' for THIS invoice; never call as automatic recovery from another failed operation. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Invoice",
+        "description": "This will permanently delete the draft invoice.",
+        "warningText": "DESTRUCTIVE — invoice record will be removed and cannot be recovered.",
+        "confirmText": "Delete Invoice",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "invoiceId"
+        ]
+      },
+      "args": [
+        {
+          "name": "invoiceId",
+          "description": "The unique identifier (UUID) of the draft or upcoming invoice to delete.",
+          "type": "string",
+          "required": true,
+          "position": "path"
+        }
+      ],
+      "requestTemplate": {
+        "url": "/invoices/{invoiceId}",
+        "method": "DELETE",
+        "headers": {
+          "Content-Type": "application/json"
+        }
+      },
+      "responseTemplate": {
+        "prependBody": "## Invoice Deleted\n\n"
+      }
+    },
     {
       "name": "createInvoiceCreditNote",
       "description": "Create a credit note against a specific invoice. The credit_note_amount is in the invoice's currency (e.g. 25 for $25). The API stores amounts in cents internally. Returns the created credit note.",
@@ -3046,7 +3125,7 @@
     },
     {
       "name": "generateInvoice",
-      "description": "Generate an invoice for a customer given a contract and date range. Use this for billing replay or on-demand invoice generation.",
+      "description": "STOP — read this before calling. Granularity is PER PHASE, NOT per product. ONE call generates ONE invoice covering ALL products active in the (contract, customer, from_date, to_date) window — every product becomes a line item on the same invoice. NEVER iterate over products. Iterate over PHASES only. CORRECT: a 2-phase contract with 2 products per phase → exactly 2 calls (one per phase), producing 2 invoices each with 2 line items. WRONG: 4 calls (one per product per phase) → produces 4 fragmented duplicate invoices, which is the #1 bug reported on this tool. Before calling, fetch the contract's phases via getContractById and use each phase's start_date / end_date as from_date / to_date. Use for billing replay or on-demand invoice generation.",
       "args": [
         {
           "name": "contract_id",
@@ -3302,7 +3381,18 @@
     },
     {
       "name": "deleteManualPayment",
-      "description": "Delete a manual payment. Only works on payments that are in an eligible status for deletion.",
+      "description": "Permanently delete a manual payment record. Only works on payments in an eligible status for deletion. DESTRUCTIVE — only call when the user explicitly says 'delete' for THIS payment; never as automatic recovery from another failed operation. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Manual Payment",
+        "description": "This will permanently remove the manual payment record.",
+        "warningText": "DESTRUCTIVE — payment record will be removed and cannot be recovered. Linked invoice balance may shift as a result.",
+        "confirmText": "Delete Payment",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "paymentId"
+        ]
+      },
       "args": [
         {
           "name": "paymentId",
@@ -4126,7 +4216,7 @@
     },
     {
       "name": "createProductPricing",
-      "description": "Create a new pricing configuration for a product. The pricing_data object is a discriminated union — the 'pricing_type' field determines which pricing model schema to use.",
+      "description": "Create a new pricing configuration for a product. MANDATORY pre-call checklist — ask the user for ALL of these and do NOT default any silently: (1) currency (ISO 4217), (2) pricing_type (per_unit|flat_fee|tiered|volume|percent|package|step|matrix), (3) unit_amount in MAJOR currency units (float — 3 means $3, NOT 300 cents), (4) quantity object with type (fixed|metered) and unit label (e.g. 'user', 'request') and either quantity (for fixed) or aggregate_id (for metered), (5) billing_period.cadence (ISO 8601 — 'P1M' monthly, 'P3M' quarterly, 'P1Y' yearly) and billing_period.offset. SKIPPING quantity OR billing_period causes the Zenskar UI to render 'Undefined- Every Undefined Undefined' for billing cadence and 0 for billing metric — that is the #1 bug reported on this tool.",
       "args": [
         {
           "name": "productId",
@@ -4151,16 +4241,23 @@
         },
         {
           "name": "pricing_data",
-          "description": "Pricing data object (required). Must include 'pricing_type' discriminator. Supported types: flat_fee: {pricing_type:'flat_fee', unit_amount:10000}. per_unit: {pricing_type:'per_unit', unit_amount:500}. tiered: {pricing_type:'tiered', unit_amount:[1000,500], up_to:[100,null]}. volume: {pricing_type:'volume', unit_amount:[1000,500], up_to:[100,null]}. percent: {pricing_type:'percent', percentage:5.0}. package: {pricing_type:'package', package_size:10, unit_amount:5000}. step: {pricing_type:'step', unit_amount:[...], up_to:[...]}. matrix: {pricing_type:'matrix', dimensions:[...], values:[...]}.",
+          "description": "Pricing data object (required). MUST include 'pricing_type' discriminator AND 'currency' (ISO 4217, e.g. 'USD'). 'unit_amount' is in MAJOR currency units (float) — 3 means $3, NOT 300 cents. Do NOT convert to cents. Supported pricing_type values with examples: flat_fee: {pricing_type:'flat_fee', unit_amount:100, currency:'USD'}. per_unit: {pricing_type:'per_unit', unit_amount:3, currency:'USD'}. tiered: {pricing_type:'tiered', unit_amount:[10,5], up_to:[100,null], currency:'USD'}. volume: {pricing_type:'volume', unit_amount:[10,5], up_to:[100,null], currency:'USD'}. percent: {pricing_type:'percent', percentage:5.0, currency:'USD'}. package: {pricing_type:'package', package_size:10, unit_amount:50, currency:'USD'}. step: {pricing_type:'step', unit_amount:[...], up_to:[...], currency:'USD'}. matrix: {pricing_type:'matrix', dimensions:[...], values:[...], currency:'USD'}. Optional inside pricing_data for per_unit: 'proration_type' ('day_based'|'cadence_based'), 'charge_full_amount' (bool).",
+          "type": "object",
+          "required": true,
+          "position": "body"
+        },
+        {
+          "name": "quantity",
+          "description": "Quantity configuration (REQUIRED — ask the user; do not omit). Top-level object, NOT inside pricing_data. Shape: {type: 'fixed'|'metered', quantity?: number, unit?: string, aggregate_id?: UUID}. 'fixed' = static quantity (e.g. seats); also set 'unit' (label like 'user') and 'quantity' (number). 'metered' = consumption tracked via a billable metric; set aggregate_id to the billable-metric UUID. Omitting this object causes the UI to show 0 for billing metric.",
           "type": "object",
           "required": true,
           "position": "body"
         },
         {
           "name": "billing_period",
-          "description": "Billing cadence for this pricing. Object with 'cadence' (ISO 8601 duration, e.g. 'P1M' for monthly, 'P3M' for quarterly, 'P1Y' for annually) and optional 'offset'. Example: {cadence: 'P1M'}.",
+          "description": "Billing cadence (REQUIRED — ask the user; do not omit). Object: {cadence: ISO-8601 duration ('P1M'=monthly, 'P3M'=quarterly, 'P1Y'=annually), offset: ISO-8601 duration ('P0D' for no offset, 'P1M' to bill 1 month after period start)}. Both fields needed. Example: {\"cadence\":\"P1M\",\"offset\":\"P0D\"}. Omitting this causes the UI to render 'Undefined- Every Undefined Undefined'.",
           "type": "object",
-          "required": false,
+          "required": true,
           "position": "body"
         },
         {
@@ -4191,7 +4288,7 @@
     },
     {
       "name": "listPlans",
-      "description": "Retrieve a paginated list of plans (templates v3) that define reusable contract structures.",
+      "description": "Retrieve a paginated list of plans that define reusable contract structures. Hits /plans — the same data the Zenskar app's Plans page reads.",
       "args": [
         {
           "name": "cursor",
@@ -4223,7 +4320,7 @@
         }
       ],
       "requestTemplate": {
-        "url": "/templates/plan",
+        "url": "/plans",
         "method": "GET",
         "headers": {
           "Content-Type": "application/json"
@@ -4246,7 +4343,7 @@
         }
       ],
       "requestTemplate": {
-        "url": "/templates/plan/{planId}",
+        "url": "/plans/{planId}",
         "method": "GET",
         "headers": {
           "Content-Type": "application/json"
@@ -4258,141 +4355,58 @@
     },
     {
       "name": "createPlan",
-      "description": "Create a new plan (template) that defines a reusable contract structure with products and pricing.",
+      "description": "Create a new plan — a reusable contract template with phased pricing. Hits POST /plans (same Plan table the Zenskar app's PlansV2 page reads). The request body shape is NESTED, not flat: top-level fields are name, status, schedule, optional description, optional phases[]. Currency is set per-pricing inside phase.pricings[].pricing.pricing_data.currency, NOT at the top level. A plan with no phases is unusable in the UI — always include at least one phase. Plan starts as 'draft'; the user must publish it to make it active.",
       "args": [
         {
           "name": "name",
-          "description": "Name of the plan.",
+          "description": "Name of the plan (required).",
           "type": "string",
           "required": true,
           "position": "body"
         },
         {
-          "name": "currency",
-          "description": "Three-letter ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP').",
+          "name": "status",
+          "description": "Plan status (required). Valid values: 'draft', 'active', 'archived'. New plans almost always start as 'draft' — the user publishes via the UI to activate.",
           "type": "string",
           "required": true,
-          "position": "body"
-        },
-        {
-          "name": "display_config",
-          "description": "Customer-facing display content. Object with fields like title, description, etc.",
-          "type": "object",
-          "required": false,
-          "position": "body"
-        },
-        {
-          "name": "duration",
-          "description": "Billing period in ISO 8601 duration format (e.g., 'P1M' for monthly, 'P1Y' for yearly).",
-          "type": "string",
-          "required": false,
-          "position": "body"
-        },
-        {
-          "name": "products",
-          "description": "Array of products to add to plan, each with product_id and pricing configuration.",
-          "type": "array",
-          "required": false,
-          "position": "body"
+          "position": "body",
+          "enum": [
+            "draft",
+            "active",
+            "archived"
+          ]
         },
         {
-          "name": "custom_attributes",
-          "description": "Custom attributes as key-value pairs.",
+          "name": "schedule",
+          "description": "Plan-level schedule (required). Object: {duration: ISO-8601 e.g. 'P1Y'|'P1M', start_offset?: ISO-8601 e.g. 'P0D', trigger_type?: 'time_based'}. Example: {\"duration\":\"P1Y\",\"start_offset\":\"P0D\"}.",
           "type": "object",
-          "required": false,
-          "position": "body"
-        },
-        {
-          "name": "status",
-          "description": "Plan status. Default: 'draft'. Options: 'draft', 'active', 'archived'.",
-          "type": "string",
-          "required": false,
+          "required": true,
           "position": "body"
         },
         {
-          "name": "business_entity_id",
-          "description": "Business entity ID for invoicing.",
+          "name": "description",
+          "description": "Optional plan description.",
           "type": "string",
           "required": false,
           "position": "body"
-        }
-      ],
-      "requestTemplate": {
-        "url": "/templates/plan",
-        "method": "POST",
-        "headers": {
-          "Content-Type": "application/json"
-        }
-      },
-      "responseTemplate": {
-        "prependBody": "## Created Plan\n\n"
-      }
-    },
-    {
-      "name": "addProductsToPlan",
-      "description": "Add products with pricing to an existing plan.",
-      "args": [
-        {
-          "name": "planId",
-          "description": "The unique identifier of the plan.",
-          "type": "string",
-          "required": true,
-          "position": "path"
         },
         {
-          "name": "products",
-          "description": "Array of product objects to add, each with product_id and pricing configuration.",
+          "name": "phases",
+          "description": "Array of plan phases (REQUIRED — must be non-empty). Each phase: {name: string (required), schedule: {duration, start_offset?, trigger_type?} (required), order: int (required, 0-indexed), description?: string, features?: CreateProductPricingRequestSchema (one-off phase-level pricing/features), pricings?: [{schedule, pricing_id?, product_id?, pricing?: CreateProductPricingRequestSchema, product?: CreateProductRequestSchema}] (per-product pricings)}. Each phase must have features OR a non-empty pricings array. Minimal example: [{\"name\":\"Phase 1\",\"schedule\":{\"duration\":\"P1Y\"},\"order\":0,\"features\":{\"pricing_data\":{\"pricing_type\":\"features\"}}}].",
           "type": "array",
           "required": true,
           "position": "body"
         }
       ],
       "requestTemplate": {
-        "url": "/templates/plan/{planId}/products",
+        "url": "/plans",
         "method": "POST",
         "headers": {
           "Content-Type": "application/json"
         }
       },
       "responseTemplate": {
-        "prependBody": "## Updated Plan Products\n\n"
-      }
-    },
-    {
-      "name": "previewPlanEstimate",
-      "description": "Preview the estimated billing for a plan, showing projected charges per phase.",
-      "args": [
-        {
-          "name": "planId",
-          "description": "The unique identifier of the plan.",
-          "type": "string",
-          "required": true,
-          "position": "path"
-        },
-        {
-          "name": "start_date",
-          "description": "Start date for the estimate (YYYY-MM-DD).",
-          "type": "string",
-          "required": true,
-          "position": "body"
-        },
-        {
-          "name": "end_date",
-          "description": "End date for the estimate (YYYY-MM-DD). Optional — calculated from plan duration if omitted.",
-          "type": "string",
-          "required": false,
-          "position": "body"
-        }
-      ],
-      "requestTemplate": {
-        "url": "/templates/plan/{planId}/preview",
-        "method": "POST",
-        "headers": {
-          "Content-Type": "application/json"
-        }
-      },
-      "responseTemplate": {
-        "prependBody": "## Plan Estimate Preview\n\n"
+        "prependBody": "## Created Plan\n\n"
       }
     },
     {
@@ -5107,7 +5121,18 @@
     },
     {
       "name": "deleteCustomer",
-      "description": "Delete a customer by ID. This is permanent and cannot be undone. The customer must not have active contracts or unpaid invoices.",
+      "description": "Permanently delete a customer by ID. DESTRUCTIVE and cannot be undone. The customer must not have active contracts or unpaid invoices. ONLY call when the user explicitly says 'delete' for THIS customer; never as automatic recovery from another failed operation. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Customer",
+        "description": "This will permanently delete the customer and all associated records.",
+        "warningText": "DESTRUCTIVE — customer record cannot be recovered. Verify there are no active contracts or unpaid invoices first.",
+        "confirmText": "Delete Customer",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "customerId"
+        ]
+      },
       "args": [
         {
           "name": "customerId",
@@ -5130,7 +5155,18 @@
     },
     {
       "name": "deleteContact",
-      "description": "Delete a contact by ID.",
+      "description": "Permanently delete a contact by ID. DESTRUCTIVE — only call when the user explicitly says 'delete' for THIS contact; never as automatic recovery from another failed operation. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Contact",
+        "description": "This will permanently delete the contact record.",
+        "warningText": "DESTRUCTIVE — contact record will be removed and cannot be recovered.",
+        "confirmText": "Delete Contact",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "contactId"
+        ]
+      },
       "args": [
         {
           "name": "contactId",
@@ -5153,7 +5189,19 @@
     },
     {
       "name": "deletePaymentMethod",
-      "description": "Delete a payment method from a customer.",
+      "description": "Permanently delete a payment method from a customer. DESTRUCTIVE — saved card/bank details will be removed; recurring auto-charges using this method will fail. Only call when the user explicitly says 'delete' for THIS payment method. Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.",
+      "needsApproval": true,
+      "approvalConfig": {
+        "title": "Delete Payment Method",
+        "description": "This will permanently delete the payment method from the customer's profile.",
+        "warningText": "DESTRUCTIVE — saved payment details will be removed. Any auto-charge or scheduled charge using this method will fail.",
+        "confirmText": "Delete Payment Method",
+        "cancelText": "Cancel",
+        "sensitiveFields": [
+          "customerId",
+          "paymentMethodId"
+        ]
+      },
       "args": [
         {
           "name": "customerId",
@@ -5183,7 +5231,7 @@
     },
     {
       "name": "pauseContract",
-      "description": "Pause an active contract. Requires a start_date for the pause and an unpause_extension_policy.",
+      "description": "Pause an active contract. ALWAYS ask the user explicitly for both 'start_date' and 'unpause_extension_policy' before calling — do NOT silently default. A future-dated start_date will create a scheduled pause that has not yet begun; the contract's top-level status stays 'active' until start_date passes. Use 'editPauseContract' to adjust the pause window or set a resume date afterward.",
       "args": [
         {
           "name": "contractId",
@@ -5194,14 +5242,14 @@
         },
         {
           "name": "start_date",
-          "description": "Date when the pause begins (ISO 8601 format, e.g. 2026-04-01T00:00:00).",
+          "description": "Date when the pause begins (ISO 8601 format, e.g. 2026-04-01T00:00:00). REQUIRED — ask the user; never default to today or a future date silently.",
           "type": "string",
           "required": true,
           "position": "body"
         },
         {
           "name": "unpause_extension_policy",
-          "description": "How to handle the contract end date when unpaused.",
+          "description": "How to handle the contract end date when unpaused. 'extend' pushes the end_date out by the pause duration; 'overlap' keeps end_date fixed. ASK the user.",
           "type": "string",
           "required": true,
           "position": "body",
@@ -5229,9 +5277,57 @@
         "prependBody": "## Contract Paused\n\n"
       }
     },
+    {
+      "name": "editPauseContract",
+      "description": "Edit an existing pause phase on a contract. Use this when 'resumeContract' returns 'pause phase not found' for a future-dated pause, or when the user wants to set a resume date (pause end_date), shift the pause start, or change the unpause_extension_policy. Hits PATCH /contract_v2/{contractId}/pause.",
+      "args": [
+        {
+          "name": "contractId",
+          "description": "The unique identifier (UUID) of the contract whose pause phase to edit.",
+          "type": "string",
+          "required": true,
+          "position": "path"
+        },
+        {
+          "name": "start_date",
+          "description": "New pause start date (ISO 8601). Optional.",
+          "type": "string",
+          "required": false,
+          "position": "body"
+        },
+        {
+          "name": "end_date",
+          "description": "Resume date — when the pause ends (ISO 8601). Set this to schedule a future resume.",
+          "type": "string",
+          "required": false,
+          "position": "body"
+        },
+        {
+          "name": "unpause_extension_policy",
+          "description": "How to handle the contract end date when unpaused. 'extend' or 'overlap'.",
+          "type": "string",
+          "required": false,
+          "position": "body",
+          "enum": [
+            "extend",
+            "overlap"
+          ]
+        }
+      ],
+      "requestTemplate": {
+        "url": "/contract_v2/{contractId}/pause",
+        "method": "PATCH",
+        "headers": {
+          "Content-Type": "application/json"
+        }
+      },
+      "responseTemplate": {
+        "prependBody": "## Pause Phase Updated\n\n"
+      }
+    },
     {
       "name": "resumeContract",
-      "description": "Resume a paused contract. No request body needed.",
+      "description": "Resume a contract that is currently in an actively-running pause. MANDATORY FLOW: (1) ASK the user 'What date should the contract resume from?' — never call without a known resume date even though this endpoint takes no body. (2) Call getContractById and check the pause phase's start_date. (3a) If pause start_date is strictly in the past (pause currently active) AND the user wants to resume immediately/today → call this endpoint. (3b) If pause start_date is today OR in the future, OR the user wants a specific future resume date → call 'editPauseContract' with end_date=<resume_date> instead. The error 'pause phase not found' does NOT mean no pause exists — it means no pause has yet started; on this error, automatically pivot to 'editPauseContract' with the resume date. Never escalate to deleteContract or any destructive fallback.",
       "args": [
         {
           "name": "contractId",

package/src/server.js

@@ -1113,43 +1113,77 @@ async function executeAPICall(tool, args) {
   }
 }
 
+// One-time approval tokens. Server issues a token on the approval_required response;
+// the host must echo it back on the second invocation. Prevents prompt-injection
+// scenarios where an LLM fabricates `approval.approved=true` to bypass the dialog.
+// Tokens are single-use and expire after 5 minutes.
+const APPROVAL_TOKEN_TTL_MS = 5 * 60 * 1000;
+const approvalTokens = new Map(); // token -> {toolName, issuedAt, expiresAt}
+
+function issueApprovalToken(toolName) {
+  const token = uuidv4();
+  const issuedAt = Date.now();
+  approvalTokens.set(token, {
+    toolName,
+    issuedAt,
+    expiresAt: issuedAt + APPROVAL_TOKEN_TTL_MS
+  });
+  // Opportunistic cleanup of expired tokens.
+  for (const [t, entry] of approvalTokens) {
+    if (entry.expiresAt < issuedAt) approvalTokens.delete(t);
+  }
+  return token;
+}
+
+function consumeApprovalToken(token, toolName) {
+  if (!token || typeof token !== 'string') return false;
+  const entry = approvalTokens.get(token);
+  if (!entry) return false;
+  approvalTokens.delete(token); // single-use regardless of validity
+  if (entry.toolName !== toolName) return false;
+  if (entry.expiresAt < Date.now()) return false;
+  return true;
+}
+
 // Function to check if tool needs approval
 function checkNeedsApproval(tool, args) {
   if (!tool.needsApproval) {
     return false;
   }
-  
-  // Check if this is a re-execution after approval
+
+  // Check if this is a re-execution after approval. The host must echo the
+  // server-issued one-time token; bare `approved: true` is no longer trusted.
   const userContext = args.__userContext;
-  if (userContext && userContext.approval && userContext.approval.approved === true) {
-    logger.info(`[${tool.name}] Tool was approved by user, using modified arguments`);
-    
-    // Replace current args with user-approved/modified arguments
-    const modifiedArgs = userContext.approval.modifiedArguments;
-    if (modifiedArgs) {
-      // Clear existing tool args but keep __userContext
-      const savedUserContext = args.__userContext;
-      Object.keys(args).forEach(key => {
-        if (key !== '__userContext') {
-          delete args[key];
-        }
-      });
-      
-      // Apply user's modified arguments
-      Object.assign(args, modifiedArgs);
-      args.__userContext = savedUserContext;
-      
-      logger.info(`[${tool.name}] Using user-modified arguments:`, modifiedArgs);
+  const approval = userContext && userContext.approval;
+  if (approval && approval.approved === true) {
+    if (consumeApprovalToken(approval.token, tool.name)) {
+      logger.info(`[${tool.name}] Approval token verified, executing with approved arguments`);
+
+      // Replace current args with user-approved/modified arguments
+      const modifiedArgs = approval.modifiedArguments;
+      if (modifiedArgs) {
+        const savedUserContext = args.__userContext;
+        Object.keys(args).forEach(key => {
+          if (key !== '__userContext') {
+            delete args[key];
+          }
+        });
+        Object.assign(args, modifiedArgs);
+        args.__userContext = savedUserContext;
+        logger.info(`[${tool.name}] Using user-modified arguments:`, modifiedArgs);
+      }
+
+      return false; // Skip approval, execute with approved args
     }
-    
-    return false; // Skip approval, execute with approved args
+    logger.warn(`[${tool.name}] Approval received without valid token (got: ${approval.token ? 'expired/mismatched' : 'missing'}); requiring re-approval`);
+    // Fall through to issue a fresh approval_required response.
   }
-  
+
   // If needsApproval is a function, evaluate it
   if (typeof tool.needsApproval === 'function') {
     return tool.needsApproval(args);
   }
-  
+
   // If it's a boolean true, always needs approval
   return tool.needsApproval === true;
 }
@@ -1159,12 +1193,15 @@ function generateApprovalRequest(tool, args) {
   const userContext = args.__userContext;
   const cleanArgs = { ...args };
   delete cleanArgs.__userContext;
-  
+  const approvalToken = issueApprovalToken(tool.name);
+
   return {
     type: 'approval_required',
     toolName: tool.name,
     toolDescription: tool.description,
     arguments: cleanArgs,
+    approvalToken,
+    approvalTokenExpiresInSeconds: Math.floor(APPROVAL_TOKEN_TTL_MS / 1000),
     approvalConfig: tool.approvalConfig || {
       title: `Approve ${tool.name}`,
       description: `This action requires your approval: ${tool.description}`,
@@ -1184,6 +1221,76 @@ function generateApprovalRequest(tool, args) {
   };
 }
 
+// Tool-specific deep argument validation. Catches semantic gaps that JSON Schema
+// `required` cannot express (e.g. nested fields inside an `object` arg).
+// Return shape matches validateToolLimits: {valid, errors[]}.
+function validateToolArgs(toolName, args) {
+  const errors = [];
+
+  if (toolName === 'createProductPricing') {
+    const pd = args.pricing_data;
+    if (!pd || typeof pd !== 'object') {
+      errors.push("'pricing_data' is required and must be an object containing 'pricing_type' and 'currency'.");
+    } else {
+      if (!pd.pricing_type) errors.push("'pricing_data.pricing_type' is required (e.g. 'per_unit', 'flat_fee', 'tiered', 'volume', 'percent', 'package').");
+      if (!pd.currency) errors.push("'pricing_data.currency' is required (ISO 4217, e.g. 'USD').");
+    }
+    const q = args.quantity;
+    if (!q || typeof q !== 'object') {
+      errors.push("'quantity' is required and must be an object: {type:'fixed'|'metered', quantity?, unit?, aggregate_id?}. Without it the UI shows 0 for billing_metric.");
+    } else {
+      if (q.type !== 'fixed' && q.type !== 'metered') errors.push("'quantity.type' must be exactly 'fixed' or 'metered'.");
+      if (q.type === 'fixed' && (q.quantity == null || !q.unit)) errors.push("'quantity.type'='fixed' requires both 'quantity' (number) and 'unit' (label string).");
+      if (q.type === 'metered' && !q.aggregate_id) errors.push("'quantity.type'='metered' requires 'aggregate_id' (UUID of the billable metric).");
+    }
+    const bp = args.billing_period;
+    if (!bp || typeof bp !== 'object') {
+      errors.push("'billing_period' is required and must be an object: {cadence:'P1M'|'P3M'|'P1Y'|..., offset:'P0D'|...}. Without it the UI renders 'Undefined- Every Undefined Undefined'.");
+    } else {
+      if (!bp.cadence) errors.push("'billing_period.cadence' is required (ISO-8601 duration: 'P1M'=monthly, 'P3M'=quarterly, 'P1Y'=yearly).");
+      if (!bp.offset) errors.push("'billing_period.offset' is required (ISO-8601 duration, 'P0D' for no offset).");
+    }
+  }
+
+  if (toolName === 'createPlan') {
+    if (!args.schedule || typeof args.schedule !== 'object' || !args.schedule.duration) {
+      errors.push("'schedule' is required and must include 'duration' (ISO-8601, e.g. 'P1Y').");
+    }
+    if (!args.status) {
+      errors.push("'status' is required: 'draft' | 'active' | 'archived'.");
+    }
+    const phases = args.phases;
+    if (!Array.isArray(phases) || phases.length === 0) {
+      errors.push("'phases' must be a non-empty array. A plan with no phases is unusable in PlansV2 — include at least one phase with name, schedule, order, and either features or pricings.");
+    } else {
+      phases.forEach((p, i) => {
+        if (!p || typeof p !== 'object') { errors.push(`'phases[${i}]' must be an object.`); return; }
+        if (!p.name) errors.push(`'phases[${i}].name' is required.`);
+        if (!p.schedule || !p.schedule.duration) errors.push(`'phases[${i}].schedule.duration' is required (ISO-8601).`);
+        if (typeof p.order !== 'number') errors.push(`'phases[${i}].order' is required (integer, 0-indexed).`);
+        if (!p.features && (!Array.isArray(p.pricings) || p.pricings.length === 0)) {
+          errors.push(`'phases[${i}]' has neither 'features' nor non-empty 'pricings' — phase will be empty in the UI.`);
+        }
+      });
+    }
+  }
+
+  if (toolName === 'generateInvoice') {
+    if (!Number.isInteger(args.from_date)) errors.push("'from_date' must be an INTEGER UNIX timestamp (seconds), not a date string.");
+    if (!Number.isInteger(args.to_date)) errors.push("'to_date' must be an INTEGER UNIX timestamp (seconds), not a date string.");
+    if (Number.isInteger(args.from_date) && Number.isInteger(args.to_date) && args.to_date <= args.from_date) {
+      errors.push("'to_date' must be strictly greater than 'from_date'.");
+    }
+  }
+
+  if (toolName === 'pauseContract') {
+    if (!args.start_date) errors.push("'start_date' is required (ISO 8601).");
+    if (!args.unpause_extension_policy) errors.push("'unpause_extension_policy' is required: 'extend' or 'overlap'.");
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
 // Helper to map API types to form field types
 function getFieldType(apiType) {
   switch (apiType) {
@@ -1229,38 +1336,62 @@ if (mcpConfig.tools && mcpConfig.tools.length > 0) {
             approvedInArgs: args.__userContext?.approved
           });
           
-          // Check if this tool needs approval and hasn't been approved yet
+          // Validate args BEFORE the approval gate so users do not approve broken calls.
+          const earlyArgValidation = validateToolArgs(tool.name, args);
+          if (!earlyArgValidation.valid) {
+            logger.error(`[${tool.name}] Tool execution blocked due to invalid arguments (pre-approval):`, earlyArgValidation.errors);
+            tokenUsageStatus = 'blocked';
+            tokenUsageReason = `invalid_args: ${earlyArgValidation.errors.join('; ')}`;
+            const errorJson = {
+              type: 'invalid_arguments',
+              toolName: tool.name,
+              errors: earlyArgValidation.errors
+            };
+            return {
+              content: [
+                { type: "text", text: JSON.stringify(errorJson, null, 2) },
+                {
+                  type: "text",
+                  text: `ACTION_NOT_EXECUTED — INVALID_ARGUMENTS\n\nTool '${tool.name}' was NOT executed because the supplied arguments are invalid or incomplete:\n\n` +
+                        earlyArgValidation.errors.map((e, i) => `${i + 1}. ${e}`).join('\n') +
+                        `\n\nFix the arguments and call again. Do NOT report success to the user.`
+                }
+              ],
+              isError: true
+            };
+          }
+
+          // Check if this tool needs approval and hasn't been approved yet.
+          // checkNeedsApproval() validates the one-time token from
+          // __userContext.approval.token; bare `approved: true` is not trusted.
           const needsApproval = checkNeedsApproval(tool, args);
           const userContext = args.__userContext;
-          const isApproved = userContext?.approved === true;
-          
+
           logger.info(`[${tool.name}] Approval check:`, {
             needsApproval,
-            isApproved,
             hasUserContext: !!userContext,
             userContextKeys: userContext ? Object.keys(userContext) : [],
-            approvedValue: userContext?.approved,
-            fullUserContext: JSON.stringify(userContext, null, 2)
+            hasApprovalBlock: !!(userContext && userContext.approval),
+            hasToken: !!(userContext && userContext.approval && userContext.approval.token)
           });
-          
-          if (needsApproval && !isApproved) {
+
+          if (needsApproval) {
             logger.info(`[${tool.name}] Tool requires approval, generating approval request`);
             const approvalRequest = generateApprovalRequest(tool, args);
-            
             return {
-              content: [{
-                type: "text",
-                text: JSON.stringify(approvalRequest, null, 2)
-              }],
+              content: [
+                { type: "text", text: JSON.stringify(approvalRequest, null, 2) },
+                {
+                  type: "text",
+                  text: `ACTION_NOT_EXECUTED — APPROVAL_REQUIRED\n\n` +
+                        `Tool '${tool.name}' was NOT executed. The host must render an approval dialog from the JSON payload above and re-invoke this tool with __userContext.approval = {approved: true, token: '<approvalToken from payload>'} to actually perform the action. The token is single-use and expires in ${Math.floor(APPROVAL_TOKEN_TTL_MS / 1000)}s. Do NOT fabricate the token. Do NOT report success to the user; surface the dialog instead.`
+                }
+              ],
               isApprovalRequired: true,
               approvalRequest: approvalRequest
             };
           }
           
-          if (needsApproval && isApproved) {
-            logger.info(`[${tool.name}] Tool was approved, executing actual API call`);
-          }
-          
           // Extract user context for token usage tracking
           const userId = userContext?.userId || 'unknown';
           const chatId = userContext?.chatId || null; // Use NULL for direct MCP calls
@@ -1311,6 +1442,8 @@ if (mcpConfig.tools && mcpConfig.tools.length > 0) {
             };
           }
           
+          // (validateToolArgs already ran pre-approval; no duplicate check here.)
+
           // Use adjusted args with enforced limits
           const adjustedArgs = limitsValidation.adjustedArgs;