@sutraspaces/mcp-server 1.0.1 → 1.1.2

package/src/tools/properties.js

@@ -89,6 +89,75 @@ export function registerPropertyTools(server, client) {
     }
   );
 
+  server.tool(
+    "bulk_update_member_property_values",
+    "Set property values for up to 100 members. Requires an Idempotency-Key. Use null to clear a value.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      idempotency_key: z.string().describe("Unique key for this batch operation"),
+      items: z.array(z.object({
+        member_id: z.string().describe("Member ID (mem_...)"),
+        properties: z.record(z.any()).describe("Object keyed by property key or mprop_ ID, values to set (null to clear)"),
+      })).describe("Array of member property updates (max 100)"),
+    },
+    async ({ space_id, idempotency_key, items }) => {
+      const data = await client.patch(
+        `/spaces/${space_id}/members/properties/bulk`,
+        { items },
+        { "Idempotency-Key": idempotency_key }
+      );
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_contact_property_values",
+    "Get all property values for a specific contact in a space. Contacts use the same member property definitions as members.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      contact_id: z.string().describe("Contact ID (contact_...)"),
+    },
+    async ({ space_id, contact_id }) => {
+      const data = await client.get(`/spaces/${space_id}/contacts/${contact_id}/properties`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_contact_property_values",
+    "Set property values for a contact. Use null to clear a value. Keys can be property keys or mprop_ IDs.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      contact_id: z.string().describe("Contact ID (contact_...)"),
+      properties: z.record(z.any()).describe("Object keyed by property key or mprop_ ID, values to set (null to clear)"),
+    },
+    async ({ space_id, contact_id, properties }) => {
+      const data = await client.patch(`/spaces/${space_id}/contacts/${contact_id}/properties`, { properties });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "bulk_update_contact_property_values",
+    "Set property values for up to 100 contacts. Requires an Idempotency-Key. Use null to clear a value.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      idempotency_key: z.string().describe("Unique key for this batch operation"),
+      items: z.array(z.object({
+        contact_id: z.string().describe("Contact ID (contact_...)"),
+        properties: z.record(z.any()).describe("Object keyed by property key or mprop_ ID, values to set (null to clear)"),
+      })).describe("Array of contact property updates (max 100)"),
+    },
+    async ({ space_id, idempotency_key, items }) => {
+      const data = await client.patch(
+        `/spaces/${space_id}/contacts/properties/bulk`,
+        { items },
+        { "Idempotency-Key": idempotency_key }
+      );
+      return json(data);
+    }
+  );
+
   // --- Space Properties ---
 
   server.tool(

package/src/tools/spaces.js

@@ -1,5 +1,14 @@
 import { z } from "zod";
 
+const placementSchema = z.object({
+  surface: z.enum(["auto", "collection", "document"]).optional().describe("Where the child appears. Use auto for normal course/section placement."),
+  position: z.number().int().nonnegative().optional().describe("Zero-based order in the resolved surface."),
+  view_as: z.enum(["list", "hcard", "vcard", "button", "link"]).optional().describe("Document card render mode. Ignored for collection placement."),
+  insert: z.enum(["append", "before", "after", "inside"]).optional().describe("Document insertion mode."),
+  anchor_node_uid: z.string().optional().describe("Tiptap node UID used with before/after/inside."),
+  set_parent_ordering: z.enum(["custom_order"]).optional().describe("Set parent list ordering so collection position is visually effective."),
+}).optional();
+
 export function registerSpaceTools(server, client) {
   server.tool(
     "list_spaces",
@@ -18,6 +27,19 @@ export function registerSpaceTools(server, client) {
     }
   );
 
+  server.tool(
+    "list_membership_spaces",
+    "List basic information about spaces where the API token owner is a member. This is read-only membership inventory, not admin access to space subresources.",
+    {
+      limit: z.number().optional().describe("Max results per page (default 25, max 100)"),
+      cursor: z.string().optional().describe("Pagination cursor from a previous response"),
+    },
+    async ({ limit, cursor }) => {
+      const data = await client.get("/me/membership_spaces", { limit, cursor });
+      return json(data);
+    }
+  );
+
   server.tool(
     "get_space",
     "Get details for a single space by its ID (sp_...).",
@@ -46,7 +68,7 @@ export function registerSpaceTools(server, client) {
 
   server.tool(
     "create_space",
-    "Create a new space. Omit parent_id for a top-level space, or include it to create a child space.",
+    "Create a new space. Omit parent_id for a top-level space, or include a parent sp_ ID to create a child. Use sp_ IDs, not slugs.",
     {
       name: z.string().describe("Space name"),
       description: z.string().optional().describe("Space description"),
@@ -54,14 +76,84 @@ export function registerSpaceTools(server, client) {
       privacy: z.string().optional().describe("Privacy level (default: open)"),
       pod_type: z.enum(["standard", "readonly"]).optional().describe("Pod type (default: standard)"),
       parent_id: z.string().optional().describe("Parent space ID (sp_...) to create as a child"),
+      content_scaffold: z.enum(["none", "ui_default"]).optional().describe("Use none when document content will be written through document tools."),
+      placement: placementSchema,
     },
-    async ({ name, description, type, privacy, pod_type, parent_id }) => {
-      const body = { name, description, type, privacy, pod_type, parent_id };
+    async ({ name, description, type, privacy, pod_type, parent_id, content_scaffold, placement }) => {
+      const body = { name, description, type, privacy, pod_type, parent_id, content_scaffold, placement };
       const data = await client.post("/spaces", body);
       return json(data);
     }
   );
 
+  server.tool(
+    "create_child_space",
+    "Create a child space under a parent sp_ ID and make it visible through placement. For courses and sections use placement.surface = auto.",
+    {
+      parent_id: z.string().describe("Parent space ID (sp_...). Do not use a slug."),
+      name: z.string().describe("Child space name"),
+      description: z.string().optional(),
+      type: z.string().optional().describe("Space type (default: content)"),
+      privacy: z.string().optional(),
+      pod_type: z.enum(["standard", "readonly"]).optional(),
+      content_scaffold: z.enum(["none", "ui_default"]).optional().describe("Use none when document content will be written through document tools."),
+      placement: placementSchema,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ parent_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.post(`/spaces/${parent_id}/children`, body, headers);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "attach_child_space",
+    "Attach an existing child sp_ ID to a parent sp_ ID and make it visible. Use this when a space already exists but is not showing in the course/section/page.",
+    {
+      parent_id: z.string().describe("Parent space ID (sp_...). Do not use a slug."),
+      child_id: z.string().describe("Existing child space ID (sp_...). Do not use a slug."),
+      placement: placementSchema,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ parent_id, child_id, placement, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.put(`/spaces/${parent_id}/children/${child_id}`, { placement }, headers);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_child_space_placement",
+    "Move or repair a child space display under a parent. Use auto for normal course/section placement; use document for a card in a content page.",
+    {
+      parent_id: z.string().describe("Parent space ID (sp_...). Do not use a slug."),
+      child_id: z.string().describe("Child space ID (sp_...). Do not use a slug."),
+      placement: placementSchema,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ parent_id, child_id, placement, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.patch(`/spaces/${parent_id}/children/${child_id}/placement`, { placement }, headers);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "detach_child_space",
+    "Detach a child space from one parent without deleting the child space.",
+    {
+      parent_id: z.string().describe("Parent space ID (sp_...). Do not use a slug."),
+      child_id: z.string().describe("Child space ID (sp_...). Do not use a slug."),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ parent_id, child_id, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const data = await client.delete(`/spaces/${parent_id}/children/${child_id}`, headers);
+      return json(data);
+    }
+  );
+
   server.tool(
     "update_space",
     "Update an existing space's name, description, type, privacy, or state.",