askell-mcp 0.1.0

package/src/tools/analysis.ts

@@ -0,0 +1,286 @@
+import type { CallToolResult, McpServer } from '@modelcontextprotocol/server';
+import * as z from 'zod';
+
+import { AskellClient } from '../client/askell-client.ts';
+
+/** Minimal shape of the handler `ctx` param needed here — avoids depending on the SDK's internal context type name. */
+type ToolContext = { mcpReq: { signal: AbortSignal } };
+
+async function safeRequest(
+  client: AskellClient,
+  request: Parameters<AskellClient['request']>[0],
+): Promise<{ ok: boolean; data: unknown; error?: string }> {
+  try {
+    const response = await client.request(request);
+    const parsed = JSON.parse(response.text) as { body?: unknown };
+    return {
+      ok: response.ok,
+      data: parsed.body ?? parsed,
+      error: response.ok ? undefined : response.text,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      data: null,
+      error: error instanceof Error ? error.message : 'Request failed',
+    };
+  }
+}
+
+export function registerAnalysisTools(
+  server: McpServer,
+  client: AskellClient,
+): void {
+  server.registerTool(
+    'askell_paginate_all',
+    {
+      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.',
+      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),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (input, ctx: ToolContext): Promise<CallToolResult> => {
+      try {
+        const response = await client.paginateAll({
+          ...input,
+          signal: ctx.mcpReq.signal,
+        });
+        return {
+          content: [{ type: 'text', text: response.text }],
+          isError: !response.ok,
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: error instanceof Error ? error.message : 'Pagination failed',
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  server.registerTool(
+    'askell_customer_overview',
+    {
+      title: 'Customer overview (v1)',
+      description:
+        'Fetch a v1 customer and their v1 subscriptions in one call. Useful for support and billing investigations.',
+      inputSchema: z.object({
+        customerReference: z
+          .string()
+          .describe('Customer reference from Askell'),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ customerReference }, ctx: ToolContext): Promise<CallToolResult> => {
+      const [customer, subscriptions] = await Promise.all([
+        safeRequest(client, {
+          method: 'GET',
+          path: `/customers/${encodeURIComponent(customerReference)}/`,
+          signal: ctx.mcpReq.signal,
+        }),
+        safeRequest(client, {
+          method: 'GET',
+          path: `/customers/${encodeURIComponent(customerReference)}/subscriptions/`,
+          signal: ctx.mcpReq.signal,
+        }),
+      ]);
+
+      const payload = {
+        customerReference,
+        customer,
+        subscriptions,
+      };
+
+      const notFoundHint =
+        !customer.ok && !subscriptions.ok
+          ? ' Verify the customerReference with askell_call GET /customers/ or askell_paginate_all.'
+          : '';
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(payload, null, 2) + notFoundHint,
+          },
+        ],
+        isError: !customer.ok && !subscriptions.ok,
+      };
+    },
+  );
+
+  server.registerTool(
+    'askell_contract_overview',
+    {
+      title: 'Subscription contract overview (v2)',
+      description:
+        'Fetch a v2 subscription contract and recent billing runs filtered by contract id.',
+      inputSchema: z.object({
+        contractId: z.union([z.string(), z.number()]),
+        billingRunLimit: z.int().positive().max(50).default(10),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (
+      { contractId, billingRunLimit },
+      ctx: ToolContext,
+    ): Promise<CallToolResult> => {
+      const contractPath = `/v2/subscription-contracts/${encodeURIComponent(String(contractId))}/`;
+
+      const [contract, billingRuns] = await Promise.all([
+        safeRequest(client, {
+          method: 'GET',
+          path: contractPath,
+          signal: ctx.mcpReq.signal,
+        }),
+        safeRequest(client, {
+          method: 'GET',
+          path: '/v2/billing-runs/',
+          query: {
+            contract: contractId,
+            page_size: billingRunLimit,
+          },
+          signal: ctx.mcpReq.signal,
+        }),
+      ]);
+
+      const payload = {
+        contractId,
+        contract,
+        billingRuns,
+      };
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              JSON.stringify(payload, null, 2) +
+              (!contract.ok
+                ? ' Verify the contractId with askell_call GET /v2/subscription-contracts/.'
+                : ''),
+          },
+        ],
+        isError: !contract.ok,
+      };
+    },
+  );
+
+  server.registerTool(
+    'askell_billing_run_triage',
+    {
+      title: 'Billing run triage (v2)',
+      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),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (
+      { billingRunId, includeContract },
+      ctx: ToolContext,
+    ): Promise<CallToolResult> => {
+      const billingRun = await safeRequest(client, {
+        method: 'GET',
+        path: `/v2/billing-runs/${encodeURIComponent(String(billingRunId))}/`,
+        signal: ctx.mcpReq.signal,
+      });
+
+      let contract: Awaited<ReturnType<typeof safeRequest>> | undefined;
+
+      if (includeContract && billingRun.ok && billingRun.data) {
+        const run = billingRun.data as {
+          contract?: string | number;
+          contract_id?: string | number;
+        };
+        const contractId = run.contract ?? run.contract_id;
+
+        if (contractId != null) {
+          contract = await safeRequest(client, {
+            method: 'GET',
+            path: `/v2/subscription-contracts/${encodeURIComponent(String(contractId))}/`,
+            signal: ctx.mcpReq.signal,
+          });
+        }
+      }
+
+      const payload = {
+        billingRunId,
+        billingRun,
+        contract,
+      };
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              JSON.stringify(payload, null, 2) +
+              (!billingRun.ok
+                ? ' Verify the billingRunId with askell_call GET /v2/billing-runs/.'
+                : ''),
+          },
+        ],
+        isError: !billingRun.ok,
+      };
+    },
+  );
+
+  server.registerTool(
+    'askell_list_webhooks',
+    {
+      title: 'List configured webhooks (v1)',
+      description:
+        'List Askell webhook endpoints configured for the account (management API only).',
+      inputSchema: z.object({
+        page_size: z.int().positive().max(1000).optional(),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (input, ctx: ToolContext): Promise<CallToolResult> => {
+      const response = await safeRequest(client, {
+        method: 'GET',
+        path: '/webhooks/',
+        query: input,
+        signal: ctx.mcpReq.signal,
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(response, null, 2),
+          },
+        ],
+        isError: !response.ok,
+      };
+    },
+  );
+}

package/src/tools/call.ts

@@ -0,0 +1,129 @@
+import {
+  acceptedContent,
+  inputRequired,
+  type CallToolResult,
+  type InputRequiredResult,
+  type McpServer,
+} from '@modelcontextprotocol/server';
+import * as z from 'zod';
+
+import { AskellClient, type AskellRequest } from '../client/askell-client.ts';
+import { normalizeApiPath } from '../client/paths.ts';
+import { isMutatingMethod } from '../client/response-formatter.ts';
+import type { AppConfig } from '../config.ts';
+import { operationRegistry } from '../openapi/registry.ts';
+
+const confirmationSchema = z.object({
+  confirm: z.boolean().meta({ title: 'Confirm mutating Askell API request' }),
+});
+
+const callInputSchema = z.object({
+  method: z
+    .enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'])
+    .describe('HTTP method'),
+  path: z
+    .string()
+    .describe('API path relative to apiBaseUrl, e.g. /v2/subscription-contracts/'),
+  query: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe('Query string parameters'),
+  body: z.unknown().optional().describe('JSON request body'),
+  apiKeyKind: z
+    .enum(['secret', 'public'])
+    .default('secret')
+    .describe('Which configured API key to use'),
+});
+
+function buildApprovalMessage(input: z.infer<typeof callInputSchema>): string {
+  const lines = [
+    `Approve this Askell API request?`,
+    '',
+    `${input.method} ${input.path}`,
+    `apiKeyKind: ${input.apiKeyKind}`,
+  ];
+
+  if (input.query && Object.keys(input.query).length > 0) {
+    lines.push('', 'Query:', JSON.stringify(input.query, null, 2));
+  }
+
+  if (input.body !== undefined) {
+    lines.push('', 'Body:', JSON.stringify(input.body, null, 2));
+  }
+
+  return lines.join('\n');
+}
+
+export function registerCallTool(
+  server: McpServer,
+  client: AskellClient,
+  config: AppConfig,
+): void {
+  server.registerTool(
+    'askell_call',
+    {
+      title: 'Call Askell API',
+      description:
+        'Execute any Askell API endpoint (v1 or v2). Mutating requests require operator approval when requireMutationApproval is enabled. Use askell_list_operations and askell_describe_operation first to discover paths and parameters.',
+      inputSchema: callInputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+      },
+    },
+    async (input, ctx): Promise<CallToolResult | InputRequiredResult> => {
+      const mutating = isMutatingMethod(input.method);
+
+      if (config.requireMutationApproval && mutating) {
+        const confirmed = acceptedContent(
+          ctx.mcpReq.inputResponses,
+          'confirm',
+          confirmationSchema,
+        );
+
+        if (confirmed?.confirm !== true) {
+          return inputRequired({
+            inputRequests: {
+              confirm: inputRequired.elicit({
+                message: buildApprovalMessage(input),
+                requestedSchema: confirmationSchema,
+              }),
+            },
+          });
+        }
+      }
+
+      const path = normalizeApiPath(input.path);
+      const known = operationRegistry.find({
+        method: input.method,
+        pathPrefix: path,
+      }).find((operation) => operation.path === path);
+
+      const request: AskellRequest = {
+        method: input.method,
+        path,
+        query: input.query,
+        body: input.body,
+        apiKeyKind: input.apiKeyKind ?? known?.apiKeyKind ?? 'secret',
+        signal: ctx.mcpReq.signal,
+      };
+
+      try {
+        const response = await client.request(request);
+        return {
+          content: [{ type: 'text', text: response.text }],
+          isError: !response.ok,
+        };
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : 'Unknown Askell API error';
+        return {
+          content: [{ type: 'text', text: message }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/src/tools/discovery.ts

@@ -0,0 +1,180 @@
+import type { CallToolResult, McpServer } from '@modelcontextprotocol/server';
+import * as z from 'zod';
+
+import { operationRegistry } from '../openapi/registry.ts';
+
+const listInputSchema = z.object({
+  apiVersion: z
+    .enum(['v1', 'v2', 'all'])
+    .default('all')
+    .describe('Filter by API version'),
+  tag: z.string().optional().describe('Filter by OpenAPI tag'),
+  method: z
+    .enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'])
+    .optional()
+    .describe('Filter by HTTP method'),
+  pathPrefix: z
+    .string()
+    .optional()
+    .describe('Filter paths starting with this prefix, e.g. /v2/billing-runs/'),
+  search: z
+    .string()
+    .optional()
+    .describe(
+      'Case-insensitive search in id, path, summary, description, tags',
+    ),
+  apiKeyKind: z
+    .enum(['secret', 'public'])
+    .optional()
+    .describe('Filter by required API key type'),
+  limit: z
+    .int()
+    .positive()
+    .max(200)
+    .default(50)
+    .describe('Maximum number of operations to return'),
+});
+
+const describeInputSchema = z.object({
+  operationId: z
+    .string()
+    .describe(
+      'Operation id from askell_list_operations, e.g. v2:GET:/v2/billing-runs/',
+    ),
+});
+
+const apiVersionSchema = z.enum(['v1', 'v2']);
+const apiKeyKindSchema = z.enum(['secret', 'public']);
+const httpMethodSchema = z.enum([
+  'GET',
+  'POST',
+  'PUT',
+  'PATCH',
+  'DELETE',
+  'HEAD',
+]);
+
+const operationSummarySchema = z.object({
+  id: z.string(),
+  apiVersion: apiVersionSchema,
+  method: httpMethodSchema,
+  path: z.string(),
+  tags: z.array(z.string()),
+  summary: z.string(),
+  apiKeyKind: apiKeyKindSchema,
+  deprecated: z.boolean(),
+});
+
+const listOperationsOutputSchema = z.object({
+  totalMatched: z.int(),
+  returned: z.int(),
+  availableTags: z.array(z.string()),
+  operations: z.array(operationSummarySchema),
+});
+
+const openApiParameterSchema = z.object({
+  name: z.string().optional(),
+  in: z.enum(['query', 'path', 'header', 'cookie']).optional(),
+  required: z.boolean().optional(),
+  description: z.string().optional(),
+  schema: z.unknown().optional(),
+  $ref: z.string().optional(),
+});
+
+const operationDetailSchema = z.object({
+  id: z.string(),
+  apiVersion: apiVersionSchema,
+  method: httpMethodSchema,
+  path: z.string(),
+  tags: z.array(z.string()),
+  summary: z.string(),
+  description: z.string().optional(),
+  parameters: z.array(openApiParameterSchema),
+  requestBody: z
+    .object({
+      required: z.boolean().optional(),
+      description: z.string().optional(),
+      contentTypes: z.array(z.string()),
+      schema: z.unknown().optional(),
+    })
+    .optional(),
+  apiKeyKind: apiKeyKindSchema,
+  deprecated: z.boolean().optional(),
+});
+
+export function registerDiscoveryTools(server: McpServer): void {
+  server.registerTool(
+    'askell_list_operations',
+    {
+      title: 'List Askell API operations',
+      description:
+        'Discover Askell v1 and v2 API operations from bundled OpenAPI specs. Returns operation ids usable with askell_describe_operation. NOTE: results are capped by `limit` (default 50) — always check `totalMatched` in the response, not just the length of `operations`, to know if more results exist.',
+      inputSchema: listInputSchema,
+      outputSchema: listOperationsOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (input): Promise<CallToolResult> => {
+      const allMatches = operationRegistry.find(input);
+      const matches = allMatches.slice(0, input.limit);
+
+      const payload: z.infer<typeof listOperationsOutputSchema> = {
+        totalMatched: allMatches.length,
+        returned: matches.length,
+        availableTags: operationRegistry.listTags(input.apiVersion),
+        operations: matches.map((operation) => ({
+          id: operation.id,
+          apiVersion: operation.apiVersion,
+          method: operation.method,
+          path: operation.path,
+          tags: operation.tags,
+          summary: operation.summary,
+          apiKeyKind: operation.apiKeyKind,
+          deprecated: operation.deprecated ?? false,
+        })),
+      };
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+      };
+    },
+  );
+
+  server.registerTool(
+    'askell_describe_operation',
+    {
+      title: 'Describe Askell API operation',
+      description:
+        'Return full OpenAPI details for one operation: parameters, request body schema, auth requirements.',
+      inputSchema: describeInputSchema,
+      outputSchema: operationDetailSchema,
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
+    },
+    async ({ operationId }): Promise<CallToolResult> => {
+      const operation = operationRegistry.getById(operationId);
+
+      if (!operation) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Unknown operationId: ${operationId}. Use askell_list_operations to discover valid ids.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(operation, null, 2) }],
+        structuredContent: operation,
+      };
+    },
+  );
+}