@zaai-dev/mcp 0.3.1 → 0.6.1

package/dist/bin/stdio.js

@@ -10,7 +10,7 @@ import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js
 import { z } from "zod";
 
 // src/version.ts
-var PKG_VERSION = true ? "0.3.1" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.6.1" : "0.0.0-dev";
 
 // src/tools/health.ts
 var healthInputSchema = z.object({});
@@ -82,7 +82,8 @@ async function mcpApiFetch(config, path, init = {}) {
     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));
+        const serverWait = res.status === 429 ? rateLimitWaitMs(res.headers) : null;
+        await sleep(serverWait ?? BASE_BACKOFF_MS * 2 ** (attempt - 1));
         continue;
       }
     }
@@ -90,6 +91,25 @@ async function mcpApiFetch(config, path, init = {}) {
   }
   throw lastErr ?? new WorkspaceApiError(0, { message: "no attempts" }, path);
 }
+var MAX_RATE_LIMIT_WAIT_MS = 1e4;
+function rateLimitWaitMs(headers) {
+  const retryAfter = headers.get("retry-after");
+  if (retryAfter) {
+    const secs = Number(retryAfter);
+    if (Number.isFinite(secs) && secs >= 0) {
+      return Math.min(secs * 1e3, MAX_RATE_LIMIT_WAIT_MS);
+    }
+  }
+  const reset = headers.get("x-ratelimit-reset");
+  if (reset) {
+    const resetEpoch = Number(reset);
+    if (Number.isFinite(resetEpoch)) {
+      const ms = resetEpoch * 1e3 - Date.now();
+      if (ms > 0) return Math.min(ms, MAX_RATE_LIMIT_WAIT_MS);
+    }
+  }
+  return null;
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -128,7 +148,7 @@ 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(
+      type: z3.enum(["page", "element", "composite", "recording"]).describe(
         "page = full-page screenshot + DOM context; element = a single picked element; composite = multiple elements stacked."
       ),
       sourceTitle: z3.string(),
@@ -160,7 +180,7 @@ var getCaptureInputSchema = z4.object({
 });
 var getCaptureOutputSchema = z4.object({
   id: z4.string(),
-  type: z4.enum(["page", "element", "composite"]),
+  type: z4.enum(["page", "element", "composite", "recording"]),
   projectId: z4.string(),
   sourceTitle: z4.string(),
   sourceUrl: z4.string(),
@@ -193,7 +213,7 @@ var searchCapturesOutputSchema = z5.object({
   captures: z5.array(
     z5.object({
       id: z5.string(),
-      type: z5.enum(["page", "element", "composite"]),
+      type: z5.enum(["page", "element", "composite", "recording"]),
       sourceTitle: z5.string(),
       sourceUrl: z5.string(),
       capturedAt: z5.string(),
@@ -217,7 +237,7 @@ var focusedGetterInputSchema = z6.object({
 });
 var focusedGetterOutputSchema = z6.object({
   id: z6.string(),
-  type: z6.enum(["page", "element", "composite"]),
+  type: z6.enum(["page", "element", "composite", "recording"]),
   field: z6.string(),
   data: z6.unknown()
 }).passthrough();
@@ -242,11 +262,19 @@ async function getMedia(store, args) {
   return store.getField(args.id, "media");
 }
 
+// src/tools/get-structure.ts
+async function getStructure(store, args) {
+  return store.getField(args.id, "structure");
+}
+
 // 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."
+    "Zaai Dev project UUID. Find via the workspace at zaaidev.com/dev/projects."
+  ),
+  brief_id: z7.string().uuid().optional().describe(
+    "Target a specific brief by id (from list_briefs). Omit to read the project's brand-identity brief."
   )
 });
 var getBrandBriefOutputSchema = z7.object({
@@ -281,13 +309,16 @@ var getBrandBriefOutputSchema = z7.object({
   updated_at: z7.string()
 }).passthrough();
 async function getBrandBrief(store, args) {
-  return store.getBrandBrief(args.project_id);
+  return store.getBrandBrief(args.project_id, args.brief_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.")
+  project_id: z8.string().uuid().describe("Zaai Dev project UUID."),
+  brief_id: z8.string().uuid().optional().describe(
+    "Target a specific brief by id (from list_briefs). Omit to read the project's brand-identity brief."
+  )
 });
 var getVoiceOutputSchema = z8.object({
   project_id: z8.string(),
@@ -298,13 +329,16 @@ var getVoiceOutputSchema = z8.object({
   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);
+  return store.getVoice(args.project_id, args.brief_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.")
+  project_id: z9.string().uuid().describe("Zaai Dev project UUID."),
+  brief_id: z9.string().uuid().optional().describe(
+    "Target a specific brief by id (from list_briefs). Omit to read the project's brand-identity brief."
+  )
 });
 var getAudienceOutputSchema = z9.object({
   project_id: z9.string(),
@@ -314,13 +348,16 @@ var getAudienceOutputSchema = z9.object({
   channels: z9.array(z9.string()).describe("Where this audience consumes content.")
 }).passthrough();
 async function getAudience(store, args) {
-  return store.getAudience(args.project_id);
+  return store.getAudience(args.project_id, args.brief_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.")
+  project_id: z10.string().uuid().describe("Zaai Dev project UUID."),
+  brief_id: z10.string().uuid().optional().describe(
+    "Target a specific brief by id (from list_briefs). Omit to read the project's brand-identity brief."
+  )
 });
 var getDesignIntentOutputSchema = z10.object({
   project_id: z10.string(),
@@ -331,13 +368,16 @@ var getDesignIntentOutputSchema = z10.object({
   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);
+  return store.getDesignIntent(args.project_id, args.brief_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.")
+  project_id: z11.string().uuid().describe("Zaai Dev project UUID."),
+  brief_id: z11.string().uuid().optional().describe(
+    "Target a specific brief by id (from list_briefs). Omit to read the project's brand-identity brief."
+  )
 });
 var getBrandTokensOutputSchema = z11.object({
   project_id: z11.string(),
@@ -359,7 +399,7 @@ var getBrandTokensOutputSchema = z11.object({
   shadows: z11.array(z11.object({ name: z11.string(), value: z11.string() }))
 }).passthrough();
 async function getBrandTokens(store, args) {
-  return store.getBrandTokens(args.project_id);
+  return store.getBrandTokens(args.project_id, args.brief_id);
 }
 
 // src/tools/get-decisions.ts
@@ -397,7 +437,7 @@ var getReferencesInputSchema = z13.object({
 });
 var referenceItem = z13.object({
   id: z13.string(),
-  type: z13.enum(["page", "element", "composite"]),
+  type: z13.enum(["page", "element", "composite", "recording"]),
   source_url: z13.string(),
   source_title: z13.string(),
   note: z13.string().nullable(),
@@ -426,7 +466,7 @@ var searchReferencesInputSchema = z14.object({
 });
 var searchReferenceItem = z14.object({
   id: z14.string(),
-  type: z14.enum(["page", "element", "composite"]),
+  type: z14.enum(["page", "element", "composite", "recording"]),
   source_url: z14.string(),
   source_title: z14.string(),
   note: z14.string().nullable(),
@@ -448,6 +488,164 @@ async function searchReferences(store, args) {
   });
 }
 
+// src/tools/list-briefs.ts
+import { z as z15 } from "zod";
+var listBriefsInputSchema = z15.object({
+  project_id: z15.string().uuid().describe("Zaai Dev project UUID.")
+});
+var briefTypeEnum = z15.enum([
+  "brand_identity",
+  "web_site",
+  "layout_page",
+  "component",
+  "campaign",
+  "naming"
+]);
+var briefStatusEnum = z15.enum([
+  "to_draft",
+  "drafting",
+  "synthesised",
+  "in_review",
+  "changes_requested",
+  "approved"
+]);
+var listBriefsItem = z15.object({
+  id: z15.string(),
+  brief_type: briefTypeEnum,
+  name: z15.string().nullable(),
+  display_name: z15.string(),
+  status: briefStatusEnum,
+  current_version: z15.object({ version: z15.number().int(), created_at: z15.string() }).nullable(),
+  created_at: z15.string(),
+  updated_at: z15.string()
+}).passthrough();
+var listBriefsOutputSchema = z15.object({
+  project_id: z15.string(),
+  items: z15.array(listBriefsItem)
+}).passthrough();
+async function listBriefs(store, args) {
+  return store.listBriefs(args.project_id);
+}
+
+// src/tools/list-docs.ts
+var listDocsInputSchema = listBriefsInputSchema;
+var listDocsOutputSchema = listBriefsOutputSchema;
+async function listDocs(store, args) {
+  return store.listDocs(args.project_id);
+}
+
+// src/tools/get-doc.ts
+import { z as z16 } from "zod";
+var getDocInputSchema = z16.object({
+  project_id: z16.string().uuid().describe("Zaai Dev project UUID."),
+  doc_id: z16.string().uuid().optional().describe(
+    "Target a specific doc by id (from list_docs). Omit to read the project's brand-identity doc."
+  )
+});
+var briefStatusEnum2 = z16.enum([
+  "to_draft",
+  "drafting",
+  "synthesised",
+  "in_review",
+  "changes_requested",
+  "approved"
+]);
+var docBlock = z16.object({
+  type: z16.enum(["text", "capture", "image", "divider"]),
+  markdown: z16.string().optional(),
+  capture_id: z16.string().nullable().optional(),
+  role: z16.string().optional(),
+  treatment: z16.string().optional(),
+  note: z16.string().nullable().optional(),
+  src: z16.string().optional()
+}).passthrough();
+var getDocOutputSchema = z16.object({
+  project_id: z16.string(),
+  doc_id: z16.string(),
+  kind: z16.literal("block-doc"),
+  name: z16.string(),
+  version: z16.number().int(),
+  status: briefStatusEnum2,
+  approval: z16.object({ state: z16.string(), version: z16.number().int().nullable() }).nullable().describe("Sign-off signal: whether the doc is an approved spec or a draft."),
+  blocks: z16.array(docBlock),
+  references: z16.array(z16.object({}).passthrough())
+}).passthrough();
+async function getDoc(store, args) {
+  return store.getDoc(args.project_id, args.doc_id);
+}
+
+// src/tools/get-project-bundle.ts
+import { z as z17 } from "zod";
+var getProjectBundleInputSchema = z17.object({
+  project_id: z17.string().uuid().describe("Zaai Dev project UUID.")
+});
+var getProjectBundleOutputSchema = z17.object({
+  project_id: z17.string(),
+  project_name: z17.string(),
+  docs: z17.array(getDocOutputSchema),
+  captures: z17.array(
+    z17.object({
+      id: z17.string(),
+      title: z17.string(),
+      type: z17.string(),
+      palette: z17.array(z17.string()),
+      vibe: z17.array(z17.string())
+    }).passthrough()
+  )
+}).passthrough();
+async function getProjectBundle(store, args) {
+  return store.getProjectBundle(args.project_id);
+}
+
+// src/tools/add-reference.ts
+import { z as z18 } from "zod";
+var addReferenceInputSchema = z18.object({
+  project_id: z18.string().uuid().describe("Zaai Dev project UUID."),
+  source_url: z18.string().url().describe("URL of the page/element being referenced."),
+  source_title: z18.string().min(1).max(500).describe("Human-readable title for the reference."),
+  note: z18.string().max(5e3).nullable().optional().describe("Optional note explaining why this reference matters."),
+  tags: z18.array(z18.string().min(1).max(60)).max(50).optional().describe("Optional tags to organise the reference.")
+});
+var addReferenceOutputSchema = z18.object({
+  id: z18.string(),
+  project_id: z18.string(),
+  source_url: z18.string(),
+  source_title: z18.string(),
+  source_kind: z18.enum(["extension", "mcp"]).describe("Origin of the reference. MCP-added references are 'mcp'."),
+  captured_at: z18.string()
+}).passthrough();
+async function addReference(store, args) {
+  return store.addReference(args.project_id, {
+    source_url: args.source_url,
+    source_title: args.source_title,
+    note: args.note,
+    tags: args.tags
+  });
+}
+
+// src/tools/log-decision.ts
+import { z as z19 } from "zod";
+var logDecisionInputSchema = z19.object({
+  project_id: z19.string().uuid().describe("Zaai Dev project UUID."),
+  title: z19.string().min(1).max(200).describe("What was decided (one line)."),
+  rationale: z19.string().max(5e3).nullable().optional().describe("Optional reasoning behind the decision."),
+  brief_field: z19.string().max(100).nullable().optional().describe("Optional brief slice this decision concerns (e.g. 'voice.tone').")
+});
+var logDecisionOutputSchema = z19.object({
+  id: z19.string(),
+  project_id: z19.string(),
+  title: z19.string(),
+  brief_field: z19.string().nullable(),
+  created_at: z19.string()
+}).passthrough();
+async function logDecision(store, args) {
+  return store.logDecision(args.project_id, {
+    title: args.title,
+    rationale: args.rationale,
+    brief_field: args.brief_field
+  });
+}
+
 // src/store/http-store.ts
 var HttpCaptureStore = class {
   constructor(config) {
@@ -480,39 +678,45 @@ var HttpCaptureStore = class {
 };
 
 // src/store/project-store.ts
+function briefIdQuery(briefId) {
+  if (!briefId) return "";
+  const sp = new URLSearchParams();
+  sp.set("brief_id", briefId);
+  return `?${sp.toString()}`;
+}
 var HttpProjectStore = class {
   constructor(config) {
     this.config = config;
   }
   config;
-  async getBrandBrief(projectId) {
+  async getBrandBrief(projectId, briefId) {
     return mcpApiFetch(
       this.config,
-      `/api/mcp/projects/${encodeURIComponent(projectId)}/brief`
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/brief${briefIdQuery(briefId)}`
     );
   }
-  async getVoice(projectId) {
+  async getVoice(projectId, briefId) {
     return mcpApiFetch(
       this.config,
-      `/api/mcp/projects/${encodeURIComponent(projectId)}/voice`
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/voice${briefIdQuery(briefId)}`
     );
   }
-  async getAudience(projectId) {
+  async getAudience(projectId, briefId) {
     return mcpApiFetch(
       this.config,
-      `/api/mcp/projects/${encodeURIComponent(projectId)}/audience`
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/audience${briefIdQuery(briefId)}`
     );
   }
-  async getDesignIntent(projectId) {
+  async getDesignIntent(projectId, briefId) {
     return mcpApiFetch(
       this.config,
-      `/api/mcp/projects/${encodeURIComponent(projectId)}/design-intent`
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/design-intent${briefIdQuery(briefId)}`
     );
   }
-  async getBrandTokens(projectId) {
+  async getBrandTokens(projectId, briefId) {
     return mcpApiFetch(
       this.config,
-      `/api/mcp/projects/${encodeURIComponent(projectId)}/brand-tokens`
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/brand-tokens${briefIdQuery(briefId)}`
     );
   }
   async getDecisions(projectId, limit) {
@@ -543,6 +747,54 @@ var HttpProjectStore = class {
       `/api/mcp/projects/${encodeURIComponent(projectId)}/references/search?${sp.toString()}`
     );
   }
+  // ── v1.2 / v1.3 / v1.4 ──────────────────────────────────────
+  async listBriefs(projectId) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/briefs`
+    );
+  }
+  async listDocs(projectId) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/docs`
+    );
+  }
+  async getDoc(projectId, docId) {
+    const seg = docId ? encodeURIComponent(docId) : "default";
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/docs/${seg}`
+    );
+  }
+  async getProjectBundle(projectId) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/bundle`
+    );
+  }
+  async addReference(projectId, args) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/references`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(args)
+      }
+    );
+  }
+  async logDecision(projectId, args) {
+    return mcpApiFetch(
+      this.config,
+      `/api/mcp/projects/${encodeURIComponent(projectId)}/decisions`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(args)
+      }
+    );
+  }
 };
 
 // src/resources/capture-resource.ts
@@ -777,6 +1029,16 @@ function createServer(config) {
     },
     makeFocusedGetterHandler(captureStore, getMedia, "media")
   );
+  server.registerTool(
+    "get_structure",
+    {
+      title: "Get capture structure map",
+      description: "Returns just the Layer-Explorer teardown \u2014 the 'structure map' (BUILD-PLAN \xA76.6): a flat list of the captured subtree's nodes, each with depth, a root-relative rect, short selector, inferred component, headline computed style (display/background/color/radius/font), and flags (flex/grid, animated, brandToken, a11yIssue, hidden). Page \u2192 main-content subtree; element \u2192 the captured element's subtree; composite \u2192 one map per picked element. Use this to understand HOW a reference is built before an on-brand rebuild, without loading full HTML + computed style. Returns structure:null on pre-\xA76.6 captures. Costs 1 credit.",
+      inputSchema: focusedGetterInputSchema.shape,
+      outputSchema: focusedGetterOutputSchema.shape
+    },
+    makeFocusedGetterHandler(captureStore, getStructure, "structure")
+  );
   server.registerTool(
     "get_brand_brief",
     {
@@ -889,6 +1151,90 @@ function createServer(config) {
       (r) => r.items.length === 0 ? `No references match "${r.query}".` : `${r.items.length} reference${r.items.length === 1 ? "" : "s"} matching "${r.query}".`
     )
   );
+  server.registerTool(
+    "list_briefs",
+    {
+      title: "List briefs",
+      description: "List every brief on a project \u2014 id, type, name, status, and current-version metadata. Call this first when working with a project so you know what briefs exist; then pass `brief_id` into the targeted read tools (get_brand_brief / get_voice / get_audience / get_design_intent / get_brand_tokens) to target a non-default brief. Returns oldest-first by created_at. Costs 1 credit.",
+      inputSchema: listBriefsInputSchema.shape,
+      outputSchema: listBriefsOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      listBriefs,
+      (r) => `${r.items.length} brief${r.items.length === 1 ? "" : "s"} on project ${r.project_id.slice(0, 8)}\u2026 (oldest first).`
+    )
+  );
+  server.registerTool(
+    "list_docs",
+    {
+      title: "List docs",
+      description: "List every doc on a project \u2014 id, type, name, status, and current-version metadata. Friendly alias of list_briefs. Call first, then pass `doc_id` into get_doc. Returns oldest-first. Costs 1 credit.",
+      inputSchema: listDocsInputSchema.shape,
+      outputSchema: listDocsOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      listDocs,
+      (r) => `${r.items.length} doc${r.items.length === 1 ? "" : "s"} on project ${r.project_id.slice(0, 8)}\u2026 (oldest first).`
+    )
+  );
+  server.registerTool(
+    "get_doc",
+    {
+      title: "Get doc",
+      description: "Read a doc as an agent-ready block list: text blocks as markdown, capture blocks as structured references with role / treatment / note and full capture metadata (palette, typography, vibe, inferred component) plus the captured `code` (element outerHTML + computed CSS + build tokens like bg/color/radius/padding/font/shadow/border) so you build from real values, not a screenshot guess. Includes the sign-off signal (approval state + version) so you know whether you're building from an approved spec or a draft. Omit doc_id for the project's brand-identity doc. Costs 1 credit.",
+      inputSchema: getDocInputSchema.shape,
+      outputSchema: getDocOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      getDoc,
+      (r) => `Doc "${r.name}" v${r.version} (${r.status})` + (r.approval ? `, approval: ${r.approval.state}` : "") + `, ${r.blocks.length} block${r.blocks.length === 1 ? "" : "s"}.`
+    )
+  );
+  server.registerTool(
+    "get_project_bundle",
+    {
+      title: "Get project bundle",
+      description: "Fetch the whole project as one agent-ready bundle: every doc's block list (text + roled capture references + approval state) plus the project's capture library. Use this to load full project context up front in a single call. Can be large. Costs 1 credit.",
+      inputSchema: getProjectBundleInputSchema.shape,
+      outputSchema: getProjectBundleOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      getProjectBundle,
+      (r) => `Bundle for "${r.project_name}": ${r.docs.length} doc${r.docs.length === 1 ? "" : "s"}, ${r.captures.length} capture${r.captures.length === 1 ? "" : "s"}.`
+    )
+  );
+  server.registerTool(
+    "add_reference",
+    {
+      title: "Add reference",
+      description: "Add a URL reference to a project's library \u2014 for when you've found a relevant page and want to save it. No screenshot required; stored with source_kind='mcp' so the UI distinguishes it from extension-pushed captures. Use when discovering inspiration, never to bulk-import URLs the user already has. Costs 5 credits.",
+      inputSchema: addReferenceInputSchema.shape,
+      outputSchema: addReferenceOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      addReference,
+      (r) => `Added reference "${r.source_title}" (${r.source_kind}) to project ${r.project_id.slice(0, 8)}\u2026.`
+    )
+  );
+  server.registerTool(
+    "log_decision",
+    {
+      title: "Log decision",
+      description: "Append a decision to a project's decisions log: what was decided, optionally why, optionally which brief slice it concerns (e.g. 'voice.tone'). Use this when you make or recommend a brand- or design-relevant choice that future you should trace back. Costs 1 credit.",
+      inputSchema: logDecisionInputSchema.shape,
+      outputSchema: logDecisionOutputSchema.shape
+    },
+    makeProjectToolHandler(
+      projectStore,
+      logDecision,
+      (r) => `Logged decision "${r.title}"` + (r.brief_field ? ` (${r.brief_field})` : "") + `.`
+    )
+  );
   registerCaptureResource(server, captureStore);
   info("server initialized", {
     version: PKG_VERSION,
@@ -902,6 +1248,7 @@ function createServer(config) {
       "get_html",
       "get_animation",
       "get_media",
+      "get_structure",
       "get_brand_brief",
       "get_voice",
       "get_audience",
@@ -909,7 +1256,13 @@ function createServer(config) {
       "get_brand_tokens",
       "get_decisions",
       "get_references",
-      "search_references"
+      "search_references",
+      "list_briefs",
+      "list_docs",
+      "get_doc",
+      "get_project_bundle",
+      "add_reference",
+      "log_decision"
     ],
     resources: ["zaai-capture://{id}"]
   });
@@ -952,27 +1305,61 @@ function summariseWhoami(r) {
 }
 function toolErrorResponse(err) {
   if (err instanceof WorkspaceApiError) {
+    const cls = errorClassOf(err.body);
+    const detail = describe(err.body);
     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."
+          "Authentication failed. Your ZAAI_API_TOKEN is invalid, expired, or revoked. Mint a new MCP token at https://zaaidev.com/dev/settings/tokens and update your MCP client config."
         );
       case 402:
+        if (cls === "SubscriptionRequired") {
+          return errorContent(
+            "Zaai Dev needs an active subscription or trial to use the MCP. Start one (14-day free trial, no card required) at https://zaaidev.com/dev/settings/billing."
+          );
+        }
         return errorContent(
-          "Out of credits. Top up at https://www.zaaistudio.com/dev/settings/billing."
+          "Out of credits for MCP calls. Top up at https://zaaidev.com/dev/settings/billing."
+        );
+      case 403:
+        return errorContent(
+          "This token is out of scope for that project (OutOfScope). The MCP token is restricted to specific projects; pick a project the token can access, or mint a token with broader scope at https://zaaidev.com/dev/settings/tokens."
+        );
+      case 404:
+        return errorContent(
+          `Not found (${cls ?? "not_found"}): ${detail}. The project, brief, or doc id doesn't exist or isn't visible to this token. List first (list_briefs / list_docs / list_captures) to get valid ids.`
+        );
+      case 410:
+        return errorContent(
+          "That project is archived (ProjectArchived) and can no longer be read over MCP. Unarchive it in the workspace to access it again."
+        );
+      case 422:
+        return errorContent(
+          `Unprocessable (${cls ?? "invalid"}): ${detail}. Likely a wrong brief type for this tool or an invalid doc id \u2014 check the tool's expected input against list_briefs / list_docs.`
+        );
+      case 429:
+        return errorContent(
+          "Rate limited (RateLimited). The MCP server retried with backoff and still hit the limit \u2014 wait a moment before the next call."
         );
       case 0:
         return errorContent(
-          `Network failure reaching the Zaai Dev workspace: ${describe(err.body)}. Check your connection or ZAAI_API_URL setting.`
+          `Network failure reaching the Zaai Dev workspace: ${detail}. Check your connection or ZAAI_API_URL setting.`
         );
       default:
         return errorContent(
-          `Workspace returned ${err.status} for ${err.path}: ${describe(err.body)}.`
+          `Workspace returned ${err.status}${cls ? ` (${cls})` : ""} for ${err.path}: ${detail}.`
         );
     }
   }
   return errorContent(`Unexpected MCP tool failure: ${describe(err)}`);
 }
+function errorClassOf(body) {
+  if (body && typeof body === "object" && "errorClass" in body) {
+    const v = body.errorClass;
+    return typeof v === "string" ? v : null;
+  }
+  return null;
+}
 function errorContent(text) {
   return { isError: true, content: [{ type: "text", text }] };
 }
@@ -987,7 +1374,7 @@ function describe(value) {
 }
 
 // src/config.ts
-var DEFAULT_API_URL = "https://www.zaaistudio.com";
+var DEFAULT_API_URL = "https://zaaidev.com";
 var ConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -998,19 +1385,44 @@ 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."
+      "ZAAI_API_TOKEN is not set. Mint a token at https://zaaidev.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."
+      "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://zaaidev.com/dev/settings/tokens."
     );
   }
   const rawUrl = process.env.ZAAI_API_URL ?? DEFAULT_API_URL;
-  const apiUrl = rawUrl.replace(/\/+$/, "");
+  const apiUrl = validateApiUrl(rawUrl.replace(/\/+$/, ""));
   info("config loaded", { apiUrl });
   return { apiToken, apiUrl };
 }
+function validateApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ConfigError(
+      `ZAAI_API_URL is not a valid URL: ${JSON.stringify(value)}.`
+    );
+  }
+  const host = url.hostname.toLowerCase();
+  const isLocal = host === "localhost" || host === "127.0.0.1";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocal)) {
+    throw new ConfigError(
+      `ZAAI_API_URL must use https:// (got ${url.protocol}). The MCP token is sent on every request and must never travel in cleartext.`
+    );
+  }
+  const allowAny = process.env.ZAAI_API_URL_ALLOW_ANY === "1";
+  const isZaai = host === "zaaidev.com" || host.endsWith(".zaaidev.com") || host === "zaaistudio.com" || host.endsWith(".zaaistudio.com");
+  if (!isZaai && !isLocal && !allowAny) {
+    throw new ConfigError(
+      `ZAAI_API_URL host ${JSON.stringify(host)} is not a zaaidev.com domain. The MCP token would be sent to it. If this is intentional (self-hosted/staging workspace), set ZAAI_API_URL_ALLOW_ANY=1.`
+    );
+  }
+  return value;
+}
 
 // src/bin/stdio.ts
 async function main() {