@sutraspaces/mcp-server 1.0.1 → 1.1.2

package/src/tools/help-center.js

@@ -0,0 +1,498 @@
+import { z } from "zod";
+
+const HELP_BASE_URL = process.env.SUTRA_HELP_CENTER_BASE_URL || "https://api.sutra.co/api/v4/lotus/help";
+
+async function getImageDimensions(url) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok) return null;
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf[0] === 0x89 && buf[1] === 0x50) {
+      // PNG: width at bytes 16-19, height at 20-23
+      return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+    }
+    if (buf[0] === 0xFF && buf[1] === 0xD8) {
+      // JPEG: scan for SOF markers
+      let offset = 2;
+      while (offset < buf.length - 8) {
+        if (buf[offset] !== 0xFF) break;
+        const marker = buf[offset + 1];
+        const len = buf.readUInt16BE(offset + 2);
+        if (marker >= 0xC0 && marker <= 0xCF && marker !== 0xC4 && marker !== 0xC8) {
+          return { width: buf.readUInt16BE(offset + 7), height: buf.readUInt16BE(offset + 5) };
+        }
+        offset += 2 + len;
+      }
+    }
+    if (buf.slice(0, 4).toString() === "GIF8") {
+      return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+    }
+    if (buf.slice(0, 4).toString() === "RIFF" && buf.slice(8, 12).toString() === "WEBP") {
+      if (buf.slice(12, 16).toString() === "VP8 ") {
+        return { width: buf.readUInt16LE(26) & 0x3FFF, height: buf.readUInt16LE(28) & 0x3FFF };
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function imageWidthForDimensions(dims) {
+  if (!dims) return "100%";
+  return dims.width >= dims.height ? "100%" : "60%";
+}
+
+async function normalizeGleapContent(doc) {
+  if (!doc || typeof doc !== "object") return doc;
+  const nodes = doc.content;
+  if (!Array.isArray(nodes)) return doc;
+  const normalized = nodes.flatMap(normalizeNode);
+  await resolveImageWidths(normalized);
+  return { ...doc, content: normalized };
+}
+
+async function resolveImageWidths(nodes) {
+  const imageNodes = [];
+  function collect(list) {
+    for (const node of list) {
+      if (node.type === "image" && node.attrs?.src && node.attrs?._needsResize) {
+        imageNodes.push(node);
+      }
+      if (node.content && Array.isArray(node.content)) collect(node.content);
+    }
+  }
+  collect(nodes);
+  await Promise.all(imageNodes.map(async (node) => {
+    const dims = await getImageDimensions(node.attrs.src);
+    const w = imageWidthForDimensions(dims);
+    node.attrs.resizeableWidth = w;
+    delete node.attrs._needsResize;
+    delete node.attrs.style;
+  }));
+}
+
+function normalizeNode(node) {
+  if (!node || typeof node !== "object") return [node];
+
+  if (node.type === "callout") {
+    const children = Array.isArray(node.content) ? node.content : [];
+    const textNodes = [];
+    const blockNodes = [];
+    for (const child of children) {
+      if (child.type === "text") textNodes.push(child);
+      else if (child.type === "paragraph") blockNodes.push(child);
+      else blockNodes.push(child);
+    }
+    const paragraphs = [];
+    if (textNodes.length) paragraphs.push({ type: "paragraph", attrs: { textAlign: "left" }, content: textNodes });
+    paragraphs.push(...blockNodes);
+    return [{
+      type: "infobox",
+      attrs: {
+        customSpacing: true,
+        icon: "info",
+        iconColor: "#364fc7",
+        badgeBgColor: "rgba(255,255,255,0.6)",
+        iconPosition: "left",
+        iconVerticalAlign: "top",
+        badgeShape: "circle",
+        badgeSize: 40,
+        iconSize: 20,
+        iconOffset: 18,
+        iconVerticalOffset: 18,
+        contentOffset: 70,
+        contentVerticalOffset: 20,
+        styles: {
+          "margin-top": "0px",
+          "margin-bottom": "0px",
+          "margin-left": "0px",
+          "margin-right": "0px",
+          "padding-top": "15px",
+          "padding-bottom": "10px",
+          "padding-left": "0px",
+          "padding-right": "0px",
+        },
+      },
+      content: [{
+        type: "column",
+        attrs: {
+          size: 12,
+          position: 0,
+          radius: "with-radius",
+          styles: {
+            "align-items": "flex-start",
+            "background-color": "#dbe4ff",
+            "background-image": "none",
+            "background-position": "center center",
+            "background-size": "cover",
+            "background-repeat": "no-repeat",
+            "margin-top": "0px",
+            "margin-bottom": "0px",
+            "margin-left": "0px",
+            "margin-right": "0px",
+            "padding-top": "20px",
+            "padding-bottom": "20px",
+            "padding-left": "70px",
+            "padding-right": "20px",
+          },
+          flexLayout: "stack",
+          flexGap: 0,
+          nestedRadius: "no-radius",
+        },
+        content: paragraphs.length ? paragraphs : [{ type: "paragraph", attrs: { textAlign: "left" } }],
+      }],
+    }];
+  }
+
+  if (node.type === "editor-button") {
+    const label = node.content?.[0]?.text || "Button";
+    const href = node.attrs?.href || "#";
+    return [{
+      type: "paragraph",
+      attrs: { textAlign: "left" },
+      content: [{
+        type: "text",
+        marks: [{ type: "link", attrs: { href, target: "_blank", rel: "noopener noreferrer nofollow" } }, { type: "bold" }],
+        text: `👉 ${label}`,
+      }],
+    }];
+  }
+
+  if (node.type === "imageBlock") {
+    return [{
+      type: "image",
+      attrs: {
+        src: node.attrs?.src,
+        alt: node.attrs?.alt || null,
+        textAlign: "center",
+        _needsResize: true,
+      },
+    }];
+  }
+
+  if (node.type === "image" && node.attrs?.src) {
+    return [{
+      ...node,
+      attrs: { ...node.attrs, _needsResize: true },
+    }];
+  }
+
+  if (node.type === "heading") {
+    const level = node.attrs?.level || 1;
+    const paddingTop = { 1: "32px", 2: "20px", 3: "16px", 4: "12px", 5: "10px", 6: "8px" };
+    const styles = {
+      "margin-top": "0px", "margin-bottom": "0px", "margin-left": "0px", "margin-right": "0px",
+      "padding-top": paddingTop[level] || "20px", "padding-bottom": "0px",
+      "padding-left": "0px", "padding-right": "0px",
+      "font-size": "", "line-height": "", "font-family": "",
+      ...(node.attrs?.styles || {}),
+    };
+    if (!node.attrs?.styles?.["padding-top"]) styles["padding-top"] = paddingTop[level] || "20px";
+    return [{ ...node, attrs: { ...node.attrs, styles } }];
+  }
+
+  if (node.content && Array.isArray(node.content)) {
+    return [{ ...node, content: node.content.flatMap(normalizeNode) }];
+  }
+
+  return [node];
+}
+
+export function registerHelpCenterTools(server) {
+  const token = process.env.SUTRA_HELP_CENTER_TOKEN;
+  if (!token) return;
+
+  async function request(method, path, { params, body } = {}) {
+    const url = new URL(`${HELP_BASE_URL}${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 ${token}`,
+      Accept: "application/json",
+      ...(body ? { "Content-Type": "application/json" } : {}),
+    };
+    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) : {};
+  }
+
+  // --- Articles ---
+
+  server.tool(
+    "help_list_articles",
+    "List Help Center articles with optional filters. Returns article summaries and stats.",
+    {
+      status: z.enum(["draft", "published", "archived"]).optional().describe("Filter by status"),
+      review_status: z.string().optional().describe("Filter by review status"),
+      collection_id: z.number().optional().describe("Filter by collection ID"),
+      product_area: z.string().optional().describe("Filter by product area"),
+      intent_type: z.string().optional().describe("Filter by intent type"),
+      q: z.string().optional().describe("Search title and excerpt"),
+    },
+    async (params) => {
+      const data = await request("GET", "/articles.json", { params });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_get_article",
+    "Get a Help Center article with full content, metadata, and version history.",
+    {
+      id: z.number().describe("Article ID"),
+    },
+    async ({ id }) => {
+      const data = await request("GET", `/articles/${id}.json`);
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_create_article",
+    "Create a new Help Center article. Returns the article and its first version.",
+    {
+      title: z.string().describe("Article title"),
+      slug: z.string().optional().describe("URL slug (auto-generated from title if omitted)"),
+      excerpt: z.string().optional().describe("Short description/excerpt"),
+      help_collection_id: z.number().optional().describe("Collection ID to place article in"),
+      product_area: z.string().optional().describe("Product area tag"),
+      intent_type: z.string().optional().describe("Intent type tag"),
+      subsection: z.string().optional().describe("Subsection within collection"),
+      position: z.number().optional().describe("Sort position within collection"),
+      status: z.enum(["draft", "published", "archived"]).optional().describe("Initial status (default: draft)"),
+      content: z.any().optional().describe("Tiptap JSON content"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      meta_title: z.string().optional().describe("SEO meta title"),
+      meta_description: z.string().optional().describe("SEO meta description"),
+      og_image_url: z.string().optional().describe("Open Graph image URL"),
+      heading_font: z.string().optional().describe("Heading font family"),
+      body_font: z.string().optional().describe("Body font family"),
+      audience: z.array(z.string()).optional().describe("Target audience tags"),
+      applies_to_plan: z.array(z.string()).optional().describe("Applicable plan tiers (basic, bronze, silver, gold)"),
+      alternate_phrasings: z.array(z.string()).optional().describe("Alternate search phrasings"),
+      publish: z.boolean().optional().describe("Publish immediately after creation"),
+    },
+    async (params) => {
+      const { publish, ...articleFields } = params;
+      if (articleFields.content) articleFields.content = await normalizeGleapContent(articleFields.content);
+      const data = await request("POST", "/articles.json", {
+        body: { article: articleFields, publish },
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_propose_article",
+    "Submit an AI-authored Help Center article draft for human review. Creates an ai_cobolt version and marks the article as AI changes pending.",
+    {
+      title: z.string().describe("Article title"),
+      content: z.any().describe("Tiptap JSON content"),
+      slug: z.string().optional().describe("URL slug (auto-generated from title if omitted)"),
+      excerpt: z.string().optional().describe("Short description/excerpt"),
+      help_collection_id: z.number().optional().describe("Collection ID to place article in; omitted uses Untriaged AI Drafts"),
+      product_area: z.string().optional().describe("Product area tag"),
+      intent_type: z.string().optional().describe("Intent type tag"),
+      subsection: z.string().optional().describe("Subsection within collection"),
+      position: z.number().optional().describe("Sort position within collection"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      meta_title: z.string().optional().describe("SEO meta title"),
+      meta_description: z.string().optional().describe("SEO meta description"),
+      og_image_url: z.string().optional().describe("Open Graph image URL"),
+      heading_font: z.string().optional().describe("Heading font family"),
+      body_font: z.string().optional().describe("Body font family"),
+      audience: z.array(z.string()).optional().describe("Target audience tags"),
+      applies_to_plan: z.array(z.string()).optional().describe("Applicable plan tiers (basic, bronze, silver, gold)"),
+      alternate_phrasings: z.array(z.string()).optional().describe("Alternate search phrasings"),
+      ai_agent_id: z.string().optional().describe("Identifier for the AI agent submitting the draft"),
+      source_signal: z.record(z.any()).optional().describe("Evidence or trigger that led to this draft"),
+    },
+    async ({ ai_agent_id, source_signal, ...articleFields }) => {
+      if (articleFields.content) articleFields.content = await normalizeGleapContent(articleFields.content);
+      const data = await request("POST", "/articles/propose.json", {
+        body: { article: articleFields, ai_agent_id, source_signal },
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_update_article",
+    "Update an existing Help Center article and create a new version.",
+    {
+      id: z.number().describe("Article ID"),
+      title: z.string().optional().describe("Article title"),
+      slug: z.string().optional().describe("URL slug"),
+      excerpt: z.string().optional().describe("Short description/excerpt"),
+      help_collection_id: z.number().optional().describe("Collection ID"),
+      product_area: z.string().optional().describe("Product area tag"),
+      intent_type: z.string().optional().describe("Intent type tag"),
+      subsection: z.string().optional().describe("Subsection within collection"),
+      position: z.number().optional().describe("Sort position"),
+      status: z.string().optional().describe("Status (draft/published/archived)"),
+      content: z.any().optional().describe("Tiptap JSON content"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      meta_title: z.string().optional().describe("SEO meta title"),
+      meta_description: z.string().optional().describe("SEO meta description"),
+      og_image_url: z.string().optional().describe("Open Graph image URL"),
+      heading_font: z.string().optional().describe("Heading font family"),
+      body_font: z.string().optional().describe("Body font family"),
+      audience: z.array(z.string()).optional().describe("Target audience tags"),
+      applies_to_plan: z.array(z.string()).optional().describe("Applicable plan tiers (basic, bronze, silver, gold)"),
+      alternate_phrasings: z.array(z.string()).optional().describe("Alternate search phrasings"),
+      publish: z.boolean().optional().describe("Publish this version immediately"),
+    },
+    async ({ id, publish, ...articleFields }) => {
+      if (articleFields.content) articleFields.content = await normalizeGleapContent(articleFields.content);
+      const data = await request("PUT", `/articles/${id}.json`, {
+        body: { article: articleFields, publish },
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_propose_article_update",
+    "Submit AI-authored changes to an existing Help Center article for human review. Creates an ai_cobolt pending version without publishing it.",
+    {
+      id: z.number().describe("Article ID"),
+      title: z.string().optional().describe("Proposed article title"),
+      slug: z.string().optional().describe("Proposed URL slug"),
+      excerpt: z.string().optional().describe("Proposed short description/excerpt"),
+      help_collection_id: z.number().optional().describe("Proposed collection ID"),
+      product_area: z.string().optional().describe("Proposed product area tag"),
+      intent_type: z.string().optional().describe("Proposed intent type tag"),
+      subsection: z.string().optional().describe("Proposed subsection within collection"),
+      position: z.number().optional().describe("Proposed sort position"),
+      content: z.any().optional().describe("Proposed Tiptap JSON content; omit for metadata-only proposals"),
+      commit_message: z.string().optional().describe("Version commit message"),
+      meta_title: z.string().optional().describe("Proposed SEO meta title"),
+      meta_description: z.string().optional().describe("Proposed SEO meta description"),
+      og_image_url: z.string().optional().describe("Proposed Open Graph image URL"),
+      heading_font: z.string().optional().describe("Proposed heading font family"),
+      body_font: z.string().optional().describe("Proposed body font family"),
+      audience: z.array(z.string()).optional().describe("Proposed target audience tags"),
+      applies_to_plan: z.array(z.string()).optional().describe("Proposed applicable plan tiers (basic, bronze, silver, gold)"),
+      alternate_phrasings: z.array(z.string()).optional().describe("Proposed alternate search phrasings"),
+      ai_agent_id: z.string().optional().describe("Identifier for the AI agent submitting the proposal"),
+      source_signal: z.record(z.any()).optional().describe("Evidence or trigger that led to this update"),
+    },
+    async ({ id, ai_agent_id, source_signal, ...articleFields }) => {
+      if (articleFields.content) articleFields.content = await normalizeGleapContent(articleFields.content);
+      const data = await request("POST", `/articles/${id}/propose_update.json`, {
+        body: { article: articleFields, ai_agent_id, source_signal },
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_publish_article",
+    "Publish a Help Center article version. Publishes the latest version if no version_id is given.",
+    {
+      id: z.number().describe("Article ID"),
+      version_id: z.number().optional().describe("Specific version ID to publish (defaults to latest)"),
+    },
+    async ({ id, version_id }) => {
+      const data = await request("POST", `/articles/${id}/publish.json`, {
+        body: version_id ? { version_id } : {},
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_review_article",
+    "Approve or reject a pending Help Center article version.",
+    {
+      id: z.number().describe("Article ID"),
+      version_id: z.number().describe("Version ID to review"),
+      decision: z.enum(["approve", "reject"]).describe("Review decision"),
+      comment: z.string().optional().describe("Review comment"),
+    },
+    async ({ id, ...body }) => {
+      const data = await request("POST", `/articles/${id}/review.json`, { body });
+      return json(data);
+    }
+  );
+
+  // --- Collections ---
+
+  server.tool(
+    "help_list_collections",
+    "List all Help Center collections (categories).",
+    {},
+    async () => {
+      const data = await request("GET", "/collections.json");
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_create_collection",
+    "Create a new Help Center collection.",
+    {
+      name: z.string().describe("Collection name"),
+      slug: z.string().optional().describe("URL slug"),
+      description: z.string().optional().describe("Collection description"),
+      icon_library: z.string().optional().describe("Icon library name"),
+      icon_name: z.string().optional().describe("Icon name"),
+      icon_color: z.string().optional().describe("Icon color hex"),
+      position: z.number().optional().describe("Sort position"),
+      published: z.boolean().optional().describe("Whether collection is published"),
+    },
+    async (params) => {
+      const data = await request("POST", "/collections.json", {
+        body: { collection: params },
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_update_collection",
+    "Update a Help Center collection.",
+    {
+      id: z.number().describe("Collection ID"),
+      name: z.string().optional().describe("Collection name"),
+      slug: z.string().optional().describe("URL slug"),
+      description: z.string().optional().describe("Collection description"),
+      icon_library: z.string().optional().describe("Icon library name"),
+      icon_name: z.string().optional().describe("Icon name"),
+      icon_color: z.string().optional().describe("Icon color hex"),
+      position: z.number().optional().describe("Sort position"),
+      published: z.boolean().optional().describe("Whether collection is published"),
+    },
+    async ({ id, ...fields }) => {
+      const data = await request("PUT", `/collections/${id}.json`, {
+        body: { collection: fields },
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "help_delete_collection",
+    "Delete a Help Center collection. Archives it if it has articles, permanently deletes if empty.",
+    {
+      id: z.number().describe("Collection ID"),
+    },
+    async ({ id }) => {
+      const data = await request("DELETE", `/collections/${id}.json`);
+      return json(data);
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/media.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+const mediaPlacementSchema = z.object({
+  insert_node: z.boolean().optional().describe("Insert a placeholder node in the document (default true)"),
+  insert: z.enum(["append", "before", "after", "inside"]).optional(),
+  anchor_node_uid: z.string().optional(),
+}).optional();
+
+export function registerMediaTools(server, client) {
+  server.tool(
+    "create_media_upload",
+    "Create a Sutra media upload session for a local file. Upload bytes to the returned PUT URL, then call complete_media_upload.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+      filename: z.string().describe("Original filename"),
+      content_type: z.string().describe("MIME type, e.g. video/mp4"),
+      size_bytes: z.number().int().nonnegative().describe("File size in bytes"),
+      kind: z.enum(["video", "file", "audio", "image"]).optional().describe("Media kind (default video)"),
+      placement: mediaPlacementSchema,
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post(`/spaces/${space_id}/media_uploads`, body, headers));
+    }
+  );
+
+  server.tool(
+    "complete_media_upload",
+    "Complete an upload after bytes have been PUT to S3. Sutra verifies the object and queues processing for videos.",
+    {
+      media_id: z.string().describe("Media ID (media_...)"),
+      size_bytes: z.number().int().nonnegative().optional(),
+      etag: z.string().optional(),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ media_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post(`/media_uploads/${media_id}/complete`, body, headers));
+    }
+  );
+
+  server.tool(
+    "get_media_upload",
+    "Get upload and processing status for a media item.",
+    {
+      media_id: z.string().describe("Media ID (media_...)"),
+    },
+    async ({ media_id }) => json(await client.get(`/media_uploads/${media_id}`))
+  );
+
+  server.tool(
+    "cancel_media_upload",
+    "Cancel or abandon a pending media upload. This does not delete any uploaded S3 object.",
+    {
+      media_id: z.string().describe("Media ID (media_...)"),
+      remove_document_node: z.boolean().optional().describe("Remove the placeholder node when possible"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ media_id, remove_document_node, idempotency_key }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      const query = remove_document_node ? "?remove_document_node=true" : "";
+      return json(await client.delete(`/media_uploads/${media_id}${query}`, headers));
+    }
+  );
+
+  server.tool(
+    "create_media_reference",
+    "Insert an external media embed such as Loom, YouTube, or Vimeo into a Sutra document without creating an upload session.",
+    {
+      space_id: z.string().describe("Space ID (sp_...). Do not use a slug."),
+      url: z.string().min(1).describe("External media URL or iframe embed code from Loom, YouTube, or Vimeo"),
+      placement: mediaPlacementSchema,
+      base_revision: z.string().optional().describe("Optional document revision guard"),
+      idempotency_key: z.string().optional().describe("Idempotency-Key header for safe retries"),
+    },
+    async ({ space_id, idempotency_key, ...body }) => {
+      const headers = idempotency_key ? { "Idempotency-Key": idempotency_key } : undefined;
+      return json(await client.post(`/spaces/${space_id}/media_references`, body, headers));
+    }
+  );
+}
+
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}

package/src/tools/members.js

@@ -1,9 +1,19 @@
 import { z } from "zod";
 
 export function registerMemberTools(server, client) {
+  const propertyValueSchema = z.union([z.string(), z.number(), z.boolean()]).describe("Exact property value");
+  const propertyFilterSchema = z.object({
+    property_key: z.string().optional().describe("Property key or mprop_ ID"),
+    key: z.string().optional().describe("Property key"),
+    property_id: z.string().optional().describe("Property ID (mprop_...)"),
+    member_property_id: z.string().optional().describe("Property ID (mprop_...)"),
+    property_value: propertyValueSchema.optional(),
+    value: propertyValueSchema.optional(),
+  });
+
   server.tool(
     "list_members",
-    "List members of a space. Returns member IDs (mem_...), user info, roles, and states. Use `q` to search by name or email.",
+    "List members of a space. Returns member IDs (mem_...), user info, roles, and states. Use `q` to search by name or email. Use property_key/property_value or property_filters for custom property filtering.",
     {
       space_id: z.string().describe("Space ID (sp_...)"),
       limit: z.number().optional().describe("Max results (default 25)"),
@@ -13,9 +23,63 @@ export function registerMemberTools(server, client) {
       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"),
+      property_key: z.string().optional().describe("Filter by member property key or mprop_ ID (requires member_properties:read)"),
+      property_value: propertyValueSchema.optional().describe("Exact property value for property_key. Select values may use option names or option values."),
+      property_filters: z.array(propertyFilterSchema).optional().describe("Multiple property filters. Each filter needs a property key/ID and value."),
+    },
+    async ({ space_id, limit, cursor, user_id, email, q, role, state, property_key, property_value, property_filters }) => {
+      const data = await client.get(`/spaces/${space_id}/members`, {
+        limit,
+        cursor,
+        user_id,
+        email,
+        q,
+        role,
+        state,
+        property_key,
+        property_value,
+        property_filters: encodePropertyFilters(property_filters),
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "list_contacts",
+    "List CRM contacts in a space. Contacts are non-member people in the Contacts/Interested layer. Use property_key/property_value to filter by custom member properties.",
+    {
+      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("Filter by exact email (requires members.email:read scope)"),
+      q: z.string().optional().describe("Search by contact name, and by email when scoped"),
+      property_key: z.string().optional().describe("Filter by member property key or mprop_ ID (requires member_properties:read)"),
+      property_value: propertyValueSchema.optional().describe("Exact property value for property_key. Select values may use option names or option values."),
+      property_filters: z.array(propertyFilterSchema).optional().describe("Multiple property filters. Each filter needs a property key/ID and value."),
+    },
+    async ({ space_id, limit, cursor, email, q, property_key, property_value, property_filters }) => {
+      const data = await client.get(`/spaces/${space_id}/contacts`, {
+        limit,
+        cursor,
+        email,
+        q,
+        property_key,
+        property_value,
+        property_filters: encodePropertyFilters(property_filters),
+      });
+      return json(data);
+    }
+  );
+
+  server.tool(
+    "get_contact",
+    "Get details for a specific CRM contact in a space.",
+    {
+      space_id: z.string().describe("Space ID (sp_...)"),
+      contact_id: z.string().describe("Contact ID (contact_...)"),
     },
-    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 });
+    async ({ space_id, contact_id }) => {
+      const data = await client.get(`/spaces/${space_id}/contacts/${contact_id}`);
       return json(data);
     }
   );
@@ -142,6 +206,10 @@ export function registerMemberTools(server, client) {
   );
 }
 
+function encodePropertyFilters(filters) {
+  return filters && filters.length > 0 ? JSON.stringify(filters) : undefined;
+}
+
 function json(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }