@skeletiq/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,1674 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+
+// src/config.ts
+var SERVER_NAME = "skeletiq";
+var SERVER_VERSION = "0.1.0";
+var DEFAULT_API_URL = "https://api.skeletiq.com";
+var TOKEN_PREFIX = "skq_";
+var ConfigError = class extends Error {
+};
+function readConfig(env = process.env) {
+  const apiKey = (env.SKELETIQ_API_KEY ?? "").trim();
+  if (!apiKey) {
+    throw new ConfigError(
+      `SKELETIQ_API_KEY is not set. Create a token in SkeletIQ under Settings \u2192 Agent access and put it in this server's env. It needs the "read" scope at minimum; add "generate" to let the agent create designs and "report" to let it check drift.`
+    );
+  }
+  if (!apiKey.startsWith(TOKEN_PREFIX)) {
+    throw new ConfigError(
+      `SKELETIQ_API_KEY does not look like a SkeletIQ API token (they start with "${TOKEN_PREFIX}"). Personal API tokens are created under Settings \u2192 Agent access.`
+    );
+  }
+  return { apiUrl: normalizeApiUrl(env.SKELETIQ_API_URL), apiKey };
+}
+function normalizeApiUrl(raw) {
+  const value = (raw ?? "").trim();
+  if (!value) return DEFAULT_API_URL;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ConfigError(`SKELETIQ_API_URL is not a valid URL: ${value}`);
+  }
+  const path = url.pathname.replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+  return `${url.origin}${path}`;
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/server";
+
+// src/http/errors.ts
+var SkeletiqApiError = class extends Error {
+  status;
+  code;
+  detail;
+  requestId;
+  /** From the `Retry-After` header, in seconds, when the server set one. */
+  retryAfterSeconds;
+  constructor(args) {
+    super(args.message);
+    this.name = "SkeletiqApiError";
+    this.status = args.status;
+    this.code = args.code;
+    this.detail = args.detail;
+    this.requestId = args.requestId;
+    this.retryAfterSeconds = args.retryAfterSeconds;
+  }
+  /**
+   * A `GET` may be retried after a 429; a `POST` that may have spent credits may not.
+   *
+   * A spent daily allowance is the one 429 that is *not* retryable: it refills on a clock
+   * measured in hours, so a caller backing off and trying again is burning its budget on a
+   * call that cannot succeed today.
+   */
+  get isRetryable() {
+    if (this.code === "DAILY_LIMIT_REACHED") return false;
+    return this.status === 429 || this.code === "IDEMPOTENCY_UNAVAILABLE";
+  }
+};
+var SkeletiqNetworkError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "SkeletiqNetworkError";
+  }
+};
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function asString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function parseApiError(status, body, retryAfterSeconds) {
+  const envelope = asRecord(asRecord(body)?.error);
+  const detailRecord = asRecord(envelope?.detail);
+  const detail = detailRecord ?? (Array.isArray(envelope?.detail) ? envelope.detail : void 0);
+  const code = asString(detailRecord?.code) ?? asString(envelope?.code) ?? `HTTP_${status}`;
+  const message = asString(detailRecord?.message) ?? asString(detailRecord?.error) ?? asString(envelope?.message) ?? `SkeletIQ returned HTTP ${status}.`;
+  return new SkeletiqApiError({
+    status,
+    code,
+    message,
+    detail,
+    requestId: asString(envelope?.request_id),
+    retryAfterSeconds
+  });
+}
+function describeApiError(error) {
+  const lines = [];
+  const detail = asRecord(error.detail);
+  switch (error.code) {
+    case "SESSION_AUTH_REQUIRED":
+      lines.push(
+        "That operation is not available to API tokens at all \u2014 it needs a signed-in browser session. A wider token will not help; ask the user to do it in the SkeletIQ app."
+      );
+      break;
+    case "INSUFFICIENT_SCOPE": {
+      const required = asString(detail?.required_scope);
+      lines.push(
+        required ? `This API token does not carry the "${required}" scope.` : "This API token is not wide enough for that operation."
+      );
+      lines.push(
+        "Ask the user to mint a new token under Settings \u2192 Agent access with that scope ticked, and update SKELETIQ_API_KEY."
+      );
+      break;
+    }
+    case "INSUFFICIENT_CREDITS": {
+      lines.push(error.message);
+      const balance = detail?.balance;
+      const required = detail?.required;
+      if (typeof balance === "number" && typeof required === "number") {
+        lines.push(`Balance ${balance}, this run needs up to ${required}.`);
+      }
+      const solutions = detail?.solutions;
+      if (Array.isArray(solutions)) {
+        for (const solution of solutions) {
+          if (typeof solution === "string") lines.push(`- ${solution}`);
+        }
+      }
+      break;
+    }
+    case "DAILY_LIMIT_REACHED": {
+      lines.push(error.message);
+      const resetAt = asString(detail?.reset_at);
+      if (resetAt) lines.push(`The allowance refills at ${resetAt}.`);
+      const upgradeUrl = asString(detail?.upgrade_url);
+      if (upgradeUrl) lines.push(`A larger plan raises the daily limit: ${upgradeUrl}`);
+      break;
+    }
+    case "PLAN_LIMIT_EXCEEDED":
+    case "FEATURE_NOT_AVAILABLE":
+    case "VERSION_LOCKED": {
+      lines.push(error.message);
+      const upgradeUrl = asString(detail?.upgrade_url);
+      if (upgradeUrl) lines.push(`Upgrade: ${upgradeUrl}`);
+      break;
+    }
+    case "BACKGROUND_JOBS_UNAVAILABLE":
+      lines.push(
+        "This SkeletIQ deployment runs no background worker, so a generation cannot be queued. Call generate_architecture again with wait: true and it will run inline."
+      );
+      break;
+    case "IDEMPOTENCY_UNAVAILABLE":
+      lines.push(
+        "SkeletIQ could not confirm this was not a duplicate request, so it refused it. Nothing was started and nothing was charged \u2014 retrying is safe."
+      );
+      break;
+    case "JOB_QUEUE_FULL": {
+      const wait = detail?.retry_after_seconds;
+      lines.push("SkeletIQ's generation queue is full.");
+      if (typeof wait === "number") lines.push(`Try again in about ${wait} seconds.`);
+      break;
+    }
+    case "ACTIVE_GENERATION_EXISTS":
+      lines.push(
+        "A generation is already running for this account. Wait for it to finish \u2014 get_generation_status will tell you when \u2014 before starting another."
+      );
+      break;
+    case "RATE_LIMITED":
+      lines.push(error.message);
+      if (error.retryAfterSeconds !== void 0) {
+        lines.push(`Retry after ${error.retryAfterSeconds} seconds.`);
+      }
+      break;
+    default:
+      if (error.status === 401) {
+        lines.push(
+          "SkeletIQ rejected the API token. It may be wrong, revoked or expired \u2014 SkeletIQ answers all three identically, so there is nothing more specific to report. Check SKELETIQ_API_KEY, or mint a new token under Settings \u2192 Agent access."
+        );
+      } else {
+        lines.push(error.message);
+      }
+  }
+  if (error.requestId) lines.push(`(SkeletIQ request id: ${error.requestId})`);
+  return lines.join("\n");
+}
+
+// src/http/client.ts
+var API_PREFIX = "/api/v1";
+var READ_TIMEOUT_MS = 6e5;
+var SkeletiqClient = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /** A parsed JSON response, or a thrown `SkeletiqApiError` carrying the server's own words. */
+  async request(path, options = {}) {
+    const response = await this.fetch(path, options);
+    const text = await response.text();
+    return text ? JSON.parse(text) : void 0;
+  }
+  /** The raw `Response`, for the one caller that reads a stream rather than a body. */
+  async fetch(path, options = {}) {
+    const url = this.url(path, options.query);
+    const timeout = AbortSignal.timeout(READ_TIMEOUT_MS);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let response;
+    try {
+      response = await fetch(url, {
+        method: options.method ?? "GET",
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          Accept: "application/json",
+          "User-Agent": `${SERVER_NAME}-mcp/${SERVER_VERSION}`,
+          ...options.body === void 0 ? {} : { "Content-Type": "application/json" },
+          ...options.headers
+        },
+        body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+        signal
+      });
+    } catch (cause) {
+      if (options.signal?.aborted) throw cause;
+      throw new SkeletiqNetworkError(`Could not reach SkeletIQ at ${this.config.apiUrl}.`, { cause });
+    }
+    if (!response.ok) throw await this.toError(response);
+    return response;
+  }
+  url(path, query) {
+    const url = new URL(`${this.config.apiUrl}${API_PREFIX}${path}`);
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value !== void 0 && value !== "") url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+  async toError(response) {
+    let body;
+    try {
+      body = JSON.parse(await response.text());
+    } catch {
+      body = void 0;
+    }
+    return parseApiError(response.status, body, parseRetryAfter(response));
+  }
+};
+function parseRetryAfter(response) {
+  const header = response.headers.get("retry-after");
+  if (!header) return void 0;
+  const seconds = Number.parseInt(header, 10);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : void 0;
+}
+
+// src/wire/schemas.ts
+import * as z from "zod/v4";
+var ReleaseFactsSchema = z.looseObject({
+  is_released: z.boolean(),
+  released_at: z.string().nullable().optional(),
+  latest_release_version: z.number().nullable().optional(),
+  newer_release_exists: z.boolean(),
+  newer_draft_exists: z.boolean()
+});
+var ProjectSchema = z.looseObject({
+  id: z.string(),
+  title: z.string(),
+  description: z.string().nullable().optional(),
+  tags: z.array(z.string()).nullable().optional(),
+  team_id: z.string().nullable().optional(),
+  architecture_count: z.number().optional(),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional()
+});
+var ProjectListSchema = z.looseObject({
+  projects: z.array(ProjectSchema),
+  total: z.number(),
+  page: z.number().optional(),
+  page_size: z.number().optional()
+});
+var ComponentSchema = z.looseObject({
+  id: z.string(),
+  name: z.string(),
+  type: z.string(),
+  description: z.string().nullable().optional(),
+  technology: z.string().nullable().optional(),
+  role: z.string().nullable().optional(),
+  /** Why the component is in the design (`core`, `security`, …) — see the API's `component_concerns`. */
+  concern: z.string().nullable().optional(),
+  requirement_ids: z.array(z.string()).nullable().optional()
+});
+var ConnectionSchema = z.looseObject({
+  id: z.string().nullable().optional(),
+  source: z.string(),
+  target: z.string(),
+  label: z.string().nullable().optional(),
+  protocol: z.string().nullable().optional(),
+  is_async: z.boolean().optional()
+});
+var GapEntrySchema = z.union([
+  z.string(),
+  z.looseObject({
+    text: z.string(),
+    recommendation: z.string().nullable().optional(),
+    options: z.array(z.string()).nullable().optional(),
+    impact: z.string().nullable().optional()
+  })
+]);
+var ArchitectureJsonSchema = z.looseObject({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  components: z.array(ComponentSchema).optional(),
+  connections: z.array(ConnectionSchema).optional(),
+  design_decisions: z.array(z.string()).nullable().optional(),
+  trade_offs: z.array(z.string()).nullable().optional(),
+  scalability_notes: z.string().nullable().optional(),
+  assumptions: z.array(GapEntrySchema).nullable().optional(),
+  open_questions: z.array(GapEntrySchema).nullable().optional()
+});
+var ArchitectureSchema = z.looseObject({
+  id: z.string(),
+  project_id: z.string(),
+  prompt: z.string().optional(),
+  architecture_json: ArchitectureJsonSchema,
+  version: z.number(),
+  status: z.string().optional(),
+  created_at: z.string().optional(),
+  updated_at: z.string().optional(),
+  is_released: z.boolean().optional(),
+  released_at: z.string().nullable().optional()
+});
+var ArchitecturePageSchema = z.looseObject({
+  items: z.array(ArchitectureSchema),
+  total: z.number(),
+  limit: z.number().optional(),
+  offset: z.number().optional()
+});
+var BriefSchema = z.looseObject({
+  architecture_id: z.string(),
+  version: z.number(),
+  is_draft: z.boolean(),
+  markdown: z.string(),
+  release: ReleaseFactsSchema
+});
+var BuildStepSchema = z.looseObject({
+  order: z.number(),
+  component_id: z.string(),
+  name: z.string(),
+  type: z.string(),
+  role: z.string().nullable().optional(),
+  technology: z.string().nullable().optional(),
+  reason: z.string(),
+  depends_on: z.array(z.string()).optional(),
+  /** The `depends_on` entries built *after* this step — non-empty only where the design cycles. */
+  blocked_by: z.array(z.string()).optional()
+});
+var BuildOrderSchema = z.looseObject({
+  architecture_id: z.string(),
+  version: z.number(),
+  steps: z.array(BuildStepSchema),
+  release: ReleaseFactsSchema
+});
+var ReadinessRowSchema = z.looseObject({
+  key: z.string(),
+  label: z.string(),
+  count: z.number(),
+  // Three states, not two. `unknown` is a *settled* answer meaning the check never ran — never
+  // render it as a zero, which would claim a check passed that was never performed.
+  state: z.string(),
+  category: z.string(),
+  gating: z.boolean(),
+  detail: z.string().nullable().optional()
+});
+var ReadinessSchema = z.looseObject({
+  architecture_id: z.string(),
+  version: z.number(),
+  /** `verdict === 'ready'`. Kept for callers that only want the boolean. */
+  ready: z.boolean(),
+  /**
+   * Three values, not two. `unanswered` means every gate is clear but at least one
+   * could not be answered for this version — a state that reports `ready: false`
+   * while no row is `gating`, so a renderer keyed on `gating` alone says "0 of 6
+   * gates still open" and means nothing by it.
+   *
+   * Optional so a server that predates the field parses rather than throwing; the
+   * caller falls back to the boolean.
+   */
+  verdict: z.enum(["ready", "outstanding", "unanswered"]).optional(),
+  unknown_gate_count: z.number().optional(),
+  /** Keys of advisory rows whose check never ran. Named, never counted. */
+  unrun_checks: z.array(z.string()).optional(),
+  rows: z.array(ReadinessRowSchema),
+  release: ReleaseFactsSchema
+});
+var DesignGapSchema = z.looseObject({
+  gap_id: z.string(),
+  kind: z.string(),
+  text: z.string(),
+  resolved: z.boolean(),
+  action: z.string().nullable().optional(),
+  note: z.string().nullable().optional(),
+  adr_id: z.string().nullable().optional()
+});
+var DesignGapListSchema = z.looseObject({
+  project_id: z.string(),
+  architecture_id: z.string().nullable().optional(),
+  version: z.number().nullable().optional(),
+  gaps: z.array(DesignGapSchema),
+  unresolved_count: z.number()
+});
+var ComponentRefSchema = z.looseObject({
+  id: z.string(),
+  name: z.string(),
+  type: z.string()
+});
+var UnknownIdSchema = z.looseObject({
+  id: z.string(),
+  suggestions: z.array(ComponentRefSchema).optional()
+});
+var DriftSchema = z.looseObject({
+  architecture_id: z.string(),
+  version: z.number(),
+  in_sync: z.boolean(),
+  missing: z.array(ComponentRefSchema),
+  unreported: z.array(ComponentRefSchema),
+  partial: z.array(ComponentRefSchema),
+  elsewhere: z.array(ComponentRefSchema),
+  unknown_ids: z.array(UnknownIdSchema),
+  extra_components: z.array(z.looseObject({ name: z.string() })),
+  extra_connections: z.array(z.looseObject({ source: z.string(), target: z.string() })),
+  counts: z.record(z.string(), z.number()),
+  release: ReleaseFactsSchema
+});
+var CritiqueFindingSchema = z.looseObject({
+  message: z.string(),
+  pattern_id: z.string(),
+  category: z.string(),
+  severity: z.string().optional(),
+  affected_components: z.array(z.string()).optional(),
+  evidence: z.string().optional(),
+  remediation: z.string().optional()
+});
+var PayloadCritiqueSchema = z.looseObject({
+  architecture_score: z.number(),
+  security_score: z.number(),
+  performance_score: z.number(),
+  resilience_score: z.number(),
+  data_score: z.number(),
+  findings: z.array(CritiqueFindingSchema),
+  bottlenecks: z.array(z.string()).optional(),
+  risks: z.array(z.string()).optional(),
+  recommendations: z.array(z.string()).optional(),
+  strengths: z.array(z.string()).optional(),
+  compliance_assessed: z.boolean().optional(),
+  frameworks_checked: z.array(z.string()).optional(),
+  compliance_note: z.string().nullable().optional(),
+  exposure_assessed: z.string().optional()
+});
+var ClarifyingQuestionSchema = z.looseObject({
+  id: z.string(),
+  question: z.string(),
+  why: z.string().optional(),
+  kind: z.string().optional(),
+  options: z.array(z.string()).nullable().optional(),
+  decline_options: z.array(z.string()).nullable().optional()
+});
+var IntentDecisionSchema = z.looseObject({
+  intent: z.string().optional(),
+  reason: z.string().optional(),
+  new_project_recommended: z.boolean().optional(),
+  clarifying_questions: z.array(ClarifyingQuestionSchema).nullable().optional()
+});
+var GenerateResponseSchema = z.looseObject({
+  response_mode: z.string().optional(),
+  model_used: z.string().optional(),
+  conversation_id: z.string().optional(),
+  architecture: ArchitectureJsonSchema.nullable().optional(),
+  architecture_id: z.string().nullable().optional(),
+  architecture_version: z.number().nullable().optional(),
+  assistant_message: z.string().nullable().optional(),
+  degradations: z.array(z.string()).optional()
+});
+var DecisionRefusalSchema = z.looseObject({
+  kind: z.literal("decision_refusal"),
+  code: z.string(),
+  response_mode: z.string().optional(),
+  intent: z.string().optional(),
+  new_project_recommended: z.boolean().optional(),
+  clarifying_questions: z.array(ClarifyingQuestionSchema).optional()
+});
+var JobProgressSchema = z.looseObject({
+  data: z.looseObject({ failure_detail: z.unknown().optional() }).optional()
+});
+var JobSchema = z.looseObject({
+  job_id: z.string(),
+  status: z.string(),
+  project_id: z.string().nullable().optional(),
+  architecture_id: z.string().nullable().optional(),
+  conversation_id: z.string().nullable().optional(),
+  prompt: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  started_at: z.string().nullable().optional(),
+  completed_at: z.string().nullable().optional(),
+  error: z.string().nullable().optional(),
+  progress: z.unknown().optional(),
+  queue_state: z.string().optional()
+});
+var GenerateAsyncSchema = z.looseObject({
+  job_id: z.string(),
+  status: z.string(),
+  job: JobSchema.optional()
+});
+
+// src/lib/resolve.ts
+var AmbiguousProjectError = class extends Error {
+  candidates;
+  constructor(query, candidates) {
+    super(`"${query}" matches ${candidates.length} SkeletIQ projects.`);
+    this.name = "AmbiguousProjectError";
+    this.candidates = candidates;
+  }
+};
+var PROJECT_PAGE_SIZE = 50;
+var ARCHITECTURE_PAGE_SIZE = 100;
+var DesignResolver = class {
+  client;
+  versions = /* @__PURE__ */ new Map();
+  designs = /* @__PURE__ */ new Map();
+  constructor(client) {
+    this.client = client;
+  }
+  async listProjects(query) {
+    const body = await this.client.request("/projects/", {
+      query: { page_size: PROJECT_PAGE_SIZE, search: query }
+    });
+    return ProjectListSchema.parse(body).projects;
+  }
+  /**
+   * A project id, or the candidates that stopped us being sure.
+   *
+   * An exact (case-insensitive) title match settles it even when other titles contain the same
+   * words — "Payments" should not be ambiguous just because "Payments v2" exists.
+   */
+  async resolveProject(idOrQuery) {
+    if (isUuid(idOrQuery)) {
+      const body = await this.client.request(`/projects/${idOrQuery}`);
+      return ProjectListSchema.shape.projects.element.parse(body);
+    }
+    const candidates = await this.listProjects(idOrQuery);
+    if (candidates.length === 0) throw new Error(`No SkeletIQ project matches "${idOrQuery}".`);
+    if (candidates.length === 1) return candidates[0];
+    const exact = candidates.filter((p) => p.title.toLowerCase() === idOrQuery.toLowerCase());
+    if (exact.length === 1) return exact[0];
+    throw new AmbiguousProjectError(idOrQuery, candidates);
+  }
+  /** Every version of a project, newest first. Cached: one call serves a whole session. */
+  async versionsFor(projectId) {
+    const cached = this.versions.get(projectId);
+    if (cached) return cached;
+    const body = await this.client.request(`/projects/${projectId}/architectures`, {
+      query: { limit: ARCHITECTURE_PAGE_SIZE, offset: 0 }
+    });
+    const items = [...ArchitecturePageSchema.parse(body).items].sort((a, b) => b.version - a.version);
+    this.versions.set(projectId, items);
+    for (const item of items) this.designs.set(item.id, item);
+    return items;
+  }
+  /** The version rule. */
+  async resolveVersion(projectId, requested) {
+    const versions = await this.versionsFor(projectId);
+    if (versions.length === 0) {
+      throw new Error(
+        "That SkeletIQ project has no architecture versions yet. Run generate_architecture against it first."
+      );
+    }
+    const latestReleaseVersion = versions.find((v) => v.is_released)?.version;
+    let chosen;
+    let resolvedBy;
+    if (requested !== void 0) {
+      chosen = versions.find((v) => v.version === requested);
+      resolvedBy = "requested";
+      if (!chosen) {
+        const available = versions.map((v) => v.version).reverse().join(", ");
+        throw new Error(
+          `That SkeletIQ project has no version ${requested}. Available versions: ${available}. (On the free plan older unreleased versions are outside the readable window.)`
+        );
+      }
+    } else if (latestReleaseVersion !== void 0) {
+      chosen = versions.find((v) => v.version === latestReleaseVersion);
+      resolvedBy = "latest_release";
+    } else {
+      chosen = versions[0];
+      resolvedBy = "latest_version";
+    }
+    const target = chosen;
+    return {
+      architectureId: target.id,
+      version: target.version,
+      isReleased: target.is_released === true,
+      newerReleaseExists: latestReleaseVersion !== void 0 && latestReleaseVersion > target.version,
+      resolvedBy
+    };
+  }
+  /**
+   * The full design for one version.
+   *
+   * The list response already carries `architecture_json`, so the cache seeded by
+   * `versionsFor` usually answers this without a second request.
+   */
+  async design(architectureId) {
+    const cached = this.designs.get(architectureId);
+    if (cached) return cached;
+    const body = await this.client.request(`/architectures/${architectureId}`);
+    const design = ArchitectureSchema.parse(body);
+    this.designs.set(architectureId, design);
+    return design;
+  }
+};
+function factsFrom(resolved) {
+  return {
+    version: resolved.version,
+    is_released: resolved.isReleased,
+    newer_release_exists: resolved.newerReleaseExists,
+    resolved_by: resolved.resolvedBy
+  };
+}
+function factsFromRelease(resolved, release) {
+  return {
+    version: resolved.version,
+    is_released: release.is_released,
+    newer_release_exists: release.newer_release_exists,
+    resolved_by: resolved.resolvedBy
+  };
+}
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(value) {
+  return UUID.test(value.trim());
+}
+
+// src/tools/check-drift.ts
+import * as z2 from "zod/v4";
+
+// src/lib/result.ts
+function ok(structured, text) {
+  return { content: [{ type: "text", text }], structuredContent: structured };
+}
+function failure(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+async function guard(run) {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof SkeletiqApiError) return failure(describeApiError(error));
+    if (error instanceof SkeletiqNetworkError) return failure(error.message);
+    if (error instanceof AmbiguousProjectError) {
+      const lines = [
+        error.message,
+        "Ask which one, and call again with the id:",
+        ...error.candidates.map((project) => `- ${project.title} (${project.id})`)
+      ];
+      return failure(lines.join("\n"));
+    }
+    return failure(error instanceof Error ? error.message : String(error));
+  }
+}
+function versionLine(facts) {
+  const state = facts.is_released ? "released" : "DRAFT \u2014 not released, and may change without notice";
+  const line = `Version ${facts.version} (${state}).`;
+  return facts.newer_release_exists ? `${line} A newer version has since been released \u2014 re-read the design before relying on this.` : line;
+}
+
+// src/tools/check-drift.ts
+var input = z2.object({
+  project_id: z2.string().describe("A SkeletIQ project id, or its exact name."),
+  version: z2.number().int().positive().optional().describe(
+    "The version you built from \u2014 the `version=` stamped in the AGENTS.md fence. Defaults to the latest released version. Component ids are only meaningful within one version."
+  ),
+  covers: z2.array(z2.string()).max(500).optional().describe(
+    "The component ids this repository is responsible for. Omit only when this repo implements the whole design \u2014 otherwise everything you leave out is reported as missing."
+  ),
+  components: z2.array(
+    z2.object({
+      id: z2.string().max(200).describe("The component id from the design."),
+      name: z2.string().max(255).optional().describe("The component name, which survives a regeneration when the id does not."),
+      status: z2.enum(["implemented", "partial", "not_started"]),
+      note: z2.string().max(2e3).optional()
+    })
+  ).max(500).describe("What you built. Report every component in `covers`, including the ones not started."),
+  extra_components: z2.array(
+    z2.object({
+      name: z2.string().max(255),
+      type: z2.string().max(64).optional(),
+      technology: z2.string().max(255).optional()
+    })
+  ).max(200).optional().describe("Things in the code that the design does not contain."),
+  extra_connections: z2.array(
+    z2.object({
+      source: z2.string().max(255),
+      target: z2.string().max(255),
+      protocol: z2.string().max(64).optional()
+    })
+  ).max(500).optional().describe("Edges in the code the design does not have. Endpoints may be component ids or names.")
+});
+var refs = z2.array(z2.object({ id: z2.string(), name: z2.string(), type: z2.string() }));
+var output = z2.object({
+  architecture_id: z2.string(),
+  version: z2.number(),
+  is_released: z2.boolean(),
+  newer_release_exists: z2.boolean(),
+  resolved_by: z2.string(),
+  in_sync: z2.boolean(),
+  missing: refs,
+  unreported: refs,
+  partial: refs,
+  elsewhere: refs,
+  unknown_ids: z2.array(z2.object({ id: z2.string(), suggestions: refs })),
+  counts: z2.record(z2.string(), z2.number())
+});
+function registerCheckDrift(server, client, resolver) {
+  server.registerTool(
+    "check_drift",
+    {
+      title: "Report build progress and check drift",
+      description: "Tell SkeletIQ which components you have built and get back what is missing, what is only half done, and what exists in the code but not in the design. Declare `covers` when this repository implements only part of the design. This changes nothing in SkeletIQ \u2014 an agent never writes back to a design.",
+      inputSchema: input,
+      outputSchema: output,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
+    },
+    async ({ project_id, version, covers, components, extra_components, extra_connections }) => guard(async () => {
+      const project = await resolver.resolveProject(project_id);
+      const resolved = await resolver.resolveVersion(project.id, version);
+      const report = DriftSchema.parse(
+        await client.request(`/architectures/${resolved.architectureId}/drift-check`, {
+          method: "POST",
+          body: {
+            covers: covers ?? null,
+            components,
+            extra_components: extra_components ?? null,
+            extra_connections: extra_connections ?? null
+          }
+        })
+      );
+      const facts = factsFromRelease(resolved, report.release);
+      const structured = {
+        architecture_id: report.architecture_id,
+        ...facts,
+        in_sync: report.in_sync,
+        missing: report.missing,
+        unreported: report.unreported,
+        partial: report.partial,
+        elsewhere: report.elsewhere,
+        unknown_ids: report.unknown_ids.map((entry) => ({
+          id: entry.id,
+          suggestions: entry.suggestions ?? []
+        })),
+        counts: report.counts
+      };
+      const lines = [];
+      lines.push(
+        report.in_sync ? "In sync \u2014 everything this repository covers is built as designed." : "Drift found:"
+      );
+      push(lines, "Not started", report.missing, report.counts.missing);
+      push(lines, "Half built", report.partial, report.counts.partial);
+      push(lines, "You did not mention", report.unreported, report.counts.unreported);
+      if (report.extra_components.length) {
+        lines.push(`In the code but not the design: ${report.extra_components.map((c) => c.name).join(", ")}`);
+      }
+      if (report.extra_connections.length) {
+        lines.push(
+          `Connections the design does not have: ${report.extra_connections.map((c) => `${c.source} \u2192 ${c.target}`).join(", ")}`
+        );
+      }
+      if (report.unknown_ids.length) {
+        lines.push("");
+        lines.push(
+          `${report.unknown_ids.length} id(s) are not in version ${report.version}. Ids are minted per version, so a regeneration voids them. These are suggestions \u2014 confirm with a person before treating any of them as the same component:`
+        );
+        for (const entry of report.unknown_ids) {
+          const suggestions = (entry.suggestions ?? []).map((s) => `${s.name} (${s.id})`).join(", ");
+          lines.push(`- ${entry.id} \u2192 ${suggestions || "nothing similar in this version"}`);
+        }
+      }
+      if (report.elsewhere.length) {
+        lines.push("");
+        lines.push(
+          `${report.elsewhere.length} component(s) are outside this repository's declared scope. That is not drift \u2014 they are built elsewhere, or not yet.`
+        );
+      }
+      lines.push("");
+      lines.push(versionLine(facts));
+      return ok(structured, lines.join("\n"));
+    })
+  );
+}
+function push(lines, label, refs2, total) {
+  if (refs2.length === 0) return;
+  const shown = refs2.map((ref) => `${ref.name} (${ref.id})`).join(", ");
+  const more = total !== void 0 && total > refs2.length ? ` \u2014 and ${total - refs2.length} more` : "";
+  lines.push(`${label} (${total ?? refs2.length}): ${shown}${more}`);
+}
+
+// src/tools/critique.ts
+import * as z3 from "zod/v4";
+var input2 = z3.object({
+  architecture_json: z3.looseObject({
+    title: z3.string(),
+    description: z3.string(),
+    components: z3.array(z3.looseObject({ id: z3.string(), name: z3.string(), type: z3.string() })),
+    connections: z3.array(z3.looseObject({ source: z3.string(), target: z3.string() }))
+  }).optional().describe(
+    "A design to check. Free and deterministic \u2014 no model call. The shape SkeletIQ uses: title, description, components[{id,name,type,technology?}], connections[{source,target,protocol?}]."
+  ),
+  domain: z3.string().optional().describe(
+    "The design's domain \u2014 e-commerce, fintech, healthcare, saas, social, iot, gaming, infrastructure, streaming, logistics, ai-ml, search, data-analytics, content-platform, internal-tool. Worth sending: the domain is what selects the compliance frameworks to check against, and without it none apply, so no compliance finding is possible and the score comes back higher than the SkeletIQ app would show for the same design \u2014 by up to 15 points."
+  ),
+  secondary_domains: z3.array(z3.string()).max(8).optional().describe(
+    "Further domains the design spans, when it spans more than one \u2014 a multi-tenant shop that takes payments is e-commerce plus fintech and saas. These select frameworks on top of the primary domain's, so leaving them off is why a design already checked against SOC2 and SOX in the app comes back here checked against neither, and scored higher for it. frameworks_checked says which were actually used."
+  ),
+  exposure: z3.enum(["public_internet", "private_network", "air_gapped"]).optional().describe(
+    "Where the design runs. Worth sending: four checks \u2014 CDN, WAF, rate limiting and multi-region \u2014 ask whether traffic arriving from the public internet is handled safely, and they only apply to a system that takes any. Left unset, the design is assessed as internet-facing, which is why an air-gapped design comes back told to add a CDN. exposure_assessed says which exposure was actually used."
+  )
+});
+var SCORE_BASIS_FINDINGS_ONLY = "findings_only";
+var SCORE_BASIS_NOTE = "This score is findings only. It is not held to a traceability ceiling, because this tool is given a design and no requirement set to trace it against. The app can show a lower number for the same stored design for exactly that reason.";
+var output2 = z3.object({
+  architecture_score: z3.number(),
+  score_basis: z3.literal(SCORE_BASIS_FINDINGS_ONLY).describe(SCORE_BASIS_NOTE),
+  security_score: z3.number(),
+  performance_score: z3.number(),
+  resilience_score: z3.number(),
+  data_score: z3.number(),
+  findings: z3.array(
+    z3.object({
+      severity: z3.string(),
+      category: z3.string(),
+      message: z3.string(),
+      affected_components: z3.array(z3.string()),
+      remediation: z3.string()
+    })
+  ),
+  finding_count: z3.number(),
+  compliance_assessed: z3.boolean().describe("False means no compliance framework was checked, so no compliance finding was possible."),
+  frameworks_checked: z3.array(z3.string()),
+  compliance_note: z3.string().nullable(),
+  exposure_assessed: z3.string().describe(
+    "The exposure this critique was actually run under. An absent or unreadable exposure is assessed as public_internet, so a value the server could not read shows up here rather than arriving silently as four extra security findings."
+  )
+});
+var SEVERITY_ORDER = ["critical", "high", "medium", "low", "info"];
+function registerCritique(server, client) {
+  server.registerTool(
+    "critique_architecture",
+    {
+      title: "Critique an architecture",
+      description: "Check a design against SkeletIQ's architecture rules and get scored findings back. Deterministic and free \u2014 no model call, no credits, nothing stored. Useful on a design you drafted yourself before committing to it.",
+      inputSchema: input2,
+      outputSchema: output2,
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }
+    },
+    async ({ architecture_json, domain, secondary_domains, exposure }) => guard(async () => {
+      if (!architecture_json) {
+        throw new Error(
+          "critique_architecture needs an architecture_json to check. If you only have a plan in prose, run generate_architecture first \u2014 that spends credits, so say so before you do it."
+        );
+      }
+      const critique = PayloadCritiqueSchema.parse(
+        await client.request("/handoff/critique", {
+          method: "POST",
+          body: { architecture_json, domain, secondary_domains, exposure }
+        })
+      );
+      const findings = [...critique.findings].sort((a, b) => rank(a.severity) - rank(b.severity)).map((finding) => ({
+        severity: finding.severity ?? "medium",
+        category: finding.category,
+        message: finding.message,
+        affected_components: finding.affected_components ?? [],
+        remediation: finding.remediation ?? ""
+      }));
+      const complianceAssessed = critique.compliance_assessed ?? false;
+      const exposureAssessed = critique.exposure_assessed ?? "public_internet";
+      const structured = {
+        architecture_score: critique.architecture_score,
+        score_basis: SCORE_BASIS_FINDINGS_ONLY,
+        security_score: critique.security_score,
+        performance_score: critique.performance_score,
+        resilience_score: critique.resilience_score,
+        data_score: critique.data_score,
+        findings,
+        finding_count: findings.length,
+        compliance_assessed: complianceAssessed,
+        frameworks_checked: critique.frameworks_checked ?? [],
+        compliance_note: critique.compliance_note ?? null,
+        exposure_assessed: exposureAssessed
+      };
+      const lines = [
+        `Architecture ${round(critique.architecture_score)}/100 \xB7 security ${round(critique.security_score)} \xB7 performance ${round(critique.performance_score)} \xB7 resilience ${round(critique.resilience_score)} \xB7 data ${round(critique.data_score)}`,
+        SCORE_BASIS_NOTE,
+        "",
+        // An agent that reads only the text has to see this too. Without it, "the app
+        // said 59 and the tool said 74" is an unexplained contradiction it will either
+        // resolve wrongly or report as a bug.
+        complianceAssessed ? `Compliance checked against ${(critique.frameworks_checked ?? []).join(", ")} \u2014 the frameworks systems in this domain are usually held to, inferred from the domain you sent rather than from a regime anyone named. Confirm them.` : critique.compliance_note ?? "Compliance was not assessed.",
+        // Only when the exposure used is not the one the agent chose. When a
+        // non-public exposure *was* applied the server returns an
+        // `exposure_scoped_checks` finding naming exactly which checks it took off
+        // the table, and restating that list here would be a second copy to drift.
+        ...exposureLines(exposure, exposureAssessed),
+        "",
+        findings.length === 0 ? "No findings." : `${findings.length} finding(s):`,
+        ...findings.map(
+          (finding) => `- [${finding.severity}] ${finding.message}` + (finding.affected_components.length ? ` (${finding.affected_components.join(", ")})` : "") + (finding.remediation ? `
+  Fix: ${finding.remediation}` : "")
+        )
+      ];
+      return ok(structured, lines.join("\n"));
+    })
+  );
+}
+function exposureLines(requested, assessed) {
+  if (requested === void 0) {
+    return [
+      'Assessed as internet-facing, because no exposure was sent. Four checks \u2014 CDN, WAF, rate limiting and multi-region \u2014 only apply to a system that takes traffic from the public internet; send exposure: "private_network" or "air_gapped" if this one does not.'
+    ];
+  }
+  if (requested !== assessed) {
+    return [
+      `You sent exposure "${requested}" but the critique was run as ${assessed} \u2014 this SkeletIQ server did not apply it, which one predating the exposure axis does. The CDN, WAF, rate-limiting and multi-region checks therefore ran as though the design were internet-facing.`
+    ];
+  }
+  return [];
+}
+function rank(severity) {
+  const index = SEVERITY_ORDER.indexOf((severity ?? "medium").toLowerCase());
+  return index === -1 ? SEVERITY_ORDER.length : index;
+}
+function round(value) {
+  return Math.round(value * 10) / 10;
+}
+
+// src/tools/generate.ts
+import { randomUUID } from "crypto";
+import * as z4 from "zod/v4";
+
+// src/http/sse.ts
+async function* readSseFrames(response) {
+  const body = response.body;
+  if (!body) return;
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let boundary = buffer.indexOf("\n\n");
+    while (boundary !== -1) {
+      const record4 = buffer.slice(0, boundary);
+      buffer = buffer.slice(boundary + 2);
+      const frame = parseRecord(record4);
+      if (frame) yield frame;
+      boundary = buffer.indexOf("\n\n");
+    }
+  }
+  const trailing = parseRecord(buffer);
+  if (trailing) yield trailing;
+}
+function parseRecord(record4) {
+  const data = record4.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+  if (!data) return null;
+  try {
+    const parsed = JSON.parse(data);
+    if (parsed && typeof parsed === "object" && typeof parsed.type === "string") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+
+// src/tools/generate.ts
+var PROGRESS_LABELS = {
+  analysis: "Analysing requirements",
+  patterns: "Selecting architecture patterns",
+  generating: "Generating the design",
+  validation: "Validating the design",
+  refining: "Refining the design"
+};
+var PROGRESS_TOTAL = Object.keys(PROGRESS_LABELS).length + 1;
+var PROVENANCE_LABELS = {
+  user_supplied: "stated",
+  llm_inferred: "inferred",
+  tier_default: "assumed",
+  guardrail_clamped: "adjusted"
+};
+function asRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function asText(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return typeof value === "string" && value.trim() && value !== "unknown" ? value.trim() : void 0;
+}
+function frameDetail(frame) {
+  const data = asRecord2(frame.pipeline_step);
+  if (!data) return void 0;
+  const parts = [];
+  const domain = asText(data.domain);
+  if (domain) parts.push(domain);
+  const rps = asText(data.requests_per_second);
+  const figure = rps ? `${rps} rps` : asText(data.scale);
+  if (figure) {
+    const source = asText(data.scale_source);
+    const label = source ? PROVENANCE_LABELS[source] ?? source : void 0;
+    parts.push(label ? `${figure} (${label})` : figure);
+  }
+  return parts.length > 0 ? parts.join(", ") : void 0;
+}
+var constraintsInput = z4.strictObject({
+  budget: z4.enum(["low", "medium", "high", "unlimited"]).optional(),
+  max_latency_ms: z4.number().int().positive().optional(),
+  compliance: z4.array(z4.string()).optional().describe("e.g. HIPAA, SOC2, PCI-DSS, GDPR"),
+  preferred_cloud: z4.enum(["aws", "gcp", "azure", "any"]).optional(),
+  preferred_technologies: z4.array(z4.string()).optional(),
+  max_components: z4.number().int().positive().optional(),
+  read_write_mix: z4.enum(["read_heavy", "balanced", "write_heavy"]).optional().describe("Nothing reads this from the prompt. Unset, the design assumes 80% reads."),
+  burstiness: z4.enum(["steady", "daily_peaks", "spiky"]).optional().describe("Nothing reads this from the prompt. Unset, the design assumes the tier default peak."),
+  data_retention: z4.enum(["days", "months", "years", "indefinite"]).optional(),
+  consistency: z4.enum(["strict", "eventual", "mixed"]).optional(),
+  data_residency: z4.enum(["any", "us", "eu"]).optional()
+});
+var generateInput = z4.object({
+  prompt: z4.string().min(1).max(2e4).describe("What to design. Describe the system, its scale and its constraints in prose."),
+  project_id: z4.string().optional().describe("An existing SkeletIQ project id to add a version to. Omit to start a new project."),
+  wait: z4.boolean().optional().describe(
+    "Default true: run inline and return the finished design (this takes several minutes). False queues it as a background job and returns a job_id to poll \u2014 not available on every deployment."
+  ),
+  clarification_answers: z4.record(z4.string(), z4.string()).optional().describe(
+    'Answers to the questions a previous call returned with status "clarification_required", keyed by their ids. Treated as authoritative requirements, so send what the user told you \u2014 ask them rather than guessing.'
+  ),
+  constraints: constraintsInput.optional().describe(
+    "Facts about the design that the prose does not have to carry. Anything omitted is assumed by SkeletIQ, and the design says which values were assumed."
+  )
+});
+var generateOutput = z4.object({
+  status: z4.string().describe("completed | clarification_required, or the queue state on wait: false"),
+  project_id: z4.string().nullable(),
+  architecture_id: z4.string().nullable(),
+  version: z4.number().nullable(),
+  job_id: z4.string().nullable(),
+  title: z4.string().nullable(),
+  component_count: z4.number().nullable(),
+  assistant_message: z4.string().nullable(),
+  degradations: z4.array(z4.string()),
+  /**
+   * Present, and non-empty, only on `status: "clarification_required"`. A refusal is a
+   * *result* here rather than an error: an error result may carry no `structuredContent` at
+   * all (the SDK validates it against the success shape), so reporting it that way would
+   * hand the agent the one thing it cannot act on — a sentence saying detail is missing,
+   * without saying which.
+   */
+  clarifying_questions: z4.array(
+    z4.object({
+      id: z4.string(),
+      question: z4.string(),
+      why: z4.string(),
+      options: z4.array(z4.string())
+    })
+  )
+});
+var statusInput = z4.object({
+  job_id: z4.string().describe("The job_id returned by generate_architecture with wait: false.")
+});
+var statusOutput = z4.object({
+  job_id: z4.string(),
+  status: z4.string(),
+  project_id: z4.string().nullable(),
+  architecture_id: z4.string().nullable(),
+  error: z4.string().nullable(),
+  queue_state: z4.string().nullable(),
+  /**
+   * Set when the run was *declined* rather than broken — the same three refusals the inline
+   * path answers with a 409. Nothing ran and nothing was charged, so the next call is a
+   * normal one, not a retry.
+   */
+  refusal_code: z4.string().nullable(),
+  /** Non-empty only for a `CLARIFICATION_REQUIRED` refusal. */
+  clarifying_questions: z4.array(
+    z4.object({
+      id: z4.string(),
+      question: z4.string(),
+      why: z4.string(),
+      options: z4.array(z4.string())
+    })
+  )
+});
+function registerGenerate(server, client, resolver) {
+  server.registerTool(
+    "generate_architecture",
+    {
+      title: "Generate a SkeletIQ architecture",
+      description: "Design a system architecture from a prompt. This spends the account holder's credits and takes several minutes, so do not call it speculatively \u2014 if a design already exists, read it with get_design instead. Which model runs it is the account holder's stored setting; you do not choose it. Describe the system, what it must do, and the scale and constraints it runs under: whatever the prompt leaves out is assumed, and a prompt that names no system at all comes back as clarification_required with the questions to answer.",
+      inputSchema: generateInput,
+      outputSchema: generateOutput,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    async ({ prompt, project_id, wait, clarification_answers, constraints }, ctx) => guard(async () => {
+      const projectId = project_id ? (await resolver.resolveProject(project_id)).id : void 0;
+      const body = {
+        prompt,
+        ...projectId ? { project_id: projectId } : {},
+        ...clarification_answers ? { clarification_answers } : {},
+        ...constraints ? { constraints } : {}
+      };
+      try {
+        if (wait === false) return await queueGeneration(client, body);
+        return await streamGeneration(client, body, ctx, resolver);
+      } catch (error) {
+        const questions = clarifyingQuestions(error);
+        if (!questions) throw error;
+        return clarificationResult(questions);
+      }
+    })
+  );
+  server.registerTool(
+    "get_generation_status",
+    {
+      title: "Check a queued SkeletIQ generation",
+      description: 'Check a background generation started with wait: false. When status is "completed", read the result with get_design.',
+      inputSchema: statusInput,
+      outputSchema: statusOutput,
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }
+    },
+    async ({ job_id }) => guard(async () => {
+      const job = JobSchema.parse(await client.request(`/chat/jobs/${job_id}`));
+      const refusal = decisionRefusal(job.progress);
+      const questions = refusalQuestions(refusal);
+      const structured = {
+        job_id: job.job_id,
+        status: job.status,
+        project_id: job.project_id ?? null,
+        architecture_id: job.architecture_id ?? null,
+        error: job.error ?? null,
+        queue_state: job.queue_state ?? null,
+        refusal_code: refusal?.code ?? null,
+        clarifying_questions: questions
+      };
+      const lines = refusal ? refusalLines(job.job_id, refusal, questions) : [`Generation ${job.job_id} is ${job.status}.`];
+      if (job.status === "completed" && job.project_id) {
+        lines.push(`Read it with get_design(project_id: "${job.project_id}").`);
+      }
+      if (job.error && !refusal) lines.push(job.error);
+      return ok(structured, lines.join("\n"));
+    })
+  );
+}
+function decisionRefusal(progress) {
+  const parsed = JobProgressSchema.safeParse(progress);
+  if (!parsed.success) return void 0;
+  const refusal = DecisionRefusalSchema.safeParse(parsed.data.data?.failure_detail);
+  return refusal.success ? refusal.data : void 0;
+}
+function refusalQuestions(refusal) {
+  return (refusal?.clarifying_questions ?? []).map((question) => ({
+    id: question.id,
+    question: question.question,
+    why: question.why ?? "",
+    options: (question.options ?? []).filter(
+      (option) => !(question.decline_options ?? []).includes(option)
+    )
+  }));
+}
+function refusalLines(jobId, refusal, questions) {
+  const preamble = `Generation ${jobId} was declined before it ran. Nothing was generated and nothing was charged.`;
+  switch (refusal.code) {
+    case "CLARIFICATION_REQUIRED":
+      return [
+        preamble,
+        "",
+        ...questions.flatMap((question) => [
+          `${question.id}: ${question.question}`,
+          ...question.why ? [`  Why it matters: ${question.why}`] : [],
+          ...question.options.length > 0 ? [`  For example: ${question.options.join(" \xB7 ")}`] : []
+        ]),
+        "",
+        "Call generate_architecture again with the same prompt and clarification_answers keyed by those ids. Take the answers from the user rather than inventing them."
+      ];
+    case "ASYNC_RESPONSE_MODE_UNSUPPORTED":
+      return [
+        preamble,
+        "That prompt reads as a question about a design rather than a request to build one, and a queued run can only produce a design. Ask it again with wait: true, or read the existing design with get_design and answer from it."
+      ];
+    case "NEW_PROJECT_RECOMMENDED":
+      return [
+        preamble,
+        "That prompt describes a different system from the one in this project. Create a new project for it rather than adding a version here."
+      ];
+    default:
+      return [preamble, `Refused as: ${refusal.code}.`];
+  }
+}
+function clarifyingQuestions(error) {
+  if (!(error instanceof SkeletiqApiError) || error.status !== 409) return void 0;
+  const decision = IntentDecisionSchema.safeParse(error.detail);
+  const questions = decision.success ? decision.data.clarifying_questions : void 0;
+  return questions && questions.length > 0 ? questions : void 0;
+}
+function clarificationResult(questions) {
+  const structured = questions.map((question) => ({
+    id: question.id,
+    question: question.question,
+    why: question.why ?? "",
+    options: (question.options ?? []).filter((option) => !(question.decline_options ?? []).includes(option))
+  }));
+  const lines = [
+    "SkeletIQ will not design from this prompt yet \u2014 it names no system to design. Nothing was generated and nothing was charged.",
+    "",
+    ...structured.flatMap((question) => [
+      `${question.id}: ${question.question}`,
+      ...question.why ? [`  Why it matters: ${question.why}`] : [],
+      ...question.options.length > 0 ? [`  For example: ${question.options.join(" \xB7 ")}`] : []
+    ]),
+    "",
+    "Call generate_architecture again with the same prompt and clarification_answers keyed by those ids. The answers are used as authoritative requirements, so take them from the user rather than inventing them \u2014 and put anything you already know into constraints instead, where it is used as a fact rather than as prose to interpret."
+  ];
+  return ok(
+    {
+      status: "clarification_required",
+      project_id: null,
+      architecture_id: null,
+      version: null,
+      job_id: null,
+      title: null,
+      component_count: null,
+      assistant_message: null,
+      degradations: [],
+      clarifying_questions: structured
+    },
+    lines.join("\n")
+  );
+}
+async function queueGeneration(client, body) {
+  const queued = GenerateAsyncSchema.parse(
+    await client.request("/chat/generate-async", { method: "POST", body })
+  );
+  return ok(
+    {
+      status: queued.status,
+      project_id: queued.job?.project_id ?? null,
+      architecture_id: null,
+      version: null,
+      job_id: queued.job_id,
+      title: null,
+      component_count: null,
+      assistant_message: null,
+      degradations: [],
+      clarifying_questions: []
+    },
+    `Queued as job ${queued.job_id}. Poll it with get_generation_status.`
+  );
+}
+async function streamGeneration(client, body, ctx, resolver) {
+  const progressToken = ctx.mcpReq._meta?.progressToken;
+  const response = await client.fetch("/chat/generate/stream", {
+    method: "POST",
+    body,
+    // One key per logical call. A network-level retry of the same generation replays the
+    // first result instead of running — and being charged for — a second one.
+    headers: { "Idempotency-Key": randomUUID(), Accept: "text/event-stream" },
+    signal: ctx.mcpReq.signal
+  });
+  let step = 0;
+  let finished;
+  let failed;
+  for await (const frame of readSseFrames(response)) {
+    const label = PROGRESS_LABELS[frame.type];
+    if (label && progressToken !== void 0) {
+      step += 1;
+      const detail = frameDetail(frame);
+      await ctx.mcpReq.notify({
+        method: "notifications/progress",
+        params: {
+          progressToken,
+          progress: step,
+          total: PROGRESS_TOTAL,
+          message: detail ? `${label} \u2014 ${detail}` : label
+        }
+      });
+    }
+    if (frame.type === "done") finished = frame;
+    if (frame.type === "error") failed = frame;
+  }
+  if (failed) {
+    const message = typeof failed.content === "string" ? failed.content : "The generation failed.";
+    return failure(`SkeletIQ could not complete the generation: ${message}`);
+  }
+  if (!finished) {
+    return failure(
+      "The generation stream ended without a result. Nothing here says whether it completed \u2014 check the project in SkeletIQ before generating again, so you do not pay for it twice."
+    );
+  }
+  const architectureId = typeof finished.architecture_id === "string" ? finished.architecture_id : null;
+  const version = typeof finished.architecture_version === "number" ? finished.architecture_version : null;
+  const degradations = Array.isArray(finished.degradations) ? finished.degradations.filter((d) => typeof d === "string") : [];
+  const created = architectureId ? await describeCreated(resolver, architectureId) : void 0;
+  return ok(
+    {
+      status: "completed",
+      project_id: created?.projectId ?? null,
+      architecture_id: architectureId,
+      version,
+      job_id: null,
+      title: created?.title ?? null,
+      component_count: created?.componentCount ?? null,
+      assistant_message: null,
+      degradations,
+      clarifying_questions: []
+    },
+    [
+      ...architectureId ? [
+        `Design generated as version ${version ?? "?"}.`,
+        created ? `Read it with get_design(project_id: "${created.projectId}").` : "Read it with get_design. This run could not report which project it was written to \u2014 find that with list_projects rather than assuming one.",
+        'Check get_design(mode: "readiness") before building \u2014 a fresh design is a draft, and',
+        "its open questions are the ones worth asking now."
+      ] : ["SkeletIQ answered in prose rather than producing a design."],
+      ...degradations.map((d) => `Degraded: ${d}`)
+    ].join("\n")
+  );
+}
+async function describeCreated(resolver, architectureId) {
+  try {
+    const design = await resolver.design(architectureId);
+    return {
+      projectId: design.project_id,
+      title: design.architecture_json.title ?? null,
+      componentCount: design.architecture_json.components?.length ?? null
+    };
+  } catch {
+    return void 0;
+  }
+}
+
+// src/tools/get-design.ts
+import * as z5 from "zod/v4";
+
+// src/lib/slice.ts
+function sliceComponent(design, componentId) {
+  const components = design.components ?? [];
+  const component = components.find((c) => c.id === componentId) ?? components.find((c) => normalize(c.name) === normalize(componentId));
+  if (!component) return null;
+  const connections = design.connections ?? [];
+  return {
+    component,
+    outgoing: connections.filter((c) => c.source === component.id),
+    incoming: connections.filter((c) => c.target === component.id),
+    related_decisions: relatedDecisions(design, component)
+  };
+}
+function relatedDecisions(design, component) {
+  const needles = [component.name, component.technology].filter((value) => typeof value === "string" && value.trim().length > 2).map((value) => value.toLowerCase());
+  if (needles.length === 0) return [];
+  return (design.design_decisions ?? []).filter((decision) => {
+    const haystack = decision.toLowerCase();
+    return needles.some((needle) => haystack.includes(needle));
+  });
+}
+function overview(design) {
+  return {
+    title: design.title ?? "Untitled design",
+    description: design.description ?? "",
+    components: design.components ?? [],
+    connections: design.connections ?? [],
+    design_decisions: design.design_decisions ?? [],
+    trade_offs: design.trade_offs ?? []
+  };
+}
+function normalize(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+// src/tools/get-design.ts
+var MODES = ["overview", "component", "brief", "readiness", "build_order", "gaps"];
+var input3 = z5.object({
+  project_id: z5.string().describe("A SkeletIQ project id, or its exact name."),
+  mode: z5.enum(MODES).describe(
+    "overview: the whole design. component: one component, its connections in both directions, and the decisions that mention it. brief: the fenced markdown block to write into AGENTS.md. readiness: what still has to be decided before this design is worth building. build_order: the order to build components in, and why. gaps: the open questions and unconfirmed assumptions in the design."
+  ),
+  component_id: z5.string().optional().describe('Required for mode "component". The component id, or its name.'),
+  version: z5.number().int().positive().optional().describe("A specific version. Defaults to the latest released version, or the latest version if none is released.")
+});
+var output3 = z5.object({
+  project_id: z5.string(),
+  architecture_id: z5.string(),
+  version: z5.number(),
+  is_released: z5.boolean(),
+  newer_release_exists: z5.boolean(),
+  resolved_by: z5.string(),
+  mode: z5.string(),
+  /** Mode-shaped. Deliberately loose: six modes cannot share one strict schema honestly. */
+  data: z5.unknown()
+});
+function registerGetDesign(server, client, resolver) {
+  server.registerTool(
+    "get_design",
+    {
+      title: "Read a SkeletIQ design",
+      description: 'Read a SkeletIQ architecture. Start with mode "brief" to orient \u2014 it returns a fenced block to write into AGENTS.md \u2014 then "build_order" for the sequence and "component" for each piece as you build it. Every answer states which version it came from and whether that version is a release.',
+      inputSchema: input3,
+      outputSchema: output3,
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }
+    },
+    async ({ project_id, mode, component_id, version }) => guard(async () => {
+      const project = await resolver.resolveProject(project_id);
+      const resolved = await resolver.resolveVersion(project.id, version);
+      const base = {
+        project_id: project.id,
+        architecture_id: resolved.architectureId,
+        mode
+      };
+      switch (mode) {
+        case "overview": {
+          const design = await resolver.design(resolved.architectureId);
+          const data = overview(design.architecture_json);
+          const facts = factsFrom(resolved);
+          return ok({ ...base, ...facts, data }, [
+            `# ${data.title}`,
+            data.description,
+            "",
+            `${data.components.length} component(s), ${data.connections.length} connection(s).`,
+            ...data.components.map(
+              (c) => `- ${c.id} \u2014 ${c.name} (${c.type}${c.technology ? `, ${c.technology}` : ""})`
+            ),
+            "",
+            versionLine(facts)
+          ].join("\n"));
+        }
+        case "component": {
+          if (!component_id) {
+            return failure('mode "component" needs a component_id. Use mode "overview" or "build_order" to see the ids.');
+          }
+          const design = await resolver.design(resolved.architectureId);
+          const slice = sliceComponent(design.architecture_json, component_id);
+          if (!slice) {
+            const known = (design.architecture_json.components ?? []).map((c) => c.id).join(", ");
+            return failure(
+              `Version ${resolved.version} has no component "${component_id}". Component ids are only valid within one version. Known ids: ${known || "none"}.`
+            );
+          }
+          const facts = factsFrom(resolved);
+          const { component, incoming, outgoing } = slice;
+          return ok({ ...base, ...facts, data: slice }, [
+            `## ${component.name} (${component.id})`,
+            `Type: ${component.type}${component.technology ? ` \xB7 ${component.technology}` : ""}`,
+            component.description ?? "",
+            "",
+            outgoing.length ? `Calls: ${outgoing.map((c) => `${c.target}${c.protocol ? ` (${c.protocol})` : ""}`).join(", ")}` : "Calls nothing.",
+            incoming.length ? `Called by: ${incoming.map((c) => c.source).join(", ")}` : "Called by nothing in the design.",
+            ...slice.related_decisions.map((decision) => `- ${decision}`),
+            "",
+            versionLine(facts)
+          ].join("\n"));
+        }
+        case "brief": {
+          const body = await client.request(`/architectures/${resolved.architectureId}/brief`);
+          const brief = BriefSchema.parse(body);
+          const facts = factsFromRelease(resolved, brief.release);
+          return ok({ ...base, ...facts, data: { markdown: brief.markdown, is_draft: brief.is_draft } }, [
+            "Write the block below into this repository's AGENTS.md.",
+            "If a `skeletiq:brief` fence is already there, REPLACE it whole \u2014 opening fence to",
+            "closing fence. Never append a second one, and never edit inside it: a refresh",
+            "overwrites the block, so changes made there are lost silently.",
+            brief.is_draft ? "This design is a DRAFT. It has not been released and can change without notice." : "",
+            // Said here as well as inside the block, because a model that acts on
+            // this tool response without re-reading the markdown it just wrote to
+            // disk would otherwise never learn it. `check_drift` defaults to "this
+            // repo is the whole design", and a repo implementing part of one gets
+            // every component built elsewhere reported as missing.
+            "If this repository implements only PART of the design, pass `covers` to",
+            "check_drift with just the component ids you are responsible for. The block",
+            'below lists every id under "What this repo covers".',
+            "",
+            brief.markdown,
+            "",
+            versionLine(facts)
+          ].filter(Boolean).join("\n"));
+        }
+        case "readiness": {
+          const body = await client.request(`/architectures/${resolved.architectureId}/readiness`);
+          const readiness = ReadinessSchema.parse(body);
+          const facts = factsFromRelease(resolved, readiness.release);
+          const gates = readiness.rows.filter((row) => row.category === "gate");
+          const open = gates.filter((row) => row.gating);
+          const unanswered = gates.filter((row) => row.state === "unknown");
+          const advisories = readiness.rows.filter((row) => row.category !== "gate");
+          const unrun = new Set(readiness.unrun_checks ?? []);
+          const verdict = readiness.verdict ?? (readiness.ready ? "ready" : "outstanding");
+          const headline = verdict === "ready" ? "Every gate is clear \u2014 this design is ready to build." : verdict === "unanswered" ? `Nothing is undecided, but ${unanswered.length} check(s) could not be answered for this version:` : `${open.length} of ${gates.length} gate(s) still open:`;
+          const listed = verdict === "unanswered" ? unanswered : open;
+          return ok({ ...base, ...facts, data: readiness }, [
+            headline,
+            ...listed.map((row) => `- ${row.label}: ${describeRow(row)}`),
+            "",
+            "Advisory checks (they never block, and some need a paid plan to clear):",
+            // An advisory that never ran is marked, not counted. "The advisor has
+            // not looked at this design" is a fact an agent being handed work is
+            // entitled to, and it is invisible in a bare count of open items.
+            ...advisories.map(
+              (row) => `- ${row.label}: ${describeRow(row)}${unrun.has(row.key) ? " (never run on this version)" : ""}`
+            ),
+            "",
+            "Only a person can clear a gate. Ask; do not decide on their behalf.",
+            versionLine(facts)
+          ].join("\n"));
+        }
+        case "build_order": {
+          const body = await client.request(`/architectures/${resolved.architectureId}/build-order`);
+          const buildOrder = BuildOrderSchema.parse(body);
+          const facts = factsFromRelease(resolved, buildOrder.release);
+          return ok({ ...base, ...facts, data: { steps: buildOrder.steps } }, [
+            "Build in this order. It follows the dependency graph \u2014 an arrow means the",
+            "source calls the target, so the target is built first \u2014 and falls back to what",
+            "each component *is* wherever the graph is silent.",
+            ...buildOrder.steps.map((step) => {
+              const blocked = new Set(step.blocked_by ?? []);
+              const after = (step.depends_on ?? []).filter((id) => !blocked.has(id));
+              return `${step.order}. ${step.name} (${step.component_id}) \u2014 ${step.reason}` + (after.length ? ` [after: ${after.join(", ")}]` : "") + (blocked.size ? ` [cycle: it calls ${[...blocked].join(", ")}, built later \u2014 stub or defer that edge]` : "");
+            }),
+            "",
+            versionLine(facts)
+          ].join("\n"));
+        }
+        case "gaps": {
+          const body = await client.request(`/projects/${project.id}/design-gaps`, {
+            query: { architecture_id: resolved.architectureId }
+          });
+          const gaps = DesignGapListSchema.parse(body);
+          const facts = factsFrom(resolved);
+          const unresolved = gaps.gaps.filter((gap) => !gap.resolved);
+          const settled = gaps.gaps.filter((gap) => gap.resolved && gap.action !== "dismissed");
+          return ok({ ...base, ...facts, data: gaps }, [
+            unresolved.length === 0 ? "Every open question and assumption in this design has been dealt with." : `${unresolved.length} unresolved:`,
+            ...unresolved.map((gap) => `- [${gap.kind}] ${gap.text}`),
+            ...settled.length > 0 ? [
+              "",
+              `${settled.length} settled during review \u2014 treat these as decided:`,
+              ...settled.map((gap) => `- [${gap.kind}] ${gap.text} \u2192 ${settledAnswer(gap)}`)
+            ] : [],
+            "",
+            "The unresolved ones are questions for a person, not for you to answer. Raise",
+            "them; do not guess and build on the guess. An API token cannot resolve them \u2014",
+            "that is done in the SkeletIQ app, on purpose.",
+            versionLine(facts)
+          ].join("\n"));
+        }
+      }
+    })
+  );
+}
+function settledAnswer(gap) {
+  const note = (gap.note ?? "").trim();
+  if (gap.adr_id) {
+    const pointer = `recorded as a Decision (${gap.adr_id})`;
+    return note ? `${pointer} \u2014 ${note}` : pointer;
+  }
+  if (note) return note;
+  if (gap.action === "confirmed") return "confirmed as it stands";
+  return "answered, but no wording was recorded \u2014 ask before relying on it";
+}
+function describeRow(row) {
+  if (row.state === "unknown") return "not checked";
+  return `${row.count}${row.detail ? ` \u2014 ${row.detail}` : ""}`;
+}
+
+// src/tools/list-projects.ts
+import * as z6 from "zod/v4";
+var input4 = z6.object({
+  query: z6.string().optional().describe("Filter by name or description. Omit to list everything the token can see.")
+});
+var output4 = z6.object({
+  projects: z6.array(
+    z6.object({
+      id: z6.string(),
+      title: z6.string(),
+      description: z6.string().nullable(),
+      architecture_count: z6.number(),
+      updated_at: z6.string().nullable()
+    })
+  ),
+  total: z6.number()
+});
+function registerListProjects(server, resolver) {
+  server.registerTool(
+    "list_projects",
+    {
+      title: "List SkeletIQ projects",
+      description: "List the SkeletIQ projects this token can see, optionally filtered by name. Use this first to turn a project a person named in conversation into an id. If more than one project matches, ask which \u2014 do not pick one.",
+      inputSchema: input4,
+      outputSchema: output4,
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }
+    },
+    async ({ query }) => guard(async () => {
+      const projects = await resolver.listProjects(query);
+      const structured = {
+        projects: projects.map((project) => ({
+          id: project.id,
+          title: project.title,
+          description: project.description ?? null,
+          architecture_count: project.architecture_count ?? 0,
+          updated_at: project.updated_at ?? null
+        })),
+        total: projects.length
+      };
+      if (projects.length === 0) {
+        return ok(
+          structured,
+          query ? `No SkeletIQ project matches "${query}".` : "This token can see no SkeletIQ projects."
+        );
+      }
+      const lines = projects.map(
+        (project) => `- ${project.title} (${project.id}) \u2014 ${project.architecture_count ?? 0} version(s)`
+      );
+      return ok(structured, [`${projects.length} project(s):`, ...lines].join("\n"));
+    })
+  );
+}
+
+// src/server.ts
+var INSTRUCTIONS = `SkeletIQ holds the system architecture this codebase is meant to implement: its components, how they connect, what was decided and why, and what is still an open question. It is the design's source of truth, and this server is how you read it.
+
+Orient before you build. Call get_design with mode "brief" and write the block it returns into this repository's AGENTS.md. The block is fenced with an HTML comment (skeletiq:brief). If one is already there, replace it whole \u2014 opening fence to closing fence. Never append a second, and never edit inside it: a refresh overwrites the block, so anything written there is lost without warning.
+
+Then build in the order get_design(mode: "build_order") gives you, reading each component with mode "component" as you reach it.
+
+Four things that are easy to get wrong:
+
+A DRAFT design has not been approved by anyone and can change under you on any edit. Prefer a released version, and if a tool tells you newer_release_exists, refresh the brief before going further.
+
+Component ids belong to one version. A regeneration mints new ones, so an id from an older brief may name nothing. When check_drift returns unknown ids with suggestions, they are suggestions \u2014 put them to a person rather than assuming the mapping.
+
+Open questions are for people. get_design(mode: "gaps") lists what the design has not settled. Raise them; do not answer them yourself and build on the answer. You cannot resolve them through this server, and that is deliberate.
+
+Report what you build with check_drift, and declare covers when this repository implements only part of the design \u2014 otherwise every component built elsewhere is reported to you as missing.
+
+Designing costs the account holder credits and takes minutes. Read before you generate.`;
+function createServerFactory(config) {
+  const client = new SkeletiqClient(config);
+  const resolver = new DesignResolver(client);
+  return () => buildServer(client, resolver);
+}
+function buildServer(client, resolver) {
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { instructions: INSTRUCTIONS, capabilities: { tools: {} } }
+  );
+  registerListProjects(server, resolver);
+  registerGetDesign(server, client, resolver);
+  registerGenerate(server, client, resolver);
+  registerCritique(server, client);
+  registerCheckDrift(server, client, resolver);
+  return server;
+}
+
+// src/index.ts
+function main() {
+  let config;
+  try {
+    config = readConfig();
+  } catch (error) {
+    process.stderr.write(
+      `${error instanceof ConfigError ? error.message : String(error)}
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  serveStdio(createServerFactory(config), {
+    onerror: (error) => process.stderr.write(`skeletiq-mcp: ${error.message}
+`)
+  });
+}
+main();