askell-mcp 0.1.0

package/src/client/askell-client.ts

@@ -0,0 +1,243 @@
+import { normalizeBaseUrl, type AppConfig } from '../config.ts';
+import { normalizeApiPath } from './paths.ts';
+import {
+  buildBoundedListPayload,
+  formatApiResponse,
+  isMutatingMethod,
+  type FormattedResponse,
+} from './response-formatter.ts';
+
+import type { ApiKeyKind } from '../openapi/types.ts';
+
+export interface AskellRequest {
+  method: string;
+  path: string;
+  query?: Record<string, unknown>;
+  body?: unknown;
+  apiKeyKind?: ApiKeyKind;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+export class AskellClient {
+  private readonly baseUrl: string;
+
+  constructor(private readonly config: AppConfig) {
+    this.baseUrl = normalizeBaseUrl(config.apiBaseUrl);
+  }
+
+  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}`);
+
+    if (input.query) {
+      for (const [key, value] of Object.entries(input.query)) {
+        if (value === undefined || value === null) {
+          continue;
+        }
+
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            url.searchParams.append(key, String(item));
+          }
+          continue;
+        }
+
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    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 started = performance.now();
+    const response = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Api-Key ${apiKey}`,
+        Accept: 'application/json',
+        ...(input.body !== undefined
+          ? { 'Content-Type': 'application/json' }
+          : {}),
+        ...input.headers,
+      },
+      body:
+        input.body !== undefined ? JSON.stringify(input.body) : undefined,
+      signal: input.signal,
+    });
+
+    const bodyText = await response.text();
+    const formatted = formatApiResponse(
+      response.status,
+      response.headers,
+      bodyText,
+      this.config.responseMaxBytes,
+      {
+        method,
+        url: url.toString(),
+        durationMs: Math.round(performance.now() - started),
+        mutating: isMutatingMethod(method),
+      },
+    );
+
+    return {
+      ...formatted,
+      ok: response.ok,
+      status: response.status,
+    };
+  }
+
+  async paginateAll(input: {
+    path: string;
+    query?: Record<string, unknown>;
+    apiKeyKind?: ApiKeyKind;
+    maxPages?: number;
+    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 collected: unknown[] = [];
+    let nextUrl: URL | null = null;
+    let page = 0;
+    let lastStatus = 200;
+
+    const buildInitialUrl = (): URL => {
+      const path = normalizeApiPath(input.path);
+      const url = new URL(`${this.baseUrl}${path}`);
+
+      if (input.query) {
+        for (const [key, value] of Object.entries(input.query)) {
+          if (value === undefined || value === null) {
+            continue;
+          }
+          url.searchParams.set(key, String(value));
+        }
+      }
+
+      return url;
+    };
+
+    do {
+      page += 1;
+      const url = nextUrl ?? buildInitialUrl();
+      const started = performance.now();
+
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+          Authorization: `Api-Key ${apiKey}`,
+          Accept: 'application/json',
+        },
+        signal: input.signal,
+      });
+
+      lastStatus = response.status;
+      const bodyText = await response.text();
+
+      if (!response.ok) {
+        return {
+          ...formatApiResponse(
+            response.status,
+            response.headers,
+            bodyText,
+            this.config.responseMaxBytes,
+            {
+              method: 'GET',
+              url: url.toString(),
+              durationMs: Math.round(performance.now() - started),
+              mutating: false,
+            },
+          ),
+          ok: false,
+          status: response.status,
+        };
+      }
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(bodyText);
+      } catch {
+        return {
+          text: bodyText,
+          truncated: false,
+          byteLength: Buffer.byteLength(bodyText, 'utf8'),
+          ok: false,
+          status: lastStatus,
+        };
+      }
+
+      if (Array.isArray(parsed)) {
+        collected.push(...parsed);
+        nextUrl = null;
+      } else if (
+        parsed &&
+        typeof parsed === 'object' &&
+        'results' in parsed &&
+        Array.isArray((parsed as { results: unknown[] }).results)
+      ) {
+        const pageBody = parsed as {
+          results: unknown[];
+          next?: string | null;
+        };
+        collected.push(...pageBody.results);
+        nextUrl = pageBody.next ? new URL(pageBody.next) : null;
+      } else {
+        const bodyText = JSON.stringify(parsed, null, 2);
+
+        return {
+          ...formatApiResponse(
+            lastStatus,
+            response.headers,
+            bodyText,
+            this.config.responseMaxBytes,
+            {
+              pagesFetched: page,
+              note: 'Response is not a paginated list; returning raw body',
+            },
+          ),
+          ok: true,
+          status: lastStatus,
+        };
+      }
+    } while (nextUrl && page < maxPages);
+
+    return {
+      ...buildBoundedListPayload({
+        status: lastStatus,
+        meta: {
+          pagesFetched: page,
+          truncatedByMaxPages: Boolean(nextUrl),
+        },
+        items: collected,
+        maxBytes: this.config.responseMaxBytes,
+      }),
+      ok: true,
+      status: lastStatus,
+    };
+  }
+}

package/src/client/paths.ts

@@ -0,0 +1,10 @@
+/** Normalize Askell API paths: leading slash + trailing slash (OpenAPI convention). */
+export function normalizeApiPath(path: string): string {
+  let normalized = path.startsWith('/') ? path : `/${path}`;
+
+  if (normalized !== '/' && !normalized.endsWith('/')) {
+    normalized += '/';
+  }
+
+  return normalized;
+}

package/src/client/response-formatter.ts

@@ -0,0 +1,302 @@
+export interface FormattedResponse {
+  text: string;
+  truncated: boolean;
+  byteLength: number;
+}
+
+export function truncateUtf8(text: string, maxBytes: number): string {
+  if (Buffer.byteLength(text, 'utf8') <= maxBytes) {
+    return text;
+  }
+
+  let end = Math.min(text.length, maxBytes);
+  while (end > 0) {
+    const slice = text.slice(0, end);
+    if (Buffer.byteLength(slice, 'utf8') <= maxBytes) {
+      return slice;
+    }
+    end -= 1;
+  }
+
+  return '';
+}
+
+export function limitText(
+  text: string,
+  maxBytes: number,
+): Pick<FormattedResponse, 'text' | 'truncated' | 'byteLength'> {
+  const byteLength = Buffer.byteLength(text, 'utf8');
+  const truncated = byteLength > maxBytes;
+
+  return {
+    text: truncated ? truncateUtf8(text, maxBytes) : text,
+    truncated,
+    byteLength,
+  };
+}
+
+function summarizeListItem(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> = {};
+  const scalarKeys = [
+    'id',
+    'reference',
+    'customer_reference',
+    'uuid',
+    'name',
+    'state',
+    'status',
+    'active',
+    'cancelled',
+    'start_date',
+    'created_at',
+    'ended_at',
+    'active_until',
+    'email',
+    'first_name',
+    'last_name',
+    'description',
+    'currency',
+    'amount',
+    'total_amount',
+  ] as const;
+
+  for (const key of scalarKeys) {
+    if (key in obj) {
+      out[key] = obj[key];
+    }
+  }
+
+  if (obj.customer && typeof obj.customer === 'object') {
+    const customer = obj.customer as Record<string, unknown>;
+    out.customer = {
+      id: customer.id,
+      customer_reference:
+        customer.customer_reference ?? customer.reference ?? customer.id,
+    };
+  }
+
+  if (obj.plan && typeof obj.plan === 'object') {
+    const plan = obj.plan as Record<string, unknown>;
+    out.plan = {
+      id: plan.id,
+      name: plan.name,
+    };
+  }
+
+  return Object.keys(out).length > 0 ? out : obj;
+}
+
+function serializeListPayload(
+  status: number,
+  meta: Record<string, unknown>,
+  items: unknown[],
+  returnedCount: number,
+  truncatedByMaxBytes: boolean,
+  pretty: boolean,
+): string {
+  const payload = {
+    status,
+    meta: {
+      ...meta,
+      itemCount: items.length,
+      returnedCount,
+      truncatedByMaxBytes,
+    },
+    body: items.slice(0, returnedCount),
+  };
+
+  return pretty
+    ? JSON.stringify(payload, null, 2)
+    : JSON.stringify(payload);
+}
+
+function maxFittingCount(
+  items: unknown[],
+  status: number,
+  meta: Record<string, unknown>,
+  maxBytes: number,
+  pretty: boolean,
+): number {
+  const itemCount = items.length;
+  let lo = 0;
+  let hi = itemCount;
+
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    const candidate = serializeListPayload(
+      status,
+      meta,
+      items,
+      mid,
+      mid < itemCount,
+      pretty,
+    );
+    if (Buffer.byteLength(candidate, 'utf8') <= maxBytes) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+
+  return lo;
+}
+
+export function buildBoundedListPayload(input: {
+  status: number;
+  meta: Record<string, unknown>;
+  items: unknown[];
+  maxBytes: number;
+}): FormattedResponse {
+  const { status, meta, items, maxBytes } = input;
+  const itemCount = items.length;
+
+  const attempts: Array<{
+    items: unknown[];
+    pretty: boolean;
+    compacted: boolean;
+    note?: string;
+  }> = [
+    { items, pretty: true, compacted: false },
+    { items, pretty: false, compacted: false },
+    {
+      items: items.map(summarizeListItem),
+      pretty: false,
+      compacted: true,
+      note: 'Items summarized to fit responseMaxBytes',
+    },
+  ];
+
+  let fullByteLength = 0;
+
+  for (const attempt of attempts) {
+    const fullText = serializeListPayload(
+      status,
+      meta,
+      attempt.items,
+      attempt.items.length,
+      false,
+      attempt.pretty,
+    );
+    fullByteLength = Buffer.byteLength(fullText, 'utf8');
+
+    if (fullByteLength <= maxBytes) {
+      return {
+        text: fullText,
+        truncated: false,
+        byteLength: fullByteLength,
+      };
+    }
+
+    const returnedCount = maxFittingCount(
+      attempt.items,
+      status,
+      {
+        ...meta,
+        ...(attempt.compacted ? { compacted: true, note: attempt.note } : {}),
+      },
+      maxBytes,
+      attempt.pretty,
+    );
+
+    if (returnedCount > 0) {
+      const text = serializeListPayload(
+        status,
+        {
+          ...meta,
+          ...(attempt.compacted ? { compacted: true, note: attempt.note } : {}),
+        },
+        attempt.items,
+        returnedCount,
+        true,
+        attempt.pretty,
+      );
+
+      return {
+        text,
+        truncated: true,
+        byteLength: fullByteLength,
+      };
+    }
+  }
+
+  const text = serializeListPayload(
+    status,
+    {
+      ...meta,
+      compacted: true,
+      note: 'Response too large; returning metadata only',
+    },
+    [],
+    0,
+    true,
+    false,
+  );
+
+  return {
+    text,
+    truncated: true,
+    byteLength: fullByteLength,
+  };
+}
+
+export function formatApiResponse(
+  status: number,
+  headers: Headers,
+  bodyText: string,
+  maxBytes: number,
+  meta?: Record<string, unknown>,
+): FormattedResponse {
+  const byteLength = Buffer.byteLength(bodyText, 'utf8');
+  const truncated = byteLength > maxBytes;
+  const visibleBody = truncated ? truncateUtf8(bodyText, maxBytes) : bodyText;
+
+  let parsedBody: unknown = visibleBody;
+  try {
+    parsedBody = JSON.parse(visibleBody);
+  } catch {
+    // keep raw text
+  }
+
+  const payload = {
+    status,
+    headers: pickHeaders(headers),
+    meta,
+    truncated,
+    byteLength,
+    body: parsedBody,
+  };
+
+  return {
+    text: JSON.stringify(payload, null, 2),
+    truncated,
+    byteLength,
+  };
+}
+
+function pickHeaders(headers: Headers): Record<string, string> {
+  const interesting = [
+    'content-type',
+    'date',
+    'x-request-id',
+    'retry-after',
+  ];
+  const out: Record<string, string> = {};
+
+  for (const name of interesting) {
+    const value = headers.get(name);
+    if (value) {
+      out[name] = value;
+    }
+  }
+
+  return out;
+}
+
+export function isMutatingMethod(method: string): boolean {
+  return !['GET', 'HEAD', 'OPTIONS'].includes(method.toUpperCase());
+}

package/src/config.ts

@@ -0,0 +1,104 @@
+import * as z from 'zod';
+
+export const ConfigSchema = z.object({
+  apiBaseUrl: z
+    .httpUrl()
+    .default('https://askell.is/api')
+    .describe('Askell API base URL (default production host)'),
+  secretApiKey: z.string().min(1).describe('Secret (private) API key'),
+  publicApiKey: z
+    .string()
+    .optional()
+    .describe('Public API key for temporary payment method endpoints'),
+  responseMaxBytes: z
+    .int()
+    .positive()
+    .default(64_000)
+    .describe('Max response body size returned to the model'),
+  requireMutationApproval: z
+    .boolean()
+    .default(true)
+    .describe('Require operator confirmation before mutating requests'),
+});
+
+export type AppConfig = z.infer<typeof ConfigSchema>;
+
+const CONFIG_HELP = `Askell MCP credentials missing.
+
+Set ASKELL_PRIVATE_API_KEY (or ASKELL_SECRET_API_KEY), optionally ASKELL_PUBLIC_API_KEY and ASKELL_API_URL:
+
+  Local dev — create .env in the project root (Bun loads it automatically):
+    ASKELL_PRIVATE_API_KEY=...
+    ASKELL_PUBLIC_API_KEY=...
+
+  Published package (requires Bun) — Cursor / Claude mcp.json:
+    {
+      "mcpServers": {
+        "askell": {
+          "command": "bunx",
+          "args": ["-y", "askell-mcp"],
+          "env": {
+            "ASKELL_PRIVATE_API_KEY": "...",
+            "ASKELL_PUBLIC_API_KEY": "..."
+          }
+        }
+      }
+    }`;
+
+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;
+
+  if (!secretApiKey) {
+    return undefined;
+  }
+
+  const apiBaseUrl = env.ASKELL_API_URL ?? env.ASKELL_API_BASE_URL;
+  const responseMaxBytes = env.ASKELL_RESPONSE_MAX_BYTES;
+  const requireMutationApproval = env.ASKELL_REQUIRE_MUTATION_APPROVAL;
+
+  return {
+    ...(apiBaseUrl ? { apiBaseUrl } : {}),
+    secretApiKey,
+    ...(env.ASKELL_PUBLIC_API_KEY
+      ? { publicApiKey: env.ASKELL_PUBLIC_API_KEY }
+      : {}),
+    ...(responseMaxBytes ? { responseMaxBytes: Number(responseMaxBytes) } : {}),
+    ...(requireMutationApproval !== undefined
+      ? {
+          requireMutationApproval: parseEnvFlag(requireMutationApproval, true),
+        }
+      : {}),
+  };
+}
+
+export async function loadConfig(): Promise<AppConfig> {
+  const fromEnv = loadConfigFromEnv();
+  if (!fromEnv) {
+    throw new Error(CONFIG_HELP);
+  }
+
+  const parsed = ConfigSchema.safeParse(fromEnv);
+  if (!parsed.success) {
+    throw new Error(
+      `Invalid config from environment: ${z.prettifyError(parsed.error)}`,
+    );
+  }
+
+  return parsed.data;
+}
+
+export function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/+$/, '');
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+
+import { loadConfig } from './config.ts';
+import { createServer } from './server.ts';
+
+try {
+  const config = await loadConfig();
+
+  void serveStdio(() => createServer(config));
+
+  console.error('askell-mcp running on stdio');
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`askell-mcp failed to start: ${message}`);
+  process.exit(1);
+}