@sutraspaces/mcp-server 1.0.1 → 1.1.2

package/src/tools/blog.js

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

package/src/tools/design.js

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

package/src/tools/documents.js

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