@sutraspaces/mcp-server 1.2.1 → 1.4.0

package/README.md

@@ -90,8 +90,11 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server`. The server communicat
 | `SUTRA_SCOPES` | No | Space-separated scopes to request during OAuth login (default: all scopes your account can authorize) |
 | `SUTRA_CONFIG_DIR` | No | Directory for cached OAuth credentials (default: `~/.sutra`) |
 | `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_LOTUS_TOKEN` | No | Internal scoped admin key (`sutra_admin_...`) for Lotus tools. Add `help_center:read`, `help_center:write`, `blog:read`, and/or `blog:write` to the same key as needed. |
 | `SUTRA_HELP_CENTER_BASE_URL` | No | Override the Help Center API URL (default: `https://api.sutra.co/api/v4/lotus/help`) |
+| `SUTRA_BLOG_BASE_URL` | No | Override the Blog API URL (default: `https://api.sutra.co/api/v4/lotus/blog`) |
+
+`SUTRA_HELP_CENTER_TOKEN` and `SUTRA_BLOG_TOKEN` are still accepted as backwards-compatible aliases, but new setups should use one `SUTRA_LOTUS_TOKEN`.
 
 ## Available Tools
 
@@ -108,12 +111,18 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server`. The server communicat
 - **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
+- **update_space** — Update General settings: name, description, format, privacy, visibility, member limit, registration gates, behavior flags, shareable link, and state (archive/unarchive)
 - **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"`.
 
+### Space Settings, Appearance, Images & Payment
+- **update_space_settings** — Behavioral settings: scheduling (launch/archive/readonly), membership & notifications, content behavior, sidebar/page display, registration display, SEO, members map, Cobolt AI indexing, and list/post display
+- **update_space_appearance** — Theme colors, fonts, accent palette, gradients, corner style, density, and hidden layout elements (a base-color write cascades the full theme to descendants)
+- **set_space_image** — Set or remove the cover, logo, thumbnail, or social-share (meta) image from a URL
+- **update_space_payment** — Enable/disable paid access (plans system) with guarded preconditions and teardown, plus checkout toggles (multi-plan selection, guest checkout, terms)
+
 ### Members
 - **list_members** — List space members with optional email, user_id, search, role, state, and custom property filtering
 - **get_member** — Get member details
@@ -153,6 +162,15 @@ Use `sp_...` IDs, not slugs. For normal course and section pages, use `placement
 - **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
+
+### Website Tools
+
+Website mode is root-scoped (any managed space resolves to its website root) and tier-gated (enabling requires the Silver plan or above). Enabling auto-creates a default header (a navbar) and footer; you then author those configs. A header's nav lives in a NavbarConfig referenced by the site_header share block's navbar node.
+
+- **get_space_website** / **update_space_website** — Read and set website-mode state: enable/disable, `show_spaces_in_page`, and the header/footer share-block pointers
+- **list_share_block_configs** / **get_share_block_config** / **create_share_block_config** / **update_share_block_config** / **delete_share_block_config** — Manage site_header / site_footer / generic share blocks (deleting an in-use header or footer returns 409)
+- **list_navbar_configs** / **get_navbar_config** / **create_navbar_config** / **update_navbar_config** / **delete_navbar_config** / **duplicate_navbar_config** — Manage the website header's navbar (links, logo, title, alignment)
+
 - **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
 
@@ -173,7 +191,7 @@ Use `sp_...` IDs, not slugs. For normal course and section pages, use `placement
 - **get_survey_submissions** — Read survey responses
 
 ### Plans & Enrollments
-- **list_plans** / **get_plan** / **create_plan** / **update_plan** / **delete_plan** — Manage plans
+- **list_plans** / **get_plan** / **create_plan** / **update_plan** / **delete_plan** — Manage payment plans (full pricing surface; `amount` is in integer cents). Creating plans does not enable paid access — use **update_space_payment** for the gate.
 - **list_enrollments** / **get_enrollment** — Read enrollments
 - **list_payments** / **get_payment** — Read payment history
 
@@ -186,7 +204,7 @@ Use `sp_...` IDs, not slugs. For normal course and section pages, use `placement
 - **get_broadcast_delivery_status** — Check delivery progress
 
 ### Help Center
-These tools are available only when `SUTRA_HELP_CENTER_TOKEN` is set.
+These tools are available when `SUTRA_LOTUS_TOKEN` is set with `help_center:read` / `help_center:write` scopes.
 
 - **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
@@ -196,6 +214,18 @@ These tools are available only when `SUTRA_HELP_CENTER_TOKEN` is set.
 - **help_publish_article** — Explicitly publish an article version
 - **help_list_collections** / **help_create_collection** / **help_update_collection** / **help_delete_collection** — Manage Help Center collections
 
+### Blog
+These tools are available when `SUTRA_LOTUS_TOKEN` is set. The token needs `blog:read` for list/get tools and `blog:write` for create, update, proposal, publish, review, and category tools.
+
+- **blog_list_posts** / **blog_get_post** — Read Lotus Blog posts, metadata, and version history
+- **blog_create_post** / **blog_update_post** — Human/admin-style create and update through Lotus
+- **blog_propose_post** — Submit an AI-authored draft as `ai_cobolt` and mark it pending human review
+- **blog_propose_post_update** — Submit AI-authored changes to an existing post without publishing them
+- **blog_review_post** — Approve or reject a pending post version
+- **blog_publish_post** — Explicitly publish a post version
+- **blog_list_categories** / **blog_create_category** / **blog_update_category** / **blog_delete_category** — Manage Blog categories
+- **blog_list_tags** — List Blog tags
+
 ## Available Resources
 
 - **sutra://admin-api/overview** — Core Admin API concepts, public ID prefixes, scopes, pagination, and filtering

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sutraspaces/mcp-server",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "MCP server for the Sutra Admin API — manage spaces, members, contacts, content, and more via AI agents",
   "type": "module",
   "main": "src/index.js",
@@ -37,7 +37,7 @@
   "homepage": "https://github.com/lorenzsell/sutra-mcp",
   "repository": {
     "type": "git",
-    "url": "https://github.com/lorenzsell/sutra-mcp.git"
+    "url": "git+https://github.com/lorenzsell/sutra-mcp.git"
   },
   "bugs": {
     "url": "https://github.com/lorenzsell/sutra-mcp/issues"

package/src/index.js

@@ -5,6 +5,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 import { SutraAdminClient } from "./client.js";
 import { registerSpaceTools } from "./tools/spaces.js";
+import { registerSpaceSettingsTools } from "./tools/space-settings.js";
 import { registerMemberTools } from "./tools/members.js";
 import { registerContentTools } from "./tools/content.js";
 import { registerDocumentTools } from "./tools/documents.js";
@@ -20,6 +21,7 @@ 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 { registerWebsiteTools } from "./tools/website.js";
 import { registerAdminApiResources } from "./resources/admin-api.js";
 import { registerDesignResources } from "./resources/design.js";
 import { getValidAccessToken, login, refresh } from "./auth/oauth.js";
@@ -119,12 +121,14 @@ if (SUTRA_API_TOKEN) {
 
 const server = new McpServer({
   name: "sutra",
-  version: "1.2.0",
+  // Keep in lockstep with package.json.
+  version: "1.4.0",
   description:
     "Sutra Admin API — manage spaces, members, contacts, content, discussions, surveys, plans, broadcasts, and more.",
 });
 
 registerSpaceTools(server, client);
+registerSpaceSettingsTools(server, client);
 registerMemberTools(server, client);
 registerContentTools(server, client);
 registerDocumentTools(server, client);
@@ -138,6 +142,7 @@ registerBroadcastTools(server, client);
 registerDeepTool(server, client);
 registerAutomationTools(server, client);
 registerDesignTools(server, client);
+registerWebsiteTools(server, client);
 registerHelpCenterTools(server);
 registerBlogTools(server);
 registerAdminApiResources(server);

package/src/resources/admin-api.js

@@ -8,6 +8,15 @@ const RESOURCES = [
 
 The Sutra Admin API lets authorized tokens manage spaces, members, contacts, content, invitations, properties, surveys, plans, coupons, and broadcasts.
 
+Space configuration tools:
+- update_space covers the General settings core: name, description, format (type), privacy, visibility, member limit, registration gates, behavior flags, shareable link, and archive/unarchive.
+- update_space_settings covers behavioral settings: scheduling, notifications, content behavior, display, registration, SEO, members map, Cobolt indexing, and list/post display.
+- update_space_appearance covers theme colors, fonts, accents, gradients, corner style, density, and hidden layout elements.
+- set_space_image sets or removes the cover, logo, thumbnail, or meta image from a URL.
+- update_space_payment enables/disables paid access (plans system) and configures checkout toggles. Plans themselves are managed with create_plan/update_plan/delete_plan (amounts in integer cents).
+- update_space_website enables/disables website mode (root-scoped; Silver+ to enable) and points the site at header/footer share blocks. Enabling auto-creates a default header + footer. Author the header with create/update_navbar_config (links, logo, title) referenced by a site_header share block, and the footer with update_share_block_config. get_space_website reads the current state.
+- get_space returns the detail read with nested settings, appearance, payment, and website objects.
+
 Important IDs:
 - Spaces use sp_ IDs.
 - Members use mem_ IDs.
@@ -15,6 +24,8 @@ Important IDs:
 - Users use usr_ IDs.
 - Member property definitions use mprop_ IDs.
 - Space property definitions use sprop_ IDs.
+- Share-block configs (website header/footer) use shbk_ IDs.
+- Navbar configs use nvbr_ IDs.
 
 Pagination:
 - List tools return data and pagination.
@@ -25,6 +36,8 @@ Scopes:
 - members:read reads members and contacts.
 - members:write writes member/contact-related values where supported.
 - spaces:read lists spaces where the token owner has admin access.
+- spaces:write creates, updates, configures, and archives spaces — including settings, appearance, images, and the payment gate (update_space_payment).
+- plans:read / plans:write manage payment plans; the payment gate itself needs spaces:write.
 - membership_spaces:read lists basic read-only inventory for spaces where the token owner is a member.
 - members.email:read is required to see or filter by email.
 - member_properties:read is required to list definitions, read values, and filter people by properties.

package/src/tools/blog.js

@@ -7,7 +7,7 @@ import { z } from "zod";
 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;
+  const token = process.env.SUTRA_LOTUS_TOKEN || process.env.SUTRA_BLOG_TOKEN || process.env.SUTRA_HELP_CENTER_TOKEN;
   if (!token) return;
 
   async function request(method, path, { params, body } = {}) {
@@ -47,6 +47,7 @@ export function registerBlogTools(server) {
     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)"),
+    published_at: z.string().optional().describe("ISO8601 publish date-time to preserve (e.g. '2025-06-30T00:00:00Z'). If omitted, publishing stamps the current time. Useful for content migrations that need to keep original dates."),
   };
 
   // --- Posts ---

package/src/tools/design.js

@@ -42,7 +42,11 @@ export function registerDesignTools(server, client) {
     "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"),
+      // Typed as an array (not z.any()) so MCP clients serialize it as
+      // structured JSON. With an untyped schema the harness can stringify the
+      // value, and the API's Document.wrap rejects a JSON string. Pass the bare
+      // node array; the API still also accepts a wrapped doc when not stringified.
+      nodes: z.array(z.any()).describe("Array of Tiptap design node objects (bare array — a stringified JSON doc is rejected by the API)."),
       base_digest: z.string().optional().describe("Digest from get_space_design, if available"),
     },
     async ({ space_id, nodes, base_digest }) => {
@@ -56,7 +60,9 @@ export function registerDesignTools(server, client) {
     "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"),
+      // Typed as an array (see validate_space_design) so the value is sent as
+      // structured JSON rather than being stringified by the MCP client.
+      nodes: z.array(z.any()).describe("Array of Tiptap design node objects (bare array — a stringified JSON doc is rejected by the API)."),
       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"),

package/src/tools/help-center.js

@@ -200,7 +200,7 @@ function normalizeNode(node) {
 }
 
 export function registerHelpCenterTools(server) {
-  const token = process.env.SUTRA_HELP_CENTER_TOKEN;
+  const token = process.env.SUTRA_LOTUS_TOKEN || process.env.SUTRA_HELP_CENTER_TOKEN;
   if (!token) return;
 
   async function request(method, path, { params, body } = {}) {

package/src/tools/plans.js

@@ -32,42 +32,74 @@ export function registerPlanTools(server, client) {
     }
   );
 
+  // Shared write surface for create_plan / update_plan. The API takes
+  // `amount` in integer CENTS (5000 = $50.00) — there is no `price` param.
+  const planWriteShape = {
+    name: z.string().optional().describe("Plan name"),
+    short_description: z.string().nullable().optional().describe("One-line description shown on the plan card"),
+    long_description: z.string().nullable().optional().describe("Full description (HTML)"),
+    amount: z.number().int().optional().describe("Price in integer CENTS (e.g. 5000 = $50.00). Must be > 0 unless pwyc_enabled."),
+    amount_cents: z.number().int().optional().describe("Alias for amount (matches the read shape); amount wins when both are sent"),
+    currency: z.string().optional().describe('ISO currency code, e.g. "usd"'),
+    frequency: z.enum(["once", "monthly", "quarterly", "yearly"]).optional().describe("Billing frequency"),
+    billing_limit_type: z.enum(["ongoing", "fixed_count", "until_date"]).optional().describe("How long recurring billing runs"),
+    billing_count: z.number().int().min(1).nullable().optional().describe("Number of charges when billing_limit_type is fixed_count"),
+    billing_until_date: z.string().nullable().optional().describe("ISO date for billing_limit_type until_date. Null clears."),
+    trial_period_days: z.number().int().min(0).max(730).optional().describe("Free trial length in days"),
+    pwyc_enabled: z.boolean().optional().describe("Pay-what-you-can pricing (tier-gated in the web UI)"),
+    pwyc_min: z.number().int().min(0).optional().describe("PWYC minimum in cents"),
+    pwyc_max: z.number().int().nullable().optional().describe("PWYC maximum in cents"),
+    pwyc_default: z.number().int().nullable().optional().describe("PWYC suggested amount in cents"),
+    sort_order: z.number().int().optional().describe("Display order on the checkout page"),
+    status: z.enum(["active", "inactive"]).optional(),
+    visibility: z.enum(["visible", "hidden"]).optional().describe("hidden plans are purchasable only by direct link"),
+    recommended: z.boolean().optional().describe("Highlight as the recommended plan"),
+    features: z.record(z.any()).optional().describe("Feature list metadata shown on the plan card"),
+    max_purchasers: z.number().int().min(1).nullable().optional().describe("Cap on total purchasers. Null = unlimited."),
+    redirect_after_purchase: z.string().nullable().optional().describe("URL to send buyers to after checkout. Null clears."),
+    show_on_registration: z.boolean().optional().describe("Offer this plan on the registration page"),
+  };
+
   server.tool(
     "create_plan",
-    "Create a plan for a space.",
+    "Create a payment plan for a space. amount is in integer CENTS (5000 = $50.00). Creating a plan does NOT enable paid access by itself — when the response carries a warning that the payment gate is off, call update_space_payment(enabled: true) to make plans purchasable. While multiple plan selection is enabled on the space, all active plans must share one currency and one billing family (all one-time or all recurring).",
     {
       space_id: z.string().describe("Space ID (sp_...)"),
-      name: z.string().optional().describe("Plan name"),
-      price: z.number().optional().describe("Price amount"),
+      ...planWriteShape,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
     },
-    async ({ space_id, ...body }) => {
-      const data = await client.post(`/spaces/${space_id}/plans`, body);
+    async ({ space_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.post(`/spaces/${space_id}/plans`, body, headers);
       return json(data);
     }
   );
 
   server.tool(
     "update_plan",
-    "Update a plan.",
+    "Update a payment plan. Only the keys you send are written; nullable fields are cleared with null. amount is in integer CENTS. Deactivating the last active plan behind an enabled paywall returns a warning (visitors would reach an empty paywall).",
     {
       plan_id: z.string().describe("Plan ID (plan_...)"),
-      name: z.string().optional(),
-      price: z.number().optional(),
+      ...planWriteShape,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
     },
-    async ({ plan_id, ...body }) => {
-      const data = await client.patch(`/plans/${plan_id}`, body);
+    async ({ plan_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.patch(`/plans/${plan_id}`, body, headers);
       return json(data);
     }
   );
 
   server.tool(
     "delete_plan",
-    "Delete a plan.",
+    "Deactivate a plan (soft delete — enrollments are preserved and the plan can be reactivated with update_plan). Deactivating the last active plan behind an enabled paywall returns a warning.",
     {
       plan_id: z.string().describe("Plan ID (plan_...)"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
     },
-    async ({ plan_id }) => {
-      const data = await client.delete(`/plans/${plan_id}`);
+    async ({ plan_id, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.delete(`/plans/${plan_id}`, headers);
       return json(data);
     }
   );

package/src/tools/space-settings.js

@@ -0,0 +1,213 @@
+import { z } from "zod";
+
+// Space → Settings → General tools beyond the core update_space surface:
+// behavioral settings (update_space_settings), appearance, images, and
+// payment. Split from spaces.js because these schemas are large.
+export function registerSpaceSettingsTools(server, client) {
+  server.tool(
+    "update_space_settings",
+    "Update a space's behavioral settings: scheduling (launch/archive/readonly), membership and notifications, content behavior, sidebar and page display, registration display, SEO, members map, Cobolt AI indexing, and list/post display. Partial update — only the keys you send are written; nullable fields are cleared with null. Scheduling gates need their time in the same call (launch_on_date + launch_time); while a future launch is scheduled the space state reads as pending, and any settings write re-pends it. Changing display fields (space_width, show_page_icon, apply_to_sub_spaces) propagates the parent's display settings to children when apply_to_sub_spaces is on.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+
+      // Scheduling (tier-gated professional/organization)
+      show_start_date: z.boolean().optional().describe("Show the space's start date publicly"),
+      start_date: z.string().nullable().optional().describe("ISO-8601 start date(time). Null clears."),
+      end_date: z.string().nullable().optional().describe("ISO-8601 end date(time). Null clears."),
+      launch_on_date: z.boolean().optional().describe("Schedule the space to launch at launch_time (send both together). Turning this off clears launch_time and un-pends the space."),
+      launch_time: z.string().nullable().optional().describe("ISO-8601 launch datetime"),
+      archive_on_date: z.boolean().optional().describe("Schedule automatic archiving at archive_time"),
+      archive_time: z.string().nullable().optional().describe("ISO-8601 archive datetime"),
+      readonly_on_date: z.boolean().optional().describe("Schedule the space to become read-only at readonly_time"),
+      readonly_time: z.string().nullable().optional().describe("ISO-8601 read-only datetime"),
+
+      // Membership & notifications
+      new_member_notifications: z.enum(["manager", "none"]).optional().describe("Who is notified when someone joins"),
+      hide_member_emails: z.boolean().optional(),
+      allow_member_copy: z.boolean().optional().describe("Allow members to copy/duplicate the space"),
+      max_sub_space_membership: z.number().int().min(0).nullable().optional().describe("Max sub-spaces a member can join. Null = unlimited."),
+
+      // Content behavior
+      is_focus_mode: z.boolean().optional(),
+      allow_comments: z.boolean().optional(),
+      allow_completions: z.boolean().optional().describe("Enable mark-as-complete (tier-gated when enabling). Must agree with show_mark_complete_button_in_header when both are sent."),
+      show_mark_complete_button_in_header: z.boolean().optional().describe("Show the complete button in the header. Sent alone, allow_completions is set to match."),
+      allow_members_to_create_tags: z.boolean().optional(),
+      list_auto_tag: z.boolean().optional().describe("Auto-tag posts with AI (tier-gated when enabling)"),
+      redirect_to_space: z.string().nullable().optional().describe("Slug of an existing active space to redirect visitors to. Null clears."),
+
+      // Sidebar / page display
+      sidebar_default_opened: z.boolean().optional(),
+      sidebar_hide_children: z.boolean().optional(),
+      show_page_icon: z.boolean().optional(),
+      apply_to_sub_spaces: z.boolean().optional().describe("Apply display settings (width, page icon, hidden layout elements) to sub-spaces"),
+      is_cover_full_width: z.boolean().optional(),
+      space_width: z.enum(["wide", "narrow"]).optional(),
+
+      // Registration display
+      show_join_button: z.boolean().optional(),
+      show_registration_sidebar: z.boolean().optional(),
+      registration_button_text: z.string().nullable().optional().describe("Custom join-button label. Null restores the default."),
+      registration_width: z.enum(["wide", "narrow"]).optional(),
+      allow_interested_on_join: z.boolean().optional(),
+
+      // SEO
+      meta_title: z.string().nullable().optional(),
+      meta_description: z.string().nullable().optional(),
+      seo_indexable: z.boolean().optional(),
+
+      // Members map
+      members_map_interests_enabled: z.boolean().optional(),
+      members_map_show_ai_interests: z.boolean().optional(),
+
+      // Cobolt AI indexing
+      cobolt_indexing_excluded: z.boolean().optional().describe("Exclude this space (and subtree) from Cobolt AI indexing. Turning on purges the subtree's index and denormalizes the flag to descendants; turning off restores indexing for this space only."),
+
+      // List / posts display
+      list_action_text: z.string().nullable().optional(),
+      list_template_id: z.string().nullable().optional().describe("Template space slug for template-backed creation. Requires list_child_version: template; auto-cleared when switching away."),
+      list_child_version: z.enum(["posts", "content", "discussions", "link", "template"]).optional(),
+      list_link_action: z.enum(["subspace", "linked"]).optional(),
+      list_show_author: z.boolean().optional(),
+      list_show_preview_text: z.boolean().optional(),
+      list_show_thumbnail: z.boolean().optional(),
+      list_show_comments_count: z.boolean().optional(),
+      list_show_members: z.boolean().optional(),
+      list_show_timestamp: z.boolean().optional(),
+      list_auto_thumbnail: z.boolean().optional(),
+      list_flat_view: z.boolean().optional(),
+      list_open_in_modal: z.boolean().optional(),
+      list_allow_likes: z.boolean().optional(),
+      list_filter_by: z.enum([
+        "custom_order",
+        "pods.created_at DESC",
+        "pods.created_at ASC",
+        "pods.last_active DESC",
+        "pods.updated_at ASC",
+        "LOWER(pods.intention) ASC",
+        "LOWER(pods.intention) DESC",
+      ]).optional().describe("Child ordering"),
+      list_privacy_control: z.enum(["open", "private", "any"]).optional(),
+      list_title_line_clamp: z.number().int().min(1).nullable().optional().describe("The web UI writes only 2 or 20 and round-trips its own values"),
+      list_abstract_line_clamp: z.number().int().min(1).nullable().optional(),
+      list_add_creator_as_role: z.enum(["moderator", "editor", "manager"]).optional().describe("member is rejected: posts force editor, courses/sections force manager"),
+      list_children_capabilities: z.array(z.enum(["full", "limited"])).optional().describe('The web UI writes exactly ["full"] or ["limited"]'),
+
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...updates }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.patch(`/spaces/${space_id}/settings`, updates, headers);
+      return json(data);
+    }
+  );
+
+  const hexColor = (desc) =>
+    z.string().regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "must be a hex color like #1a2b3c")
+      .nullable().optional().describe(desc);
+
+  server.tool(
+    "update_space_appearance",
+    "Update a space's theme: colors, fonts, accent palette, gradients, corner style, density, and hidden layout elements. Tier-gated to professional/organization accounts (hidden_layout_elements: personal and up). Null clears a theme override. WARNING: writing any base color cascades the parent's FULL current theme — fonts, font weights, corner style, density, accents, gradients, sidebar style, and the logo file — to every descendant space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+
+      // Base colors (writing any of these triggers the descendant cascade)
+      header_color: hexColor("Header background color"),
+      header_link_color: hexColor("Header link color"),
+      primary_button_background_color: hexColor("Primary button background"),
+      primary_button_text_color: hexColor("Primary button text"),
+      secondary_button_background_color: hexColor("Secondary button background"),
+      secondary_button_text_color: hexColor("Secondary button text"),
+      background_color: hexColor("Page background"),
+      secondary_background_color: hexColor("Secondary background"),
+      default_text_color: hexColor("Default text color"),
+      sub_header_text_color: hexColor("Sub-header text color"),
+      sidebar_background_color: hexColor("Sidebar background"),
+      sidebar_text_color: hexColor("Sidebar text"),
+      default_link_color: hexColor("Link color"),
+      default_badge_color: hexColor("Badge background"),
+      default_badge_text_color: hexColor("Badge text"),
+
+      // Registration page (no cascade)
+      registration_page_background_color: hexColor("Registration page background"),
+      registration_page_default_text_color: hexColor("Registration page text"),
+      registration_page_sidebar_background_color: hexColor("Registration sidebar background"),
+      registration_page_sidebar_text_color: hexColor("Registration sidebar text"),
+      registration_page_button_background_color: hexColor("Registration button background"),
+      registration_page_button_text_color: hexColor("Registration button text"),
+      registration_page_link_color: hexColor("Registration link color"),
+      registration_page_heading_font: z.string().nullable().optional(),
+      registration_page_body_font: z.string().nullable().optional(),
+
+      // Fonts & expansion theme
+      heading_font: z.string().nullable().optional().describe("Heading font family name"),
+      body_font: z.string().nullable().optional().describe("Body font family name"),
+      accent_font: z.string().nullable().optional().describe("Accent font family name"),
+      accent_color: hexColor("Accent color"),
+      accents: z.array(z.string()).min(3).max(5).nullable().optional().describe("3-5 hex colors used by templates for accent elements. Null clears."),
+      gradients: z.object({
+        hero: z.string().optional(),
+        cta: z.string().optional(),
+        ambient: z.string().optional(),
+      }).nullable().optional().describe("Slot → gradient ID from the frontend gradient library. Null clears."),
+      corner_style: z.enum(["sharp", "subtle", "soft", "rounded"]).nullable().optional(),
+      density: z.enum(["compact", "standard", "comfortable", "spacious"]).nullable().optional(),
+      heading_font_weight: z.string().nullable().optional().describe('CSS font weight, e.g. "600"'),
+      body_font_weight: z.string().nullable().optional(),
+
+      // Layout
+      hidden_layout_elements: z.array(z.enum(["sidebar", "header", "cover", "title", "breadcrumbs"])).optional().describe("Layout chrome to hide. Empty array shows everything."),
+
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...updates }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.patch(`/spaces/${space_id}/appearance`, updates, headers);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "set_space_image",
+    "Set or remove a space image by URL. Kinds: cover = page banner (center-cropped toward 2400×600, never upscaled; jpg/jpeg/gif/png/webp), logo = 250×80 crop (jpg/jpeg/gif/png; professional/organization only; propagates to all descendant spaces), thumbnail = list-card image (600×300 crop; setting one protects it from post-driven auto-generation, removing re-arms it), meta = social-share image (1200×630 crop). Processing is synchronous (ImageMagick + storage) — use reasonably sized source files (hard cap 25 MB) and expect the call to take a few seconds. Unlike the web app, cover writes only the banner, never the thumbnail.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      kind: z.enum(["cover", "logo", "thumbnail", "meta"]).describe("Which space image to set"),
+      source_url: z.string().nullable().describe("Public http(s) URL of the image, or null to remove the current image"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries (a retry re-downloads the image)"),
+    },
+    async ({ space_id, kind, source_url, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.post(`/spaces/${space_id}/images`, { kind, source_url }, headers);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_space_payment",
+    "Enable, disable, or configure paid access for a space (plans system; legacy single-price config is not accessible through the API). Enabling requires at least one active plan (create_plan first) AND a connected Stripe account — each missing precondition returns a specific 422 (no_active_plans / stripe_not_connected). Disabling is a guarded teardown: it returns 409 (live_enrollments) while live enrollments exist unless force: true, which cancels their Stripe subscriptions; active plans are soft-deactivated and the space's privacy moves to target_privacy (default private). Disabling a space that was never paid is a harmless no-op. The space's payment state reads back under payment in get_space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      enabled: z.boolean().optional().describe("true = turn paid access on (after preconditions); false = guarded teardown"),
+      force: z.boolean().optional().describe("With enabled: false — cancel live Stripe subscriptions (active/trialing/pending/past_due/requires_action) instead of failing with 409"),
+      target_privacy: z.enum(["open", "private"]).optional().describe("Privacy the space moves to on disable (default private)"),
+      allow_multiple_space_plan_selections: z.boolean().optional().describe("Let buyers pick multiple plans at checkout. Requires ALL active plans (including hidden) to share one currency and one billing family."),
+      guest_checkout_enabled: z.boolean().optional().describe("Allow purchase without creating an account first. Rejected while any active plan has prerequisites."),
+      guest_invitation_message: z.string().nullable().optional().describe("Message in the guest's invitation email. Null clears."),
+      terms_enabled: z.boolean().optional().describe("Require accepting terms at checkout"),
+      terms_link_label: z.string().nullable().optional().describe('Label for the terms link (default "Terms and Conditions")'),
+      terms_content: z.string().nullable().optional().describe("Terms content (HTML). Null clears."),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...updates }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.patch(`/spaces/${space_id}/payment`, updates, headers);
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/spaces.js

@@ -19,7 +19,7 @@ export function registerSpaceTools(server, client) {
       q: z.string().optional().describe("Search spaces by name (case-insensitive)"),
       state: z.enum(["active", "archived"]).optional().describe("Filter by state"),
       type: z.string().optional().describe("Filter by type (e.g. content, forum)"),
-      privacy: z.enum(["open", "closed", "secret"]).optional().describe("Filter by privacy level"),
+      privacy: z.enum(["open", "private", "payment", "closed", "secret"]).optional().describe("Filter by privacy level (closed/secret are legacy values on older spaces)"),
     },
     async ({ limit, cursor, q, state, type, privacy }) => {
       const data = await client.get("/spaces", { limit, cursor, q, state, type, privacy });
@@ -78,10 +78,11 @@ export function registerSpaceTools(server, client) {
       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,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
     },
-    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);
+    async ({ idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.post("/spaces", body, headers);
       return json(data);
     }
   );
@@ -156,29 +157,49 @@ export function registerSpaceTools(server, client) {
 
   server.tool(
     "update_space",
-    "Update an existing space's name, description, type, privacy, or state.",
+    "Update a space's General settings: identity (name, description, type), access (privacy, visibility, member limit, registration gates), behavior flags, shareable link, and state. Fields marked nullable are cleared by passing null. Archiving is a two-phase transition: descendants are ghosted asynchronously, shareable links cleared, and Stripe subscriptions in the tree cancelled; unarchiving restores descendants but NOT cleared links, redirects, or subscriptions.",
     {
       space_id: z.string().describe("Space ID (sp_...)"),
-      name: z.string().optional().describe("New name"),
-      description: z.string().optional().describe("New description"),
-      type: z.string().optional().describe("New type"),
-      privacy: z.string().optional().describe("New privacy level"),
-      state: z.enum(["active", "archived"]).optional().describe("Set active or archived"),
+      name: z.string().optional().describe("New name (3-100 characters)"),
+      description: z.string().nullable().optional().describe("Description as HTML (sanitized server-side with the web app's safelist). Null clears it."),
+      type: z.enum(["discussion", "content", "list", "showcase", "events", "course", "section"]).optional().describe("Space format. Changing it is tier-gated (professional/organization) and applies the format's display defaults; reverting to content requires the space to have been a content space before."),
+      privacy: z.enum(["open", "private"]).optional().describe("Access level. private is tier-gated. To enable or disable paid access (privacy: payment), use update_space_payment instead."),
+      state: z.enum(["active", "archived"]).optional().describe("Set active or archived. See the archive warning in the tool description."),
+      visibility: z.enum(["public", ""]).nullable().optional().describe('"public" lists the space publicly, "" (or null) unlists it. Cascades to every descendant space. A private space cannot be public.'),
+      pod_type: z.enum(["standard", "readonly"]).optional().describe("readonly freezes member participation"),
+      size: z.number().int().min(1).nullable().optional().describe("Member limit (minimum 1). Null = unlimited."),
+      resource_editing: z.enum(["open", "closed"]).optional().describe("Whether members can edit shared resources"),
+      present_as: z.enum(["list", "grid"]).optional().describe("How child posts/spaces render"),
+      allow_reflections: z.boolean().optional().describe("Allow journal reflections"),
+      show_members: z.boolean().optional().describe("Show the members tab"),
+      block_until_registered: z.boolean().optional().describe("Block content until visitors register"),
+      block_until_approved: z.boolean().optional().describe("Block content until membership is approved"),
+      allow_members_to_invite: z.boolean().optional().describe("Let members invite others"),
+      use_legacy_registration_page: z.boolean().optional(),
+      hangout_link: z.string().nullable().optional().describe("Video call URL (http/https). Null clears it."),
+      abstract_text: z.string().nullable().optional().describe("Short summary text. Null clears it."),
+      emojicon: z.string().nullable().optional().describe("Emoji icon for the space. Null clears it."),
+      circle_creation: z.array(z.enum(["discussion", "subcircles", "resources"])).optional().describe("What members may create here. Empty array = nothing."),
+      url_handle: z.string().nullable().optional().describe("Shareable-link handle (3-25 letters/numbers, unique). Tier-gated to professional/organization. Null clears it."),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
     },
-    async ({ space_id, ...updates }) => {
-      const data = await client.patch(`/spaces/${space_id}`, updates);
+    async ({ space_id, idempotency_key, ...updates }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.patch(`/spaces/${space_id}`, updates, headers);
       return json(data);
     }
   );
 
   server.tool(
     "delete_space",
-    "Delete a space. This archives the space and queues cleanup.",
+    "Delete a space. Descendants are ghosted asynchronously and Stripe subscriptions in the tree are cancelled; cleanup runs in the background.",
     {
       space_id: z.string().describe("Space ID (sp_...)"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
     },
-    async ({ space_id }) => {
-      const data = await client.delete(`/spaces/${space_id}`);
+    async ({ space_id, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.delete(`/spaces/${space_id}`, headers);
       return json(data);
     }
   );
@@ -189,9 +210,11 @@ export function registerSpaceTools(server, client) {
     {
       space_id: z.string().describe("Parent space ID (sp_...)"),
       space_ids: z.array(z.string()).describe("Ordered array of child space IDs (sp_...)"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
     },
-    async ({ space_id, space_ids }) => {
-      const data = await client.patch(`/spaces/${space_id}/children/reorder`, { space_ids });
+    async ({ space_id, space_ids, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.patch(`/spaces/${space_id}/children/reorder`, { space_ids }, headers);
       return json(data);
     }
   );

package/src/tools/website.js

@@ -0,0 +1,195 @@
+import { z } from "zod";
+
+// Website mode + header/footer authoring.
+//
+// Website mode is ROOT-scoped: pass any space_id you manage and the API
+// resolves it to its website root. Enabling is tier-gated (Silver plan and
+// above) and auto-creates a default header (a navbar) + footer; you then edit
+// those configs. The header's nav (links/logo/title/alignment) lives in a
+// NavbarConfig that the site_header share block references via a navbar node.
+//
+// Tiptap arrays (content/links) and style objects are TYPED (z.array/z.record),
+// never bare z.any(), so the MCP client serializes them as structured JSON
+// rather than stringifying them (which the API rejects).
+export function registerWebsiteTools(server, client) {
+  server.tool(
+    "get_space_website",
+    "Get a space's website-mode state: enabled, show_spaces_in_page, and the header/footer share-block config IDs (shbk_...). Website mode is root-scoped — any managed space resolves to its website root.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Resolves to its website root."),
+    },
+    async ({ space_id }) => json(await client.get(`/spaces/${space_id}/website`))
+  );
+
+  server.tool(
+    "update_space_website",
+    "Enable/disable website mode and point the website at header/footer share blocks. enabled:true is tier-gated (Silver+) and, on first enable, auto-creates a default header (navbar) + footer; enabled:false preserves the configs so re-enabling is lossless. header_config_id/footer_config_id must reference a site_header/site_footer share block in the same space (null clears the pointer). Operates on the resolved website root. Typical flow: enable -> get_space_website to read the auto-created config IDs -> update_navbar_config / update_share_block_config to author them.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Resolves to its website root."),
+      enabled: z.boolean().optional().describe("true enables website mode (Silver+); false disables it (configs are preserved)."),
+      show_spaces_in_page: z.boolean().optional().describe("Show child spaces inline in the page while in website mode."),
+      header_config_id: z.string().nullable().optional().describe("shbk_ ID of a site_header share block to use as the header, or null to clear."),
+      footer_config_id: z.string().nullable().optional().describe("shbk_ ID of a site_footer share block to use as the footer, or null to clear."),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...updates }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.patch(`/spaces/${space_id}/website`, updates, headers));
+    }
+  );
+
+  // ----- Share block configs (site_header / site_footer / generic) ----------
+
+  server.tool(
+    "list_share_block_configs",
+    "List the share-block configs (kinds: site_header, site_footer, generic) for a space's website root.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Resolves to its website root."),
+    },
+    async ({ space_id }) => json(await client.get(`/spaces/${space_id}/share_block_configs`))
+  );
+
+  server.tool(
+    "get_share_block_config",
+    "Get one share-block config, including its full Tiptap content and style.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)."),
+      config_id: z.string().describe("Share-block config ID (shbk_...)."),
+    },
+    async ({ space_id, config_id }) => json(await client.get(`/spaces/${space_id}/share_block_configs/${config_id}`))
+  );
+
+  server.tool(
+    "create_share_block_config",
+    "Create a share-block config. For a website header use kind 'site_header' with content = [{ type:'navbar', attrs:{ uid:'<uuid>', navbarConfigId:<int> } }] (create the navbar first with create_navbar_config); for a footer use kind 'site_footer' with freeform blocks. name must be unique within the space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Resolves to its website root."),
+      name: z.string().describe("Config name (unique per space)."),
+      kind: z.enum(["generic", "site_header", "site_footer"]).optional().describe("Defaults to generic."),
+      content: z.array(z.any()).optional().describe("Tiptap node array (bare array, not a stringified doc)."),
+      style: z.record(z.any()).optional().describe("Style object (passthrough)."),
+      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}/share_block_configs`, body, headers));
+    }
+  );
+
+  server.tool(
+    "update_share_block_config",
+    "Update a share-block config's name, content, or style. Kind is immutable through this tool (changing a header's kind would break the website pointer).",
+    {
+      space_id: z.string().describe("Space ID (sp_...)."),
+      config_id: z.string().describe("Share-block config ID (shbk_...)."),
+      name: z.string().optional(),
+      content: z.array(z.any()).optional().describe("Tiptap node array (bare array)."),
+      style: z.record(z.any()).optional(),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, config_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.patch(`/spaces/${space_id}/share_block_configs/${config_id}`, body, headers));
+    }
+  );
+
+  server.tool(
+    "delete_share_block_config",
+    "Delete a share-block config. Returns 409 config_in_use if it is the active website header or footer — repoint or disable website mode first.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)."),
+      config_id: z.string().describe("Share-block config ID (shbk_...)."),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, config_id, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.delete(`/spaces/${space_id}/share_block_configs/${config_id}`, headers));
+    }
+  );
+
+  // ----- Navbar configs (the website header's nav) --------------------------
+
+  server.tool(
+    "list_navbar_configs",
+    "List the navbar configs for a space's website root.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Resolves to its website root."),
+    },
+    async ({ space_id }) => json(await client.get(`/spaces/${space_id}/navbar_configs`))
+  );
+
+  server.tool(
+    "get_navbar_config",
+    "Get one navbar config, including its links and style.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)."),
+      config_id: z.string().describe("Navbar config ID (nvbr_...)."),
+    },
+    async ({ space_id, config_id }) => json(await client.get(`/spaces/${space_id}/navbar_configs/${config_id}`))
+  );
+
+  server.tool(
+    "create_navbar_config",
+    "Create a navbar config (links + style) for a website header. Reference it from a site_header share block's navbar node via navbarConfigId. name must be unique within the space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Resolves to its website root."),
+      name: z.string().describe("Config name (unique per space)."),
+      links: z.array(z.any()).optional().describe("Navbar link objects (bare array)."),
+      style: z.record(z.any()).optional().describe("Navbar style object (linkSource, alignment, showLogo, titleText, etc.)."),
+      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}/navbar_configs`, body, headers));
+    }
+  );
+
+  server.tool(
+    "update_navbar_config",
+    "Update a navbar config's name, links, or style.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)."),
+      config_id: z.string().describe("Navbar config ID (nvbr_...)."),
+      name: z.string().optional(),
+      links: z.array(z.any()).optional().describe("Navbar link objects (bare array)."),
+      style: z.record(z.any()).optional(),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, config_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.patch(`/spaces/${space_id}/navbar_configs/${config_id}`, body, headers));
+    }
+  );
+
+  server.tool(
+    "delete_navbar_config",
+    "Delete a navbar config. A site_header still referencing it by navbarConfigId will render an empty nav until repointed.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)."),
+      config_id: z.string().describe("Navbar config ID (nvbr_...)."),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, config_id, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.delete(`/spaces/${space_id}/navbar_configs/${config_id}`, headers));
+    }
+  );
+
+  server.tool(
+    "duplicate_navbar_config",
+    "Duplicate a navbar config (copies its links and style under a new unique name).",
+    {
+      space_id: z.string().describe("Space ID (sp_...)."),
+      config_id: z.string().describe("Navbar config ID (nvbr_...) to duplicate."),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, config_id, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post(`/spaces/${space_id}/navbar_configs/${config_id}/duplicate`, {}, headers));
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}