@sutraspaces/mcp-server 1.3.0 → 1.4.0

package/README.md

@@ -162,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sutraspaces/mcp-server",
-  "version": "1.3.0",
+  "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",

package/src/index.js

@@ -21,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";
@@ -121,7 +122,7 @@ if (SUTRA_API_TOKEN) {
 const server = new McpServer({
   name: "sutra",
   // Keep in lockstep with package.json.
-  version: "1.3.0",
+  version: "1.4.0",
   description:
     "Sutra Admin API — manage spaces, members, contacts, content, discussions, surveys, plans, broadcasts, and more.",
 });
@@ -141,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

@@ -14,7 +14,8 @@ Space configuration tools:
 - 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.
+- 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.
@@ -23,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.

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/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) }] };
+}