askell-mcp 0.1.0

package/src/openapi/registry.ts

@@ -0,0 +1,257 @@
+import v1Spec from '../../spec/openapi-v1.json';
+import v2Spec from '../../spec/openapi-v2.json';
+
+import type {
+  ApiKeyKind,
+  ApiOperation,
+  ApiVersion,
+  HttpMethod,
+  OpenApiDocument,
+  OpenApiParameter,
+} from './types.ts';
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head'] as const;
+
+function resolveRef(
+  doc: OpenApiDocument,
+  ref: string,
+  seen = new Set<string>(),
+): unknown {
+  if (!ref.startsWith('#/')) {
+    return ref;
+  }
+
+  if (seen.has(ref)) {
+    return { $ref: ref, circular: true };
+  }
+
+  seen.add(ref);
+  const parts = ref.slice(2).split('/');
+  let current: unknown = doc;
+
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') {
+      return ref;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  if (
+    current != null &&
+    typeof current === 'object' &&
+    '$ref' in current &&
+    typeof (current as { $ref: unknown }).$ref === 'string'
+  ) {
+    return resolveRef(doc, (current as { $ref: string }).$ref, seen);
+  }
+
+  return current;
+}
+
+function resolveSchema(doc: OpenApiDocument, schema: unknown): unknown {
+  if (schema == null || typeof schema !== 'object') {
+    return schema;
+  }
+
+  if ('$ref' in schema && typeof schema.$ref === 'string') {
+    return resolveRef(doc, schema.$ref);
+  }
+
+  return schema;
+}
+
+function resolveParameters(
+  doc: OpenApiDocument,
+  parameters: OpenApiParameter[] | undefined,
+): OpenApiParameter[] {
+  if (!parameters?.length) {
+    return [];
+  }
+
+  return parameters.map((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),
+        };
+      }
+    }
+
+    return {
+      ...parameter,
+      schema: resolveSchema(doc, parameter.schema),
+    };
+  });
+}
+
+function inferApiKeyKind(
+  security: Array<Record<string, unknown[]>> | undefined,
+): ApiKeyKind {
+  if (!security?.length) {
+    return 'secret';
+  }
+
+  for (const requirement of security) {
+    if ('Public-Api-Key' in requirement) {
+      return 'public';
+    }
+  }
+
+  return 'secret';
+}
+
+function buildOperationId(
+  apiVersion: ApiVersion,
+  method: HttpMethod,
+  path: string,
+): string {
+  return `${apiVersion}:${method}:${path}`;
+}
+
+function parseDocument(
+  doc: OpenApiDocument,
+  apiVersion: ApiVersion,
+): ApiOperation[] {
+  const operations: ApiOperation[] = [];
+
+  for (const [path, pathItem] of Object.entries(doc.paths ?? {})) {
+    if (!pathItem) {
+      continue;
+    }
+
+    for (const methodKey of HTTP_METHODS) {
+      const operation = pathItem[methodKey];
+      if (!operation) {
+        continue;
+      }
+
+      const method = methodKey.toUpperCase() as HttpMethod;
+      const content = operation.requestBody?.content ?? {};
+      const contentTypes = Object.keys(content);
+      const firstContent = contentTypes[0]
+        ? content[contentTypes[0]]
+        : undefined;
+
+      operations.push({
+        id: buildOperationId(apiVersion, method, path),
+        apiVersion,
+        method,
+        path,
+        tags: operation.tags ?? [],
+        summary: operation.summary ?? `${method} ${path}`,
+        description: operation.description,
+        parameters: resolveParameters(doc, operation.parameters),
+        requestBody: operation.requestBody
+          ? {
+              required: operation.requestBody.required,
+              description: operation.requestBody.description,
+              contentTypes,
+              schema: firstContent
+                ? resolveSchema(doc, firstContent.schema)
+                : undefined,
+            }
+          : undefined,
+        apiKeyKind: inferApiKeyKind(operation.security),
+        deprecated: operation.deprecated,
+      });
+    }
+  }
+
+  return operations;
+}
+
+export class OperationRegistry {
+  readonly operations: ApiOperation[];
+
+  constructor() {
+    this.operations = [
+      ...parseDocument(v1Spec as unknown as OpenApiDocument, 'v1'),
+      ...parseDocument(v2Spec as unknown as OpenApiDocument, 'v2'),
+    ];
+  }
+
+  getById(id: string): ApiOperation | undefined {
+    return this.operations.find((operation) => operation.id === id);
+  }
+
+  find(filters: {
+    apiVersion?: ApiVersion | 'all';
+    tag?: string;
+    method?: HttpMethod;
+    pathPrefix?: string;
+    search?: string;
+    apiKeyKind?: ApiKeyKind;
+  }): ApiOperation[] {
+    const search = filters.search?.trim().toLowerCase();
+
+    return this.operations.filter((operation) => {
+      if (
+        filters.apiVersion &&
+        filters.apiVersion !== 'all' &&
+        operation.apiVersion !== filters.apiVersion
+      ) {
+        return false;
+      }
+
+      if (filters.tag && !operation.tags.includes(filters.tag)) {
+        return false;
+      }
+
+      if (filters.method && operation.method !== filters.method) {
+        return false;
+      }
+
+      if (
+        filters.pathPrefix &&
+        !operation.path.startsWith(filters.pathPrefix)
+      ) {
+        return false;
+      }
+
+      if (filters.apiKeyKind && operation.apiKeyKind !== filters.apiKeyKind) {
+        return false;
+      }
+
+      if (search) {
+        const haystack = [
+          operation.id,
+          operation.path,
+          operation.summary,
+          operation.description ?? '',
+          operation.tags.join(' '),
+        ]
+          .join(' ')
+          .toLowerCase();
+
+        if (!haystack.includes(search)) {
+          return false;
+        }
+      }
+
+      return true;
+    });
+  }
+
+  listTags(apiVersion?: ApiVersion | 'all'): string[] {
+    const tags = new Set<string>();
+
+    for (const operation of this.find({ apiVersion })) {
+      for (const tag of operation.tags) {
+        tags.add(tag);
+      }
+    }
+
+    return [...tags].sort((a, b) => a.localeCompare(b));
+  }
+}
+
+export const operationRegistry = new OperationRegistry();
+
+export function getBundledSpec(apiVersion: ApiVersion): OpenApiDocument {
+  return apiVersion === 'v1'
+    ? (v1Spec as unknown as OpenApiDocument)
+    : (v2Spec as unknown as OpenApiDocument);
+}

package/src/openapi/types.ts

@@ -0,0 +1,68 @@
+export type ApiVersion = 'v1' | 'v2';
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+
+export type ApiKeyKind = 'secret' | 'public';
+
+export interface OpenApiParameter {
+  name?: string;
+  in?: 'query' | 'path' | 'header' | 'cookie';
+  required?: boolean;
+  description?: string;
+  schema?: unknown;
+  $ref?: string;
+}
+
+export interface ApiOperation {
+  id: string;
+  apiVersion: ApiVersion;
+  method: HttpMethod;
+  path: string;
+  tags: string[];
+  summary: string;
+  description?: string;
+  parameters: OpenApiParameter[];
+  requestBody?: {
+    required?: boolean;
+    description?: string;
+    contentTypes: string[];
+    schema?: unknown;
+  };
+  apiKeyKind: ApiKeyKind;
+  deprecated?: boolean;
+}
+
+export interface OpenApiDocument {
+  openapi?: string;
+  info?: {
+    title?: string;
+    version?: string;
+    description?: string;
+  };
+  paths?: Record<
+    string,
+    Partial<
+      Record<
+        Lowercase<HttpMethod>,
+        {
+          tags?: string[];
+          summary?: string;
+          description?: string;
+          deprecated?: boolean;
+          parameters?: OpenApiParameter[];
+          requestBody?: {
+            required?: boolean;
+            description?: string;
+            content?: Record<string, { schema?: unknown }>;
+          };
+          security?: Array<Record<string, unknown[]>>;
+        }
+      >
+    >
+  >;
+  components?: {
+    parameters?: Record<string, OpenApiParameter>;
+    schemas?: Record<string, unknown>;
+    responses?: Record<string, unknown>;
+  };
+}

package/src/resources/register.ts

@@ -0,0 +1,95 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+
+import { getBundledSpec } from '../openapi/registry.ts';
+
+const WEBHOOK_EVENTS_DOC = `# Askell webhook events (reference)
+
+Askell sends signed webhook calls to your configured endpoints.
+
+Headers:
+- Hook-HMAC: base64 HMAC-SHA512 of the raw body
+- Hook-Event: event type identifier
+- Hook-API-Version: v1 for legacy plan/subscription webhooks, v2 for subscription contract webhooks
+
+Event families:
+- subscription.* (legacy v1): subscription.created, subscription.changed, subscription.renewed
+- subscription_contract.* (v2): subscription_contract.created, subscription_contract.changed,
+  subscription_contract.renewed, subscription_contract.migrated (legacy subscription migrated to a
+  V2 contract; payload includes legacy_subscription_ids and migration_effective_at)
+- billing_run.* (v2): billing_run.created, billing_run.changed, billing_run.succeeded,
+  billing_run.failed, billing_run.retry
+- customer.*: customer.created, customer.changed
+- payment.*: payment.created, payment.changed, payment.retry
+- checkout.*: checkout.created, checkout.changed
+
+Notes:
+- During migration to V2, legacy subscription.* aliases are NOT sent for the new contract (event data
+  is based on SubscriptionContract, not Subscription), and subscription.canceled is not sent solely
+  because billing moved to a V2 contract.
+
+Webhook management is available via v1 API:
+- GET/POST /webhooks/
+- GET/PATCH/DELETE /webhooks/{id}/
+
+This MCP server exposes webhook management through askell_call and askell_list_webhooks.
+`;
+
+export function registerResources(server: McpServer): void {
+  server.registerResource(
+    'openapi-v1',
+    'askell://spec/v1',
+    {
+      title: 'Askell OpenAPI v1',
+      description: 'Bundled OpenAPI 3 spec for Askell API v1',
+      mimeType: 'application/json',
+    },
+    async () => ({
+      contents: [
+        {
+          uri: 'askell://spec/v1',
+          mimeType: 'application/json',
+          text: JSON.stringify(getBundledSpec('v1'), null, 2),
+        },
+      ],
+    }),
+  );
+
+  server.registerResource(
+    'openapi-v2',
+    'askell://spec/v2',
+    {
+      title: 'Askell OpenAPI v2',
+      description:
+        'Bundled OpenAPI 3 spec for Askell Subscription Contracts V2',
+      mimeType: 'application/json',
+    },
+    async () => ({
+      contents: [
+        {
+          uri: 'askell://spec/v2',
+          mimeType: 'application/json',
+          text: JSON.stringify(getBundledSpec('v2'), null, 2),
+        },
+      ],
+    }),
+  );
+
+  server.registerResource(
+    'webhook-events',
+    'askell://docs/webhook-events',
+    {
+      title: 'Askell webhook events',
+      description: 'Webhook event types and management overview',
+      mimeType: 'text/markdown',
+    },
+    async () => ({
+      contents: [
+        {
+          uri: 'askell://docs/webhook-events',
+          mimeType: 'text/markdown',
+          text: WEBHOOK_EVENTS_DOC,
+        },
+      ],
+    }),
+  );
+}

package/src/server.ts

@@ -0,0 +1,64 @@
+import { McpServer } from '@modelcontextprotocol/server';
+
+import { AskellClient } from './client/askell-client.ts';
+import type { AppConfig } from './config.ts';
+import { registerResources } from './resources/register.ts';
+import { registerAnalysisTools } from './tools/analysis.ts';
+import { registerCallTool } from './tools/call.ts';
+import { registerDiscoveryTools } from './tools/discovery.ts';
+
+const SERVER_INSTRUCTIONS = `Askell MCP server for payment and subscription operations.
+
+Workflow:
+1. Use askell_list_operations and askell_describe_operation to discover endpoints, parameters, and auth requirements.
+2. Prefer analysis tools (askell_customer_overview, askell_contract_overview, askell_billing_run_triage, askell_paginate_all, askell_list_webhooks) for common support tasks.
+3. Use askell_call only when no dedicated tool covers the request.
+
+API models:
+- v1 (legacy): PlanVariant + Subscription at paths like /subscriptions/, /customers/. Still supported for existing integrations.
+- v2 (current): Catalog, bundles, quotes, checkouts, subscription contracts, billing runs under /v2/. Prefer v2 for new integrations.
+- Prose docs at https://docs.askell.is/api/ may describe flows (embedded checkout, 3D Secure, wallet passes) not fully listed in OpenAPI.
+
+API layout:
+- v1 paths have no prefix (e.g. /customers/, /subscriptions/, /webhooks/).
+- v2 paths start with /v2/ (e.g. /v2/subscription-contracts/, /v2/billing-runs/).
+- Askell paths use trailing slashes.
+- V2 list endpoints paginate only when page_size is provided (default 10, max 1000).
+- GET /v2/customer-entitlements/ requires customer_reference query param.
+
+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).
+
+Auth:
+- Most endpoints need the secret API key.
+- Only temporary payment method and checkout status endpoints use the public key.
+
+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.
+
+Resources:
+- askell://spec/v1 and askell://spec/v2 — bundled OpenAPI
+- askell://docs/webhook-events — webhook event types including V2 subscription_contract.* and billing_run.*`;
+
+export function createServer(config: AppConfig): McpServer {
+  const server = new McpServer(
+    {
+      name: 'askell-mcp',
+      version: '0.1.0',
+    },
+    {
+      instructions: SERVER_INSTRUCTIONS,
+    },
+  );
+
+  const client = new AskellClient(config);
+
+  registerDiscoveryTools(server);
+  registerCallTool(server, client, config);
+  registerAnalysisTools(server, client);
+  registerResources(server);
+
+  return server;
+}