@sutraspaces/mcp-server 1.1.1 → 1.1.2

package/README.md

@@ -1,6 +1,6 @@
 # Sutra MCP Server
 
-An [MCP](https://modelcontextprotocol.io) server that connects AI agents to the [Sutra Admin API](https://sutra.co). Manage spaces, members, contacts, content, discussions, surveys, plans, broadcasts, and more — all through your AI tools.
+An MCP server that connects AI agents to the Sutra Admin API. Manage spaces, members, contacts, content, discussions, surveys, plans, broadcasts, and more — all through your AI tools. See the [Sutra developer docs](https://sutra.co/developers/docs) for API documentation.
 
 ## Quick Start
 
@@ -52,6 +52,8 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TO
 |---|---|---|
 | `SUTRA_API_TOKEN` | Yes | Your Sutra Admin API token (`sutra_live_sk_...`) |
 | `SUTRA_BASE_URL` | No | Override the API URL (default: `https://api.sutra.co/api/admin/v1`) |
+| `SUTRA_HELP_CENTER_TOKEN` | No | Internal scoped admin key (`sutra_admin_...`) for Lotus Help Center tools |
+| `SUTRA_HELP_CENTER_BASE_URL` | No | Override the Help Center API URL (default: `https://api.sutra.co/api/v4/lotus/help`) |
 
 ## Available Tools
 
@@ -64,10 +66,16 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TO
 - **get_space** — Get details for a single space
 - **list_child_spaces** — List direct child spaces
 - **create_space** — Create a new space (top-level or child)
+- **create_child_space** — Create a child space and make it visible through placement
+- **attach_child_space** — Attach an existing space under a parent and make it visible
+- **update_child_space_placement** — Move or repair a child space display
+- **detach_child_space** — Detach a child from one parent without deleting it
 - **update_space** — Update space name, description, type, privacy, or state
 - **delete_space** — Delete/archive a space
 - **reorder_child_spaces** — Reorder children within a parent
 
+Use `sp_...` IDs, not slugs. For normal course and section pages, use `placement.surface = "auto"`.
+
 ### Members
 - **list_members** — List space members with optional email, user_id, search, role, state, and custom property filtering
 - **get_member** — Get member details
@@ -86,8 +94,27 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TO
 - **bulk_update_contact_property_values** — Set or clear property values for up to 100 contacts at once
 
 ### Content & Discussions
-- **list_content** / **get_content_block** / **create_content** / **update_content** / **delete_content** — Manage content blocks
+- **get_document_capabilities** / **get_document** — Read document editing rules and the visible Tiptap document
+- **replace_document** / **insert_document_nodes** / **update_document_node** / **delete_document_node** / **move_document_node** — Edit visible document content by Tiptap node UID
+- **list_content** / **get_content_block** / **create_content** / **update_content** / **delete_content** — Legacy content-block mirror tools
 - **reorder_content** — Reorder content blocks within a space
+
+### Media Uploads
+- **create_media_upload** — Create a server-mediated direct-to-S3 upload session
+- **complete_media_upload** — Verify the uploaded object and queue video processing
+- **get_media_upload** — Read upload and processing status
+- **cancel_media_upload** — Abandon a pending upload
+- **create_media_reference** — Insert a Loom, YouTube, or Vimeo embed without uploading a file
+
+### Design Tools
+
+- **get_design_capabilities** — Read Sutra's renderer-aware design manifest
+- **get_space_design** — Read current page-design nodes and digest for a space
+- **validate_space_design** — Validate proposed page-design nodes
+- **create_or_update_design_draft** — Create or update a digest-guarded design draft
+- **publish_design_draft** — Publish a draft with conflict and destructive-omission protection
+- **restore_design_draft** — Restore the pre-publish backup for a published design draft
+- **import_design_asset** — Re-host an external image URL and return the canonical Sutra URL
 - **list_messages** / **get_message** / **create_message** / **update_message** / **delete_message** — Manage discussion messages
 - **list_reflections** / **get_reflection** / **create_reflection** / **update_reflection** / **delete_reflection** — Manage threaded replies
 
@@ -120,12 +147,24 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TO
 - **send_broadcast** — Send a broadcast to space members
 - **get_broadcast_delivery_status** — Check delivery progress
 
+### Help Center
+These tools are available only when `SUTRA_HELP_CENTER_TOKEN` is set.
+
+- **help_list_articles** / **help_get_article** — Read Lotus Help Center articles, metadata, and version history
+- **help_create_article** / **help_update_article** — Human/admin-style create and update through Lotus
+- **help_propose_article** — Submit an AI-authored draft as `ai_cobolt` and mark it pending human review
+- **help_propose_article_update** — Submit AI-authored changes to an existing article without publishing them
+- **help_review_article** — Approve or reject a pending article version
+- **help_publish_article** — Explicitly publish an article version
+- **help_list_collections** / **help_create_collection** / **help_update_collection** / **help_delete_collection** — Manage Help Center collections
+
 ## Available Resources
 
 - **sutra://admin-api/overview** — Core Admin API concepts, public ID prefixes, scopes, pagination, and filtering
 - **sutra://admin-api/membership-spaces** — Difference between admin-manageable spaces and limited membership-space inventory
 - **sutra://admin-api/contacts-properties** — Contact listing and member/contact property value workflows
 - **sutra://admin-api/people-filtering** — Member and contact search, email, state, role, and custom property filtering
+- **sutra://design/capabilities** — Renderer-aware design rules and supported fonts for Sutra page-design tools
 
 ## API Concepts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sutraspaces/mcp-server",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "MCP server for the Sutra Admin API — manage spaces, members, contacts, content, and more via AI agents",
   "type": "module",
   "main": "src/index.js",
@@ -33,12 +33,12 @@
   ],
   "author": "Sutra <support@sutra.co> (https://sutra.co)",
   "license": "MIT",
-  "homepage": "https://github.com/joinsutra/mcp-server",
+  "homepage": "https://github.com/lorenzsell/sutra-mcp",
   "repository": {
     "type": "git",
-    "url": "https://github.com/joinsutra/mcp-server.git"
+    "url": "git+https://github.com/lorenzsell/sutra-mcp.git"
   },
   "bugs": {
-    "url": "https://github.com/joinsutra/mcp-server/issues"
+    "url": "https://github.com/lorenzsell/sutra-mcp/issues"
   }
 }

package/src/client.js

@@ -47,6 +47,10 @@ export class SutraAdminClient {
     return this.request("PATCH", path, { body, headers });
   }
 
+  put(path, body, headers) {
+    return this.request("PUT", path, { body, headers });
+  }
+
   delete(path, headers) {
     return this.request("DELETE", path, { headers });
   }

package/src/index.js

@@ -7,6 +7,8 @@ import { SutraAdminClient } from "./client.js";
 import { registerSpaceTools } from "./tools/spaces.js";
 import { registerMemberTools } from "./tools/members.js";
 import { registerContentTools } from "./tools/content.js";
+import { registerDocumentTools } from "./tools/documents.js";
+import { registerMediaTools } from "./tools/media.js";
 import { registerPropertyTools } from "./tools/properties.js";
 import { registerInvitationTools } from "./tools/invitations.js";
 import { registerSurveyTools } from "./tools/surveys.js";
@@ -16,7 +18,10 @@ import { registerBroadcastTools } from "./tools/broadcasts.js";
 import { registerDeepTool } from "./tools/deep.js";
 import { registerAutomationTools } from "./tools/automations.js";
 import { registerHelpCenterTools } from "./tools/help-center.js";
+import { registerBlogTools } from "./tools/blog.js";
+import { registerDesignTools } from "./tools/design.js";
 import { registerAdminApiResources } from "./resources/admin-api.js";
+import { registerDesignResources } from "./resources/design.js";
 
 const SUTRA_API_TOKEN = process.env.SUTRA_API_TOKEN;
 const SUTRA_BASE_URL = process.env.SUTRA_BASE_URL;
@@ -42,6 +47,8 @@ const client = new SutraAdminClient(SUTRA_API_TOKEN, SUTRA_BASE_URL);
 registerSpaceTools(server, client);
 registerMemberTools(server, client);
 registerContentTools(server, client);
+registerDocumentTools(server, client);
+registerMediaTools(server, client);
 registerPropertyTools(server, client);
 registerInvitationTools(server, client);
 registerSurveyTools(server, client);
@@ -50,8 +57,11 @@ registerCouponTools(server, client);
 registerBroadcastTools(server, client);
 registerDeepTool(server, client);
 registerAutomationTools(server, client);
+registerDesignTools(server, client);
 registerHelpCenterTools(server);
+registerBlogTools(server);
 registerAdminApiResources(server);
+registerDesignResources(server, client);
 
 async function main() {
   const transport = new StdioServerTransport();

package/src/resources/design.js

@@ -0,0 +1,77 @@
+const BUNDLED_CAPABILITIES_MARKDOWN = `# Sutra Design Capabilities
+
+Read this before designing Sutra pages.
+
+- Use get_design_capabilities for the live manifest whenever possible.
+- Read get_space_design before changing a page and keep its content_digest as base_digest.
+- Validate nodes before creating or publishing a draft.
+- Use create_or_update_design_draft and publish_design_draft instead of raw content writes.
+- If publish returns 409 conflict, re-read the design and rebase instead of retrying blindly.
+- Do not emit image_keywords; direct design writes require real image URLs.
+- Use actionCallbackValue and actionCallbackTarget for action buttons.
+- Use 12-unit grid dist arrays such as [6,6], [8,4], or [4,4,4].
+- Use only font families returned by get_design_capabilities fonts.available; other fonts fall back at render time.
+`;
+
+export function registerDesignResources(server, client) {
+  server.registerResource(
+    "sutra-design-capabilities",
+    "sutra://design/capabilities",
+    {
+      title: "Sutra Design Capabilities",
+      description: "Renderer-aware Sutra design rules and supported fonts for page-generation tools.",
+      mimeType: "text/markdown",
+    },
+    async () => {
+      let text = BUNDLED_CAPABILITIES_MARKDOWN;
+      try {
+        const live = await client.get("/design/capabilities");
+        text = manifestToMarkdown(live.data || live);
+      } catch (_err) {
+        text += "\n\nLive capabilities could not be fetched; this bundled guidance may be stale.\n";
+      }
+
+      return {
+        contents: [
+          {
+            uri: "sutra://design/capabilities",
+            mimeType: "text/markdown",
+            text,
+          },
+        ],
+      };
+    }
+  );
+}
+
+function manifestToMarkdown(manifest) {
+  const lines = [
+    "# Sutra Design Capabilities",
+    "",
+    `Version: ${manifest.version || "unknown"}`,
+    "",
+    "## Rules",
+  ];
+
+  for (const rule of Object.values(manifest.rules || {})) lines.push(`- ${rule}`);
+  lines.push("", "## Node Types");
+  for (const [type, spec] of Object.entries(manifest.nodes || {})) {
+    lines.push(`- \`${type}\` attrs: ${(spec.attrs || []).map((attr) => `\`${attr}\``).join(", ")}`);
+  }
+  lines.push("", "## Marks");
+  for (const [type, spec] of Object.entries(manifest.marks || {})) {
+    lines.push(`- \`${type}\` attrs: ${(spec.attrs || []).map((attr) => `\`${attr}\``).join(", ")}`);
+  }
+  const fonts = manifest.fonts || {};
+  const availableFonts = fonts.available || [];
+  lines.push("", "## Fonts");
+  if (availableFonts.length > 0) {
+    for (const font of availableFonts) lines.push(`- ${font}`);
+  } else {
+    lines.push("- No font list returned by the live manifest.");
+  }
+  if (fonts.note) lines.push(`- ${fonts.note}`);
+  lines.push("", "## Anti-patterns");
+  for (const rule of manifest.anti_patterns || []) lines.push(`- ${rule}`);
+  return lines.join("\n");
+}

package/src/tools/blog.js

@@ -0,0 +1,204 @@
+import { z } from "zod";
+
+// MCP tools for the Sutra Blog (public surface at /resources). Mirrors
+// help-center.js, blog-shaped: category is optional, tags are supported, and
+// the support-only fields (product_area, intent_type, applies_to_plan, …) are
+// dropped. Calls the admin API under /api/v4/lotus/blog.
+const BLOG_BASE_URL = process.env.SUTRA_BLOG_BASE_URL || "https://api.sutra.co/api/v4/lotus/blog";
+
+export function registerBlogTools(server) {
+  const token = process.env.SUTRA_BLOG_TOKEN || process.env.SUTRA_HELP_CENTER_TOKEN;
+  if (!token) return;
+
+  async function request(method, path, { params, body } = {}) {
+    const url = new URL(`${BLOG_BASE_URL}${path}`);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json",
+      ...(body ? { "Content-Type": "application/json" } : {}),
+    };
+    const res = await fetch(url.toString(), {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    if (!res.ok) throw new Error(`${method} ${path} → ${res.status}: ${text}`);
+    return text ? JSON.parse(text) : {};
+  }
+
+  // Shared optional post fields (used by create / propose / update).
+  const postFields = {
+    title: z.string().optional().describe("Post title"),
+    slug: z.string().optional().describe("URL slug (auto-generated from title if omitted; cannot equal a category slug)"),
+    subtitle: z.string().optional().describe("Subtitle / deck"),
+    excerpt: z.string().optional().describe("Short summary shown on cards"),
+    blog_category_id: z.number().optional().describe("Category ID — OPTIONAL (posts can be uncategorized)"),
+    hero_image_url: z.string().optional().describe("Hero / cover image URL"),
+    og_image_url: z.string().optional().describe("Open Graph image URL"),
+    meta_title: z.string().optional().describe("SEO meta title"),
+    meta_description: z.string().optional().describe("SEO meta description"),
+    featured: z.boolean().optional().describe("Feature on the landing page"),
+    position: z.number().optional().describe("Sort position"),
+    search_keywords: z.array(z.string()).optional().describe("Extra search keywords for recall"),
+    tags: z.array(z.string()).optional().describe("Tag slugs (created if missing)"),
+  };
+
+  // --- Posts ---
+
+  server.tool(
+    "blog_list_posts",
+    "List blog posts (the public Resources surface, served at /resources) with optional filters. Returns post summaries and stats.",
+    {
+      status: z.enum(["draft", "published", "archived"]).optional().describe("Filter by status"),
+      review_status: z.string().optional().describe("Filter by review status"),
+      category_id: z.number().optional().describe("Filter by category ID"),
+      featured: z.boolean().optional().describe("Filter by featured flag"),
+      q: z.string().optional().describe("Search title and excerpt"),
+    },
+    async (params) => json(await request("GET", "/posts.json", { params }))
+  );
+
+  server.tool(
+    "blog_get_post",
+    "Get a blog post with full content, metadata, and version history.",
+    { id: z.number().describe("Post ID") },
+    async ({ id }) => json(await request("GET", `/posts/${id}.json`))
+  );
+
+  server.tool(
+    "blog_create_post",
+    "Create a new blog post. Returns the post and its first version.",
+    {
+      ...postFields,
+      title: z.string().describe("Post title"),
+      status: z.enum(["draft", "published", "archived"]).optional().describe("Initial status (default: draft)"),
+      content: z.any().optional().describe("Tiptap JSON content"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      publish: z.boolean().optional().describe("Publish immediately after creation"),
+    },
+    async ({ publish, ...post }) => json(await request("POST", "/posts.json", { body: { post, publish } }))
+  );
+
+  server.tool(
+    "blog_propose_post",
+    "Submit an AI-authored blog post draft for human review. Creates an ai_cobolt version and marks the post as AI changes pending (not published).",
+    {
+      ...postFields,
+      title: z.string().describe("Post title"),
+      content: z.any().describe("Tiptap JSON content"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      ai_agent_id: z.string().optional().describe("Identifier for the AI agent submitting the draft"),
+      source_signal: z.record(z.any()).optional().describe("Evidence or trigger that led to this draft"),
+    },
+    async ({ ai_agent_id, source_signal, ...post }) =>
+      json(await request("POST", "/posts/propose.json", { body: { post, ai_agent_id, source_signal } }))
+  );
+
+  server.tool(
+    "blog_update_post",
+    "Update an existing blog post and create a new version.",
+    {
+      id: z.number().describe("Post ID"),
+      ...postFields,
+      status: z.string().optional().describe("Status (draft/published/archived)"),
+      content: z.any().optional().describe("Tiptap JSON content"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      publish: z.boolean().optional().describe("Publish this version immediately"),
+    },
+    async ({ id, publish, ...post }) => json(await request("PUT", `/posts/${id}.json`, { body: { post, publish } }))
+  );
+
+  server.tool(
+    "blog_propose_post_update",
+    "Submit AI-authored changes to an existing blog post for human review. Creates an ai_cobolt pending version without publishing.",
+    {
+      id: z.number().describe("Post ID"),
+      ...postFields,
+      content: z.any().optional().describe("Proposed Tiptap content; omit for metadata-only proposals"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      ai_agent_id: z.string().optional().describe("Identifier for the AI agent submitting the proposal"),
+      source_signal: z.record(z.any()).optional().describe("Evidence or trigger that led to this update"),
+    },
+    async ({ id, ai_agent_id, source_signal, ...post }) =>
+      json(await request("POST", `/posts/${id}/propose_update.json`, { body: { post, ai_agent_id, source_signal } }))
+  );
+
+  server.tool(
+    "blog_publish_post",
+    "Publish a blog post version. Publishes the latest version if no version_id is given.",
+    {
+      id: z.number().describe("Post ID"),
+      version_id: z.number().optional().describe("Specific version ID to publish (defaults to latest)"),
+    },
+    async ({ id, version_id }) =>
+      json(await request("POST", `/posts/${id}/publish.json`, { body: version_id ? { version_id } : {} }))
+  );
+
+  server.tool(
+    "blog_review_post",
+    "Approve or reject a pending blog post version.",
+    {
+      id: z.number().describe("Post ID"),
+      version_id: z.number().describe("Version ID to review"),
+      decision: z.enum(["approve", "reject"]).describe("Review decision"),
+      comment: z.string().optional().describe("Review comment"),
+    },
+    async ({ id, ...body }) => json(await request("POST", `/posts/${id}/review.json`, { body }))
+  );
+
+  // --- Categories ---
+
+  server.tool("blog_list_categories", "List all blog categories.", {}, async () =>
+    json(await request("GET", "/categories.json")));
+
+  server.tool(
+    "blog_create_category",
+    "Create a new blog category.",
+    {
+      name: z.string().describe("Category name"),
+      slug: z.string().optional().describe("URL slug"),
+      description: z.string().optional().describe("Category description"),
+      icon_library: z.string().optional().describe("Icon library name"),
+      icon_name: z.string().optional().describe("Icon name"),
+      icon_color: z.string().optional().describe("Icon color hex"),
+      position: z.number().optional().describe("Sort position"),
+      published: z.boolean().optional().describe("Whether the category is published"),
+    },
+    async (category) => json(await request("POST", "/categories.json", { body: { category } }))
+  );
+
+  server.tool(
+    "blog_update_category",
+    "Update a blog category.",
+    {
+      id: z.number().describe("Category ID"),
+      name: z.string().optional(),
+      slug: z.string().optional(),
+      description: z.string().optional(),
+      icon_library: z.string().optional(),
+      icon_name: z.string().optional(),
+      icon_color: z.string().optional(),
+      position: z.number().optional(),
+      published: z.boolean().optional(),
+    },
+    async ({ id, ...category }) => json(await request("PUT", `/categories/${id}.json`, { body: { category } }))
+  );
+
+  server.tool("blog_delete_category", "Delete a blog category.", { id: z.number().describe("Category ID") },
+    async ({ id }) => json(await request("DELETE", `/categories/${id}.json`)));
+
+  // --- Tags ---
+
+  server.tool("blog_list_tags", "List all blog tags.", {}, async () =>
+    json(await request("GET", "/tags.json")));
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/design.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+
+const BUNDLED_DESIGN_CAPABILITIES = {
+  version: "1.0.0-bundled",
+  rules: {
+    grid_distribution: "Use 12-unit dist arrays such as [6,6], [8,4], or [4,4,4].",
+    buttons: "Use actionCallbackValue and actionCallbackTarget for URLs and navigation targets.",
+    images: "Use a real URL for image src, include alt text, and avoid data: URLs.",
+    conflicts: "When publish returns 409, re-read the design and rebase before retrying.",
+  },
+  warning: "Bundled fallback only. The live Sutra API capabilities endpoint was unreachable, so this manifest may be stale.",
+};
+
+export function registerDesignTools(server, client) {
+  server.tool(
+    "get_design_capabilities",
+    "Get the live Sutra design capability manifest. Read this before creating or editing page designs.",
+    {},
+    async () => {
+      try {
+        return json(await client.get("/design/capabilities"));
+      } catch (err) {
+        return json({
+          data: BUNDLED_DESIGN_CAPABILITIES,
+          warning: `Live capabilities unavailable: ${err.message}`,
+        });
+      }
+    }
+  );
+
+  server.tool(
+    "get_space_design",
+    "Fetch the current Sutra-rendered design for a space, including nodes, content_digest, circles, interactive blocks, and published URL.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+    },
+    async ({ space_id }) => json(await client.get(`/spaces/${space_id}/design`))
+  );
+
+  server.tool(
+    "validate_space_design",
+    "Validate proposed Sutra design nodes and return structured diagnostics. Validate before creating or publishing a draft.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      nodes: z.any().describe("Tiptap design nodes array or wrapped { default: { type: 'doc', content: [...] } } document"),
+      base_digest: z.string().optional().describe("Digest from get_space_design, if available"),
+    },
+    async ({ space_id, nodes, base_digest }) => {
+      const body = { nodes, base_digest };
+      return json(await client.post(`/spaces/${space_id}/design/validate`, body));
+    }
+  );
+
+  server.tool(
+    "create_or_update_design_draft",
+    "Create or update a design draft for a space. Use content_digest from get_space_design as base_digest. Mutating retries should pass idempotency_key.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      nodes: z.any().describe("Tiptap design nodes array or wrapped document"),
+      base_digest: z.string().describe("Digest from get_space_design"),
+      client_draft_key: z.string().describe("Stable key for this draft variant/session"),
+      title: z.string().optional().describe("Human-readable draft title"),
+      note: z.string().optional().describe("Short note about the draft"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post(`/spaces/${space_id}/design_drafts`, body, headers));
+    }
+  );
+
+  server.tool(
+    "publish_design_draft",
+    "Publish a design draft. If the API returns a conflict, re-read/rebase or provide the explicit destructive confirmation arrays from the conflict response.",
+    {
+      draft_id: z.string().describe("Design draft ID (dsdft_...)"),
+      confirm_destroy_circles: z.array(z.string()).optional().describe("Circle slugs or sp_ IDs explicitly confirmed for removal"),
+      confirm_destroy_interactive_with_responses: z.array(z.string()).optional().describe("Interactive confirm_token values explicitly confirmed for removal"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ draft_id, idempotency_key, confirm_destroy_circles, confirm_destroy_interactive_with_responses }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const body = {
+        confirm_destroy_circles: confirm_destroy_circles || [],
+        confirm_destroy_interactive_with_responses: confirm_destroy_interactive_with_responses || [],
+      };
+      return json(await client.post(`/design_drafts/${draft_id}/publish`, body, headers));
+    }
+  );
+
+  server.tool(
+    "restore_design_draft",
+    "Restore the pre-publish backup for a published design draft. If live content changed after publish, pass force_restore with current_digest from the conflict response.",
+    {
+      draft_id: z.string().describe("Design draft ID (dsdft_...)"),
+      force_restore: z.boolean().optional().describe("Confirm restore even when live content changed after publish"),
+      current_digest: z.string().optional().describe("Current digest required when force_restore is true"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ draft_id, idempotency_key, force_restore, current_digest }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const body = { force_restore: force_restore === true, current_digest };
+      return json(await client.post(`/design_drafts/${draft_id}/restore`, body, headers));
+    }
+  );
+
+  server.tool(
+    "import_design_asset",
+    "Import an external image URL into Sutra-controlled storage and return the canonical URL to use as image.attrs.src.",
+    {
+      space_id: z.string().describe("Space ID (sp_...) used for authorization and asset organization"),
+      source_url: z.string().url().describe("Public http(s) image URL to fetch and re-host"),
+      alt: z.string().optional().describe("Alt text for the image"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post("/design/assets/import", body, headers));
+    }
+  );
+
+  server.tool(
+    "get_design_preview_link",
+    "Get a short-lived, signed, read-only link that opens a design draft's rendered preview in a browser with no Sutra login required. Share it with the user (or open it yourself if you can view web pages) to review the design before publishing.",
+    {
+      draft_id: z.string().describe("Design draft ID (dsdft_...)"),
+    },
+    async ({ draft_id }) => {
+      return json(await client.post(`/design_drafts/${draft_id}/preview_link`, {}));
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/documents.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+
+const documentPlacementSchema = z.object({
+  insert: z.enum(["append", "before", "after", "inside"]).optional().describe("Where to insert or move nodes."),
+  anchor_node_uid: z.string().optional().describe("Tiptap node UID required for before/after/inside."),
+}).optional();
+
+export function registerDocumentTools(server, client) {
+  server.tool(
+    "get_document_capabilities",
+    "Get supported Tiptap document node capabilities and reserved-node policy. Read this before writing document nodes.",
+    {},
+    async () => json(await client.get("/document/capabilities"))
+  );
+
+  server.tool(
+    "get_document",
+    "Get the visible Tiptap document for a space by sp_ ID. Use the returned revision for replace_document.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+    },
+    async ({ space_id }) => json(await client.get(`/spaces/${space_id}/document`))
+  );
+
+  server.tool(
+    "replace_document",
+    "Replace a space document. Preserve managed space/media nodes; use structure/media tools for those. Requires base_revision or force.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+      document: z.any().describe("Tiptap doc: { type: 'doc', content: [...] }"),
+      base_revision: z.string().optional().describe("Revision from get_document"),
+      force: z.boolean().optional().describe("Explicitly replace without a base revision"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.put(`/spaces/${space_id}/document`, body, headers));
+    }
+  );
+
+  server.tool(
+    "insert_document_nodes",
+    "Insert visible Tiptap nodes into a space document. Use structure tools for space cards and media tools for uploads.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+      nodes: z.array(z.any()).describe("Array of Tiptap node objects"),
+      placement: documentPlacementSchema,
+      base_revision: z.string().optional(),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post(`/spaces/${space_id}/document/nodes`, body, headers));
+    }
+  );
+
+  server.tool(
+    "update_document_node",
+    "Replace one document node by its Tiptap attrs.uid.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+      node_uid: z.string().describe("Tiptap node attrs.uid"),
+      node: z.any().describe("Replacement Tiptap node object"),
+      base_revision: z.string().optional(),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, node_uid, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.patch(`/spaces/${space_id}/document/nodes/${node_uid}`, body, headers));
+    }
+  );
+
+  server.tool(
+    "delete_document_node",
+    "Delete one document node by its Tiptap attrs.uid. Managed space cards must be detached with detach_child_space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+      node_uid: z.string().describe("Tiptap node attrs.uid"),
+      base_revision: z.string().optional(),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, node_uid, base_revision, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const query = base_revision ? `?base_revision=${encodeURIComponent(base_revision)}` : "";
+      return json(await client.delete(`/spaces/${space_id}/document/nodes/${node_uid}${query}`, headers));
+    }
+  );
+
+  server.tool(
+    "move_document_node",
+    "Move one document node by its Tiptap attrs.uid.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+      node_uid: z.string().describe("Tiptap node attrs.uid"),
+      placement: documentPlacementSchema,
+      base_revision: z.string().optional(),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, node_uid, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.patch(`/spaces/${space_id}/document/nodes/${node_uid}/placement`, body, headers));
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/help-center.js

@@ -274,8 +274,10 @@ export function registerHelpCenterTools(server) {
       meta_title: z.string().optional().describe("SEO meta title"),
       meta_description: z.string().optional().describe("SEO meta description"),
       og_image_url: z.string().optional().describe("Open Graph image URL"),
+      heading_font: z.string().optional().describe("Heading font family"),
+      body_font: z.string().optional().describe("Body font family"),
       audience: z.array(z.string()).optional().describe("Target audience tags"),
-      applies_to_plan: z.array(z.string()).optional().describe("Applicable plan types"),
+      applies_to_plan: z.array(z.string()).optional().describe("Applicable plan tiers (basic, bronze, silver, gold)"),
       alternate_phrasings: z.array(z.string()).optional().describe("Alternate search phrasings"),
       publish: z.boolean().optional().describe("Publish immediately after creation"),
     },
@@ -289,6 +291,40 @@ export function registerHelpCenterTools(server) {
     }
   );
 
+  server.tool(
+    "help_propose_article",
+    "Submit an AI-authored Help Center article draft for human review. Creates an ai_cobolt version and marks the article as AI changes pending.",
+    {
+      title: z.string().describe("Article title"),
+      content: z.any().describe("Tiptap JSON content"),
+      slug: z.string().optional().describe("URL slug (auto-generated from title if omitted)"),
+      excerpt: z.string().optional().describe("Short description/excerpt"),
+      help_collection_id: z.number().optional().describe("Collection ID to place article in; omitted uses Untriaged AI Drafts"),
+      product_area: z.string().optional().describe("Product area tag"),
+      intent_type: z.string().optional().describe("Intent type tag"),
+      subsection: z.string().optional().describe("Subsection within collection"),
+      position: z.number().optional().describe("Sort position within collection"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      meta_title: z.string().optional().describe("SEO meta title"),
+      meta_description: z.string().optional().describe("SEO meta description"),
+      og_image_url: z.string().optional().describe("Open Graph image URL"),
+      heading_font: z.string().optional().describe("Heading font family"),
+      body_font: z.string().optional().describe("Body font family"),
+      audience: z.array(z.string()).optional().describe("Target audience tags"),
+      applies_to_plan: z.array(z.string()).optional().describe("Applicable plan tiers (basic, bronze, silver, gold)"),
+      alternate_phrasings: z.array(z.string()).optional().describe("Alternate search phrasings"),
+      ai_agent_id: z.string().optional().describe("Identifier for the AI agent submitting the draft"),
+      source_signal: z.record(z.any()).optional().describe("Evidence or trigger that led to this draft"),
+    },
+    async ({ ai_agent_id, source_signal, ...articleFields }) => {
+      if (articleFields.content) articleFields.content = await normalizeGleapContent(articleFields.content);
+      const data = await request("POST", "/articles/propose.json", {
+        body: { article: articleFields, ai_agent_id, source_signal },
+      });
+      return json(data);
+    }
+  );
+
   server.tool(
     "help_update_article",
     "Update an existing Help Center article and create a new version.",
@@ -308,8 +344,10 @@ export function registerHelpCenterTools(server) {
       meta_title: z.string().optional().describe("SEO meta title"),
       meta_description: z.string().optional().describe("SEO meta description"),
       og_image_url: z.string().optional().describe("Open Graph image URL"),
+      heading_font: z.string().optional().describe("Heading font family"),
+      body_font: z.string().optional().describe("Body font family"),
       audience: z.array(z.string()).optional().describe("Target audience tags"),
-      applies_to_plan: z.array(z.string()).optional().describe("Applicable plan types"),
+      applies_to_plan: z.array(z.string()).optional().describe("Applicable plan tiers (basic, bronze, silver, gold)"),
       alternate_phrasings: z.array(z.string()).optional().describe("Alternate search phrasings"),
       publish: z.boolean().optional().describe("Publish this version immediately"),
     },
@@ -322,6 +360,41 @@ export function registerHelpCenterTools(server) {
     }
   );
 
+  server.tool(
+    "help_propose_article_update",
+    "Submit AI-authored changes to an existing Help Center article for human review. Creates an ai_cobolt pending version without publishing it.",
+    {
+      id: z.number().describe("Article ID"),
+      title: z.string().optional().describe("Proposed article title"),
+      slug: z.string().optional().describe("Proposed URL slug"),
+      excerpt: z.string().optional().describe("Proposed short description/excerpt"),
+      help_collection_id: z.number().optional().describe("Proposed collection ID"),
+      product_area: z.string().optional().describe("Proposed product area tag"),
+      intent_type: z.string().optional().describe("Proposed intent type tag"),
+      subsection: z.string().optional().describe("Proposed subsection within collection"),
+      position: z.number().optional().describe("Proposed sort position"),
+      content: z.any().optional().describe("Proposed Tiptap JSON content; omit for metadata-only proposals"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      meta_title: z.string().optional().describe("Proposed SEO meta title"),
+      meta_description: z.string().optional().describe("Proposed SEO meta description"),
+      og_image_url: z.string().optional().describe("Proposed Open Graph image URL"),
+      heading_font: z.string().optional().describe("Proposed heading font family"),
+      body_font: z.string().optional().describe("Proposed body font family"),
+      audience: z.array(z.string()).optional().describe("Proposed target audience tags"),
+      applies_to_plan: z.array(z.string()).optional().describe("Proposed applicable plan tiers (basic, bronze, silver, gold)"),
+      alternate_phrasings: z.array(z.string()).optional().describe("Proposed alternate search phrasings"),
+      ai_agent_id: z.string().optional().describe("Identifier for the AI agent submitting the proposal"),
+      source_signal: z.record(z.any()).optional().describe("Evidence or trigger that led to this update"),
+    },
+    async ({ id, ai_agent_id, source_signal, ...articleFields }) => {
+      if (articleFields.content) articleFields.content = await normalizeGleapContent(articleFields.content);
+      const data = await request("POST", `/articles/${id}/propose_update.json`, {
+        body: { article: articleFields, ai_agent_id, source_signal },
+      });
+      return json(data);
+    }
+  );
+
   server.tool(
     "help_publish_article",
     "Publish a Help Center article version. Publishes the latest version if no version_id is given.",

package/src/tools/media.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+const mediaPlacementSchema = z.object({
+  insert_node: z.boolean().optional().describe("Insert a placeholder node in the document (default true)"),
+  insert: z.enum(["append", "before", "after", "inside"]).optional(),
+  anchor_node_uid: z.string().optional(),
+}).optional();
+
+export function registerMediaTools(server, client) {
+  server.tool(
+    "create_media_upload",
+    "Create a Sutra media upload session for a local file. Upload bytes to the returned PUT URL, then call complete_media_upload.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+      filename: z.string().describe("Original filename"),
+      content_type: z.string().describe("MIME type, e.g. video/mp4"),
+      size_bytes: z.number().int().nonnegative().describe("File size in bytes"),
+      kind: z.enum(["video", "file", "audio", "image"]).optional().describe("Media kind (default video)"),
+      placement: mediaPlacementSchema,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post(`/spaces/${space_id}/media_uploads`, body, headers));
+    }
+  );
+
+  server.tool(
+    "complete_media_upload",
+    "Complete an upload after bytes have been PUT to S3. Sutra verifies the object and queues processing for videos.",
+    {
+      media_id: z.string().describe("Media ID (media_...)"),
+      size_bytes: z.number().int().nonnegative().optional(),
+      etag: z.string().optional(),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ media_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post(`/media_uploads/${media_id}/complete`, body, headers));
+    }
+  );
+
+  server.tool(
+    "get_media_upload",
+    "Get upload and processing status for a media item.",
+    {
+      media_id: z.string().describe("Media ID (media_...)"),
+    },
+    async ({ media_id }) => json(await client.get(`/media_uploads/${media_id}`))
+  );
+
+  server.tool(
+    "cancel_media_upload",
+    "Cancel or abandon a pending media upload. This does not delete any uploaded S3 object.",
+    {
+      media_id: z.string().describe("Media ID (media_...)"),
+      remove_document_node: z.boolean().optional().describe("Remove the placeholder node when possible"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ media_id, remove_document_node, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const query = remove_document_node ? "?remove_document_node=true" : "";
+      return json(await client.delete(`/media_uploads/${media_id}${query}`, headers));
+    }
+  );
+
+  server.tool(
+    "create_media_reference",
+    "Insert an external media embed such as Loom, YouTube, or Vimeo into a Sutra document without creating an upload session.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+      url: z.string().min(1).describe("External media URL or iframe embed code from Loom, YouTube, or Vimeo"),
+      placement: mediaPlacementSchema,
+      base_revision: z.string().optional().describe("Optional document revision guard"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post(`/spaces/${space_id}/media_references`, body, headers));
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/spaces.js

@@ -1,5 +1,14 @@
 import { z } from "zod";
 
+const placementSchema = z.object({
+  surface: z.enum(["auto", "collection", "document"]).optional().describe("Where the child appears. Use auto for normal course/section placement."),
+  position: z.number().int().nonnegative().optional().describe("Zero-based order in the resolved surface."),
+  view_as: z.enum(["list", "hcard", "vcard", "button", "link"]).optional().describe("Document card render mode. Ignored for collection placement."),
+  insert: z.enum(["append", "before", "after", "inside"]).optional().describe("Document insertion mode."),
+  anchor_node_uid: z.string().optional().describe("Tiptap node UID used with before/after/inside."),
+  set_parent_ordering: z.enum(["custom_order"]).optional().describe("Set parent list ordering so collection position is visually effective."),
+}).optional();
+
 export function registerSpaceTools(server, client) {
   server.tool(
     "list_spaces",
@@ -59,7 +68,7 @@ export function registerSpaceTools(server, client) {
 
   server.tool(
     "create_space",
-    "Create a new space. Omit parent_id for a top-level space, or include it to create a child space.",
+    "Create a new space. Omit parent_id for a top-level space, or include a parent sp_ ID to create a child. Use sp_ IDs, not slugs.",
     {
       name: z.string().describe("Space name"),
       description: z.string().optional().describe("Space description"),
@@ -67,14 +76,84 @@ export function registerSpaceTools(server, client) {
       privacy: z.string().optional().describe("Privacy level (default: open)"),
       pod_type: z.enum(["standard", "readonly"]).optional().describe("Pod type (default: standard)"),
       parent_id: z.string().optional().describe("Parent space ID (sp_...) to create as a child"),
+      content_scaffold: z.enum(["none", "ui_default"]).optional().describe("Use none when document content will be written through document tools."),
+      placement: placementSchema,
     },
-    async ({ name, description, type, privacy, pod_type, parent_id }) => {
-      const body = { name, description, type, privacy, pod_type, parent_id };
+    async ({ name, description, type, privacy, pod_type, parent_id, content_scaffold, placement }) => {
+      const body = { name, description, type, privacy, pod_type, parent_id, content_scaffold, placement };
       const data = await client.post("/spaces", body);
       return json(data);
     }
   );
 
+  server.tool(
+    "create_child_space",
+    "Create a child space under a parent sp_ ID and make it visible through placement. For courses and sections use placement.surface = auto.",
+    {
+      parent_id: z.string().describe("Parent space ID (sp_...). Do not use a slug."),
+      name: z.string().describe("Child space name"),
+      description: z.string().optional(),
+      type: z.string().optional().describe("Space type (default: content)"),
+      privacy: z.string().optional(),
+      pod_type: z.enum(["standard", "readonly"]).optional(),
+      content_scaffold: z.enum(["none", "ui_default"]).optional().describe("Use none when document content will be written through document tools."),
+      placement: placementSchema,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ parent_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.post(`/spaces/${parent_id}/children`, body, headers);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "attach_child_space",
+    "Attach an existing child sp_ ID to a parent sp_ ID and make it visible. Use this when a space already exists but is not showing in the course/section/page.",
+    {
+      parent_id: z.string().describe("Parent space ID (sp_...). Do not use a slug."),
+      child_id: z.string().describe("Existing child space ID (sp_...). Do not use a slug."),
+      placement: placementSchema,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ parent_id, child_id, placement, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.put(`/spaces/${parent_id}/children/${child_id}`, { placement }, headers);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_child_space_placement",
+    "Move or repair a child space display under a parent. Use auto for normal course/section placement; use document for a card in a content page.",
+    {
+      parent_id: z.string().describe("Parent space ID (sp_...). Do not use a slug."),
+      child_id: z.string().describe("Child space ID (sp_...). Do not use a slug."),
+      placement: placementSchema,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ parent_id, child_id, placement, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.patch(`/spaces/${parent_id}/children/${child_id}/placement`, { placement }, headers);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "detach_child_space",
+    "Detach a child space from one parent without deleting the child space.",
+    {
+      parent_id: z.string().describe("Parent space ID (sp_...). Do not use a slug."),
+      child_id: z.string().describe("Child space ID (sp_...). Do not use a slug."),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ parent_id, child_id, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.delete(`/spaces/${parent_id}/children/${child_id}`, headers);
+      return json(data);
+    }
+  );
+
   server.tool(
     "update_space",
     "Update an existing space's name, description, type, privacy, or state.",