@sutraspaces/mcp-server 1.0.0 → 1.0.1

package/README.md

@@ -5,13 +5,13 @@ An [MCP](https://modelcontextprotocol.io) server that connects AI agents to the
 ## Quick Start
 
 ```bash
-npm install
+npm install -g @sutraspaces/mcp-server
 ```
 
-Set your Sutra API token:
+Or run directly with npx:
 
 ```bash
-export SUTRA_API_TOKEN="sutra_live_sk_..."
+SUTRA_API_TOKEN="sutra_live_sk_..." npx -y @sutraspaces/mcp-server
 ```
 
 You can get an API token from your Sutra account settings or by contacting support@sutra.co.
@@ -26,8 +26,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 {
   "mcpServers": {
     "sutra": {
-      "command": "node",
-      "args": ["/path/to/sutra-mcp/src/index.js"],
+      "command": "npx",
+      "args": ["-y", "@sutraspaces/mcp-server"],
       "env": {
         "SUTRA_API_TOKEN": "sutra_live_sk_..."
       }
@@ -39,12 +39,12 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 ### Claude Code
 
 ```bash
-claude mcp add sutra -- env SUTRA_API_TOKEN=sutra_live_sk_... node /path/to/sutra-mcp/src/index.js
+claude mcp add sutra -- env SUTRA_API_TOKEN=sutra_live_sk_... npx -y @sutraspaces/mcp-server
 ```
 
 ### 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.
+Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TOKEN` environment variable set. The server communicates over stdio.
 
 ## Configuration
 
@@ -123,6 +123,14 @@ Point your MCP client at the server entry point with the `SUTRA_API_TOKEN` envir
 
 **Pagination** is cursor-based. List endpoints return `{ data, pagination: { next_cursor, has_more } }`. Pass `cursor` to get the next page.
 
+**Filtering & Search** — most list endpoints accept optional query parameters to narrow results:
+- `q` — case-insensitive text search (spaces by name, members by name/email, surveys/broadcasts/plans by title/name, coupons by code)
+- `state` / `status` — exact-match enum filters (e.g. `state=active` for spaces, `status=sent` for broadcasts)
+- `role` — filter members or invitations by role
+- `type` / `privacy` / `frequency` — filter by type, privacy level, or billing frequency
+- `user_id` — filter messages or payments by author/user
+- `email` — filter invitations by email (requires `members.email:read` scope)
+
 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sutraspaces/mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for the Sutra Admin API — manage spaces, members, content, and more via AI agents",
   "type": "module",
   "main": "src/index.js",

package/src/tools/broadcasts.js

@@ -3,14 +3,16 @@ 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.",
+    "List broadcasts for a space. Broadcasts are mass communications sent to space members. Use `q` to search by title.",
     {
       space_id: z.string().describe("Space ID (sp_...)"),
       limit: z.number().optional().describe("Max results (default 25)"),
       cursor: z.string().optional().describe("Pagination cursor"),
+      q: z.string().optional().describe("Search broadcasts by title (case-insensitive)"),
+      status: z.enum(["draft", "scheduled", "sent"]).optional().describe("Filter by status"),
     },
-    async ({ space_id, limit, cursor }) => {
-      const data = await client.get(`/spaces/${space_id}/broadcasts`, { limit, cursor });
+    async ({ space_id, limit, cursor, q, status }) => {
+      const data = await client.get(`/spaces/${space_id}/broadcasts`, { limit, cursor, q, status });
       return json(data);
     }
   );

package/src/tools/content.js

@@ -89,14 +89,15 @@ export function registerContentTools(server, client) {
 
   server.tool(
     "list_messages",
-    "List discussion messages in a space. Messages are top-level discussion posts that members create.",
+    "List discussion messages in a space. Messages are top-level discussion posts that members create. Filter by author with user_id.",
     {
       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 author user ID (usr_...)"),
     },
-    async ({ space_id, limit, cursor }) => {
-      const data = await client.get(`/spaces/${space_id}/messages`, { limit, cursor });
+    async ({ space_id, limit, cursor, user_id }) => {
+      const data = await client.get(`/spaces/${space_id}/messages`, { limit, cursor, user_id });
       return json(data);
     }
   );

package/src/tools/coupons.js

@@ -3,14 +3,16 @@ import { z } from "zod";
 export function registerCouponTools(server, client) {
   server.tool(
     "list_coupons",
-    "List coupons for a space.",
+    "List coupons for a space. Use `q` to search by coupon code.",
     {
       space_id: z.string().describe("Space ID (sp_...)"),
       limit: z.number().optional().describe("Max results (default 25)"),
       cursor: z.string().optional().describe("Pagination cursor"),
+      q: z.string().optional().describe("Search coupons by code (case-insensitive)"),
+      status: z.string().optional().describe("Filter by coupon status"),
     },
-    async ({ space_id, limit, cursor }) => {
-      const data = await client.get(`/spaces/${space_id}/coupons`, { limit, cursor });
+    async ({ space_id, limit, cursor, q, status }) => {
+      const data = await client.get(`/spaces/${space_id}/coupons`, { limit, cursor, q, status });
       return json(data);
     }
   );

package/src/tools/invitations.js

@@ -3,14 +3,17 @@ import { z } from "zod";
 export function registerInvitationTools(server, client) {
   server.tool(
     "list_invitations",
-    "List invitations for a space.",
+    "List invitations for a space. Filter by email, state, or role.",
     {
       space_id: z.string().describe("Space ID (sp_...)"),
       limit: z.number().optional().describe("Max results (default 25)"),
       cursor: z.string().optional().describe("Pagination cursor"),
+      email: z.string().optional().describe("Search by email (case-insensitive, requires members.email:read scope)"),
+      state: z.enum(["pending", "accepted", "declined"]).optional().describe("Filter by invitation state"),
+      role: z.enum(["member", "editor", "moderator"]).optional().describe("Filter by role"),
     },
-    async ({ space_id, limit, cursor }) => {
-      const data = await client.get(`/spaces/${space_id}/invitations`, { limit, cursor });
+    async ({ space_id, limit, cursor, email, state, role }) => {
+      const data = await client.get(`/spaces/${space_id}/invitations`, { limit, cursor, email, state, role });
       return json(data);
     }
   );

package/src/tools/members.js

@@ -3,16 +3,19 @@ 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.",
+    "List members of a space. Returns member IDs (mem_...), user info, roles, and states. Use `q` to search by name or email.",
     {
       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)"),
+      q: z.string().optional().describe("Search by member name or email (case-insensitive)"),
+      role: z.enum(["member", "editor", "moderator"]).optional().describe("Filter by role"),
+      state: z.enum(["active", "pending"]).optional().describe("Filter by state"),
     },
-    async ({ space_id, limit, cursor, user_id, email }) => {
-      const data = await client.get(`/spaces/${space_id}/members`, { limit, cursor, user_id, email });
+    async ({ space_id, limit, cursor, user_id, email, q, role, state }) => {
+      const data = await client.get(`/spaces/${space_id}/members`, { limit, cursor, user_id, email, q, role, state });
       return json(data);
     }
   );

package/src/tools/plans.js

@@ -5,14 +5,17 @@ export function registerPlanTools(server, client) {
 
   server.tool(
     "list_plans",
-    "List plans (offerings) for a space. Plans describe what can be purchased or enrolled in.",
+    "List plans (offerings) for a space. Plans describe what can be purchased or enrolled in. Use `q` to search by name.",
     {
       space_id: z.string().describe("Space ID (sp_...)"),
       limit: z.number().optional().describe("Max results (default 25)"),
       cursor: z.string().optional().describe("Pagination cursor"),
+      q: z.string().optional().describe("Search plans by name (case-insensitive)"),
+      status: z.string().optional().describe("Filter by status"),
+      frequency: z.string().optional().describe("Filter by billing frequency"),
     },
-    async ({ space_id, limit, cursor }) => {
-      const data = await client.get(`/spaces/${space_id}/plans`, { limit, cursor });
+    async ({ space_id, limit, cursor, q, status, frequency }) => {
+      const data = await client.get(`/spaces/${space_id}/plans`, { limit, cursor, q, status, frequency });
       return json(data);
     }
   );
@@ -101,14 +104,16 @@ export function registerPlanTools(server, client) {
 
   server.tool(
     "list_payments",
-    "List payments for a space.",
+    "List payments for a space. Filter by user or status.",
     {
       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_...)"),
+      status: z.string().optional().describe("Filter by payment status"),
     },
-    async ({ space_id, limit, cursor }) => {
-      const data = await client.get(`/spaces/${space_id}/payments`, { limit, cursor });
+    async ({ space_id, limit, cursor, user_id, status }) => {
+      const data = await client.get(`/spaces/${space_id}/payments`, { limit, cursor, user_id, status });
       return json(data);
     }
   );

package/src/tools/spaces.js

@@ -3,13 +3,17 @@ 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.",
+    "List all spaces the API token can access. Returns space IDs (sp_...), names, types, and states. Use `q` to search by name.",
     {
       limit: z.number().optional().describe("Max results per page (default 25, max 100)"),
       cursor: z.string().optional().describe("Pagination cursor from a previous response"),
+      q: z.string().optional().describe("Search spaces by name (case-insensitive)"),
+      state: z.enum(["active", "archived"]).optional().describe("Filter by state"),
+      type: z.string().optional().describe("Filter by type (e.g. content, forum)"),
+      privacy: z.enum(["open", "closed", "secret"]).optional().describe("Filter by privacy level"),
     },
-    async ({ limit, cursor }) => {
-      const data = await client.get("/spaces", { limit, cursor });
+    async ({ limit, cursor, q, state, type, privacy }) => {
+      const data = await client.get("/spaces", { limit, cursor, q, state, type, privacy });
       return json(data);
     }
   );

package/src/tools/surveys.js

@@ -3,14 +3,16 @@ import { z } from "zod";
 export function registerSurveyTools(server, client) {
   server.tool(
     "list_surveys",
-    "List surveys in a space.",
+    "List surveys in a space. Use `q` to search by title.",
     {
       space_id: z.string().describe("Space ID (sp_...)"),
       limit: z.number().optional().describe("Max results (default 25)"),
       cursor: z.string().optional().describe("Pagination cursor"),
+      q: z.string().optional().describe("Search surveys by title (case-insensitive)"),
+      type: z.string().optional().describe("Filter by survey type"),
     },
-    async ({ space_id, limit, cursor }) => {
-      const data = await client.get(`/spaces/${space_id}/surveys`, { limit, cursor });
+    async ({ space_id, limit, cursor, q, type }) => {
+      const data = await client.get(`/spaces/${space_id}/surveys`, { limit, cursor, q, type });
       return json(data);
     }
   );