@zaai-dev/mcp 0.1.0 → 0.3.0

package/dist/bin/http.js

@@ -0,0 +1,1097 @@
+#!/usr/bin/env node
+
+// src/bin/http.ts
+import { createServer as createHttpServer } from "http";
+import { randomUUID } from "crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+// src/server.ts
+import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/health.ts
+import { z } from "zod";
+
+// src/version.ts
+var PKG_VERSION = true ? "0.3.0" : "0.0.0-dev";
+
+// src/tools/health.ts
+var healthInputSchema = z.object({});
+var healthOutputSchema = z.object({
+  ok: z.boolean().describe("Always true \u2014 health is the server admitting it answered."),
+  version: z.string().describe("The MCP server's package version."),
+  node: z.string().describe("The Node.js runtime version the server is running on."),
+  uptimeSeconds: z.number().describe("Seconds since this server process started.")
+});
+function health() {
+  return {
+    ok: true,
+    version: PKG_VERSION,
+    node: process.versions.node,
+    uptimeSeconds: Math.round(process.uptime())
+  };
+}
+
+// src/tools/whoami.ts
+import { z as z2 } from "zod";
+
+// src/util/auth.ts
+function bearerHeader(token) {
+  return { Authorization: `Bearer ${token}` };
+}
+
+// src/util/api.ts
+var WorkspaceApiError = class extends Error {
+  constructor(status, body, path) {
+    super(`${path} \u2192 ${status}`);
+    this.status = status;
+    this.body = body;
+    this.path = path;
+    this.name = "WorkspaceApiError";
+  }
+  status;
+  body;
+  path;
+};
+var MAX_ATTEMPTS = 3;
+var BASE_BACKOFF_MS = 250;
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+async function mcpApiFetch(config, path, init = {}) {
+  const url = `${config.apiUrl}${path}`;
+  let lastErr = null;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, {
+        ...init,
+        headers: {
+          ...bearerHeader(config.apiToken),
+          ...init.headers ?? {}
+        }
+      });
+    } catch (err2) {
+      lastErr = new WorkspaceApiError(0, { message: String(err2) }, path);
+      if (attempt < MAX_ATTEMPTS) {
+        await sleep(BASE_BACKOFF_MS * 2 ** (attempt - 1));
+        continue;
+      }
+      throw lastErr;
+    }
+    if (res.ok) {
+      return await res.json();
+    }
+    const body = await res.json().catch(() => ({ error: `Non-JSON ${res.status} response` }));
+    const err = new WorkspaceApiError(res.status, body, path);
+    if (RETRYABLE_STATUSES.has(res.status) || res.status >= 502 && res.status <= 504) {
+      lastErr = err;
+      if (attempt < MAX_ATTEMPTS) {
+        await sleep(BASE_BACKOFF_MS * 2 ** (attempt - 1));
+        continue;
+      }
+    }
+    throw err;
+  }
+  throw lastErr ?? new WorkspaceApiError(0, { message: "no attempts" }, path);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/tools/whoami.ts
+var whoamiInputSchema = z2.object({});
+var whoamiOutputSchema = z2.object({
+  userId: z2.string().describe("Workspace user id this token belongs to."),
+  orgId: z2.string().describe("Organisation id the token is scoped to."),
+  projectScope: z2.array(z2.string()).nullable().describe(
+    "List of project ids the token can access, or null when scoped to every project in the org."
+  ),
+  balance: z2.object({
+    currentBalance: z2.number().describe("Top-up credits (never expire)."),
+    monthlyGrantRemaining: z2.number().describe("Monthly grant remaining (resets on the 1st)."),
+    totalBalance: z2.number().describe("Sum of the two \u2014 what's available right now.")
+  }).describe("Credit balance available for MCP calls."),
+  mcpCallCost: z2.number().describe("Credits debited per successful MCP tool call.")
+});
+async function whoami(config) {
+  return mcpApiFetch(config, "/api/mcp/me");
+}
+
+// src/tools/list-captures.ts
+import { z as z3 } from "zod";
+var listCapturesInputSchema = z3.object({
+  q: z3.string().optional().describe(
+    "Optional text filter applied to source_title, source_url, and note (case-insensitive substring match). Leave blank to list all."
+  ),
+  cursor: z3.string().optional().describe(
+    "Opaque pagination cursor from a previous response's nextCursor field. Omit on the first page."
+  ),
+  limit: z3.number().int().min(1).max(50).optional().describe("Max captures to return. Default 20, max 50.")
+});
+var listCapturesOutputSchema = z3.object({
+  captures: z3.array(
+    z3.object({
+      id: z3.string().describe("Capture UUID. Pass to get_capture for the full payload."),
+      type: z3.enum(["page", "element", "composite"]).describe(
+        "page = full-page screenshot + DOM context; element = a single picked element; composite = multiple elements stacked."
+      ),
+      sourceTitle: z3.string(),
+      sourceUrl: z3.string(),
+      capturedAt: z3.string().describe("ISO 8601 timestamp from the extension at capture time."),
+      tags: z3.array(z3.string()),
+      thumbnailUrl: z3.string().nullable().describe(
+        "Signed Supabase Storage URL (1h TTL). Fetch fresh by re-calling list_captures or get_capture."
+      )
+    })
+  ),
+  nextCursor: z3.string().optional().describe(
+    "When present, pass back as `cursor` to fetch the next page. Absent = no more rows."
+  )
+});
+async function listCaptures(store, args) {
+  return store.list({
+    q: args.q,
+    cursor: args.cursor,
+    limit: args.limit
+  });
+}
+
+// src/tools/get-capture.ts
+import { z as z4 } from "zod";
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var getCaptureInputSchema = z4.object({
+  id: z4.string().regex(UUID_RE, "id must be a UUID").describe("Capture id from list_captures.")
+});
+var getCaptureOutputSchema = z4.object({
+  id: z4.string(),
+  type: z4.enum(["page", "element", "composite"]),
+  projectId: z4.string(),
+  sourceTitle: z4.string(),
+  sourceUrl: z4.string(),
+  capturedAt: z4.string(),
+  note: z4.string().nullable(),
+  tags: z4.array(z4.string()),
+  screenshotUrl: z4.string().nullable().describe("Signed PNG URL, 1h TTL."),
+  thumbnailUrl: z4.string().nullable(),
+  fullPageScreenshotUrl: z4.string().nullable().describe(
+    "Page captures with the M9 stitch get a full-page PNG too. Null for element + composite + page captures without a stitch."
+  ),
+  payload: z4.unknown().describe(
+    "Full extension-side Capture JSON. Shape depends on `type` \u2014 see https://github.com/POLONIBOI/ZAAI_STUDIO-ext/blob/main/src/shared/types.ts for the union."
+  )
+}).passthrough();
+async function getCapture(store, args) {
+  return store.get(args.id);
+}
+
+// src/tools/search-captures.ts
+import { z as z5 } from "zod";
+var searchCapturesInputSchema = z5.object({
+  q: z5.string().min(1).describe(
+    "Case-insensitive substring match against source_title, source_url, and note. Required \u2014 use list_captures if you don't have a query."
+  ),
+  cursor: z5.string().optional(),
+  limit: z5.number().int().min(1).max(50).optional()
+});
+var searchCapturesOutputSchema = z5.object({
+  captures: z5.array(
+    z5.object({
+      id: z5.string(),
+      type: z5.enum(["page", "element", "composite"]),
+      sourceTitle: z5.string(),
+      sourceUrl: z5.string(),
+      capturedAt: z5.string(),
+      tags: z5.array(z5.string()),
+      thumbnailUrl: z5.string().nullable()
+    })
+  ),
+  nextCursor: z5.string().optional()
+});
+async function searchCaptures(store, args) {
+  return store.list({ q: args.q, cursor: args.cursor, limit: args.limit });
+}
+
+// src/tools/_focused-getter.ts
+import { z as z6 } from "zod";
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var focusedGetterInputSchema = z6.object({
+  id: z6.string().regex(UUID_RE2, "id must be a UUID").describe(
+    "Capture id from list_captures or search_captures. UUID format."
+  )
+});
+var focusedGetterOutputSchema = z6.object({
+  id: z6.string(),
+  type: z6.enum(["page", "element", "composite"]),
+  field: z6.string(),
+  data: z6.unknown()
+}).passthrough();
+
+// src/tools/get-palette.ts
+async function getPalette(store, args) {
+  return store.getField(args.id, "palette");
+}
+
+// src/tools/get-html.ts
+async function getHtml(store, args) {
+  return store.getField(args.id, "html");
+}
+
+// src/tools/get-animation.ts
+async function getAnimation(store, args) {
+  return store.getField(args.id, "animation");
+}
+
+// src/tools/get-media.ts
+async function getMedia(store, args) {
+  return store.getField(args.id, "media");
+}
+
+// src/tools/get-brand-brief.ts
+import { z as z7 } from "zod";
+var getBrandBriefInputSchema = z7.object({
+  project_id: z7.string().uuid().describe(
+    "Zaai Dev project UUID. Find via the workspace at zaaistudio.com/dev/projects."
+  )
+});
+var getBrandBriefOutputSchema = z7.object({
+  project_id: z7.string(),
+  project_name: z7.string(),
+  version: z7.string().describe("Brief version number, or '0' if no brief has been generated yet."),
+  status: z7.enum(["draft", "published", "archived"]),
+  positioning: z7.string(),
+  values: z7.array(z7.string()),
+  voice: z7.object({
+    one_liner: z7.string(),
+    do_say: z7.array(z7.string()),
+    dont_say: z7.array(z7.string())
+  }),
+  audience: z7.object({
+    primary: z7.string(),
+    secondary: z7.string().nullable(),
+    needs: z7.array(z7.string())
+  }),
+  design_intent: z7.object({
+    descriptors: z7.array(z7.string()),
+    anti_descriptors: z7.array(z7.string())
+  }),
+  decisions: z7.array(
+    z7.object({
+      id: z7.string(),
+      title: z7.string(),
+      decided_at: z7.string(),
+      rationale: z7.string()
+    })
+  ),
+  updated_at: z7.string()
+}).passthrough();
+async function getBrandBrief(store, args) {
+  return store.getBrandBrief(args.project_id);
+}
+
+// src/tools/get-voice.ts
+import { z as z8 } from "zod";
+var getVoiceInputSchema = z8.object({
+  project_id: z8.string().uuid().describe("Zaai Dev project UUID.")
+});
+var getVoiceOutputSchema = z8.object({
+  project_id: z8.string(),
+  one_liner: z8.string().describe("One-sentence summary of how the brand sounds."),
+  tone_descriptors: z8.array(z8.string()).describe("Adjectives the brand voice aims for."),
+  do_say: z8.array(z8.string()).describe("Phrasings / patterns the brand actively uses."),
+  dont_say: z8.array(z8.string()).describe("Phrasings / patterns the brand explicitly avoids."),
+  example_phrases: z8.array(z8.string()).describe("Concrete phrases that exemplify the voice.")
+}).passthrough();
+async function getVoice(store, args) {
+  return store.getVoice(args.project_id);
+}
+
+// src/tools/get-audience.ts
+import { z as z9 } from "zod";
+var getAudienceInputSchema = z9.object({
+  project_id: z9.string().uuid().describe("Zaai Dev project UUID.")
+});
+var getAudienceOutputSchema = z9.object({
+  project_id: z9.string(),
+  primary: z9.string().describe("Primary audience segment."),
+  secondary: z9.string().nullable().describe("Secondary audience segment, or null."),
+  needs: z9.array(z9.string()).describe("Jobs-to-be-done / pain points the audience has."),
+  channels: z9.array(z9.string()).describe("Where this audience consumes content.")
+}).passthrough();
+async function getAudience(store, args) {
+  return store.getAudience(args.project_id);
+}
+
+// src/tools/get-design-intent.ts
+import { z as z10 } from "zod";
+var getDesignIntentInputSchema = z10.object({
+  project_id: z10.string().uuid().describe("Zaai Dev project UUID.")
+});
+var getDesignIntentOutputSchema = z10.object({
+  project_id: z10.string(),
+  descriptors: z10.array(z10.string()).describe(
+    "Visual adjectives the brand aims for (e.g. 'editorial', 'spacious', 'monochrome')."
+  ),
+  anti_descriptors: z10.array(z10.string()).describe("Visual adjectives the brand explicitly avoids."),
+  inspiration_summary: z10.string().describe("Free-form summary of the inspiration the brief points at.")
+}).passthrough();
+async function getDesignIntent(store, args) {
+  return store.getDesignIntent(args.project_id);
+}
+
+// src/tools/get-brand-tokens.ts
+import { z as z11 } from "zod";
+var getBrandTokensInputSchema = z11.object({
+  project_id: z11.string().uuid().describe("Zaai Dev project UUID.")
+});
+var getBrandTokensOutputSchema = z11.object({
+  project_id: z11.string(),
+  colors: z11.array(
+    z11.object({
+      name: z11.string(),
+      value: z11.string().describe("Hex / rgba / hsl value as authored."),
+      role: z11.string().optional().describe("Role like 'primary' / 'accent' / 'surface'.")
+    })
+  ),
+  fonts: z11.array(
+    z11.object({
+      role: z11.string().describe("'display', 'body', 'mono', etc."),
+      family: z11.string(),
+      weights: z11.array(z11.number().int())
+    })
+  ),
+  radius: z11.array(z11.object({ name: z11.string(), value: z11.string() })),
+  shadows: z11.array(z11.object({ name: z11.string(), value: z11.string() }))
+}).passthrough();
+async function getBrandTokens(store, args) {
+  return store.getBrandTokens(args.project_id);
+}
+
+// src/tools/get-decisions.ts
+import { z as z12 } from "zod";
+var getDecisionsInputSchema = z12.object({
+  project_id: z12.string().uuid().describe("Zaai Dev project UUID."),
+  limit: z12.number().int().min(1).max(200).optional().describe("Max decisions to return. Default 50, max 200, newest first.")
+});
+var getDecisionsOutputSchema = z12.object({
+  project_id: z12.string(),
+  items: z12.array(
+    z12.object({
+      id: z12.string(),
+      title: z12.string(),
+      rationale: z12.string(),
+      attribution: z12.string().describe(
+        "Who decided. 'mcp:<token_id>' for AI-logged decisions; user email / id for workspace-authored ones."
+      ),
+      brief_field: z12.string().nullable().describe("Which brief slice this decision concerns, if any (e.g. 'voice.tone')."),
+      reference_capture_id: z12.string().nullable(),
+      created_at: z12.string()
+    }).passthrough()
+  )
+}).passthrough();
+async function getDecisions(store, args) {
+  return store.getDecisions(args.project_id, args.limit);
+}
+
+// src/tools/get-references.ts
+import { z as z13 } from "zod";
+var getReferencesInputSchema = z13.object({
+  project_id: z13.string().uuid().describe("Zaai Dev project UUID."),
+  limit: z13.number().int().min(1).max(100).optional().describe("Max references to return. Default 20, max 100, newest first."),
+  cursor: z13.string().optional().describe("Opaque pagination cursor from the previous response's next_cursor.")
+});
+var referenceItem = z13.object({
+  id: z13.string(),
+  type: z13.enum(["page", "element", "composite"]),
+  source_url: z13.string(),
+  source_title: z13.string(),
+  note: z13.string().nullable(),
+  captured_at: z13.string(),
+  thumbnail_url: z13.string().nullable(),
+  screenshot_url: z13.string().nullable()
+}).passthrough();
+var getReferencesOutputSchema = z13.object({
+  project_id: z13.string(),
+  items: z13.array(referenceItem),
+  next_cursor: z13.string().nullable()
+}).passthrough();
+async function getReferences(store, args) {
+  return store.getReferences(args.project_id, {
+    limit: args.limit,
+    cursor: args.cursor
+  });
+}
+
+// src/tools/search-references.ts
+import { z as z14 } from "zod";
+var searchReferencesInputSchema = z14.object({
+  project_id: z14.string().uuid().describe("Zaai Dev project UUID."),
+  q: z14.string().min(1).max(200).describe("Keyword query \u2014 matched against title / url / note (case-insensitive substring)."),
+  limit: z14.number().int().min(1).max(50).optional().describe("Max results to return. Default 10, max 50.")
+});
+var searchReferenceItem = z14.object({
+  id: z14.string(),
+  type: z14.enum(["page", "element", "composite"]),
+  source_url: z14.string(),
+  source_title: z14.string(),
+  note: z14.string().nullable(),
+  captured_at: z14.string(),
+  thumbnail_url: z14.string().nullable(),
+  screenshot_url: z14.string().nullable(),
+  score: z14.number().describe("Relevance score 0..1. v1 keyword scoring: 1.0 title / 0.7 url / 0.5 note."),
+  matched_field: z14.enum(["title", "url", "note", "tag"])
+}).passthrough();
+var searchReferencesOutputSchema = z14.object({
+  project_id: z14.string(),
+  query: z14.string(),
+  items: z14.array(searchReferenceItem)
+}).passthrough();
+async function searchReferences(store, args) {
+  return store.searchReferences(args.project_id, {
+    q: args.q,
+    limit: args.limit
+  });
+}
+
+// src/store/http-store.ts
+var HttpCaptureStore = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  async list(args) {
+    const sp = new URLSearchParams();
+    if (args.q) sp.set("q", args.q);
+    if (args.cursor) sp.set("cursor", args.cursor);
+    if (args.limit !== void 0) sp.set("limit", String(args.limit));
+    const qs = sp.toString();
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/captures${qs ? `?${qs}` : ""}`
+    );
+  }
+  async get(id) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/captures/${encodeURIComponent(id)}`
+    );
+  }
+  async getField(id, field) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/captures/${encodeURIComponent(id)}/${field}`
+    );
+  }
+};
+
+// src/store/project-store.ts
+var HttpProjectStore = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  async getBrandBrief(projectId) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/brief`
+    );
+  }
+  async getVoice(projectId) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/voice`
+    );
+  }
+  async getAudience(projectId) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/audience`
+    );
+  }
+  async getDesignIntent(projectId) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/design-intent`
+    );
+  }
+  async getBrandTokens(projectId) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/brand-tokens`
+    );
+  }
+  async getDecisions(projectId, limit) {
+    const sp = new URLSearchParams();
+    if (limit !== void 0) sp.set("limit", String(limit));
+    const qs = sp.toString();
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/decisions${qs ? `?${qs}` : ""}`
+    );
+  }
+  async getReferences(projectId, args) {
+    const sp = new URLSearchParams();
+    if (args.limit !== void 0) sp.set("limit", String(args.limit));
+    if (args.cursor) sp.set("cursor", args.cursor);
+    const qs = sp.toString();
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/references${qs ? `?${qs}` : ""}`
+    );
+  }
+  async searchReferences(projectId, args) {
+    const sp = new URLSearchParams();
+    sp.set("q", args.q);
+    if (args.limit !== void 0) sp.set("limit", String(args.limit));
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/references/search?${sp.toString()}`
+    );
+  }
+};
+
+// src/resources/capture-resource.ts
+import {
+  ResourceTemplate
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+function registerCaptureResource(server, store) {
+  server.registerResource(
+    "capture",
+    new ResourceTemplate("zaai-capture://{id}", {
+      list: void 0
+    }),
+    {
+      title: "Zaai Dev capture",
+      description: "Attach one capture from the user's Zaai Dev library as JSON. URI: zaai-capture://<capture-id>. The id comes from list_captures.",
+      mimeType: "application/json"
+    },
+    async (uri, variables) => {
+      const rawId = variables.id;
+      const id = Array.isArray(rawId) ? rawId[0] : rawId;
+      const capture = await store.get(id);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(capture, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/log.ts
+var PREFIX = "[zaai-mcp]";
+function write(level, message, meta) {
+  let line = `${PREFIX} ${level} ${message}`;
+  if (meta !== void 0) {
+    line += " " + safeStringify(meta);
+  }
+  process.stderr.write(line + "\n");
+}
+function safeStringify(value) {
+  try {
+    if (value instanceof Error) {
+      return value.stack ?? `${value.name}: ${value.message}`;
+    }
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function info(message, meta) {
+  write("INFO", message, meta);
+}
+function error(message, meta) {
+  write("ERROR", message, meta);
+}
+
+// src/server.ts
+function createServer(config) {
+  const server = new McpServer2({
+    name: "zaai-dev-mcp",
+    version: PKG_VERSION
+  });
+  const captureStore = new HttpCaptureStore(config);
+  const projectStore = new HttpProjectStore(config);
+  server.registerTool(
+    "health",
+    {
+      title: "Health check",
+      description: "Returns the Zaai Dev MCP server's status, version, and uptime. Use this to confirm the server is running before relying on auth-gated tools. No workspace access required. Useful as a smoke test from the MCP Inspector before configuring credentials.",
+      inputSchema: healthInputSchema.shape,
+      outputSchema: healthOutputSchema.shape
+    },
+    async () => {
+      const result = health();
+      return {
+        structuredContent: result,
+        // Human-readable summary for clients that haven't adopted
+        // structuredContent yet. Spec 2025-06-18 still requires both.
+        content: [
+          {
+            type: "text",
+            text: `Zaai Dev MCP ${result.version} \xB7 node ${result.node} \xB7 uptime ${result.uptimeSeconds}s`
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "whoami",
+    {
+      title: "Who am I",
+      description: "Returns the Zaai Dev workspace account this server is bound to: user id, organisation id, project scope, and current credit balance. Use this to confirm the configured ZAAI_API_TOKEN is valid before calling any other workspace tool. Does NOT debit credits \u2014 the workspace treats /me as a heartbeat, not user-facing work.",
+      inputSchema: whoamiInputSchema.shape,
+      outputSchema: whoamiOutputSchema.shape
+    },
+    async () => {
+      try {
+        const result = await whoami(config);
+        return {
+          structuredContent: result,
+          content: [
+            {
+              type: "text",
+              text: summariseWhoami(result)
+            }
+          ]
+        };
+      } catch (err) {
+        return toolErrorResponse(err);
+      }
+    }
+  );
+  server.registerTool(
+    "list_captures",
+    {
+      title: "List captures",
+      description: "List the user's Zaai Dev captures (newest first, paginated). Use this to discover what's in the library before calling get_capture for specifics. Each row carries id, type, title, URL, capturedAt, tags, and a thumbnail URL \u2014 but NOT the full HTML, computed style, or animation data. Use get_capture for those. Costs 1 credit per call.",
+      inputSchema: listCapturesInputSchema.shape,
+      outputSchema: listCapturesOutputSchema.shape
+    },
+    async (args) => {
+      try {
+        const result = await listCaptures(captureStore, args);
+        return {
+          // Cast: SDK's structuredContent param wants
+          // Record<string,unknown> but our typed DTO doesn't carry
+          // an index signature. Runtime shape is identical.
+          structuredContent: result,
+          content: [
+            {
+              type: "text",
+              text: result.captures.length === 0 ? "No captures yet. The user can push captures from the Zaai Dev Chrome extension." : `${result.captures.length} capture${result.captures.length === 1 ? "" : "s"}${result.nextCursor ? " (more available \u2014 pass nextCursor for the next page)" : ""}.`
+            }
+          ]
+        };
+      } catch (err) {
+        return toolErrorResponse(err);
+      }
+    }
+  );
+  server.registerTool(
+    "get_capture",
+    {
+      title: "Get capture",
+      description: "Fetch the full payload for one capture by id. Includes everything the extension extracted (HTML, computed CSS, palette, fonts, animation data, media inventory, ancestry, page sections, manual eyedropper picks) plus fresh-signed Supabase URLs for the screenshot and thumbnail. Use list_captures or search_captures first to discover ids. Costs 1 credit per call; the 404 path (unknown id) doesn't bill.",
+      inputSchema: getCaptureInputSchema.shape,
+      outputSchema: getCaptureOutputSchema.shape
+    },
+    async (args) => {
+      try {
+        const result = await getCapture(captureStore, args);
+        return {
+          structuredContent: result,
+          content: [
+            {
+              type: "text",
+              text: `${result.type} capture "${result.sourceTitle || result.sourceUrl}" (${result.tags.length} tag${result.tags.length === 1 ? "" : "s"})` + (result.screenshotUrl ? " \u2014 screenshot URL included." : "")
+            }
+          ]
+        };
+      } catch (err) {
+        return toolErrorResponse(err);
+      }
+    }
+  );
+  server.registerTool(
+    "search_captures",
+    {
+      title: "Search captures",
+      description: "Find captures matching a text query (case-insensitive substring match against source_title, source_url, and note). Returns the same summary shape as list_captures. Use this when you have a specific concept in mind ('hero', 'pricing table', 'stripe'); use list_captures to browse instead. Costs 1 credit per call.",
+      inputSchema: searchCapturesInputSchema.shape,
+      outputSchema: searchCapturesOutputSchema.shape
+    },
+    async (args) => {
+      try {
+        const result = await searchCaptures(captureStore, args);
+        return {
+          structuredContent: result,
+          content: [
+            {
+              type: "text",
+              text: result.captures.length === 0 ? `No captures match "${args.q}".` : `${result.captures.length} capture${result.captures.length === 1 ? "" : "s"} matching "${args.q}"${result.nextCursor ? " (more available \u2014 pass nextCursor for the next page)" : ""}.`
+            }
+          ]
+        };
+      } catch (err) {
+        return toolErrorResponse(err);
+      }
+    }
+  );
+  server.registerTool(
+    "get_palette",
+    {
+      title: "Get capture palette",
+      description: "Returns just the colour palette for a capture. Page captures carry a 6-colour extracted palette (`palette`); element + composite captures carry the user's eyedropper picks (`manualPalette`). Use this when the LLM needs colour context without loading the full payload. Costs 1 credit.",
+      inputSchema: focusedGetterInputSchema.shape,
+      outputSchema: focusedGetterOutputSchema.shape
+    },
+    makeFocusedGetterHandler(captureStore, getPalette, "palette")
+  );
+  server.registerTool(
+    "get_html",
+    {
+      title: "Get capture HTML",
+      description: "Returns just the HTML for a capture. Page \u2192 full page HTML; element \u2192 outerHTML of the picked element; composite \u2192 concatenated outerHTMLs with `<!-- Element N: selector -->` markers. Use this for component-extraction prompts ('rebuild this in Tailwind'). Costs 1 credit. Page captures can be large \u2014 budget your context accordingly.",
+      inputSchema: focusedGetterInputSchema.shape,
+      outputSchema: focusedGetterOutputSchema.shape
+    },
+    makeFocusedGetterHandler(captureStore, getHtml, "html")
+  );
+  server.registerTool(
+    "get_animation",
+    {
+      title: "Get capture animation data",
+      description: "Returns just the animation data. Page \u2192 pageAnimations (keyframes vocabulary + detected motion libraries like Framer Motion, GSAP, AOS, anime.js, Lenis, Locomotive). Element \u2192 the element's CSS transitions, keyframes, hover/focus/active state diffs, and per-element library hints. Composite \u2192 per-element variants. Use this to give the LLM motion context without loading HTML and computed style. Costs 1 credit.",
+      inputSchema: focusedGetterInputSchema.shape,
+      outputSchema: focusedGetterOutputSchema.shape
+    },
+    makeFocusedGetterHandler(captureStore, getAnimation, "animation")
+  );
+  server.registerTool(
+    "get_media",
+    {
+      title: "Get capture media inventory",
+      description: "Returns just the rich-media inventory for element + composite captures: videos (src/poster/autoplay/loop), images (src/srcset/alt), background-image URLs across the subtree, and carousel containers (Swiper, Glide, Splide, Slick, Flickity, Embla, `[data-carousel]`) with slide counts. Page captures return media:null (page-level palette/fonts only). Costs 1 credit.",
+      inputSchema: focusedGetterInputSchema.shape,
+      outputSchema: focusedGetterOutputSchema.shape
+    },
+    makeFocusedGetterHandler(captureStore, getMedia, "media")
+  );
+  server.registerTool(
+    "get_brand_brief",
+    {
+      title: "Get brand brief",
+      description: "Returns the full published brand brief for a project: positioning, values, voice, audience, design intent, and decisions. Use this when the LLM needs the whole picture before writing copy or designing a component. If the project has no brief yet, the response still validates \u2014 most fields are empty strings or empty arrays.",
+      inputSchema: getBrandBriefInputSchema.shape,
+      outputSchema: getBrandBriefOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      getBrandBrief,
+      (r) => `Brief v${r.version} (${r.status}) for "${r.project_name}". Voice: ${r.voice.one_liner || "\u2014"}.`
+    )
+  );
+  server.registerTool(
+    "get_voice",
+    {
+      title: "Get voice guidelines",
+      description: "Returns only the voice slice: one-liner, tone descriptors, do-say / don't-say lists, example phrases. Lighter than the full brief when the LLM is only writing copy. Costs 1 credit.",
+      inputSchema: getVoiceInputSchema.shape,
+      outputSchema: getVoiceOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      getVoice,
+      (r) => `Voice for project ${r.project_id.slice(0, 8)}\u2026: "${r.one_liner || "\u2014"}". ${r.tone_descriptors.length} tone descriptor${r.tone_descriptors.length === 1 ? "" : "s"}.`
+    )
+  );
+  server.registerTool(
+    "get_audience",
+    {
+      title: "Get audience profile",
+      description: "Returns only the audience slice: primary segment, optional secondary, needs / pain points, channels. Use when targeting copy or design at a specific audience. Costs 1 credit.",
+      inputSchema: getAudienceInputSchema.shape,
+      outputSchema: getAudienceOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      getAudience,
+      (r) => `Audience: ${r.primary || "\u2014"}` + (r.secondary ? ` (secondary: ${r.secondary})` : "") + `. ${r.needs.length} stated need${r.needs.length === 1 ? "" : "s"}.`
+    )
+  );
+  server.registerTool(
+    "get_design_intent",
+    {
+      title: "Get design intent",
+      description: "Returns the visual descriptors and anti-descriptors that constrain design exploration, plus the inspiration_summary. Use this before generating layouts, palettes, or component styles \u2014 it's the guardrail set the brief encodes. Costs 1 credit.",
+      inputSchema: getDesignIntentInputSchema.shape,
+      outputSchema: getDesignIntentOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      getDesignIntent,
+      (r) => `${r.descriptors.length} descriptor${r.descriptors.length === 1 ? "" : "s"}, ${r.anti_descriptors.length} anti-descriptor${r.anti_descriptors.length === 1 ? "" : "s"}.`
+    )
+  );
+  server.registerTool(
+    "get_brand_tokens",
+    {
+      title: "Get brand tokens",
+      description: "Returns the brand's design tokens: colors (with optional role), fonts (role / family / weights), radius scale, shadow scale. Use this when generating CSS, Tailwind config, or component styles that should match the brand. Costs 1 credit.",
+      inputSchema: getBrandTokensInputSchema.shape,
+      outputSchema: getBrandTokensOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      getBrandTokens,
+      (r) => `${r.colors.length} color${r.colors.length === 1 ? "" : "s"}, ${r.fonts.length} font${r.fonts.length === 1 ? "" : "s"}, ${r.radius.length} radius, ${r.shadows.length} shadow${r.shadows.length === 1 ? "" : "s"}.`
+    )
+  );
+  server.registerTool(
+    "get_decisions",
+    {
+      title: "Get decisions log",
+      description: "Returns the brand + design decisions log for a project: what was decided, why, who decided, when, and which brief field (if any) it concerns. Use this to avoid re-litigating settled questions. Costs 1 credit.",
+      inputSchema: getDecisionsInputSchema.shape,
+      outputSchema: getDecisionsOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      getDecisions,
+      (r) => `${r.items.length} decision${r.items.length === 1 ? "" : "s"} returned (newest first).`
+    )
+  );
+  server.registerTool(
+    "get_references",
+    {
+      title: "Get project references",
+      description: "Paginated list of references (captures) for one project. Use this when the LLM needs to know what visual / interaction references the user has saved for a specific project \u2014 different from list_captures which is org-wide. Costs 1 credit per call.",
+      inputSchema: getReferencesInputSchema.shape,
+      outputSchema: getReferencesOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      getReferences,
+      (r) => `${r.items.length} reference${r.items.length === 1 ? "" : "s"} returned` + (r.next_cursor ? " (more available \u2014 pass next_cursor for the next page)." : ".")
+    )
+  );
+  server.registerTool(
+    "search_references",
+    {
+      title: "Search project references",
+      description: "Keyword search over a project's references (title / url / note in v1; pgvector ranking in v1.5). Returns scored matches with matched_field signals. Use when the LLM has a specific concept in mind ('hero', 'pricing table'). Costs 1 credit.",
+      inputSchema: searchReferencesInputSchema.shape,
+      outputSchema: searchReferencesOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      searchReferences,
+      (r) => r.items.length === 0 ? `No references match "${r.query}".` : `${r.items.length} reference${r.items.length === 1 ? "" : "s"} matching "${r.query}".`
+    )
+  );
+  registerCaptureResource(server, captureStore);
+  info("server initialized", {
+    version: PKG_VERSION,
+    tools: [
+      "health",
+      "whoami",
+      "list_captures",
+      "search_captures",
+      "get_capture",
+      "get_palette",
+      "get_html",
+      "get_animation",
+      "get_media",
+      "get_brand_brief",
+      "get_voice",
+      "get_audience",
+      "get_design_intent",
+      "get_brand_tokens",
+      "get_decisions",
+      "get_references",
+      "search_references"
+    ],
+    resources: ["zaai-capture://{id}"]
+  });
+  return server;
+}
+function makeProjectToolHandler(store, fn, summary) {
+  return async (args) => {
+    try {
+      const result = await fn(store, args);
+      return {
+        structuredContent: result,
+        content: [{ type: "text", text: summary(result) }]
+      };
+    } catch (err) {
+      return toolErrorResponse(err);
+    }
+  };
+}
+function makeFocusedGetterHandler(store, fn, label) {
+  return async (args) => {
+    try {
+      const result = await fn(store, args);
+      return {
+        structuredContent: result,
+        content: [
+          {
+            type: "text",
+            text: `${result.type} capture \xB7 ${label} slice for id ${result.id.slice(0, 8)}\u2026`
+          }
+        ]
+      };
+    } catch (err) {
+      return toolErrorResponse(err);
+    }
+  };
+}
+function summariseWhoami(r) {
+  const scope = r.projectScope === null ? "all projects in org" : `${r.projectScope.length} project${r.projectScope.length === 1 ? "" : "s"}`;
+  return `Zaai Dev workspace \xB7 user ${r.userId.slice(0, 8)}\u2026 \xB7 org ${r.orgId.slice(0, 8)}\u2026 \xB7 ${scope} \xB7 ${r.balance.totalBalance} credits (${r.mcpCallCost}/call)`;
+}
+function toolErrorResponse(err) {
+  if (err instanceof WorkspaceApiError) {
+    switch (err.status) {
+      case 401:
+        return errorContent(
+          "Authentication failed. Your ZAAI_API_TOKEN is invalid, expired, or revoked. Mint a new MCP token at https://www.zaaistudio.com/dev/settings/tokens and update your MCP client config."
+        );
+      case 402:
+        return errorContent(
+          "Out of credits. Top up at https://www.zaaistudio.com/dev/settings/billing."
+        );
+      case 0:
+        return errorContent(
+          `Network failure reaching the Zaai Dev workspace: ${describe(err.body)}. Check your connection or ZAAI_API_URL setting.`
+        );
+      default:
+        return errorContent(
+          `Workspace returned ${err.status} for ${err.path}: ${describe(err.body)}.`
+        );
+    }
+  }
+  return errorContent(`Unexpected MCP tool failure: ${describe(err)}`);
+}
+function errorContent(text) {
+  return { isError: true, content: [{ type: "text", text }] };
+}
+function describe(value) {
+  if (value instanceof Error) return value.message;
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+// src/config.ts
+var DEFAULT_API_URL = "https://www.zaaistudio.com";
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+function loadConfig() {
+  const apiToken = process.env.ZAAI_API_TOKEN;
+  if (!apiToken) {
+    throw new ConfigError(
+      "ZAAI_API_TOKEN is not set. Mint a token at https://www.zaaistudio.com/dev/settings/tokens (kind = mcp) and pass it via the env in your MCP client config."
+    );
+  }
+  if (!apiToken.startsWith("zaai_mcp_")) {
+    throw new ConfigError(
+      "ZAAI_API_TOKEN must start with 'zaai_mcp_'. Did you paste an extension token (zaai_ext_*) by accident? Issue an AI tool token at https://www.zaaistudio.com/dev/settings/tokens."
+    );
+  }
+  const rawUrl = process.env.ZAAI_API_URL ?? DEFAULT_API_URL;
+  const apiUrl = rawUrl.replace(/\/+$/, "");
+  info("config loaded", { apiUrl });
+  return { apiToken, apiUrl };
+}
+
+// src/bin/http.ts
+var DEFAULT_PORT = 3001;
+async function main() {
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      error("FATAL: " + err.message);
+      process.exit(1);
+    }
+    throw err;
+  }
+  const port = parseInt(process.env.ZAAI_HTTP_PORT ?? String(DEFAULT_PORT), 10);
+  if (!Number.isFinite(port) || port < 1 || port > 65535) {
+    error(`FATAL: ZAAI_HTTP_PORT must be a valid port number, got ${process.env.ZAAI_HTTP_PORT}`);
+    process.exit(1);
+  }
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => randomUUID()
+  });
+  const server = createServer(config);
+  await server.connect(transport);
+  const httpServer = createHttpServer(async (req, res) => {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS, DELETE");
+    res.setHeader(
+      "Access-Control-Allow-Headers",
+      "Content-Type, Authorization, Mcp-Session-Id, Last-Event-ID"
+    );
+    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+    if (req.method === "OPTIONS") {
+      res.writeHead(204).end();
+      return;
+    }
+    if (req.method === "GET" && req.url === "/healthz") {
+      res.writeHead(200, { "Content-Type": "application/json" }).end(
+        JSON.stringify({ ok: true, version: PKG_VERSION, transport: "streamable-http" })
+      );
+      return;
+    }
+    if (req.url === "/mcp" || req.url?.startsWith("/mcp?")) {
+      try {
+        await transport.handleRequest(req, res);
+      } catch (err) {
+        error("transport.handleRequest threw", err);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" }).end(
+            JSON.stringify({ error: "internal_error" })
+          );
+        }
+      }
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "application/json" }).end(
+      JSON.stringify({ error: "not_found", expected: ["/mcp", "/healthz"] })
+    );
+  });
+  httpServer.listen(port, () => {
+    info("streamable-http transport listening", {
+      port,
+      version: PKG_VERSION,
+      mode: "single-tenant"
+    });
+  });
+  const shutdown = (signal) => {
+    info(`received ${signal}, closing http server`);
+    httpServer.close(() => {
+      transport.close().catch((err) => error("transport close failed", err));
+      process.exit(0);
+    });
+    setTimeout(() => process.exit(0), 1e4).unref();
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+}
+main().catch((err) => {
+  error("fatal startup error", err);
+  process.exit(1);
+});
+//# sourceMappingURL=http.js.map