@sutraspaces/mcp-server 1.0.0

package/src/tools/properties.js

@@ -0,0 +1,181 @@
+import { z } from "zod";
+
+export function registerPropertyTools(server, client) {
+  // --- Member Properties ---
+
+  server.tool(
+    "list_member_properties",
+    "List member property definitions for a space. Member properties are custom fields like company, role, or interests.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      limit: z.number().optional().describe("Max results (default 25)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ space_id, limit, cursor }) => {
+      const data = await client.get(`/spaces/${space_id}/member_properties`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_member_property",
+    "Create a member property definition for a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      name: z.string().describe("Display name"),
+      key: z.string().describe("Machine key (e.g. company, role)"),
+      type: z.enum(["text", "select", "multi_select", "number", "date", "url", "phone", "location"]).describe("Property type"),
+      options: z.any().optional().describe("For select/multi_select: { values: [{ value, name }] }"),
+      visibility: z.array(z.string()).optional().describe("Visibility settings"),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/member_properties`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_member_property",
+    "Update a member property definition.",
+    {
+      member_property_id: z.string().describe("Member property ID (mprop_...)"),
+      name: z.string().optional(),
+      type: z.enum(["text", "select", "multi_select", "number", "date", "url", "phone", "location"]).optional(),
+      options: z.any().optional(),
+      visibility: z.array(z.string()).optional(),
+    },
+    async ({ member_property_id, ...body }) => {
+      const data = await client.patch(`/member_properties/${member_property_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_member_property",
+    "Delete a member property definition.",
+    {
+      member_property_id: z.string().describe("Member property ID (mprop_...)"),
+    },
+    async ({ member_property_id }) => {
+      const data = await client.delete(`/member_properties/${member_property_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_member_property_values",
+    "Get all property values for a specific member in a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      member_id: z.string().describe("Member ID (mem_...)"),
+    },
+    async ({ space_id, member_id }) => {
+      const data = await client.get(`/spaces/${space_id}/members/${member_id}/properties`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_member_property_values",
+    "Set property values for a member. Use null to clear a value. Keys can be property keys or mprop_ IDs.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      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)"),
+    },
+    async ({ space_id, member_id, properties }) => {
+      const data = await client.patch(`/spaces/${space_id}/members/${member_id}/properties`, { properties });
+      return json(data);
+    }
+  );
+
+  // --- Space Properties ---
+
+  server.tool(
+    "list_space_properties",
+    "List space property definitions owned by a space. Space properties describe child spaces (e.g. category, date, featured).",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      limit: z.number().optional().describe("Max results (default 25)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ space_id, limit, cursor }) => {
+      const data = await client.get(`/spaces/${space_id}/space_properties`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_space_property",
+    "Create a space property definition for a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      name: z.string().describe("Display name"),
+      key: z.string().describe("Machine key"),
+      type: z.enum(["text", "select", "multi_select", "number", "date", "url", "phone", "location"]).describe("Property type"),
+      options: z.any().optional().describe("For select/multi_select: { values: [{ value, name }] }"),
+      visibility: z.array(z.string()).optional(),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/space_properties`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_space_property",
+    "Update a space property definition.",
+    {
+      space_property_id: z.string().describe("Space property ID (sprop_...)"),
+      name: z.string().optional(),
+      type: z.enum(["text", "select", "multi_select", "number", "date", "url", "phone", "location"]).optional(),
+      options: z.any().optional(),
+      visibility: z.array(z.string()).optional(),
+    },
+    async ({ space_property_id, ...body }) => {
+      const data = await client.patch(`/space_properties/${space_property_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_space_property",
+    "Delete a space property definition.",
+    {
+      space_property_id: z.string().describe("Space property ID (sprop_...)"),
+    },
+    async ({ space_property_id }) => {
+      const data = await client.delete(`/space_properties/${space_property_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_space_property_values",
+    "Get all property values for a space (typically a child space with properties defined by its parent).",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+    },
+    async ({ space_id }) => {
+      const data = await client.get(`/spaces/${space_id}/properties`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_space_property_values",
+    "Set property values on a space. Use null to clear a value. Keys can be property keys or sprop_ IDs.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      properties: z.record(z.any()).describe("Object keyed by property key or sprop_ ID, values to set (null to clear)"),
+    },
+    async ({ space_id, properties }) => {
+      const data = await client.patch(`/spaces/${space_id}/properties`, { properties });
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/spaces.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+
+export function registerSpaceTools(server, client) {
+  server.tool(
+    "list_spaces",
+    "List all spaces the API token can access. Returns space IDs (sp_...), names, types, and states. Start here to discover available spaces.",
+    {
+      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("/spaces", { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_space",
+    "Get details for a single space by its ID (sp_...).",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+    },
+    async ({ space_id }) => {
+      const data = await client.get(`/spaces/${space_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "list_child_spaces",
+    "List direct child spaces of a parent space. Use this to explore the space hierarchy.",
+    {
+      space_id: z.string().describe("Parent space ID (sp_...)"),
+      limit: z.number().optional().describe("Max results (default 25)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ space_id, limit, cursor }) => {
+      const data = await client.get(`/spaces/${space_id}/children`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_space",
+    "Create a new space. Omit parent_id for a top-level space, or include it to create a child space.",
+    {
+      name: z.string().describe("Space name"),
+      description: z.string().optional().describe("Space description"),
+      type: z.string().optional().describe("Space type (default: content)"),
+      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"),
+    },
+    async ({ name, description, type, privacy, pod_type, parent_id }) => {
+      const body = { name, description, type, privacy, pod_type, parent_id };
+      const data = await client.post("/spaces", body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_space",
+    "Update an existing space's name, description, type, privacy, or state.",
+    {
+      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"),
+    },
+    async ({ space_id, ...updates }) => {
+      const data = await client.patch(`/spaces/${space_id}`, updates);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_space",
+    "Delete a space. This archives the space and queues cleanup.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+    },
+    async ({ space_id }) => {
+      const data = await client.delete(`/spaces/${space_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "reorder_child_spaces",
+    "Reorder child spaces within a parent by providing the desired order of space IDs.",
+    {
+      space_id: z.string().describe("Parent space ID (sp_...)"),
+      space_ids: z.array(z.string()).describe("Ordered array of child space IDs (sp_...)"),
+    },
+    async ({ space_id, space_ids }) => {
+      const data = await client.patch(`/spaces/${space_id}/children/reorder`, { space_ids });
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/surveys.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+
+export function registerSurveyTools(server, client) {
+  server.tool(
+    "list_surveys",
+    "List surveys in a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      limit: z.number().optional().describe("Max results (default 25)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ space_id, limit, cursor }) => {
+      const data = await client.get(`/spaces/${space_id}/surveys`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_survey",
+    "Get a single survey with its questions.",
+    {
+      survey_id: z.string().describe("Survey ID (surv_...)"),
+    },
+    async ({ survey_id }) => {
+      const data = await client.get(`/surveys/${survey_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_survey_submissions",
+    "Get submissions (responses) for a survey.",
+    {
+      survey_id: z.string().describe("Survey ID (surv_...)"),
+      limit: z.number().optional().describe("Max results (default 25)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ survey_id, limit, cursor }) => {
+      const data = await client.get(`/surveys/${survey_id}/submissions`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_survey",
+    "Create a survey in a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      title: z.string().optional().describe("Survey title"),
+      questions: z.array(z.any()).optional().describe("Array of question objects"),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/surveys`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_survey",
+    "Update a survey.",
+    {
+      survey_id: z.string().describe("Survey ID (surv_...)"),
+      title: z.string().optional(),
+      questions: z.array(z.any()).optional(),
+    },
+    async ({ survey_id, ...body }) => {
+      const data = await client.patch(`/surveys/${survey_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_survey",
+    "Delete a survey.",
+    {
+      survey_id: z.string().describe("Survey ID (surv_...)"),
+    },
+    async ({ survey_id }) => {
+      const data = await client.delete(`/surveys/${survey_id}`);
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/utils/extract-text.js

@@ -0,0 +1,85 @@
+export function extractFromTiptap(node) {
+  if (!node) return "";
+  if (typeof node === "string") return node;
+  if (Array.isArray(node)) {
+    return node.map(extractFromTiptap).filter(Boolean).join("\n");
+  }
+
+  if (node.type === "text") return node.text || "";
+
+  const children = node.content
+    ? node.content.map(extractFromTiptap).filter(Boolean)
+    : [];
+
+  switch (node.type) {
+    case "doc":
+      return children.join("\n\n");
+    case "paragraph":
+      return children.join("");
+    case "heading": {
+      const prefix = "#".repeat(node.attrs?.level || 1);
+      return `${prefix} ${children.join("")}`;
+    }
+    case "bulletList":
+    case "bullet_list":
+      return children.map((c) => `- ${c}`).join("\n");
+    case "orderedList":
+    case "ordered_list":
+      return children.map((c, i) => `${i + 1}. ${c}`).join("\n");
+    case "listItem":
+    case "list_item":
+      return children.join("\n");
+    case "blockquote":
+      return children.map((c) => `> ${c}`).join("\n");
+    case "codeBlock":
+    case "code_block":
+      return `\`\`\`\n${children.join("\n")}\n\`\`\``;
+    case "hardBreak":
+    case "hard_break":
+      return "\n";
+    case "horizontalRule":
+    case "horizontal_rule":
+      return "---";
+    case "image":
+      return `[Image: ${node.attrs?.alt || node.attrs?.src || ""}]`;
+    case "mention":
+      return `@${node.attrs?.label || node.attrs?.id || "someone"}`;
+    case "sutra_embed":
+    case "sutra_video":
+    case "sutra_audio":
+    case "sutra_file":
+      return `[${node.type}: ${node.attrs?.title || node.attrs?.name || node.attrs?.url || ""}]`;
+    default:
+      return children.join("\n");
+  }
+}
+
+function extractFromHtml(html) {
+  if (!html || typeof html !== "string") return "";
+  return html
+    .replace(/<\/(p|div|h[1-6]|li|br|tr)>/gi, "\n")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export function extractText(content) {
+  if (!content) return "";
+  if (typeof content === "string") {
+    if (/<[a-z][\s\S]*>/i.test(content)) return extractFromHtml(content);
+    try {
+      return extractFromTiptap(JSON.parse(content));
+    } catch {
+      return content.trim();
+    }
+  }
+  if (typeof content === "object") return extractFromTiptap(content);
+  return String(content);
+}