@sutraspaces/mcp-server 1.2.0 → 1.3.0

package/README.md

@@ -86,12 +86,15 @@ Point your MCP client at `npx -y @sutraspaces/mcp-server`. The server communicat
 | Variable | Required | Description |
 |---|---|---|
 | `SUTRA_API_TOKEN` | No* | Your Sutra Admin API token (`sutra_live_sk_...`). *Required only if not using OAuth. When set, OAuth is skipped. |
-| `SUTRA_OAUTH_ISSUER` | No | OAuth issuer base URL (default: `https://sutra.co`). Must be `https://` (only loopback hosts may use `http://`). Separate from the Admin API URL. |
+| `SUTRA_OAUTH_ISSUER` | No | OAuth issuer base URL (default: `https://api.sutra.co`). Must be `https://` (only loopback hosts may use `http://`). Separate from the Admin API URL. |
 | `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
@@ -173,7 +182,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 +195,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 +205,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.0",
+  "version": "1.3.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";
@@ -33,7 +34,7 @@ import { clear, load } from "./auth/store.js";
 const args = process.argv.slice(2);
 
 if (args.includes("login")) {
-  const issuer = process.env.SUTRA_OAUTH_ISSUER || "https://sutra.co";
+  const issuer = process.env.SUTRA_OAUTH_ISSUER || "https://api.sutra.co";
   try {
     await login({ issuer });
     process.exit(0);
@@ -44,7 +45,7 @@ if (args.includes("login")) {
 }
 
 if (args.includes("logout")) {
-  const issuer = process.env.SUTRA_OAUTH_ISSUER || "https://sutra.co";
+  const issuer = process.env.SUTRA_OAUTH_ISSUER || "https://api.sutra.co";
   clear(issuer);
   process.stderr.write("Logged out — cached credentials removed.\n");
   process.exit(0);
@@ -56,7 +57,7 @@ if (args.includes("logout")) {
 
 const SUTRA_API_TOKEN = process.env.SUTRA_API_TOKEN;
 const SUTRA_BASE_URL = process.env.SUTRA_BASE_URL;
-const SUTRA_OAUTH_ISSUER = process.env.SUTRA_OAUTH_ISSUER || "https://sutra.co";
+const SUTRA_OAUTH_ISSUER = process.env.SUTRA_OAUTH_ISSUER || "https://api.sutra.co";
 
 let client;
 
@@ -119,12 +120,14 @@ if (SUTRA_API_TOKEN) {
 
 const server = new McpServer({
   name: "sutra",
-  version: "1.2.0",
+  // Keep in lockstep with package.json.
+  version: "1.3.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);

package/src/resources/admin-api.js

@@ -8,6 +8,14 @@ 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).
+- get_space returns the detail read with nested settings, appearance, and payment objects.
+
 Important IDs:
 - Spaces use sp_ IDs.
 - Members use mem_ IDs.
@@ -25,6 +33,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/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);
     }
   );