@sutraspaces/mcp-server 1.1.1 → 1.2.0

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.",