askell-mcp 0.1.2 → 0.2.0

package/README.md

@@ -8,7 +8,7 @@ Connect it to Cursor, Claude Desktop, or any MCP client to discover Askell endpo
 
 - An [Askell](https://askell.is) account and **secret API key** (from the Askell dashboard)
 - One of:
-  - [Bun](https://bun.sh) ≥ 1.3.14 (for `bunx`), or
+  - [Bun](https://bun.sh) ≥ 1.4.0 (for `bunx`), or
   - a prebuilt binary from [Releases](https://github.com/Neschadin/askell-mcp/releases) (no Bun needed)
 
 ## Quick start
@@ -99,6 +99,7 @@ Typical agent workflow:
 
 - **v1** — legacy paths like `/customers/`, `/subscriptions/` (no `/v2` prefix)
 - **v2** — current model: catalogs, quotes, checkouts, contracts, billing runs under `/v2/`
+- **v2 coupons** — `GET/POST /v2/subscription-contracts/{id}/discount|apply-code|remove-discount` (one active coupon). Quotes take `promotion_code`. Not the v1 `discount` 0–100 field.
 - Paths use **trailing slashes**
 - Prefer **v2** for new integrations; v1 remains for existing ones
 - Docs: [docs.askell.is](https://docs.askell.is/) · OpenAPI: [v1](https://askell.is/api/swagger/swagger.json) · [v2](https://askell.is/api/swagger/v2/swagger.json)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "mcp.json.example"
   ],
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   },
   "publishConfig": {
     "access": "public",
@@ -47,19 +47,20 @@
     "test": "bun test",
     "smoke": "bun run scripts/smoke-test.ts",
     "test:integration": "bun run scripts/integration-test.ts",
+    "eval:tools": "bun run scripts/eval-tools.ts",
     "typecheck": "tsc --noEmit",
     "inspect": "bunx @modelcontextprotocol/inspector bun bin/askell-mcp",
     "sync-specs": "bun run scripts/sync-specs.ts",
     "prepack": "bun test && bun run typecheck",
-    "build": "bun build --compile --minify src/index.ts --outfile dist/askell-mcp",
-    "build:linux-x64": "bun build --compile --minify --target=bun-linux-x64 src/index.ts --outfile dist/askell-mcp-linux-x64",
-    "build:linux-arm64": "bun build --compile --minify --target=bun-linux-arm64 src/index.ts --outfile dist/askell-mcp-linux-arm64",
-    "build:darwin-arm64": "bun build --compile --minify --target=bun-darwin-arm64 src/index.ts --outfile dist/askell-mcp-darwin-arm64",
-    "build:darwin-x64": "bun build --compile --minify --target=bun-darwin-x64 src/index.ts --outfile dist/askell-mcp-darwin-x64",
+    "build": "bun build --compile --minify --bytecode --format=esm src/index.ts --outfile dist/askell-mcp",
+    "build:linux-x64": "bun build --compile --minify --bytecode --format=esm --target=bun-linux-x64 src/index.ts --outfile dist/askell-mcp-linux-x64",
+    "build:linux-arm64": "bun build --compile --minify --bytecode --format=esm --target=bun-linux-arm64 src/index.ts --outfile dist/askell-mcp-linux-arm64",
+    "build:darwin-arm64": "bun build --compile --minify --bytecode --format=esm --target=bun-darwin-arm64 src/index.ts --outfile dist/askell-mcp-darwin-arm64",
+    "build:darwin-x64": "bun build --compile --minify --bytecode --format=esm --target=bun-darwin-x64 src/index.ts --outfile dist/askell-mcp-darwin-x64",
     "build:all": "bun run build && bun run build:linux-x64 && bun run build:linux-arm64 && bun run build:darwin-arm64 && bun run build:darwin-x64"
   },
   "devDependencies": {
-    "@types/bun": "1.3.14",
+    "@types/bun": "1.4.0",
     "typescript": "7.0.2"
   },
   "dependencies": {

package/spec/openapi-v2.json

@@ -1137,6 +1137,161 @@
         ]
       }
     },
+    "/v2/subscription-contracts/{contractId}/apply-code/": {
+      "post": {
+        "tags": [
+          "V2 Subscription Contracts"
+        ],
+        "summary": "Apply a promotion code to a V2 subscription contract",
+        "description": "Validates and redeems a promotion code for the contract, creating an active discount that is applied to subsequent billing runs. A contract can only carry one active discount at a time. Requires a secret key.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/V2ContractId"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "promotion_code"
+                ],
+                "properties": {
+                  "promotion_code": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Promotion code applied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "message": {
+                      "type": "string"
+                    },
+                    "discount": {
+                      "$ref": "#/components/schemas/V2ContractDiscount"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/V2ValidationError"
+          },
+          "404": {
+            "$ref": "#/components/responses/V2NotFound"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
+    },
+    "/v2/subscription-contracts/{contractId}/discount/": {
+      "get": {
+        "tags": [
+          "V2 Subscription Contracts"
+        ],
+        "summary": "Get the active discount for a V2 subscription contract",
+        "description": "Returns the contract's active coupon discount, or null when none is active. Requires a secret key.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/V2ContractId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Active discount",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "discount": {
+                      "allOf": [
+                        {
+                          "$ref": "#/components/schemas/V2ContractDiscount"
+                        }
+                      ],
+                      "nullable": true
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/V2NotFound"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
+    },
+    "/v2/subscription-contracts/{contractId}/remove-discount/": {
+      "post": {
+        "tags": [
+          "V2 Subscription Contracts"
+        ],
+        "summary": "Remove the active discount from a V2 subscription contract",
+        "description": "Ends the contract's active coupon discount. Subsequent billing runs are charged at full price. Requires a secret key.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/V2ContractId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Discount removed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/V2ValidationError"
+          },
+          "404": {
+            "$ref": "#/components/responses/V2NotFound"
+          }
+        },
+        "security": [
+          {
+            "Secret-Api-Key": []
+          }
+        ]
+      }
+    },
     "/v2/checkouts/": {
       "post": {
         "tags": [
@@ -2091,6 +2246,80 @@
           }
         }
       },
+      "V2ContractDiscount": {
+        "type": "object",
+        "description": "An applied coupon discount on a V2 subscription contract.",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "coupon": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string",
+                "nullable": true
+              },
+              "amount_off": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true
+              },
+              "currency": {
+                "type": "string",
+                "nullable": true
+              },
+              "percent_off": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true
+              },
+              "duration": {
+                "type": "string",
+                "enum": [
+                  "forever",
+                  "once",
+                  "repeating"
+                ]
+              },
+              "duration_in_months": {
+                "type": "integer",
+                "nullable": true
+              },
+              "discount_display": {
+                "type": "string"
+              }
+            }
+          },
+          "promotion_code": {
+            "type": "object",
+            "nullable": true,
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "code": {
+                "type": "string"
+              }
+            }
+          },
+          "start": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "end": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "is_active": {
+            "type": "boolean"
+          }
+        }
+      },
       "V2SubscriptionOfferQuoteCreate": {
         "type": "object",
         "properties": {
@@ -2135,6 +2364,11 @@
             "items": {
               "$ref": "#/components/schemas/V2AdditionalBundle"
             }
+          },
+          "promotion_code": {
+            "type": "string",
+            "nullable": true,
+            "description": "Optional promotion code. When valid, the resulting discount is folded into the offer totals; on contract creation the code is redeemed and a discount is attached to the contract."
           }
         }
       },
@@ -2405,58 +2639,14 @@
           }
         }
       },
-      "V2SubscriptionContractProrationPreview": {
+      "V2SubscriptionContractChangeCommon": {
         "type": "object",
         "properties": {
-          "operation": {
-            "type": "string",
-            "enum": [
-              "add_item",
-              "remove_item",
-              "update_item",
-              "pause",
-              "resume",
-              "cancel",
-              "restart"
-            ],
-            "default": "update_item"
-          },
-          "contract_item": {
-            "type": "integer"
-          },
-          "price": {
-            "type": "integer",
-            "nullable": true
-          },
-          "quantity": {
-            "type": "integer",
-            "nullable": true
-          },
-          "discount_percent": {
-            "type": "string",
-            "format": "decimal",
-            "nullable": true
-          },
           "effective_at": {
             "type": "string",
             "format": "date-time",
             "nullable": true
           },
-          "start_date": {
-            "type": "string",
-            "format": "date",
-            "nullable": true
-          },
-          "end_date": {
-            "type": "string",
-            "format": "date",
-            "nullable": true
-          },
-          "pause_end_at": {
-            "type": "string",
-            "format": "date-time",
-            "nullable": true
-          },
           "proration_behavior": {
             "type": "string",
             "enum": [
@@ -2486,13 +2676,86 @@
           }
         }
       },
+      "V2SubscriptionContractProrationPreview": {
+        "description": "Polymorphic preview request. Fields beyond the common ones are operation-specific; fields not supported by the selected operation are rejected with a 400 validation error.",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/V2SubscriptionContractChangeCommon"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "operation": {
+                "type": "string",
+                "enum": [
+                  "add_item",
+                  "remove_item",
+                  "update_item",
+                  "pause",
+                  "resume",
+                  "cancel",
+                  "restart"
+                ],
+                "default": "update_item"
+              },
+              "contract_item": {
+                "type": "integer",
+                "description": "Required for update_item and remove_item."
+              },
+              "price": {
+                "type": "integer",
+                "nullable": true,
+                "description": "Only applies to add_item and update_item. Required for add_item."
+              },
+              "quantity": {
+                "type": "integer",
+                "nullable": true,
+                "description": "Only applies to add_item and update_item."
+              },
+              "discount_percent": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true,
+                "description": "Only applies to add_item and update_item."
+              },
+              "unit_amount_override": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true,
+                "description": "Fixed per-unit amount for the item, used instead of the catalog price. Only applies to add_item and update_item. On update_item, omitting the field keeps the item's current override while an explicit null clears it so the item reverts to the catalog price."
+              },
+              "start_date": {
+                "type": "string",
+                "format": "date",
+                "nullable": true,
+                "description": "Only applies to pause."
+              },
+              "end_date": {
+                "type": "string",
+                "format": "date",
+                "nullable": true,
+                "description": "Only applies to pause."
+              },
+              "pause_end_at": {
+                "type": "string",
+                "format": "date-time",
+                "nullable": true,
+                "description": "Only applies to pause."
+              }
+            }
+          }
+        ]
+      },
       "V2SubscriptionContractItemAdd": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/V2SubscriptionContractProrationPreview"
+            "$ref": "#/components/schemas/V2SubscriptionContractChangeCommon"
           },
           {
             "type": "object",
+            "required": [
+              "price"
+            ],
             "properties": {
               "operation": {
                 "type": "string",
@@ -2501,6 +2764,24 @@
                 ],
                 "default": "add_item"
               },
+              "price": {
+                "type": "integer"
+              },
+              "quantity": {
+                "type": "integer",
+                "nullable": true
+              },
+              "discount_percent": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true
+              },
+              "unit_amount_override": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true,
+                "description": "Fixed per-unit amount for the new item, used instead of the catalog price."
+              },
               "idempotency_key": {
                 "type": "string",
                 "nullable": true
@@ -2515,7 +2796,7 @@
       "V2SubscriptionContractItemRemove": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/V2SubscriptionContractProrationPreview"
+            "$ref": "#/components/schemas/V2SubscriptionContractChangeCommon"
           },
           {
             "type": "object",
@@ -2530,6 +2811,9 @@
                 ],
                 "default": "remove_item"
               },
+              "contract_item": {
+                "type": "integer"
+              },
               "idempotency_key": {
                 "type": "string",
                 "nullable": true
@@ -2544,7 +2828,7 @@
       "V2SubscriptionContractItemUpdate": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/V2SubscriptionContractProrationPreview"
+            "$ref": "#/components/schemas/V2SubscriptionContractChangeCommon"
           },
           {
             "type": "object",
@@ -2552,6 +2836,35 @@
               "contract_item"
             ],
             "properties": {
+              "operation": {
+                "type": "string",
+                "enum": [
+                  "update_item"
+                ],
+                "default": "update_item"
+              },
+              "contract_item": {
+                "type": "integer"
+              },
+              "price": {
+                "type": "integer",
+                "nullable": true
+              },
+              "quantity": {
+                "type": "integer",
+                "nullable": true
+              },
+              "discount_percent": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true
+              },
+              "unit_amount_override": {
+                "type": "string",
+                "format": "decimal",
+                "nullable": true,
+                "description": "Fixed per-unit amount for the item, used instead of the catalog price. Omitting the field keeps the item's current override; an explicit null clears it so the item reverts to the catalog price."
+              },
               "idempotency_key": {
                 "type": "string",
                 "nullable": true
@@ -2688,9 +3001,15 @@
             "type": "string",
             "format": "decimal"
           },
+          "discount_amount_due_now": {
+            "type": "string",
+            "format": "decimal",
+            "description": "Contract coupon discount applied to the immediate (invoice_now) charge. Percent-off, non-once coupons only; 0.0000 otherwise."
+          },
           "next_billing_estimate": {
             "type": "string",
-            "format": "decimal"
+            "format": "decimal",
+            "description": "Estimated next recurring charge, net of the contract's active coupon discount."
           },
           "resolved_price_version_ids": {
             "type": "object",
@@ -3537,6 +3856,64 @@
           "billing_schedule_preview": {
             "$ref": "#/components/schemas/V2Metadata"
           },
+          "promotion_code": {
+            "type": "string",
+            "nullable": true,
+            "description": "The promotion code applied to this quote, if any. When set, subtotal_amount, tax_amount, and total_amount already include the discount."
+          },
+          "discount": {
+            "type": "object",
+            "nullable": true,
+            "description": "Discount preview when a promotion code was applied.",
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "coupon_display": {
+                "type": "string"
+              },
+              "duration": {
+                "type": "string",
+                "enum": [
+                  "forever",
+                  "once",
+                  "repeating"
+                ]
+              },
+              "duration_in_months": {
+                "type": "integer",
+                "nullable": true
+              },
+              "skip_trial_period": {
+                "type": "boolean",
+                "description": "When true, the coupon skipped the offer's trial period: the quoted totals bill the first period immediately."
+              },
+              "discount_subtotal_amount": {
+                "type": "string",
+                "format": "decimal"
+              },
+              "discount_tax_amount": {
+                "type": "string",
+                "format": "decimal"
+              },
+              "discount_total_amount": {
+                "type": "string",
+                "format": "decimal"
+              },
+              "original_subtotal_amount": {
+                "type": "string",
+                "format": "decimal"
+              },
+              "original_tax_amount": {
+                "type": "string",
+                "format": "decimal"
+              },
+              "original_total_amount": {
+                "type": "string",
+                "format": "decimal"
+              }
+            }
+          },
           "recurring_items": {
             "type": "array",
             "items": {
@@ -4253,6 +4630,15 @@
           "customer_reference": {
             "type": "string"
           },
+          "discount": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/V2ContractDiscount"
+              }
+            ],
+            "nullable": true,
+            "description": "The active coupon discount on this contract, if any."
+          },
           "state": {
             "type": "string"
           },

package/src/client/response-formatter.ts

@@ -59,7 +59,6 @@ function summarizeListItem(item: unknown): unknown {
     'email',
     'first_name',
     'last_name',
-    'description',
     'currency',
     'amount',
     'total_amount',
@@ -91,6 +90,56 @@ function summarizeListItem(item: unknown): unknown {
   return Object.keys(out).length > 0 ? out : obj;
 }
 
+/** Tight projection for analytical list queries (dates, plan name, customer). */
+function indexListItem(item: unknown): unknown {
+  if (item == null || typeof item !== 'object' || Array.isArray(item)) {
+    return item;
+  }
+
+  const obj = item as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+
+  if ('id' in obj) {
+    out.id = obj.id;
+  }
+
+  if ('start_date' in obj) {
+    out.start_date = obj.start_date;
+  } else if ('created_at' in obj) {
+    out.created_at = obj.created_at;
+  }
+
+  if ('ended_at' in obj && obj.ended_at != null) {
+    out.ended_at = obj.ended_at;
+  }
+
+  const plan = obj.plan;
+  if (typeof plan === 'string' || typeof plan === 'number') {
+    out.plan = plan;
+  } else if (plan && typeof plan === 'object' && 'name' in plan) {
+    out.plan = (plan as { name: unknown }).name;
+  } else if ('name' in obj && typeof obj.name === 'string') {
+    out.name = obj.name;
+  }
+
+  const customerRef =
+    obj.customer_reference ??
+    (obj.customer && typeof obj.customer === 'object'
+      ? ((obj.customer as Record<string, unknown>).customer_reference ??
+        (obj.customer as Record<string, unknown>).reference ??
+        (obj.customer as Record<string, unknown>).id)
+      : undefined);
+  if (customerRef !== undefined) {
+    out.customer_reference = customerRef;
+  }
+
+  if (typeof obj.email === 'string') {
+    out.email = obj.email;
+  }
+
+  return Object.keys(out).length > 0 ? out : summarizeListItem(item);
+}
+
 function serializeListPayload(
   status: number,
   meta: Record<string, unknown>,
@@ -146,6 +195,8 @@ function maxFittingCount(
   return lo;
 }
 
+type CompactedMode = 'none' | 'summary' | 'index';
+
 export function buildBoundedListPayload(input: {
   status: number;
   meta: Record<string, unknown>;
@@ -153,30 +204,42 @@ export function buildBoundedListPayload(input: {
   maxBytes: number;
 }): FormattedResponse {
   const { status, meta, items, maxBytes } = input;
-  const itemCount = items.length;
 
   const attempts: Array<{
     items: unknown[];
     pretty: boolean;
-    compacted: boolean;
+    compactedMode: CompactedMode;
     note?: string;
   }> = [
-    { items, pretty: true, compacted: false },
-    { items, pretty: false, compacted: false },
+    { items, pretty: true, compactedMode: 'none' },
+    { items, pretty: false, compactedMode: 'none' },
     {
       items: items.map(summarizeListItem),
       pretty: false,
-      compacted: true,
+      compactedMode: 'summary',
       note: 'Items summarized to fit responseMaxBytes',
     },
+    {
+      items: items.map(indexListItem),
+      pretty: false,
+      compactedMode: 'index',
+      note: 'Items reduced to an index (id, dates, plan, customer) to fit responseMaxBytes',
+    },
   ];
 
   let fullByteLength = 0;
+  let bestPartial: {
+    text: string;
+    returnedCount: number;
+    compactedMode: CompactedMode;
+    note?: string;
+  } | null = null;
 
   for (const attempt of attempts) {
+    const attemptMeta = compactMeta(meta, attempt.compactedMode, attempt.note);
     const fullText = serializeListPayload(
       status,
-      meta,
+      attemptMeta,
       attempt.items,
       attempt.items.length,
       false,
@@ -195,42 +258,43 @@ export function buildBoundedListPayload(input: {
     const returnedCount = maxFittingCount(
       attempt.items,
       status,
-      {
-        ...meta,
-        ...(attempt.compacted ? { compacted: true, note: attempt.note } : {}),
-      },
+      attemptMeta,
       maxBytes,
       attempt.pretty,
     );
 
-    if (returnedCount > 0) {
-      const text = serializeListPayload(
-        status,
-        {
-          ...meta,
-          ...(attempt.compacted ? { compacted: true, note: attempt.note } : {}),
-        },
-        attempt.items,
+    if (returnedCount > (bestPartial?.returnedCount ?? 0)) {
+      bestPartial = {
+        text: serializeListPayload(
+          status,
+          attemptMeta,
+          attempt.items,
+          returnedCount,
+          true,
+          attempt.pretty,
+        ),
         returnedCount,
-        true,
-        attempt.pretty,
-      );
-
-      return {
-        text,
-        truncated: true,
-        byteLength: fullByteLength,
+        compactedMode: attempt.compactedMode,
+        note: attempt.note,
       };
     }
   }
 
+  if (bestPartial && bestPartial.returnedCount > 0) {
+    return {
+      text: bestPartial.text,
+      truncated: true,
+      byteLength: fullByteLength,
+    };
+  }
+
   const text = serializeListPayload(
     status,
-    {
-      ...meta,
-      compacted: true,
-      note: 'Response too large; returning metadata only',
-    },
+    compactMeta(
+      meta,
+      'index',
+      'Response too large; returning metadata only',
+    ),
     [],
     0,
     true,
@@ -244,6 +308,23 @@ export function buildBoundedListPayload(input: {
   };
 }
 
+function compactMeta(
+  meta: Record<string, unknown>,
+  compactedMode: CompactedMode,
+  note?: string,
+): Record<string, unknown> {
+  if (compactedMode === 'none') {
+    return meta;
+  }
+
+  return {
+    ...meta,
+    compacted: true,
+    compactedMode,
+    ...(note ? { note } : {}),
+  };
+}
+
 export function formatApiResponse(
   status: number,
   headers: Headers,

package/src/config.ts

@@ -1,22 +1,25 @@
 import * as z from 'zod';
 
+const httpUrl = z
+  .url({ protocol: /^https?$/ })
+  .describe('Askell API base URL (default production host)');
+
 export const ConfigSchema = z.object({
-  apiBaseUrl: z
-    .httpUrl()
-    .default('https://askell.is/api')
-    .describe('Askell API base URL (default production host)'),
+  apiBaseUrl: httpUrl.default('https://askell.is/api'),
   secretApiKey: z.string().min(1).describe('Secret (private) API key'),
   publicApiKey: z
     .string()
+    .min(1)
     .optional()
     .describe('Public API key for temporary payment method endpoints'),
-  responseMaxBytes: z
+  responseMaxBytes: z.coerce
+    .number()
     .int()
     .positive()
     .default(64_000)
     .describe('Max response body size returned to the model'),
   requireMutationApproval: z
-    .boolean()
+    .union([z.boolean(), z.stringbool()])
     .default(true)
     .describe('Require operator confirmation before mutating requests'),
 });
@@ -45,17 +48,6 @@ Set ASKELL_PRIVATE_API_KEY (or ASKELL_SECRET_API_KEY), optionally ASKELL_PUBLIC_
       }
     }`;
 
-function parseEnvFlag(
-  value: string | undefined,
-  defaultValue: boolean,
-): boolean {
-  if (value === undefined) {
-    return defaultValue;
-  }
-
-  return !['0', 'false', 'no', 'off'].includes(value.toLowerCase());
-}
-
 function loadConfigFromEnv(): unknown {
   const env = Bun.env;
   const secretApiKey = env.ASKELL_PRIVATE_API_KEY ?? env.ASKELL_SECRET_API_KEY;
@@ -74,11 +66,9 @@ function loadConfigFromEnv(): unknown {
     ...(env.ASKELL_PUBLIC_API_KEY
       ? { publicApiKey: env.ASKELL_PUBLIC_API_KEY }
       : {}),
-    ...(responseMaxBytes ? { responseMaxBytes: Number(responseMaxBytes) } : {}),
+    ...(responseMaxBytes ? { responseMaxBytes } : {}),
     ...(requireMutationApproval !== undefined
-      ? {
-          requireMutationApproval: parseEnvFlag(requireMutationApproval, true),
-        }
+      ? { requireMutationApproval }
       : {}),
   };
 }

package/src/openapi/registry.ts

@@ -69,20 +69,30 @@ function resolveParameters(
   }
 
   return parameters.map((parameter) => {
+    let source: OpenApiParameter = parameter;
+
     if ('$ref' in parameter && typeof parameter.$ref === 'string') {
       const resolved = resolveRef(doc, parameter.$ref);
       if (resolved && typeof resolved === 'object') {
-        const param = resolved as OpenApiParameter;
-        return {
-          ...param,
-          schema: resolveSchema(doc, param.schema),
-        };
+        source = resolved as OpenApiParameter;
       }
     }
 
+    // Pick known fields only — OpenAPI params often include style/explode/example,
+    // which MCP outputSchema rejects (additionalProperties: false).
     return {
-      ...parameter,
-      schema: resolveSchema(doc, parameter.schema),
+      ...(source.name !== undefined ? { name: source.name } : {}),
+      ...(source.in !== undefined ? { in: source.in } : {}),
+      ...(source.required !== undefined ? { required: source.required } : {}),
+      ...(source.description !== undefined
+        ? { description: source.description }
+        : {}),
+      ...(source.schema !== undefined
+        ? { schema: resolveSchema(doc, source.schema) }
+        : {}),
+      ...(source.$ref !== undefined && source.name === undefined
+        ? { $ref: source.$ref }
+        : {}),
     };
   });
 }

package/src/server.ts

@@ -26,6 +26,11 @@ API layout:
 - V2 list endpoints paginate only when page_size is provided (default 10, max 1000).
 - GET /v2/customer-entitlements/ requires customer_reference query param.
 
+V2 discounts (coupons / promotion codes) — not the same as v1:
+- v2 contracts: one active coupon at a time. GET /v2/subscription-contracts/{id}/discount/ (also nested as contract.discount). Apply with POST .../apply-code/ {promotion_code}. Remove with POST .../remove-discount/.
+- Quotes: pass promotion_code on POST /v2/subscription-offer-quotes/; totals already include the discount when set.
+- v1 Subscription.discount is a 0-100 percent override on a PlanVariant subscription. Do not send it to v2 contract endpoints.
+
 V2 checkout notes:
 - checkout_url on V2 checkouts points to the API object URL, not a browser payment page.
 - Embedded checkout uses POST /v2/checkout-sessions/ plus browser session-token sub-paths (see docs, not all in OpenAPI).
@@ -36,7 +41,7 @@ Auth:
 
 Safety:
 - Mutating askell_call requests require operator approval when requireMutationApproval is enabled.
-- Large list responses may be truncated or summarized to fit responseMaxBytes; check meta.truncatedByMaxBytes and meta.compacted.
+- Large list responses are compacted (index of id/dates/plan/customer) to fit responseMaxBytes before dropping rows; check meta.truncatedByMaxBytes, meta.compacted, and meta.compactedMode.
 
 Resources:
 - askell://spec/v1 and askell://spec/v2 — bundled OpenAPI

package/src/tools/analysis.ts

@@ -36,12 +36,23 @@ export function registerAnalysisTools(
     {
       title: 'Paginate Askell list endpoint',
       description:
-        'Fetch all pages from a paginated Askell list endpoint (v1/v2). Follows `next` links until exhausted or maxPages is reached. Large results are summarized to fit responseMaxBytes — check meta.truncatedByMaxBytes and meta.compacted in the response.',
+        'Fetch all pages from a paginated Askell list endpoint (v1/v2). Follows `next` links until exhausted or maxPages is reached. When the full payload exceeds responseMaxBytes, items are compacted (summary, then an index of id/dates/plan/customer) so rows are kept — dropping rows is last resort. Check meta.truncatedByMaxBytes, meta.compacted, and meta.compactedMode.',
       inputSchema: z.object({
         path: z.string().describe('List endpoint path, e.g. /subscriptions/'),
-        query: z.record(z.string(), z.unknown()).optional(),
-        apiKeyKind: z.enum(['secret', 'public']).default('secret'),
-        maxPages: z.int().positive().max(100).default(20),
+        query: z
+          .record(z.string(), z.json())
+          .optional()
+          .describe('Query string parameters forwarded to the list endpoint'),
+        apiKeyKind: z
+          .enum(['secret', 'public'])
+          .default('secret')
+          .describe('Which configured API key to use'),
+        maxPages: z
+          .int()
+          .positive()
+          .max(100)
+          .default(20)
+          .describe('Stop after this many pages (default 20, max 100)'),
       }),
       annotations: {
         readOnlyHint: true,
@@ -130,10 +141,17 @@ export function registerAnalysisTools(
     {
       title: 'Subscription contract overview (v2)',
       description:
-        'Fetch a v2 subscription contract and recent billing runs filtered by contract id.',
+        'Fetch a v2 subscription contract and recent billing runs filtered by contract id. The contract payload includes `discount` (active coupon) when one is applied.',
       inputSchema: z.object({
-        contractId: z.union([z.string(), z.number()]),
-        billingRunLimit: z.int().positive().max(50).default(10),
+        contractId: z
+          .union([z.string().min(1), z.int()])
+          .describe('V2 subscription contract id'),
+        billingRunLimit: z
+          .int()
+          .positive()
+          .max(50)
+          .default(10)
+          .describe('Max billing runs to include (page_size)'),
       }),
       annotations: {
         readOnlyHint: true,
@@ -192,8 +210,13 @@ export function registerAnalysisTools(
       description:
         'Fetch a billing run by id with optional related contract context for failure analysis.',
       inputSchema: z.object({
-        billingRunId: z.union([z.string(), z.number()]),
-        includeContract: z.boolean().default(true),
+        billingRunId: z
+          .union([z.string().min(1), z.int()])
+          .describe('V2 billing run id'),
+        includeContract: z
+          .boolean()
+          .default(true)
+          .describe('Also fetch the related subscription contract when the run has a contract id'),
       }),
       annotations: {
         readOnlyHint: true,
@@ -257,7 +280,12 @@ export function registerAnalysisTools(
       description:
         'List Askell webhook endpoints configured for the account (management API only).',
       inputSchema: z.object({
-        page_size: z.int().positive().max(1000).optional(),
+        page_size: z
+          .int()
+          .positive()
+          .max(1000)
+          .optional()
+          .describe('Page size for GET /webhooks/ (Askell default 10, max 1000)'),
       }),
       annotations: {
         readOnlyHint: true,

package/src/tools/call.ts

@@ -25,10 +25,10 @@ const callInputSchema = z.object({
     .string()
     .describe('API path relative to apiBaseUrl, e.g. /v2/subscription-contracts/'),
   query: z
-    .record(z.string(), z.unknown())
+    .record(z.string(), z.json())
     .optional()
     .describe('Query string parameters'),
-  body: z.unknown().optional().describe('JSON request body'),
+  body: z.json().optional().describe('JSON request body'),
   apiKeyKind: z
     .enum(['secret', 'public'])
     .default('secret')

package/src/tools/discovery.ts

@@ -77,11 +77,11 @@ const openApiParameterSchema = z.object({
   in: z.enum(['query', 'path', 'header', 'cookie']).optional(),
   required: z.boolean().optional(),
   description: z.string().optional(),
-  schema: z.unknown().optional(),
+  schema: z.json().optional(),
   $ref: z.string().optional(),
 });
 
-const operationDetailSchema = z.object({
+export const operationDetailSchema = z.object({
   id: z.string(),
   apiVersion: apiVersionSchema,
   method: httpMethodSchema,
@@ -95,7 +95,7 @@ const operationDetailSchema = z.object({
       required: z.boolean().optional(),
       description: z.string().optional(),
       contentTypes: z.array(z.string()),
-      schema: z.unknown().optional(),
+      schema: z.json().optional(),
     })
     .optional(),
   apiKeyKind: apiKeyKindSchema,
@@ -171,9 +171,13 @@ export function registerDiscoveryTools(server: McpServer): void {
         };
       }
 
+      // Strip OpenAPI extras (style/explode/…) so structuredContent matches
+      // the output JSON Schema (additionalProperties: false).
+      const payload = operationDetailSchema.parse(operation);
+
       return {
-        content: [{ type: 'text', text: JSON.stringify(operation, null, 2) }],
-        structuredContent: operation,
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
       };
     },
   );