@sutraspaces/mcp-server 1.0.0

package/src/tools/coupons.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+
+export function registerCouponTools(server, client) {
+  server.tool(
+    "list_coupons",
+    "List coupons for 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}/coupons`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_coupon",
+    "Get a single coupon by ID.",
+    {
+      coupon_id: z.string().describe("Coupon ID (cpn_...)"),
+    },
+    async ({ coupon_id }) => {
+      const data = await client.get(`/coupons/${coupon_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_coupon",
+    "Create a coupon for a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      code: z.string().optional().describe("Coupon code"),
+      discount_type: z.string().optional().describe("Discount type"),
+      discount_amount: z.number().optional().describe("Discount amount"),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/coupons`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_coupon",
+    "Update a coupon.",
+    {
+      coupon_id: z.string().describe("Coupon ID (cpn_...)"),
+      code: z.string().optional(),
+      discount_type: z.string().optional(),
+      discount_amount: z.number().optional(),
+    },
+    async ({ coupon_id, ...body }) => {
+      const data = await client.patch(`/coupons/${coupon_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_coupon",
+    "Delete a coupon.",
+    {
+      coupon_id: z.string().describe("Coupon ID (cpn_...)"),
+    },
+    async ({ coupon_id }) => {
+      const data = await client.delete(`/coupons/${coupon_id}`);
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/deep.js

@@ -0,0 +1,181 @@
+import { z } from "zod";
+import { extractText } from "../utils/extract-text.js";
+
+const CONCURRENCY = 5;
+
+export function registerDeepTool(server, client) {
+  server.tool(
+    "get_space_deep",
+    "Recursively fetch a space and all its nested content in one call. Returns content blocks, discussion messages, reflections (threaded replies), and child spaces as a single nested object. Rich text is converted to plain text for readability. Best for exploring an entire course, community, or discussion hierarchy.",
+    {
+      space_id: z.string().describe("Space ID (sp_...) to traverse"),
+      max_depth: z.number().optional().describe("How deep to recurse into child spaces (default 3)"),
+      max_items_per_list: z.number().optional().describe("Max content blocks, messages, or reflections per space (default 100)"),
+      max_children: z.number().optional().describe("Max child spaces to traverse per level (default 25)"),
+      include_reflections: z.boolean().optional().describe("Include threaded replies on messages (default true)"),
+    },
+    async ({ space_id, max_depth, max_items_per_list, max_children, include_reflections }) => {
+      const opts = {
+        maxDepth: max_depth ?? 3,
+        maxItems: max_items_per_list ?? 100,
+        maxChildren: max_children ?? 25,
+        includeReflections: include_reflections !== false,
+      };
+
+      const result = await traverse(client, space_id, 0, opts);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+}
+
+async function traverse(client, spaceId, depth, opts) {
+  const res = await client.get(`/spaces/${spaceId}`);
+  const space = res.data || res;
+
+  const node = {
+    id: space.id,
+    name: space.name,
+    type: space.type,
+    state: space.state,
+    privacy: space.privacy,
+    content_blocks: [],
+    messages: [],
+    children: [],
+  };
+
+  // Fetch content blocks
+  try {
+    const blocks = await client.getAll(`/spaces/${spaceId}/content`, {}, opts.maxItems);
+    node.content_blocks = blocks.map(formatBlock);
+    if (blocks.length >= opts.maxItems) {
+      node.content_blocks_truncated = true;
+    }
+  } catch (err) {
+    node.content_blocks_error = err.message;
+  }
+
+  // Fetch messages
+  try {
+    const messages = await client.getAll(`/spaces/${spaceId}/messages`, {}, opts.maxItems);
+    for (const msg of messages) {
+      const formatted = formatMessage(msg);
+
+      if (opts.includeReflections) {
+        try {
+          const reflections = await client.getAll(
+            `/messages/${msg.id}/reflections`, {}, opts.maxItems
+          );
+          if (reflections.length > 0) {
+            formatted.reflections = reflections.map(formatReflection);
+            if (reflections.length >= opts.maxItems) {
+              formatted.reflections_truncated = true;
+            }
+          }
+        } catch {
+          // Skip reflection errors silently
+        }
+      }
+
+      node.messages.push(formatted);
+    }
+    if (messages.length >= opts.maxItems) {
+      node.messages_truncated = true;
+    }
+  } catch (err) {
+    node.messages_error = err.message;
+  }
+
+  // Recurse into children
+  if (depth < opts.maxDepth) {
+    try {
+      const allChildren = await client.getAll(`/spaces/${spaceId}/children`, {}, opts.maxChildren + 1);
+      const toTraverse = allChildren.slice(0, opts.maxChildren);
+      const remaining = allChildren.length - toTraverse.length;
+
+      const results = await parallelMap(toTraverse, async (child) => {
+        try {
+          return await traverse(client, child.id, depth + 1, opts);
+        } catch (err) {
+          return { id: child.id, name: child.name, error: err.message };
+        }
+      }, CONCURRENCY);
+
+      node.children = results;
+
+      if (remaining > 0) {
+        node.children_truncated = true;
+        node.children_remaining = remaining;
+      }
+    } catch (err) {
+      node.children_error = err.message;
+    }
+  } else {
+    try {
+      const children = await client.getAll(`/spaces/${spaceId}/children`, {}, 1);
+      if (children.length > 0) {
+        node.children_note = `Has children — not fetched (max_depth ${opts.maxDepth} reached). Increase max_depth or call list_child_spaces.`;
+      }
+    } catch {
+      // Ignore
+    }
+  }
+
+  // Clean up empty arrays
+  if (node.content_blocks.length === 0) delete node.content_blocks;
+  if (node.messages.length === 0) delete node.messages;
+  if (node.children.length === 0 && !node.children_note) delete node.children;
+
+  return node;
+}
+
+function formatBlock(block) {
+  return {
+    id: block.id,
+    author: formatAuthor(block.author),
+    text: extractText(block.content) || block.raw_content || "",
+    priority: block.priority,
+    created_at: block.created_at,
+  };
+}
+
+function formatMessage(msg) {
+  return {
+    id: msg.id,
+    type: msg.type,
+    author: formatAuthor(msg.author),
+    text: extractText(msg.content) || msg.raw_content || "",
+    created_at: msg.created_at,
+  };
+}
+
+function formatReflection(ref) {
+  return {
+    id: ref.id,
+    author: formatAuthor(ref.author),
+    text: extractText(ref.content) || ref.raw_content || "",
+    created_at: ref.created_at,
+  };
+}
+
+function formatAuthor(user) {
+  if (!user) return null;
+  return {
+    id: user.id,
+    name: user.name || [user.first_name, user.last_name].filter(Boolean).join(" ") || user.username,
+  };
+}
+
+async function parallelMap(items, fn, concurrency) {
+  const results = [];
+  let index = 0;
+  async function worker() {
+    while (index < items.length) {
+      const i = index++;
+      results[i] = await fn(items[i]);
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, () => worker())
+  );
+  return results;
+}

package/src/tools/invitations.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+
+export function registerInvitationTools(server, client) {
+  server.tool(
+    "list_invitations",
+    "List invitations for 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}/invitations`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_invitation",
+    "Get a single invitation by ID.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      invitation_id: z.string().describe("Invitation ID (inv_...)"),
+    },
+    async ({ space_id, invitation_id }) => {
+      const data = await client.get(`/spaces/${space_id}/invitations/${invitation_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_invitation",
+    "Create an invitation to a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      email: z.string().describe("Email address to invite"),
+      message: z.string().optional().describe("Custom invitation message"),
+      role: z.enum(["member", "editor", "moderator"]).optional().describe("Role for the invitee"),
+      notify: z.boolean().optional().describe("Send email notification (default: false)"),
+      free_access: z.boolean().optional().describe("Grant free access (default: false)"),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/invitations`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_invitation",
+    "Update an invitation.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      invitation_id: z.string().describe("Invitation ID (inv_...)"),
+      message: z.string().optional(),
+      role: z.enum(["member", "editor", "moderator"]).optional(),
+      free_access: z.boolean().optional(),
+    },
+    async ({ space_id, invitation_id, ...body }) => {
+      const data = await client.patch(`/spaces/${space_id}/invitations/${invitation_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_invitation",
+    "Delete an invitation.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      invitation_id: z.string().describe("Invitation ID (inv_...)"),
+    },
+    async ({ space_id, invitation_id }) => {
+      const data = await client.delete(`/spaces/${space_id}/invitations/${invitation_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "resend_invitation",
+    "Resend an invitation email.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      invitation_id: z.string().describe("Invitation ID (inv_...)"),
+    },
+    async ({ space_id, invitation_id }) => {
+      const data = await client.post(`/spaces/${space_id}/invitations/${invitation_id}/resend`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "bulk_create_invitations",
+    "Create up to 100 invitations at once. Requires an Idempotency-Key.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      idempotency_key: z.string().describe("Unique key for this batch operation"),
+      items: z.array(z.object({
+        email: z.string(),
+        message: z.string().optional(),
+        role: z.enum(["member", "editor", "moderator"]).optional(),
+        notify: z.boolean().optional(),
+        free_access: z.boolean().optional(),
+      })).describe("Array of invitation objects (max 100)"),
+    },
+    async ({ space_id, idempotency_key, items }) => {
+      const data = await client.post(
+        `/spaces/${space_id}/invitations/bulk`,
+        { items },
+        { "Idempotency-Key": idempotency_key }
+      );
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/members.js

@@ -0,0 +1,144 @@
+import { z } from "zod";
+
+export function registerMemberTools(server, client) {
+  server.tool(
+    "list_members",
+    "List members of a space. Returns member IDs (mem_...), user info, roles, and states.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      limit: z.number().optional().describe("Max results (default 25)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+      user_id: z.string().optional().describe("Filter by user ID (usr_...)"),
+      email: z.string().optional().describe("Filter by exact email (requires members.email:read scope)"),
+    },
+    async ({ space_id, limit, cursor, user_id, email }) => {
+      const data = await client.get(`/spaces/${space_id}/members`, { limit, cursor, user_id, email });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_member",
+    "Get details 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}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "add_member",
+    "Add a member to a space by email or user ID. Use email to auto-resolve or create a user account.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      email: z.string().optional().describe("Member's email address"),
+      user_id: z.string().optional().describe("User ID (usr_...) — alternative to email"),
+      first_name: z.string().optional().describe("First name (used when creating a new user via email)"),
+      last_name: z.string().optional().describe("Last name"),
+      username: z.string().optional().describe("Username"),
+      role: z.enum(["member", "editor", "moderator"]).optional().describe("Role (default: member)"),
+      notify: z.boolean().optional().describe("Send email notification (default: false)"),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/members`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_member",
+    "Update a member's role or notification settings.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      member_id: z.string().describe("Member ID (mem_...)"),
+      role: z.enum(["member", "editor", "moderator"]).optional().describe("New role"),
+      email_frequency: z.string().optional().describe("Email notification frequency"),
+    },
+    async ({ space_id, member_id, ...body }) => {
+      const data = await client.patch(`/spaces/${space_id}/members/${member_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "remove_member",
+    "Remove a member from a space. This also removes memberships in descendant spaces. Requires an Idempotency-Key.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      member_id: z.string().describe("Member ID (mem_...)"),
+      idempotency_key: z.string().describe("Unique key for this operation (e.g. remove-mem_abc-2026-04-30)"),
+    },
+    async ({ space_id, member_id, idempotency_key }) => {
+      const data = await client.delete(`/spaces/${space_id}/members/${member_id}`, {
+        "Idempotency-Key": idempotency_key,
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "approve_member",
+    "Approve a pending 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.post(`/spaces/${space_id}/members/${member_id}/approve`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "bulk_add_members",
+    "Add up to 100 members to a space in one call. Requires an Idempotency-Key. Returns per-item results.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      idempotency_key: z.string().describe("Unique key for this batch operation"),
+      items: z.array(z.object({
+        email: z.string().optional(),
+        user_id: z.string().optional(),
+        first_name: z.string().optional(),
+        last_name: z.string().optional(),
+        role: z.enum(["member", "editor", "moderator"]).optional(),
+        notify: z.boolean().optional(),
+      })).describe("Array of member objects (max 100). Each needs email or user_id."),
+    },
+    async ({ space_id, idempotency_key, items }) => {
+      const data = await client.post(
+        `/spaces/${space_id}/members/bulk`,
+        { items },
+        { "Idempotency-Key": idempotency_key }
+      );
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "bulk_remove_members",
+    "Remove up to 100 members from a space. Requires an Idempotency-Key. Returns per-item results.",
+    {
+      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_...)"),
+      })).describe("Array of member references (max 100)"),
+    },
+    async ({ space_id, idempotency_key, items }) => {
+      const data = await client.post(
+        `/spaces/${space_id}/members/bulk_delete`,
+        { items },
+        { "Idempotency-Key": idempotency_key }
+      );
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/plans.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+
+export function registerPlanTools(server, client) {
+  // --- Plans ---
+
+  server.tool(
+    "list_plans",
+    "List plans (offerings) for a space. Plans describe what can be purchased or enrolled in.",
+    {
+      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}/plans`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_plan",
+    "Get a single plan by ID.",
+    {
+      plan_id: z.string().describe("Plan ID (plan_...)"),
+    },
+    async ({ plan_id }) => {
+      const data = await client.get(`/plans/${plan_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_plan",
+    "Create a plan for a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      name: z.string().optional().describe("Plan name"),
+      price: z.number().optional().describe("Price amount"),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/plans`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_plan",
+    "Update a plan.",
+    {
+      plan_id: z.string().describe("Plan ID (plan_...)"),
+      name: z.string().optional(),
+      price: z.number().optional(),
+    },
+    async ({ plan_id, ...body }) => {
+      const data = await client.patch(`/plans/${plan_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_plan",
+    "Delete a plan.",
+    {
+      plan_id: z.string().describe("Plan ID (plan_...)"),
+    },
+    async ({ plan_id }) => {
+      const data = await client.delete(`/plans/${plan_id}`);
+      return json(data);
+    }
+  );
+
+  // --- Enrollments ---
+
+  server.tool(
+    "list_enrollments",
+    "List enrollments for a plan. Enrollments represent people enrolled through a specific plan.",
+    {
+      plan_id: z.string().describe("Plan ID (plan_...)"),
+      limit: z.number().optional().describe("Max results (default 25)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ plan_id, limit, cursor }) => {
+      const data = await client.get(`/plans/${plan_id}/enrollments`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_enrollment",
+    "Get a single enrollment by ID.",
+    {
+      enrollment_id: z.string().describe("Enrollment ID (enr_...)"),
+    },
+    async ({ enrollment_id }) => {
+      const data = await client.get(`/enrollments/${enrollment_id}`);
+      return json(data);
+    }
+  );
+
+  // --- Payments ---
+
+  server.tool(
+    "list_payments",
+    "List payments for 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}/payments`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_payment",
+    "Get a single payment by ID.",
+    {
+      payment_id: z.string().describe("Payment ID (pay_...)"),
+    },
+    async ({ payment_id }) => {
+      const data = await client.get(`/payments/${payment_id}`);
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}