@sutraspaces/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,134 @@
+# Sutra MCP Server
+
+An [MCP](https://modelcontextprotocol.io) server that connects AI agents to the [Sutra Admin API](https://sutra.co). Manage spaces, members, content, discussions, surveys, plans, broadcasts, and more — all through your AI tools.
+
+## Quick Start
+
+```bash
+npm install
+```
+
+Set your Sutra API token:
+
+```bash
+export SUTRA_API_TOKEN="sutra_live_sk_..."
+```
+
+You can get an API token from your Sutra account settings or by contacting support@sutra.co.
+
+## Usage
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sutra": {
+      "command": "node",
+      "args": ["/path/to/sutra-mcp/src/index.js"],
+      "env": {
+        "SUTRA_API_TOKEN": "sutra_live_sk_..."
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add sutra -- env SUTRA_API_TOKEN=sutra_live_sk_... node /path/to/sutra-mcp/src/index.js
+```
+
+### Cursor / Windsurf / Other MCP Clients
+
+Point your MCP client at the server entry point with the `SUTRA_API_TOKEN` environment variable set. The server communicates over stdio.
+
+## Configuration
+
+| Variable | Required | Description |
+|---|---|---|
+| `SUTRA_API_TOKEN` | Yes | Your Sutra Admin API token (`sutra_live_sk_...`) |
+| `SUTRA_BASE_URL` | No | Override the API URL (default: `https://api.sutra.co/api/admin/v1`) |
+
+## Available Tools
+
+### Deep Traversal
+- **get_space_deep** — Recursively fetch a space and all its nested content in one call: content blocks, discussion messages, reflections, and child spaces. Rich text is converted to plain text. Configurable depth, item limits, and whether to include reflections. Best for exploring an entire course, community, or discussion hierarchy.
+
+### Spaces
+- **list_spaces** — List all spaces the API token can access
+- **get_space** — Get details for a single space
+- **list_child_spaces** — List direct child spaces
+- **create_space** — Create a new space (top-level or child)
+- **update_space** — Update space name, description, type, privacy, or state
+- **delete_space** — Delete/archive a space
+- **reorder_child_spaces** — Reorder children within a parent
+
+### Members
+- **list_members** — List space members with optional email/user_id filtering
+- **get_member** — Get member details
+- **add_member** — Add a member by email or user ID
+- **update_member** — Update role or notification settings
+- **remove_member** — Remove a member (cascades to descendant spaces)
+- **approve_member** — Approve a pending member
+- **bulk_add_members** — Add up to 100 members at once
+- **bulk_remove_members** — Remove up to 100 members at once
+
+### Content & Discussions
+- **list_content** / **get_content_block** / **create_content** / **update_content** / **delete_content** — Manage content blocks
+- **reorder_content** — Reorder content blocks within a space
+- **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
+
+### Properties
+- **list_member_properties** / **create_member_property** / **update_member_property** / **delete_member_property** — Manage custom member property definitions
+- **get_member_property_values** / **update_member_property_values** — Read and set property values per member
+- **list_space_properties** / **create_space_property** / **update_space_property** / **delete_space_property** — Manage custom space property definitions
+- **get_space_property_values** / **update_space_property_values** — Read and set property values per space
+
+### Invitations
+- **list_invitations** / **get_invitation** / **create_invitation** / **update_invitation** / **delete_invitation** — Manage invitations
+- **resend_invitation** — Resend an invitation email
+- **bulk_create_invitations** — Create up to 100 invitations at once
+
+### Surveys
+- **list_surveys** / **get_survey** / **create_survey** / **update_survey** / **delete_survey** — Manage surveys
+- **get_survey_submissions** — Read survey responses
+
+### Plans & Enrollments
+- **list_plans** / **get_plan** / **create_plan** / **update_plan** / **delete_plan** — Manage plans
+- **list_enrollments** / **get_enrollment** — Read enrollments
+- **list_payments** / **get_payment** — Read payment history
+
+### Coupons
+- **list_coupons** / **get_coupon** / **create_coupon** / **update_coupon** / **delete_coupon** — Manage discount codes
+
+### Broadcasts
+- **list_broadcasts** / **get_broadcast** / **create_broadcast** / **update_broadcast** / **delete_broadcast** — Manage broadcasts
+- **send_broadcast** — Send a broadcast to space members
+- **get_broadcast_delivery_status** — Check delivery progress
+
+## API Concepts
+
+**Spaces** are the core building block — they can be courses, communities, forums, or any structured container. Spaces form hierarchies through parent-child relationships.
+
+**Members** belong to spaces. They have roles (member, editor, moderator) and can have custom properties attached.
+
+**Content blocks** are structured content created by facilitators. **Messages** are discussion posts from participants. **Reflections** are threaded replies to messages.
+
+**All IDs** use readable prefixes: `sp_` (space), `mem_` (member), `usr_` (user), `blk_` (block/message), `reply_` (reflection), `surv_` (survey), `plan_` (plan), `enr_` (enrollment), `pay_` (payment), `cpn_` (coupon), `bcst_` (broadcast), `inv_` (invitation), `mprop_` / `sprop_` (property definitions).
+
+**Pagination** is cursor-based. List endpoints return `{ data, pagination: { next_cursor, has_more } }`. Pass `cursor` to get the next page.
+
+**Scopes** control what the API token can access. Tokens have read/write scope pairs like `spaces:read`, `members:write`, etc. Operations that exceed the token's scopes will return 403.
+
+## Architecture
+
+```
+AI Agent → MCP Protocol (stdio) → sutra-mcp → Sutra Admin API → Sutra Platform
+```
+
+The server is a thin, stateless wrapper. All data flows through the Sutra Admin API with Bearer token authentication. No data is cached or stored locally.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@sutraspaces/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for the Sutra Admin API — manage spaces, members, content, and more via AI agents",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "sutra-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.23.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sutra",
+    "ai",
+    "agent",
+    "lms",
+    "learning",
+    "community"
+  ],
+  "author": "Sutra <support@sutra.co> (https://sutra.co)",
+  "license": "MIT",
+  "homepage": "https://github.com/joinsutra/mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joinsutra/mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joinsutra/mcp-server/issues"
+  }
+}

package/src/client.js

@@ -0,0 +1,66 @@
+const BASE_URL = "https://api.sutra.co/api/admin/v1";
+
+export class SutraAdminClient {
+  constructor(apiToken, baseUrl) {
+    this.apiToken = apiToken;
+    this.baseUrl = (baseUrl || BASE_URL).replace(/\/+$/, "");
+  }
+
+  async request(method, path, { params, body, headers: extra } = {}) {
+    const url = new URL(`${this.baseUrl}${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 ${this.apiToken}`,
+      Accept: "application/json",
+      ...(body ? { "Content-Type": "application/json" } : {}),
+      ...extra,
+    };
+
+    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) : {};
+  }
+
+  get(path, params) {
+    return this.request("GET", path, { params });
+  }
+
+  post(path, body, headers) {
+    return this.request("POST", path, { body, headers });
+  }
+
+  patch(path, body, headers) {
+    return this.request("PATCH", path, { body, headers });
+  }
+
+  delete(path, headers) {
+    return this.request("DELETE", path, { headers });
+  }
+
+  async getAll(path, params = {}, maxItems = 500) {
+    const items = [];
+    let cursor = undefined;
+    while (items.length < maxItems) {
+      const res = await this.get(path, { ...params, limit: 100, cursor });
+      const data = res.data || [];
+      items.push(...data);
+      if (!res.pagination?.has_more || !res.pagination?.next_cursor) break;
+      cursor = res.pagination.next_cursor;
+    }
+    return items.slice(0, maxItems);
+  }
+}

package/src/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { SutraAdminClient } from "./client.js";
+import { registerSpaceTools } from "./tools/spaces.js";
+import { registerMemberTools } from "./tools/members.js";
+import { registerContentTools } from "./tools/content.js";
+import { registerPropertyTools } from "./tools/properties.js";
+import { registerInvitationTools } from "./tools/invitations.js";
+import { registerSurveyTools } from "./tools/surveys.js";
+import { registerPlanTools } from "./tools/plans.js";
+import { registerCouponTools } from "./tools/coupons.js";
+import { registerBroadcastTools } from "./tools/broadcasts.js";
+import { registerDeepTool } from "./tools/deep.js";
+
+const SUTRA_API_TOKEN = process.env.SUTRA_API_TOKEN;
+const SUTRA_BASE_URL = process.env.SUTRA_BASE_URL;
+
+if (!SUTRA_API_TOKEN) {
+  console.error(
+    "SUTRA_API_TOKEN is required.\n\n" +
+    "Set it to your Sutra Admin API token (sutra_live_sk_...).\n" +
+    "Get one from your Sutra account settings or contact support@sutra.co.\n"
+  );
+  process.exit(1);
+}
+
+const server = new McpServer({
+  name: "sutra",
+  version: "1.0.0",
+  description:
+    "Sutra Admin API — manage spaces, members, content, discussions, surveys, plans, broadcasts, and more.",
+});
+
+const client = new SutraAdminClient(SUTRA_API_TOKEN, SUTRA_BASE_URL);
+
+registerSpaceTools(server, client);
+registerMemberTools(server, client);
+registerContentTools(server, client);
+registerPropertyTools(server, client);
+registerInvitationTools(server, client);
+registerSurveyTools(server, client);
+registerPlanTools(server, client);
+registerCouponTools(server, client);
+registerBroadcastTools(server, client);
+registerDeepTool(server, client);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Sutra MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});

package/src/tools/broadcasts.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+
+export function registerBroadcastTools(server, client) {
+  server.tool(
+    "list_broadcasts",
+    "List broadcasts for a space. Broadcasts are mass communications sent to space members.",
+    {
+      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}/broadcasts`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_broadcast",
+    "Get a single broadcast by ID.",
+    {
+      broadcast_id: z.string().describe("Broadcast ID (bcst_...)"),
+    },
+    async ({ broadcast_id }) => {
+      const data = await client.get(`/broadcasts/${broadcast_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_broadcast",
+    "Create a draft broadcast for a space. Use send_broadcast to actually send it.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      title: z.string().optional().describe("Broadcast title/subject"),
+      content: z.any().optional().describe("Broadcast content (rich text or plain)"),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/broadcasts`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_broadcast",
+    "Update a draft broadcast before sending.",
+    {
+      broadcast_id: z.string().describe("Broadcast ID (bcst_...)"),
+      title: z.string().optional(),
+      content: z.any().optional(),
+    },
+    async ({ broadcast_id, ...body }) => {
+      const data = await client.patch(`/broadcasts/${broadcast_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_broadcast",
+    "Delete a broadcast.",
+    {
+      broadcast_id: z.string().describe("Broadcast ID (bcst_...)"),
+    },
+    async ({ broadcast_id }) => {
+      const data = await client.delete(`/broadcasts/${broadcast_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "send_broadcast",
+    "Send a broadcast to space members. This is irreversible. Requires broadcasts:send scope and an Idempotency-Key.",
+    {
+      broadcast_id: z.string().describe("Broadcast ID (bcst_...)"),
+      idempotency_key: z.string().describe("Unique key for this send operation"),
+    },
+    async ({ broadcast_id, idempotency_key }) => {
+      const data = await client.post(
+        `/broadcasts/${broadcast_id}/send`,
+        {},
+        { "Idempotency-Key": idempotency_key }
+      );
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_broadcast_delivery_status",
+    "Check delivery status of a sent broadcast.",
+    {
+      broadcast_id: z.string().describe("Broadcast ID (bcst_...)"),
+    },
+    async ({ broadcast_id }) => {
+      const data = await client.get(`/broadcasts/${broadcast_id}/delivery_status`);
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/content.js

@@ -0,0 +1,228 @@
+import { z } from "zod";
+
+export function registerContentTools(server, client) {
+  // --- Content Blocks ---
+
+  server.tool(
+    "list_content",
+    "List content blocks in a space. Content blocks are the structured content that facilitators create on space pages.",
+    {
+      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}/content`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_content_block",
+    "Get a single content block by its ID.",
+    {
+      block_id: z.string().describe("Content block ID (blk_...)"),
+    },
+    async ({ block_id }) => {
+      const data = await client.get(`/content/${block_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_content",
+    "Create a content block in a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      content: z.any().optional().describe("Rich text content (Tiptap JSON object)"),
+      raw_content: z.string().optional().describe("Plain text content"),
+      message_body: z.string().optional().describe("Message body text"),
+      priority: z.number().optional().describe("Sort order priority"),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/content`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_content",
+    "Update a content block.",
+    {
+      block_id: z.string().describe("Content block ID (blk_...)"),
+      content: z.any().optional().describe("Rich text content (Tiptap JSON)"),
+      raw_content: z.string().optional().describe("Plain text content"),
+      priority: z.number().optional().describe("Sort order priority"),
+    },
+    async ({ block_id, ...body }) => {
+      const data = await client.patch(`/content/${block_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_content",
+    "Delete a content block.",
+    {
+      block_id: z.string().describe("Content block ID (blk_...)"),
+    },
+    async ({ block_id }) => {
+      const data = await client.delete(`/content/${block_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "reorder_content",
+    "Reorder content blocks within a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      block_ids: z.array(z.string()).describe("Ordered array of content block IDs (blk_...)"),
+    },
+    async ({ space_id, block_ids }) => {
+      const data = await client.patch(`/spaces/${space_id}/content/reorder`, { block_ids });
+      return json(data);
+    }
+  );
+
+  // --- Messages (discussion posts) ---
+
+  server.tool(
+    "list_messages",
+    "List discussion messages in a space. Messages are top-level discussion posts that members create.",
+    {
+      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}/messages`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_message",
+    "Get a single message by its ID.",
+    {
+      message_id: z.string().describe("Message ID (blk_...)"),
+    },
+    async ({ message_id }) => {
+      const data = await client.get(`/messages/${message_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_message",
+    "Create a discussion message in a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      content: z.any().optional().describe("Rich text content (Tiptap JSON)"),
+      raw_content: z.string().optional().describe("Plain text content"),
+      message_body: z.string().optional().describe("Message body text"),
+    },
+    async ({ space_id, ...body }) => {
+      const data = await client.post(`/spaces/${space_id}/messages`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_message",
+    "Update a discussion message.",
+    {
+      message_id: z.string().describe("Message ID (blk_...)"),
+      content: z.any().optional().describe("Rich text content (Tiptap JSON)"),
+      raw_content: z.string().optional().describe("Plain text content"),
+    },
+    async ({ message_id, ...body }) => {
+      const data = await client.patch(`/messages/${message_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_message",
+    "Delete a discussion message.",
+    {
+      message_id: z.string().describe("Message ID (blk_...)"),
+    },
+    async ({ message_id }) => {
+      const data = await client.delete(`/messages/${message_id}`);
+      return json(data);
+    }
+  );
+
+  // --- Reflections (replies to messages) ---
+
+  server.tool(
+    "list_reflections",
+    "List reflections (threaded replies) on a message.",
+    {
+      message_id: z.string().describe("Message ID (blk_...)"),
+      limit: z.number().optional().describe("Max results (default 25)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ message_id, limit, cursor }) => {
+      const data = await client.get(`/messages/${message_id}/reflections`, { limit, cursor });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_reflection",
+    "Get a single reflection by its ID.",
+    {
+      reflection_id: z.string().describe("Reflection ID (reply_...)"),
+    },
+    async ({ reflection_id }) => {
+      const data = await client.get(`/reflections/${reflection_id}`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "create_reflection",
+    "Create a reflection (reply) on a message.",
+    {
+      message_id: z.string().describe("Message ID (blk_...)"),
+      content: z.any().optional().describe("Rich text content (Tiptap JSON)"),
+      raw_content: z.string().optional().describe("Plain text content"),
+    },
+    async ({ message_id, ...body }) => {
+      const data = await client.post(`/messages/${message_id}/reflections`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "update_reflection",
+    "Update a reflection.",
+    {
+      reflection_id: z.string().describe("Reflection ID (reply_...)"),
+      content: z.any().optional().describe("Rich text content (Tiptap JSON)"),
+      raw_content: z.string().optional().describe("Plain text content"),
+    },
+    async ({ reflection_id, ...body }) => {
+      const data = await client.patch(`/reflections/${reflection_id}`, body);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "delete_reflection",
+    "Delete a reflection.",
+    {
+      reflection_id: z.string().describe("Reflection ID (reply_...)"),
+    },
+    async ({ reflection_id }) => {
+      const data = await client.delete(`/reflections/${reflection_id}`);
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}