askell-mcp 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
   "license": "MIT",
@@ -65,6 +65,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
-    "zod": "4.4.3"
+    "zod": "4.5.4"
   }
 }

package/spec/openapi-v1.json

@@ -8,7 +8,8 @@
       "name": "Documentation",
       "url": "https://docs.askell.is"
     },
-    "version": "1.0.0"
+    "version": "1.0.0",
+    "x-askell-mcp-patched": "v1-overlay-1"
   },
   "servers": [
     {
@@ -52,10 +53,6 @@
       "name": "Webhooks",
       "description": "Management of webhooks. Requires secret api key."
     },
-    {
-      "name": "Webhook calls",
-      "description": "Webhook calls from Áskell to your system."
-    },
     {
       "name": "Transaction",
       "description": "Transaction operations, requires secret api key."
@@ -339,7 +336,14 @@
         },
         "responses": {
           "201": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Customer"
+                }
+              }
+            }
           },
           "400": {
             "description": "Invalid status value",
@@ -506,7 +510,14 @@
         ],
         "responses": {
           "200": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Customer"
+                }
+              }
+            }
           },
           "404": {
             "description": "Not found"
@@ -572,7 +583,14 @@
         ],
         "responses": {
           "200": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Customer"
+                }
+              }
+            }
           },
           "404": {
             "description": "Not found"
@@ -1367,23 +1385,6 @@
         ]
       }
     },
-    "/your-webhook-url/": {
-      "post": {
-        "tags": [
-          "Webhook calls"
-        ],
-        "summary": "Called when subscription changed or renewed",
-        "description": "We recommend that you verify all calls from us to your webhook endpoints. We sign each request with the `Hook-HMAC` header. The value is a HMAC digest derived from the body of the request and a secret key only known by the API and you. We also supply the type of event in the `Hook-Event` header.\n\nHere is a sample implementation in Python. This process is very similar to the one Shopify uses so more information can possibly be gleaned from their [documentation](https://shopify.dev/tutorials/manage-webhooks#verify-webhook).\n```\nimport base64\nimport hmac\nimport hashlib\n\nWEBHOOK_SECRET = \"Your webhook secret\".encode()\nWEBHOOK_DIGEST_TYPE = 'sha512'\n\ndef verify(hmac_header, digest_method, secret, message):\n   digestmod = getattr(hashlib, digest_method)\n   signed = base64.b64encode(\n       hmac.new(secret, message, digestmod).digest(),\n   ).strip()\n   return hmac.compare_digest(signed, hmac_header)\n\n# your view function\ndef handle_webhook(request):\n   # The signature\n   digest = request.META.get('HTTP_HOOK_HMAC').encode()\n   # The name of the webhook event\n   event = request.META.get('HTTP_HOOK_EVENT').encode()\n\n   body = request.body\n   if verify(digest, WEBHOOK_DIGEST_TYPE, WEBHOOK_SECRET, body):\n       payload = json.loads(body)\n       # ... the rest of your code here```\n",
-        "requestBody": {
-          "$ref": "#/components/requestBodies/SubscriptionMultiLite"
-        },
-        "responses": {
-          "200": {
-            "description": "Successful operation"
-          }
-        }
-      }
-    },
     "/webhooks/": {
       "get": {
         "tags": [
@@ -1423,7 +1424,14 @@
         },
         "responses": {
           "201": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Webhook"
+                }
+              }
+            }
           },
           "400": {
             "description": "Invalid status value",
@@ -1521,7 +1529,14 @@
         },
         "responses": {
           "200": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Webhook"
+                }
+              }
+            }
           },
           "400": {
             "description": "Invalid status value",
@@ -1964,27 +1979,94 @@
         }
       },
       "Customer": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/CustomerCreate"
+        "type": "object",
+        "required": [
+          "id",
+          "first_name",
+          "last_name",
+          "email",
+          "customer_reference",
+          "phone",
+          "delivery_name",
+          "address_1",
+          "address_2",
+          "address_3",
+          "zip_code",
+          "city",
+          "country",
+          "payment_method",
+          "address"
+        ],
+        "properties": {
+          "id": {
+            "type": "integer",
+            "format": "int64"
           },
-          {
-            "type": "object",
-            "properties": {
-              "id": {
-                "type": "integer",
-                "format": "int64",
-                "example": 1
-              },
-              "payment_method": {
-                "type": "array",
-                "items": {
-                  "$ref": "#/components/schemas/PaymentMethod"
-                }
-              }
+          "first_name": {
+            "type": "string",
+            "maxLength": 128
+          },
+          "last_name": {
+            "type": "string",
+            "maxLength": 128
+          },
+          "email": {
+            "type": "string",
+            "nullable": true,
+            "maxLength": 254
+          },
+          "phone": {
+            "type": "string",
+            "nullable": true,
+            "maxLength": 32
+          },
+          "customer_reference": {
+            "type": "string",
+            "maxLength": 256
+          },
+          "delivery_name": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_1": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_2": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_3": {
+            "type": "string",
+            "nullable": true
+          },
+          "zip_code": {
+            "type": "string",
+            "nullable": true
+          },
+          "city": {
+            "type": "string",
+            "nullable": true
+          },
+          "country": {
+            "type": "string",
+            "nullable": true
+          },
+          "payment_method": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PaymentMethod"
             }
+          },
+          "address": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/CustomerAddress"
+              }
+            ],
+            "nullable": true
           }
-        ]
+        }
       },
       "CustomerPaginated": {
         "type": "object",
@@ -2593,6 +2675,48 @@
             "example": "tokencreated"
           }
         }
+      },
+      "CustomerAddress": {
+        "type": "object",
+        "required": [
+          "delivery_name",
+          "address_1",
+          "address_2",
+          "address_3",
+          "zip_code",
+          "city",
+          "country"
+        ],
+        "properties": {
+          "delivery_name": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_1": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_2": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_3": {
+            "type": "string",
+            "nullable": true
+          },
+          "zip_code": {
+            "type": "string",
+            "nullable": true
+          },
+          "city": {
+            "type": "string",
+            "nullable": true
+          },
+          "country": {
+            "type": "string",
+            "nullable": true
+          }
+        }
       }
     },
     "requestBodies": {
@@ -2780,4 +2904,4 @@
       }
     }
   }
-}
+}

package/src/openapi/patch-v1.ts

@@ -0,0 +1,238 @@
+/**
+ * Overlay for Askell OpenAPI v1. Upstream swagger is wrong in a few places;
+ * this is the same transform as askell_client_v1 `patchAskellSpec` (without Orval).
+ *
+ * Idempotent: safe to run on an already-patched document.
+ */
+
+type JsonSchema = Record<string, unknown>;
+type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+
+type OpenApiResponse = {
+  description?: string;
+  content?: Record<string, { schema?: JsonSchema }>;
+  [key: string]: unknown;
+};
+
+type OpenApiOperation = {
+  tags?: string[];
+  responses?: Record<string, OpenApiResponse>;
+  [key: string]: unknown;
+};
+
+type OpenApiPathItem = Partial<Record<HttpMethod, OpenApiOperation>> & {
+  [key: string]: unknown;
+};
+
+type OpenApiDocument = {
+  info?: Record<string, unknown>;
+  tags?: Array<{ name: string; description?: string }>;
+  paths?: Record<string, OpenApiPathItem>;
+  components?: {
+    schemas?: Record<string, JsonSchema>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+};
+
+export const ASKELL_V1_PATCH = 'v1-overlay-1';
+export const WEBHOOK_CALLS_TAG = 'Webhook calls';
+
+/** Success bodies missing from swagger `content` (DELETE 204 stays empty). */
+const RESPONSE_BODIES = [
+  ['/customers/', 'post', '201', 'Customer'],
+  ['/customers/{customerReference}/', 'put', '200', 'Customer'],
+  ['/customers/{customerReference}/', 'patch', '200', 'Customer'],
+  ['/webhooks/', 'post', '201', 'Webhook'],
+  ['/webhooks/{id}/', 'patch', '200', 'Webhook'],
+] as const satisfies ReadonlyArray<
+  readonly [string, HttpMethod, string, string]
+>;
+
+const HTTP_METHODS = [
+  'get',
+  'post',
+  'put',
+  'patch',
+  'delete',
+  'head',
+] as const;
+
+const nullableString = (maxLength?: number): JsonSchema => ({
+  type: 'string',
+  nullable: true,
+  ...(maxLength === undefined ? {} : { maxLength }),
+});
+
+/** Flattened + nested address as returned by GET /customers/ and customer.* webhooks. */
+const CUSTOMER_ADDRESS_SCHEMA: JsonSchema = {
+  type: 'object',
+  required: [
+    'delivery_name',
+    'address_1',
+    'address_2',
+    'address_3',
+    'zip_code',
+    'city',
+    'country',
+  ],
+  properties: {
+    delivery_name: nullableString(),
+    address_1: nullableString(),
+    address_2: nullableString(),
+    address_3: nullableString(),
+    zip_code: nullableString(),
+    city: nullableString(),
+    country: nullableString(),
+  },
+};
+
+/**
+ * Askell swagger reuses CustomerCreate (write) as the GET model via allOf.
+ * Live GET / webhooks return extra address fields, null emails/phones, and a
+ * required numeric id. Keep CustomerCreate as the POST body.
+ */
+const CUSTOMER_READ_SCHEMA: JsonSchema = {
+  type: 'object',
+  required: [
+    'id',
+    'first_name',
+    'last_name',
+    'email',
+    'customer_reference',
+    'phone',
+    'delivery_name',
+    'address_1',
+    'address_2',
+    'address_3',
+    'zip_code',
+    'city',
+    'country',
+    'payment_method',
+    'address',
+  ],
+  properties: {
+    id: { type: 'integer', format: 'int64' },
+    first_name: { type: 'string', maxLength: 128 },
+    last_name: { type: 'string', maxLength: 128 },
+    email: nullableString(254),
+    phone: nullableString(32),
+    customer_reference: { type: 'string', maxLength: 256 },
+    delivery_name: nullableString(),
+    address_1: nullableString(),
+    address_2: nullableString(),
+    address_3: nullableString(),
+    zip_code: nullableString(),
+    city: nullableString(),
+    country: nullableString(),
+    payment_method: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/PaymentMethod' },
+    },
+    address: {
+      allOf: [{ $ref: '#/components/schemas/CustomerAddress' }],
+      nullable: true,
+    },
+  },
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function dropWebhookCallOperations(doc: OpenApiDocument): void {
+  const paths = doc.paths;
+  if (!paths) {
+    return;
+  }
+
+  for (const path of Object.keys(paths)) {
+    const pathItem = paths[path];
+    if (!pathItem) {
+      continue;
+    }
+
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method as HttpMethod];
+      if (operation?.tags?.includes(WEBHOOK_CALLS_TAG)) {
+        delete pathItem[method as HttpMethod];
+      }
+    }
+
+    const remaining = HTTP_METHODS.some(
+      (method) => pathItem[method as HttpMethod] != null,
+    );
+    if (!remaining) {
+      delete paths[path];
+    }
+  }
+
+  if (doc.tags) {
+    doc.tags = doc.tags.filter((tag) => tag.name !== WEBHOOK_CALLS_TAG);
+  }
+}
+
+function ensureResponseBody(
+  doc: OpenApiDocument,
+  path: string,
+  method: HttpMethod,
+  status: string,
+  schemaName: string,
+): void {
+  const pathItem = doc.paths?.[path];
+  const operation = pathItem?.[method];
+  const response = operation?.responses?.[status];
+  const label = `${method.toUpperCase()} ${path} ${status}`;
+
+  if (!pathItem || !operation || !response) {
+    throw new Error(`Askell spec missing ${label}`);
+  }
+
+  if (response.content?.['application/json']?.schema) {
+    return;
+  }
+
+  response.content = {
+    ...response.content,
+    'application/json': {
+      schema: { $ref: `#/components/schemas/${schemaName}` },
+    },
+  };
+}
+
+export function patchAskellV1Spec(spec: unknown): OpenApiDocument {
+  if (!isRecord(spec)) {
+    throw new Error('Askell v1 spec is not an object');
+  }
+
+  const doc = structuredClone(spec) as OpenApiDocument;
+  const schemas = doc.components?.schemas;
+  if (!schemas?.Customer) {
+    throw new Error('Askell spec missing components.schemas.Customer');
+  }
+  if (!schemas.Webhook) {
+    throw new Error('Askell spec missing components.schemas.Webhook');
+  }
+
+  dropWebhookCallOperations(doc);
+
+  doc.components = {
+    ...doc.components,
+    schemas: {
+      ...schemas,
+      CustomerAddress: CUSTOMER_ADDRESS_SCHEMA,
+      Customer: CUSTOMER_READ_SCHEMA,
+    },
+  };
+
+  for (const [path, method, status, schemaName] of RESPONSE_BODIES) {
+    ensureResponseBody(doc, path, method, status, schemaName);
+  }
+
+  doc.info = {
+    ...doc.info,
+    'x-askell-mcp-patched': ASKELL_V1_PATCH,
+  };
+
+  return doc;
+}

package/src/resources/register.ts

@@ -11,11 +11,11 @@ Headers:
 - Hook-Event: event type (\`subscription.renewed\`, \`payment.changed\`, or a family wildcard \`subscription.*\`)
 - Hook-API-Version: \`v1\` for plan/subscription/customer/payment/checkout, \`v2\` for subscription_contract / billing_run
 
-## Body shape (OpenAPI is wrong here)
+## Body shape (not in OpenAPI)
 
 JSON body **is the event object**. It is **not** \`{ event, data }\`.
 
-Ignore \`POST /your-webhook-url/\` in the bundled v1 spec — its requestBody (\`SubscriptionMultiLite\`: \`{ customer, subscriptions[] }\`) does not match live webhooks.
+Upstream swagger used to document a dummy \`POST /your-webhook-url/\` with \`SubscriptionMultiLite\` (\`{ customer, subscriptions[] }\`). \`sync-specs\` strips that path. Inbound payloads are still undocumented in OpenAPI — this resource is the overlay.
 
 Rare historical payloads used \`{ event, data, ref?, sender? }\`. If both \`event\` and \`data\` are objects, use \`data\`.
 

package/src/server.ts

@@ -46,13 +46,13 @@ Safety:
 
 Resources:
 - askell://spec/v1 and askell://spec/v2 — bundled OpenAPI
-- askell://docs/webhook-events — inbound webhook payloads (ignore OpenAPI /your-webhook-url/), HMAC-SHA512, /webhooks/ hmac_secret`;
+- askell://docs/webhook-events — inbound webhook payloads (not in OpenAPI; dummy /your-webhook-url/ is stripped on sync), HMAC-SHA512, /webhooks/ hmac_secret`;
 
 export function createServer(config: AppConfig): McpServer {
   const server = new McpServer(
     {
       name: 'askell-mcp',
-      version: '0.3.0',
+      version: '0.3.1',
     },
     {
       instructions: SERVER_INSTRUCTIONS,