askell-mcp 0.4.13 → 0.4.15

package/README.md

@@ -19,34 +19,79 @@ In the Askell dashboard, copy your **private (secret)** API key. Optionally also
 
 ### 2. Add to your MCP client
 
-Prefer **two server entries** if you have both production and sandbox keys. Tool names are the same on both; the client distinguishes them by the `mcp.json` key (`askell-prod` vs `askell-sandbox`). Set `ASKELL_ENV` — the server picks the host. Each instance's instructions include the environment it is talking to.
+Prefer **two server entries** if you have both production and sandbox keys. Tool names are the same on both; the client distinguishes them by the server key (`askell-prod` vs `askell-sandbox`). Each instance's instructions include the environment it is talking to.
 
-**With Bun** (`bunx`):
+Put keys in gitignored dotenv files, not in JSON. Copy [`.env.example`](./.env.example):
+
+- `.env` — production (`ASKELL_ENV=production` and that dashboard's keys)
+- `.env.sandbox` — sandbox (`ASKELL_ENV=sandbox` and that dashboard's keys)
+
+Bun does not auto-load `.env.sandbox`. `--no-env-file` stops the sandbox process from also reading a production `.env` that happens to sit in the cwd.
+
+#### Cursor
+
+Project file: `.cursor/mcp.json`. [`mcp.json.example`](./mcp.json.example) is this shape. `${workspaceFolder}` is the directory that contains that `mcp.json` (the repo root when the file is `.cursor/mcp.json`). In `~/.cursor/mcp.json`, use an absolute `envFile` path.
+
+**With Bun:**
 
 ```json
 {
   "mcpServers": {
     "askell-prod": {
       "command": "bunx",
-      "args": ["-y", "askell-mcp@latest"],
-      "env": {
-        "ASKELL_ENV": "production",
-        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key"
-      }
+      "args": ["--no-env-file", "x", "askell-mcp"],
+      "envFile": "${workspaceFolder}/.env"
     },
     "askell-sandbox": {
       "command": "bunx",
-      "args": ["-y", "askell-mcp@latest"],
-      "env": {
-        "ASKELL_ENV": "sandbox",
-        "ASKELL_PRIVATE_API_KEY": "your_sandbox_secret_api_key"
-      }
+      "args": ["--no-env-file", "x", "askell-mcp"],
+      "envFile": "${workspaceFolder}/.env.sandbox"
+    }
+  }
+}
+```
+
+**With a binary** (download `askell-mcp-<os>-<arch>` from [Releases](https://github.com/Neschadin/askell-mcp/releases), then `chmod +x`). Same `envFile`; the binary reads the environment Cursor injects:
+
+```json
+{
+  "mcpServers": {
+    "askell-prod": {
+      "command": "/absolute/path/to/askell-mcp-linux-x64",
+      "envFile": "${workspaceFolder}/.env"
+    }
+  }
+}
+```
+
+Reload the window after saving.
+
+#### Claude Desktop
+
+Config file:
+
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+No `envFile` field. The desktop process cwd is not your repo, so a relative `.env` path does not resolve. With Bun, pass an absolute `--env-file`:
+
+```json
+{
+  "mcpServers": {
+    "askell-prod": {
+      "command": "bunx",
+      "args": ["--no-env-file", "--env-file=/absolute/path/.env", "x", "askell-mcp"]
+    },
+    "askell-sandbox": {
+      "command": "bunx",
+      "args": ["--no-env-file", "--env-file=/absolute/path/.env.sandbox", "x", "askell-mcp"]
     }
   }
 }
 ```
 
-**With a binary** (download `askell-mcp-<os>-<arch>` from [Releases](https://github.com/Neschadin/askell-mcp/releases), then `chmod +x`):
+A binary has no `--env-file`. Put the keys in `env` (plaintext in that JSON file):
 
 ```json
 {
@@ -55,16 +100,19 @@ Prefer **two server entries** if you have both production and sandbox keys. Tool
       "command": "/absolute/path/to/askell-mcp-linux-x64",
       "env": {
         "ASKELL_ENV": "production",
-        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key"
+        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key",
+        "ASKELL_PUBLIC_API_KEY": "your_production_public_api_key_optional"
       }
     }
   }
 }
 ```
 
-Example file: [`mcp.json.example`](./mcp.json.example).
+Quit Claude Desktop completely and reopen it. Saving the file is not enough.
+
+#### Claude Code
 
-Restart the client after saving.
+Project `.mcp.json` expands `${VAR}` from the environment of the process that launched `claude`. It does not load a dotenv file. The Bun `--env-file` args from the Desktop section work here as well; a relative path is fine when you start `claude` from the repo. `${ASKELL_PRIVATE_API_KEY}` inside `env` only works when that variable is already exported in that environment. A `.env` file alone is not read.
 
 ## Configuration
 

package/mcp.json.example

@@ -2,21 +2,13 @@
   "mcpServers": {
     "askell-prod": {
       "command": "bunx",
-      "args": ["-y", "askell-mcp@latest"],
-      "env": {
-        "ASKELL_ENV": "production",
-        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key",
-        "ASKELL_PUBLIC_API_KEY": "your_production_public_api_key_optional"
-      }
+      "args": ["--no-env-file", "x", "askell-mcp"],
+      "envFile": "${workspaceFolder}/.env"
     },
     "askell-sandbox": {
       "command": "bunx",
-      "args": ["-y", "askell-mcp@latest"],
-      "env": {
-        "ASKELL_ENV": "sandbox",
-        "ASKELL_PRIVATE_API_KEY": "your_sandbox_secret_api_key",
-        "ASKELL_PUBLIC_API_KEY": "your_sandbox_public_api_key_optional"
-      }
+      "args": ["--no-env-file", "x", "askell-mcp"],
+      "envFile": "${workspaceFolder}/.env.sandbox"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
   "license": "MIT",
@@ -66,7 +66,7 @@
     "typescript": "7.0.2"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0",
+    "@modelcontextprotocol/server": "2.1.0",
     "zod": "4.6.5"
   }
 }

package/src/client/askell-client.ts

@@ -27,7 +27,27 @@ export class AskellClient {
     this.baseUrl = normalizeBaseUrl(config.apiBaseUrl);
   }
 
-  async request(input: AskellRequest): Promise<FormattedResponse & { ok: boolean; status: number }> {
+  private apiKeyFor(kind: ApiKeyKind | undefined): string {
+    const apiKeyKind = kind ?? 'secret';
+    const apiKey =
+      apiKeyKind === 'public'
+        ? this.config.publicApiKey
+        : this.config.secretApiKey;
+
+    if (!apiKey) {
+      throw new Error(
+        apiKeyKind === 'public'
+          ? 'publicApiKey is not configured'
+          : 'secretApiKey is not configured',
+      );
+    }
+
+    return apiKey;
+  }
+
+  async request(
+    input: AskellRequest,
+  ): Promise<FormattedResponse & { ok: boolean; status: number }> {
     const method = input.method.toUpperCase();
     const path = normalizeApiPath(input.path);
     const url = new URL(`${this.baseUrl}${path}`);
@@ -49,19 +69,7 @@ export class AskellClient {
       }
     }
 
-    const apiKeyKind = input.apiKeyKind ?? 'secret';
-    const apiKey =
-      apiKeyKind === 'public'
-        ? this.config.publicApiKey
-        : this.config.secretApiKey;
-
-    if (!apiKey) {
-      throw new Error(
-        apiKeyKind === 'public'
-          ? 'publicApiKey is not configured'
-          : 'secretApiKey is not configured',
-      );
-    }
+    const apiKey = this.apiKeyFor(input.apiKeyKind);
 
     const started = performance.now();
     const response = await fetch(url, {
@@ -74,8 +82,7 @@ export class AskellClient {
           : {}),
         ...input.headers,
       },
-      body:
-        input.body !== undefined ? JSON.stringify(input.body) : undefined,
+      body: input.body !== undefined ? JSON.stringify(input.body) : undefined,
       signal: input.signal,
     });
 
@@ -108,19 +115,7 @@ export class AskellClient {
     signal?: AbortSignal;
   }): Promise<FormattedResponse & { ok: boolean; status: number }> {
     const maxPages = input.maxPages ?? 20;
-    const apiKeyKind = input.apiKeyKind ?? 'secret';
-    const apiKey =
-      apiKeyKind === 'public'
-        ? this.config.publicApiKey
-        : this.config.secretApiKey;
-
-    if (!apiKey) {
-      throw new Error(
-        apiKeyKind === 'public'
-          ? 'publicApiKey is not configured'
-          : 'secretApiKey is not configured',
-      );
-    }
+    const apiKey = this.apiKeyFor(input.apiKeyKind);
 
     const collected: unknown[] = [];
     let nextUrl: URL | null = null;

package/src/client/response-formatter.ts

@@ -1,7 +1,5 @@
-import {
-  redactSensitiveFields,
-  redactSecretsInText,
-} from './redact.ts';
+import { isRecord } from '../is-record.ts';
+import { redactSensitiveFields, redactSecretsInText } from './redact.ts';
 
 export interface FormattedResponse {
   text: string;
@@ -41,11 +39,8 @@ export function limitText(
 }
 
 function summarizeListItem(item: unknown): unknown {
-  if (item == null || typeof item !== 'object' || Array.isArray(item)) {
-    return item;
-  }
+  if (!isRecord(item)) return item;
 
-  const obj = item as Record<string, unknown>;
   const out: Record<string, unknown> = {};
   const scalarKeys = [
     'id',
@@ -74,13 +69,13 @@ function summarizeListItem(item: unknown): unknown {
   ] as const;
 
   for (const key of scalarKeys) {
-    if (key in obj) {
-      out[key] = obj[key];
+    if (key in item) {
+      out[key] = item[key];
     }
   }
 
-  if (obj.customer && typeof obj.customer === 'object') {
-    const customer = obj.customer as Record<string, unknown>;
+  if (item.customer && typeof item.customer === 'object') {
+    const customer = item.customer as Record<string, unknown>;
     out.customer = {
       id: customer.id,
       customer_reference:
@@ -88,66 +83,63 @@ function summarizeListItem(item: unknown): unknown {
     };
   }
 
-  if (obj.plan && typeof obj.plan === 'object') {
-    const plan = obj.plan as Record<string, unknown>;
+  if (item.plan && typeof item.plan === 'object') {
+    const plan = item.plan as Record<string, unknown>;
     out.plan = {
       id: plan.id,
       name: plan.name,
     };
   }
 
-  return Object.keys(out).length > 0 ? out : obj;
+  return Object.keys(out).length > 0 ? out : item;
 }
 
 /** 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;
-  }
+  if (!isRecord(item)) return item;
 
-  const obj = item as Record<string, unknown>;
   const out: Record<string, unknown> = {};
 
-  if ('id' in obj) {
-    out.id = obj.id;
+  if ('id' in item) {
+    out.id = item.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 ('start_date' in item) {
+    out.start_date = item.start_date;
+  } else if ('created_at' in item) {
+    out.created_at = item.created_at;
   }
 
-  if ('ended_at' in obj && obj.ended_at != null) {
-    out.ended_at = obj.ended_at;
+  if ('ended_at' in item && item.ended_at != null) {
+    out.ended_at = item.ended_at;
   }
 
-  const plan = obj.plan;
+  const plan = item.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;
+  } else if ('name' in item && typeof item.name === 'string') {
+    out.name = item.name;
   }
 
-  if (typeof obj.code === 'string') {
-    out.code = obj.code;
+  if (typeof item.code === 'string') {
+    out.code = item.code;
   }
 
   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)
+    item.customer_reference ??
+    (item.customer && typeof item.customer === 'object'
+      ? ((item.customer as Record<string, unknown>).customer_reference ??
+        (item.customer as Record<string, unknown>).reference ??
+        (item.customer as Record<string, unknown>).id)
       : undefined);
   if (customerRef !== undefined) {
     out.customer_reference = customerRef;
   }
 
-  if (typeof obj.email === 'string') {
-    out.email = obj.email;
+  if (typeof item.email === 'string') {
+    out.email = item.email;
   }
 
   return Object.keys(out).length > 0 ? out : summarizeListItem(item);
@@ -172,9 +164,7 @@ function serializeListPayload(
     body: items.slice(0, returnedCount),
   };
 
-  return pretty
-    ? JSON.stringify(payload, null, 2)
-    : JSON.stringify(payload);
+  return pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload);
 }
 
 function maxFittingCount(
@@ -304,11 +294,7 @@ export function buildBoundedListPayload(input: {
 
   const text = serializeListPayload(
     status,
-    compactMeta(
-      meta,
-      'index',
-      'Response too large; returning metadata only',
-    ),
+    compactMeta(meta, 'index', 'Response too large; returning metadata only'),
     [],
     0,
     true,
@@ -375,12 +361,7 @@ export function formatApiResponse(
 }
 
 function pickHeaders(headers: Headers): Record<string, string> {
-  const interesting = [
-    'content-type',
-    'date',
-    'x-request-id',
-    'retry-after',
-  ];
+  const interesting = ['content-type', 'date', 'x-request-id', 'retry-after'];
   const out: Record<string, string> = {};
 
   for (const name of interesting) {

package/src/config.ts

@@ -139,29 +139,15 @@ Keys are per host. ASKELL_API_BASE_URL is only for a custom/local API.
     ASKELL_PRIVATE_API_KEY=...
     ASKELL_PUBLIC_API_KEY=...
 
-  Published package (requires Bun) — Cursor / Claude mcp.json (two entries if you use sandbox):
-    {
-      "mcpServers": {
-        "askell-prod": {
-          "command": "bunx",
-          "args": ["-y", "askell-mcp@latest"],
-          "env": {
-            "ASKELL_ENV": "production",
-            "ASKELL_PRIVATE_API_KEY": "...",
-            "ASKELL_PUBLIC_API_KEY": "..."
-          }
-        },
-        "askell-sandbox": {
-          "command": "bunx",
-          "args": ["-y", "askell-mcp@latest"],
-          "env": {
-            "ASKELL_ENV": "sandbox",
-            "ASKELL_PRIVATE_API_KEY": "...",
-            "ASKELL_PUBLIC_API_KEY": "..."
-          }
-        }
-      }
-    }`;
+  Cursor (.cursor/mcp.json) — keys in .env / .env.sandbox, not in JSON:
+    "command": "bunx",
+    "args": ["--no-env-file", "x", "askell-mcp"],
+    "envFile": "\${workspaceFolder}/.env"   (sandbox: .env.sandbox)
+
+  Claude Desktop (no envFile; cwd is not the repo — absolute path):
+    "command": "bunx",
+    "args": ["--no-env-file", "--env-file=/absolute/path/.env", "x", "askell-mcp"]
+  Binary on Claude Desktop: put ASKELL_ENV and ASKELL_PRIVATE_API_KEY in "env".`;
 
 function loadConfigFromEnv(): unknown {
   const env = Bun.env;

package/src/is-record.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/openapi/patch-v1.ts

@@ -5,6 +5,8 @@
  * Idempotent: safe to run on an already-patched document.
  */
 
+import { isRecord } from '../is-record.ts';
+
 type JsonSchema = Record<string, unknown>;
 type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 
@@ -49,14 +51,7 @@ const RESPONSE_BODIES = [
   readonly [string, HttpMethod, string, string]
 >;
 
-const HTTP_METHODS = [
-  'get',
-  'post',
-  'put',
-  'patch',
-  'delete',
-  'head',
-] as const;
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head'] as const;
 
 const nullableString = (maxLength?: number): JsonSchema => ({
   type: 'string',
@@ -136,10 +131,6 @@ const CUSTOMER_READ_SCHEMA: JsonSchema = {
   },
 };
 
-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) {

package/src/tools/analysis.ts

@@ -2,21 +2,86 @@ import type { CallToolResult, McpServer } from '@modelcontextprotocol/server';
 import * as z from 'zod';
 
 import { AskellClient } from '../client/askell-client.ts';
+import { isRecord } from '../is-record.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 } };
 
+type SafeResult = { ok: boolean; data: unknown; error?: string };
+
+const ERROR_DETAIL_MAX = 200;
+
+function clip(text: string): string {
+  const oneLine = text.replace(/\s+/g, ' ').trim();
+  if (oneLine.length <= ERROR_DETAIL_MAX) return oneLine;
+
+  return `${oneLine.slice(0, ERROR_DETAIL_MAX - 1)}…`;
+}
+
+function messageList(value: unknown): string | undefined {
+  if (typeof value === 'string') {
+    const text = clip(value);
+    return text.length > 0 ? text : undefined;
+  }
+  if (
+    !Array.isArray(value) ||
+    !value.every((item) => typeof item === 'string')
+  ) {
+    return undefined;
+  }
+  const text = clip(value.filter((item) => item.trim().length > 0).join('; '));
+  return text.length > 0 ? text : undefined;
+}
+
+/**
+ * One line for the model. The Askell body stays in `data`.
+ * DRF `detail` / `non_field_errors` / flat field errors only — a resource
+ * object must not be flattened into the summary.
+ */
+export function summarizeApiFailure(status: number, body: unknown): string {
+  const detail = apiErrorDetail(body);
+  return detail ? `HTTP ${status}: ${detail}` : `HTTP ${status}`;
+}
+
+function apiErrorDetail(body: unknown): string | undefined {
+  if (typeof body === 'string') return messageList(body);
+  if (!isRecord(body)) return undefined;
+
+  if ('detail' in body) {
+    const detail = messageList(body.detail);
+    if (detail) return detail;
+  }
+
+  if ('non_field_errors' in body) {
+    const detail = messageList(body.non_field_errors);
+    if (detail) return detail;
+  }
+
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(body)) {
+    if (key === 'detail' || key === 'non_field_errors') continue;
+    const text = messageList(value);
+    if (!text) return undefined;
+    parts.push(`${key}: ${text}`);
+  }
+
+  return parts.length > 0 ? clip(parts.join('; ')) : undefined;
+}
+
 async function safeRequest(
   client: AskellClient,
   request: Parameters<AskellClient['request']>[0],
-): Promise<{ ok: boolean; data: unknown; error?: string }> {
+): Promise<SafeResult> {
   try {
     const response = await client.request(request);
     const parsed = JSON.parse(response.text) as { body?: unknown };
+    const data = parsed.body ?? parsed;
+    if (response.ok) return { ok: true, data };
+
     return {
-      ok: response.ok,
-      data: parsed.body ?? parsed,
-      error: response.ok ? undefined : response.text,
+      ok: false,
+      data,
+      error: summarizeApiFailure(response.status, data),
     };
   } catch (error) {
     return {
@@ -27,6 +92,13 @@ async function safeRequest(
   }
 }
 
+function failedCalls(
+  calls: Array<[name: string, result: SafeResult]>,
+): string[] | undefined {
+  const names = calls.filter(([, result]) => !result.ok).map(([name]) => name);
+  return names.length > 0 ? names : undefined;
+}
+
 export function registerAnalysisTools(
   server: McpServer,
   client: AskellClient,
@@ -74,7 +146,8 @@ export function registerAnalysisTools(
           content: [
             {
               type: 'text',
-              text: error instanceof Error ? error.message : 'Pagination failed',
+              text:
+                error instanceof Error ? error.message : 'Pagination failed',
             },
           ],
           isError: true,
@@ -88,7 +161,7 @@ export function registerAnalysisTools(
     {
       title: 'Customer overview (v1)',
       description:
-        'Fetch a v1 customer and their v1 subscriptions in one call. Useful for support and billing investigations.',
+        'Fetch a v1 customer and their v1 subscriptions in one call. Useful for support and billing investigations. Result is an error when the customer fetch fails; subscriptions are still included. `failures` lists every call that failed.',
       inputSchema: z.object({
         customerReference: z
           .string()
@@ -99,7 +172,10 @@ export function registerAnalysisTools(
         openWorldHint: true,
       },
     },
-    async ({ customerReference }, ctx: ToolContext): Promise<CallToolResult> => {
+    async (
+      { customerReference },
+      ctx: ToolContext,
+    ): Promise<CallToolResult> => {
       const [customer, subscriptions] = await Promise.all([
         safeRequest(client, {
           method: 'GET',
@@ -113,25 +189,26 @@ export function registerAnalysisTools(
         }),
       ]);
 
+      const failures = failedCalls([
+        ['customer', customer],
+        ['subscriptions', subscriptions],
+      ]);
+
       const payload = {
         customerReference,
         customer,
         subscriptions,
+        ...(failures ? { failures } : {}),
+        ...(!customer.ok
+          ? {
+              hint: 'Verify the customerReference with askell_call GET /customers/ or askell_paginate_all.',
+            }
+          : {}),
       };
 
-      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,
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        isError: !customer.ok,
       };
     },
   );
@@ -141,7 +218,7 @@ export function registerAnalysisTools(
     {
       title: 'Subscription contract overview (v2)',
       description:
-        'Fetch a v2 subscription contract and recent billing runs filtered by contract id. The contract payload includes `discount` (active coupon) when one is applied, `shipping_selection` when shipping was chosen at checkout, and `subscriber_page` (customer-facing management URL, read-only).',
+        'Fetch a v2 subscription contract and recent billing runs filtered by contract id. The contract payload includes `discount` (active coupon) when one is applied, `shipping_selection` when shipping was chosen at checkout, and `subscriber_page` (customer-facing management URL, read-only). Result is an error when the contract fetch fails. `failures` lists every call that failed.',
       inputSchema: z.object({
         contractId: z
           .union([z.string().min(1), z.int()])
@@ -181,23 +258,25 @@ export function registerAnalysisTools(
         }),
       ]);
 
+      const failures = failedCalls([
+        ['contract', contract],
+        ['billingRuns', billingRuns],
+      ]);
+
       const payload = {
         contractId,
         contract,
         billingRuns,
+        ...(failures ? { failures } : {}),
+        ...(!contract.ok
+          ? {
+              hint: 'Verify the contractId with askell_call GET /v2/subscription-contracts/.',
+            }
+          : {}),
       };
 
       return {
-        content: [
-          {
-            type: 'text',
-            text:
-              JSON.stringify(payload, null, 2) +
-              (!contract.ok
-                ? ' Verify the contractId with askell_call GET /v2/subscription-contracts/.'
-                : ''),
-          },
-        ],
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
         isError: !contract.ok,
       };
     },
@@ -208,7 +287,7 @@ export function registerAnalysisTools(
     {
       title: 'Billing run triage (v2)',
       description:
-        'Fetch a billing run by id with optional related contract context for failure analysis.',
+        'Fetch a billing run by id with optional related contract context for failure analysis. Result is an error when the billing run fetch fails. A failed related contract stays in the payload and is listed in `failures`.',
       inputSchema: z.object({
         billingRunId: z
           .union([z.string().min(1), z.int()])
@@ -216,7 +295,9 @@ export function registerAnalysisTools(
         includeContract: z
           .boolean()
           .default(true)
-          .describe('Also fetch the related subscription contract when the run has a contract id'),
+          .describe(
+            'Also fetch the related subscription contract when the run has a contract id',
+          ),
       }),
       annotations: {
         readOnlyHint: true,
@@ -251,23 +332,26 @@ export function registerAnalysisTools(
         }
       }
 
+      const calls: [string, SafeResult][] = [['billingRun', billingRun]];
+      if (contract) {
+        calls.push(['contract', contract]);
+      }
+      const failures = failedCalls(calls);
+
       const payload = {
         billingRunId,
         billingRun,
         contract,
+        ...(failures ? { failures } : {}),
+        ...(!billingRun.ok
+          ? {
+              hint: 'Verify the billingRunId with askell_call GET /v2/billing-runs/.',
+            }
+          : {}),
       };
 
       return {
-        content: [
-          {
-            type: 'text',
-            text:
-              JSON.stringify(payload, null, 2) +
-              (!billingRun.ok
-                ? ' Verify the billingRunId with askell_call GET /v2/billing-runs/.'
-                : ''),
-          },
-        ],
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
         isError: !billingRun.ok,
       };
     },
@@ -285,7 +369,9 @@ export function registerAnalysisTools(
           .positive()
           .max(1000)
           .optional()
-          .describe('Page size for GET /webhooks/ (Askell default 10, max 1000)'),
+          .describe(
+            'Page size for GET /webhooks/ (Askell default 10, max 1000)',
+          ),
       }),
       annotations: {
         readOnlyHint: true,

package/src/tools/mutation-gate.ts

@@ -4,13 +4,10 @@ import {
 } from '@modelcontextprotocol/server';
 
 import type { MutationGate } from '../config.ts';
+import { isRecord } from '../is-record.ts';
 
 export type MutationGateDecision = { action: 'execute' } | { action: 'elicit' };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value != null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /**
  * Per-request client capabilities (protocol 2026-07-28).
  *
@@ -28,9 +25,8 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 export function readClientCapabilities(
   envelope: unknown,
 ): ClientCapabilities | undefined {
-  if (!isRecord(envelope)) {
-    return undefined;
-  }
+  if (!isRecord(envelope)) return undefined;
+
   const value = envelope[CLIENT_CAPABILITIES_META_KEY];
   return isRecord(value) ? (value as ClientCapabilities) : undefined;
 }
@@ -40,16 +36,13 @@ export function clientSupportsFormElicitation(
   capabilities: ClientCapabilities | undefined,
 ): boolean {
   const elicitation = capabilities?.elicitation;
-  if (elicitation == null) {
-    return false;
-  }
-  if (elicitation.form != null) {
-    return true;
-  }
+  if (elicitation == null) return false;
+  if (elicitation.form != null) return true;
+
   const keys = Object.keys(elicitation);
-  if (elicitation.url != null && keys.every((key) => key === 'url')) {
+  if (elicitation.url != null && keys.every((key) => key === 'url'))
     return false;
-  }
+
   return true;
 }